Voir la source de NF16618 — API ⇒ sécurisation du système de connexion pour se protéger des attaques de type ⇒ XSS CSRF

[[Catégorie:CG58 → A classer]]{{DebutInfoCartographe}}{{#cartographie:16618}}
<blockquote><small>''Voir la carte de la fonctionnalité : [[PP58_—_A_classer#NF16618|A classer]]''</small></blockquote>{{FinInfoCartographe}}
{{DebutChapeau}}<br/><br/>{{FinChapeau}}

Pour protéger les API des problèmes standard de sécurité, nous avons choisi de mettre en place un système à '''secret échangé sur liaison TLS avec validation optionnelle du certificat par clé partagée AES256'''.

Dans la pratique, quatre informations sont impliquées dans l'identification d'un client pour nos API : 

*un '''identifiant unique''' (appelé dans le reste de la documentation UID ou GUID)
*un '''secret''' (aka. l'équivalent d'un mot de passe très fort) ;
*une '''clé AES partagée''' ;
*'''l'empreinte du certificat du service''' ;

Ce document décrit le choix du système d'identification des API ainsi que les modalités d'installation, d'implémentation, et d'utilisation.

Afin de faciliter le travail des intégrateurs, il existe :

*une '''documentation à jour''' pour la version du Polaris auquel vous vous connectez, disponible sur ''https://[service:client]:[port]/api/''
*le documentation est au format OpenApi permettant de générer les clients plus facilement.

==Système à clé d'API (ou secret)==
Beaucoup de systèmes utilisent un système de secret ou de clé d'API.

Le système est simple et efficace : à chaque requête, le client utilise son identifiant et son secret pour prouver son identité au service qui accepte le travail s'il trouve une correspondance dans sa base d'utilisateurs.

La preuve de l'identité se fait donc à chaque requête, par la communication d'un ''secret''.

Mais ce système a une faiblesse : il est nécessaire pour le client d'identifier à coup sûr le service auquel il se connecte afin de ne pas envoyer ses informations de connexion à n'importe qui.

Explication : si un tiers venait à usurper l'identité du service, le client lui renverrait son secret sans se méfier (''phishing''). Le tiers pourra par la suite et à loisir utiliser cet accès sans que son véritable propriétaire en ait connaissance.

Pour contrer ce cas de figure, il est nécessaire d'établir la connexion sur une liaison TLS, protégée par un '''certificat X509 possédé par le service et reconnu expressément par le client'''.

'''Le fait que le certificat soit valide ne suffit pas,''' car de nombreuses autorités de confiance reconnues présentent des lacunes importantes dans le processus de validation du domaine (DCV) et peuvent délivrer par erreur à des adversaires des certificats (''MITM attacks that use valid CA-issued certificates''). 

Muni de son certificat qui valide TLS, l'adversaire peut réaliser une attaque très simple par détournement de trafic pour récupérer la clé :

<br />[[Fichier:Attaque par MITM.png|centré|sans_cadre|622x622px|Attaque par MITM]]


Afin d'éviter ce cas dit de ''misissuance'' (i.e. une autorité de certification peu soigneuse tierce délivre par erreur à un adversaire un certificat valide pour le service) '''au moins une des trois techniques suivantes doit être impérativement mise en place'''.

===Par restriction de certificat===
L'idée générale est de mémoriser la clé partagée et l'empreinte du certificat du service à l'installation du client. 

A la connexion, on vérifiera que le certificat est valide, mais également que son empreinte correspond bien à celle mémorisée. Si c'est le cas, alors on peut envoyer la clé partagée en toute sécurité.

C'est la méthode la plus simple et la plus efficace, mais également la plus contraignante car il est nécessaire de reconfirmer la clé partagée à chaque changement de certificat (tous les 3 mois pour Let's Encrypt, tous les ans pour Comodo). Tout certificat à clés suffisamment dimensionnées peut alors convenir.

'''Tout intégrateur est libre de la mettre en place à sa convenance mais nous n'assurons pas de support sur l'implémentation de la restriction.'''

===Par restriction d'autorité de certification===
L'idée générale ici est de mémoriser quelles sont les autorités de certification autorisées par le service à l'installation du client.

A la connexion, on vérifiera :

*que le certificat présenté par le service est valide<sup>1</sup>;
*qu'il n'a pas été révoqué par l'autorité qui l'a émit<sup>2</sup>;
*mais également qu'une des autorités mémorisées est bien présente dans la chaîne de validation du certificat. Si c'est le cas, alors on peut envoyer la clé partagée en toute sécurité.

Cela fonctionne car le service n'accepte de travailler qu'avec les autorités de confiance : 

*qui pratiquent le Multipath DCV (cf. https://blog.cloudflare.com/secure-certificate-issuance/) rendant difficile le ''hijacking'' lors du DCV ;
*qui utilisent le mécanisme de CT Logs (cf. http://www.certificate-transparency.org/what-is-ct) permettant un contrôle après coup ;

'''Tout intégrateur est libre de la mettre en place à sa convenance mais nous n'assurons pas de support sur l'implémentation de la restriction.'''


''<sup>1</sup> cette opération est nativement prise en charge par votre OS et tous les clients HTTP''

''le contrôle de révocation CRL ou OCSP est souvent pris en charge de manière optionnelle, il convient de vérifier et d'activer la bonne option correspondant à votre bibliothèque.''

===Vérifier le certificat par défi à l'aide d'une clé partagée===
'''C'est le niveau de sécurité optimal et c'est celui que nous avons choisi.'''

L'idée ici est de vérifier que le tiers nous présente bien un certificat qui correspond à celui que le service est censé utiliser et une fois vérifié, n'accepter les liaisons TLS que sur ce certificat (''certificate pinning'').

Rappelons nous que nous sommes dans le cadre d'une liaison TLS, ainsi, si interception il y a lieu, c'est forcement que l'adversaire est en possession d'un certificat valide du même nom que le service auquel nous nous connectons.

Puisque nous partageons normalement une clé secrète avec le serveur, nous allons nous en servir pour que ce dernier signe le certificat qu'il est censé utiliser. Ainsi, si un adversaire s'est placé entre les deux (attaque MiTM), il disposera d'un certificat valide, certes, mais pas de la clé partagée, il sera incapable de signer correctement son certificat et s'il laisse passer le trafic venant du service réel (hijack), le client constatera que le service a signé un autre certificat que celui sur lequel est établi sa liaison TLS.

'''Cette vérification est optionnelle et n'a besoin d'être effectuée que dans le cas où le certificat présenté par le serveur serait inconnu (à chaque fois qu'il change).'''

==== Déroulé de la phase de vérification du certificat ====

#le client envoi une demande avec son identifiant (UID) ;
#le service reçoit la demande, recherche la clé partagée correspondant à UID et l'utilise pour signer l'empreinte de son certificat avec le protocole HMAC-SHA256 ; puis renvoi cette signature ;
#le client effectue la même opération avec l'empreinte du certificat auquel il est connecté. Si les signatures sont égales, alors il s'agit bien du certificat autorisé et la communication peut continuer normalement ; autrement, la liaison doit être terminée et l'incident signalé.
#par la suite, seul le certificat qui a été autorisé devrait être accepté, les autres devraient être systématique rejeté (''certificate pinning''). <br />

===Considérations de sécurité===

====Pour le client====
Le client doit protéger la clé partagée et son ''secret'' par tout moyen possible. Si la clé et le secret sont stockés en base de données, ceux-ci devraient être chiffrés par une clé accessible sur un autre support que par le processus chargé de les utiliser de sorte qu'elle ne soit pas accessible à un adversaire arrivant à effectuer une lecture inappropriée de la base de données.

====Échange des informations de connexion====
Afin de permettre aux tiers de se connecter en toute sécurité sur le système sans envoyer les informations de connexion par mail, un processus de jumelage a été mis en place :

*l'administrateur ouvre un accès et déclenche une procédure d'association depuis Polaris ;
*un lien et un code PIN lui est fourni qu'il peut partager avec le fournisseur par mail ou téléphone ;
*le lien n'est valable qu'une seule fois et permet d'obtenir les informations de connexion sur une liaison sécurisée en échange du code PIN.

== Utilisation pratique ==

=== Validation du certificat ===

Que le certificat du service soit auto-signé ou bien respecte la validation, '''vous devez le valider avec notre procédure''' pour éviter tout risque de vol de certificat (voir ci-dessus).

'''Avant d'envoyer vos identifiants comme stipulé ci-dessous''', vous devez vérifier que l'empreinte du certificat présenté par le service correspond à celle qu'il signe avec la clé partagée. Une fois validé, vous ne devez valider que le dit certificat, pour le reste de la session ('''certificate pinning''').


=== Identification ===
Lors de l'association d'un système tiers à Polaris, un UID, un secret et une clé partagée sont émises.
Chaque requête HTTP doit être identifiée par l'émission de l'UID et du secret dans un ''header HTTP''.