< Interface REST

Auth

Depuis le firmware 2.1.2, l'authentification sur l'API REST se base sur celle employée sur l'interface web de configuration de la neufbox.

Vous avez donc le choix entre:

  • désactiver l'authentification,
  • le login/mot de passe,
  • le bouton de service,
  • activer toutes les méthodes d'authentification.

Pour s'authentifier avec un login et un mot de passe, il faut procéder comme avec l'authentification par bouton de service sauf qu'il faut passer le paramétre hash en plus lors de l'appel de la méthode auth.checkToken. Ce paramétre hash est la concaténation du hash du login et du hash du mot de passe.

Un hash d'une valeur est composé de 64 caractères (32 digest SHA256 en représentation hexadécimal - voir la page Example/HashC pour plus d'explications) et se calcul ainsi (value étant la valeur a hasher et key le token):

fh = sha256_hash(value)
hash = hmac_sha256_hash(key, fh)

Exemple de code de hashage en C

N.B.: Avant le firmware 2.1.2, seul l'authentification par bouton de service était disponible.

Example d'authentification avec un login et un mot de passe

Le login et le mot de passe vaut admin et admin.

$ curl -s -G  http://neufbox/api/1.0/?method=auth.getToken
<?xml version="1.0" encoding="UTF-8"?>
<rsp stat="ok" version="1.0">
   <auth token="43f6168e635b9a90774cc4d3212d5703c11c9302" method="passwd" />
</rsp>

$ ./hash 43f6168e635b9a90774cc4d3212d5703c11c9302 admin
hash = 7aa3e8b3ed7dfd7796800b4c4c67a0c56c5e4a66502155c17a7bcef5ae945ffa

$ curl -s http://neufbox/api/1.0/?method=auth.checkToken\&token=43f6168e635b9a90774cc4d3212d5703c11c9302\&hash=7aa3e8b3ed7dfd7796800b4c4c67a0c56c5e4a66502155c17a7bcef5ae945ffa
<?xml version="1.0" encoding="UTF-8"?>
<rsp stat="ok" version="1.0">
   <auth token="43f6168e635b9a90774cc4d3212d5703c11c9302" />
</rsp>

N.B: Dans la pratique, il faut que toutes ses commandes soit executés en moins de 5 secondes à cause du timeout de validité du token lors de l'utilisation de la méthode d'authentification par login/mot de passe seul.

auth.getToken

  • Méthode HTTP : GET
  • Accès : public
  • Description : retourne un nouveau token pour la procédure d'authentification, ou un code d'erreur
  • Succès :
    • tag auth avec:
      • l'attribut token
      • l'attribut method (passwd|button|all) contenant les méthodes possibles pour s'authentifier. all signifie que toutes les méthodes d'authentification sont activés. (firmware >= 2.1.2)
  • Erreur :
    • 0 : Unknown error. Erreur interne lors de la génération du token
    • 201 : Max token reached. Nombre maximal de tokens atteint (la limite est de 64 demandes simultanées)
    • 205 : Authentification disabled. L'authentification est désactivée. (firmware >= 2.1.2)
  • Exemple :
    <?xml version="1.0" ?>
    <rsp stat="ok" version="1.0">
       <auth token="fe5be7az1v9cb45zeogger8b4re145g3" method="passwd" />
    </rsp>
    

auth.checkToken

  • Méthode HTTP : GET
  • Accès : public
  • Description : vérifier si le token a été validé
  • Paramètres :
    • token : token à valider (obligatoire)
    • hash : hash du login/mot de passe si essai d'authentification par login/mot de passe (optionnel) (firmware >= 2.1.2)
      • la valeur du hash est obtenue en concaténant le hash du login et le hash du mot de passe (la longueur de cette valeur est donc de 128 caractères).
  • Succès :
    • tag auth avec attribut token
  • Erreur :
    • 201 : Invalid session. La session n'existe pas ou est déjà authentifiée.
    • 202 : Pre-Session timeout. Vous disposez de 5 minutes entre le getToken et le checkToken pour valider le token.
      • N.B: Si la méthode d'authentification autorisée est uniquement par login/mot de passe, le timeout entre le getToken et checkToken est de 5 secondes. (firmware >= 2.1.2)
    • 203 : Push button not pushed. Le bouton n'a pas été appuyé.
    • 204 : Invalid login and/or password. Le login et/ou le mot de passe est invalide. (firmware >= 2.1.2)
    • 205 : Authentification disabled. L'authentification est désactivée. (firmware >= 2.1.2)
  • Exemple d'un succès puis d'une erreur :
    <?xml version="1.0" ?>
    <rsp stat="ok" version="1.0">
       <auth token="fe5be7az1v9cb45zeogger8b4re145g3" />
    </rsp>
    
    <?xml version="1.0" ?>
    <rsp stat="fail" version="1.0">
       <err code="203" msg="Push button not pushed" />
    </rsp>