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 or multipart/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ûr

  • md5 : 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 :

  1. un horodatage UNIX, indiquez cet horodatage dans l’en-tête X-Elgg-time

  2. une chaîne aléatoire, indiquez cette chaîne dans l’en-tête X-Elgg-nonce

  3. la clef publique d’API, indiquer cette clef d’API dans l’en-tête X-Elgg-apikey

  4. la chaîne de requête url (par exemple method=test.test&foo=bar)

  5. lorsqu’il s’agit d’une requête POST, ajoutez le posthash tel qu’indiqué dans l’entête X-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.