Authentification HMAC
Le framework d’API RESTful de Elgg fournit des fonctions pour prendre en charge un schéma de signature HMAC pour l’authentification API. Le client doit envoyer la signature HMAC ainsi qu’un ensemble d’en-têtes HTTP spéciaux lors de l’exécution d’un appel qui nécessite l’authentification API. Cela garantit que l’appel API est effectué à partir du client déclaré et que les données n’ont pas été falsifiées.
Le HMAC doit être construit à partir des données suivantes :
La clef d’API publique qui vous identifie auprès du serveur api de Elgg, tel que fourni par le plugin APIAdmin
La clef privée d’API fournie par Elgg (qui accompagne la clef publique)
L’heure unix actuelle en secondes
Une valeur « nonce » créée pour l’occasion afin de garantir que deux requêtes faites à la même seconde ont des signatures différentes
Une représentation encodée pour l’URL de la chaîne de caractères des paramètres GET, par ex.
method=test.test&foo=bar
Si vous envoyez des données post, le hash de ces données
Quelques informations supplémentaires doivent être ajoutées à l’entête HTTP pour que ces données soient traitées correctement :
X-Elgg-apikey - La clef publique d’API
X-Elgg-time - L’heure Unix utilisée dans le calcul HMAC
X-Elgg-nonce - une chaîne aléatoire
X-Elgg-hmac - Le HMAC encodé en base64
X-Elgg-hmac-algo - L’algorithme utilisé dans le calcul HMAC
Si vous envoyez des données POST vous devez également envoyer :
X-Elgg-posthash - Le hash des données POST
X-Elgg-posthash-algo - Algorithme utilisé pour le hachage des données POST
Content-type - The content type of the data you are sending (this can be
application/x-www-form-urlencoded
ormultipart/form-data
)Content-Length - La longueur en octets de vos données POST
Elgg fournit un exemple de client API qui implémente cette signature HMAC : \Elgg\WebServices\ElggApiClient
. Il constitue une bonne référence sur la manière de le mettre en œuvre.
Algorithmes de hachage pris en charge
sha256
: recommandésha1
: rapide mais moins sûrmd5
: faible et sera supprimé à l’avenir
POST hash calculation
When sending the POST data as Content-Type: application/x-www-form-urlencoded;
the post hash needs to be calculated
over all the post data using one of the supported hashing algorithms.
When sending the POST data as Content-Type: multipart/form-data;
the post hash needs to be calculated
over an empty string.
The result of the hashing needs to be reported in the X-Elgg-posthash
header and the used hashing algorithm must be
reported in the X-Elgg-posthash-algo
header.
Avertissement
Since the POST hash isn’t calculated when using Content-Type: multipart/form-data;
only use this when calling
APIs that need an file input.
Calcul du hachage HMAC
Le HMAC global doit être calculé sur les données suivantes (dans l’ordre) en utilisant la clef secrète d’API comme le secret HMAC et avec l’un des algorithmes de hachage pris en charge :
un horodatage UNIX, indiquez cet horodatage dans l’en-tête
X-Elgg-time
une chaîne aléatoire, indiquez cette chaîne dans l’en-tête
X-Elgg-nonce
la clef publique d’API, indiquer cette clef d’API dans l’en-tête
X-Elgg-apikey
la chaîne de requête url (par exemple
method=test.test&foo=bar
)lorsqu’il s’agit d’une requête POST, ajoutez le
posthash
tel qu’indiqué dans l’entêteX-Elgg-posthash
The resulting string needs to be base64 encoded and then url encoded and be reported in the X-Elgg-hmac
header.
The used hashing algorithm needs to be reported in the X-Elgg-hmac-algo
.
Cache de hachage
Pour des raisons de sécurité, chaque hachage HMAC doit être unique, tous les hachages soumis sont stockés pendant 25 heures pour éviter la réutilisation.