Généralités

Authentification des requêtes

L’authentification des requêtes doit être activée dans la configuration du serveur Waarp R66 (valeur de la balise restauthenticated à true).

Si la requête doit être authentifiée, le nom de l’utilisateur doit être ajouté à la requête en définissant l’en-tête HTTP X-Auth-User.

Note

Le mot de passe n’est jamais transmis en clair dans la requête, mais sert à générer la signature de la requête.

Pour plus de sécurité, il vaut mieux activer la signature quand les requêtes sont authentifiées.

Signature des requêtes

La signature des requêtes REST permet de s’assurer que les requêtes n’ont pas été modifiées entre l’envoi et l’émission du message http (man in the middle) en transmettant une signature cryptographique de la requête.

La signature des requêtes doit être activée dans la configuration du serveur Waarp R66 (valeur de la balise restsignature à true).

Si la requête doit être signée, la signature doit être ajoutée à la requête en définissant l’en-tête HTTP X-Auth-Key. La valeur de cet en-tête est calculé selon l’algorithme décrit ci-dessous.

Calcul de la signature

La signature est calculée à partir de du chemin et de la chaîne de requête de l’URL requêtée selon l’algorithme suivant :

1. Tous les arguments de la chaîne de requête (query string), auxquels sont ajoutés les entêtes de X-Auth-Timestamp et X-Auth-User si ceux-ci sont utilisés, sont convertis en minuscules et triés dans l’ordre alphabétique des identifiants pour reconstruire une nouvelle chaine de requête.

2. Le paramètre X-Auth-InternalKey est ajouté à la chaîne de requête obtenue à l’étape precedente, avec pour valeur le mot de passe de l’utilisateur.

3. La chaîne de caractère utilisée pour le calcul de la signature est construite en concaténant le chemin de l’url et la chaîne de requête obtenue précédemment.

4. Enfin, la signature est calculée en appliquant la fonction HMAC-SHA256 à la chaîne de caractère obtenue à l’étape précédente avec la clef secrète du serveur (définie dans la balise restsigkey de sa configuration). C’est la représentation hexadécimale de la signature qui est conservée.

Exemple

On effectue une requête pour exporter l’historique des transferts terminés vers un fichier XML. La requête est envoyée à l’URL http://127.0.0.1:8088/log avec l’utilisateur adminuser (mot de passe : adminpass). La conficuration du serveur demande à ce que la requête soit horodatée.

La chaîne de requete utilisée pour le calcul de la signature sera donc x-auth-user=adminuser&x-auth-timestamp=2017-04-12T23:20:50.52Z.

Après ajout du mot de passe (étape 2), elle devient x-auth-user=adminuser&x-auth-timestamp=2017-04-12T23:20:50.52Z&X-Auth-InternalKey=adminpass.

La chaine de caractère complète utilisée pour le calcul de la signature est donc /log?x-auth-user=adminuser&x-auth-timestamp=2017-04-12T23:20:50.52Z&X-Auth-InternalKey=adminpass.

Enfin, c’est la représentation hexadécimale du hash HMAC-SHA256 appliqué à cette chaîne de caractère qui est utilisée comme signature.

Clef de signature

La clef utilisée pour la génération de la signature est stockée dans un fichier dont le chemin doit être renseigné dans la balise restsigkey du fichier de configuration du serveur.

Il s’agit d’une séquence aléatoire de 32 octets. Sous Linux, elle peut être générée avec la commande suivante :

# Pour afficher une clef
head -b 32 /dev/urandom

# Pour générer directement le fichier
head -b 32 /dev/urandom > path/to/restsigning.key

Horodatage des requêtes

Pour augmenter la sécurité de l’API, un serveur peut demander à ce que les requêtes soient horodatées.

L’horodatage des requêtes doit être activé dans la configuration du serveur Waarp R66 (valeur de la balise resttimelimit supérieur à 0).

La valeur de la balise resttimelimit représente la durée de validité de la requête : si l’écart entre l’heure du serveur Waarp R66 au moment de la recéption de la requête et la date contenue dans la requête est supérieur à resttimelimit, la requête est refusée.

Si la requête doit être horodatée, le date et l’heure doivent être ajoutées à la requête en définissant l’en-tête HTTP X-Timestamp. La date doit être au format RFC 3339 (exemple: 2018-03-22T16:00:05.352Z).