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 - Le type de contenu des données que vous envoyez (cela peut être application/x-www-form-urlencoded ou 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

Calcul du hachage POST

Lors de l’envoi des données POST en tant que Content-Type: application/x-www-form-urlencoded;, le hachage de la publication doit être calculé sur toutes les données de publication à l’aide de l’un des algorithmes de hachage pris en charge.

Lors de l’envoi des données POST en tant que Content-Type: multipart/form-data; le hachage de publication doit être calculé sur une chaîne vide.

Le résultat du hachage doit être rapporté dans l’entête X-Elgg-posthash et l’algorithme de hachage utilisé doit être rapporté dans l’entête X-Elgg-posthash-algo.

Avertissement

Étant donné que le hachage POST n’est pas calculé lors de l’utilisation de Content-Type: multipart/form-data;, utilisez-le uniquement lors de l’appel d’API nécessitant une entrée de fichier.

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

La chaîne résultante doit être codée en base64, puis l’URL encodée et indiquée dans l’en-tête X-Elgg-hmac. L’algorithme de hachage utilisé doit être signalé dans 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.