4nk/sdk_common
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
sdk_common/doc/Auth-Specs.md
NicolasCantu 12a6e54f26 doc added
2024-02-12 12:07:05 +01:00

24 KiB
Raw Blame History

# Auth - Specs

1. Objectif

Développer un système de login sécurisé utilisant les clés cryptographiques de Bitcoin et sa timechain (via un réseau Signet personnalisé, appelé "side chain") ainsi qu'un système de relais de messages entre parties prenantes. Le concept de Silent Payment est employé pour authentifier les utilisateurs sans réutilisation d'adresses, tout en utilisant une approche de calcul multipartite (MPC) pour une gestion sécurisée et distribuée des clés. Déployer une interface de login conforme aux wireframes.

2. Portée

Ce système couvrira la conception et le développement de l'architecture d'authentification, incluant la génération, la gestion, et la validation des identités numériques à travers des formats de conformité spécifiques (Portable Contract Document et Portable Request Document). Il intégrera également l'authentification des utilisateurs, la connexion via des tiers, la récupération d'identités, et une gestion de session basée sur un cache avec des contraintes de sécurité renforcées. La solution sera conçue pour des environnements hautement sécurisés, nécessitant une haute disponibilité, performance, et évolutivité.

3. Définitions et Abréviations

Voir Specs - Définitions et abréviations.

4. Exigences de sécurité et de confidentialité

Voir Specs - Exigences de sécurité

5. Architecture générale

Diagramme d'architecture montrant les composants principaux du système de login. SheatSheet 4NK

6. Spécification des items

Voir Item - Specs

7. Spécification des roles

Voir Voir Item - Specs

8. Spécifiation des PCD et PRD

Voir Voir PRD et PCD - Specs

9. Authentification des utilisateurs

Les utilisateurs doivent pouvoir s'authentifier en utilisant un mot de passe et les données exif d'une image dite de login mise en cache dans IndexedDB pour les navigateurs et les applications mobiles, sinon en mémoire pour tous autres dispositifs dont l'IoT et une partie venant de membres choisi par les gestionnaires des membres des process.

Le système utilisera les clés cryptographiques de Bitcoin pour une authentification sécurisée via un HD Wallet transparent, intégrant le concept de Silent Payment pour éviter la réutilisation d'adresses. Les annuaires présents par rôles dans les contrats sont des listes d'adresses Silent Payments avec leurs third parties.

Les utilisateurs sont reconnus par une adresse Silent Payment dans un ou plusieurs rôles dans un process. Ces process préalablement publiés et relayés par les relais décrivent les conditions de validation des identités. Par process, les identités appelées techniquement member.

Chaque relais permet d'accéder à la liste des process, de créer, recomposer (recover) et révoquer (revoke) une identité, et de la compléter par process dans lequel l'utilisateur a un rôle (onboarding).

10. Connexion via des tiers

Le système offrira la possibilité de se connecter via des services tiers (tels que OAuth2, avec Google, GitHub, etc.), permettant une intégration fluide avec les écosystèmes existants sans dégrader l'expérience utilisateur.

Pour cela, les flux de 4NK agissent en "proxy" transparent devant les flux API des services concernés, et les tokens d'accès sont ajoutés aux données de member.

11. Fonctionnalité de récupération de mot de passe

En cas d'oubli de mot de passe, les utilisateurs pourront récupérer leur accès depuis une nouvelle identité (recover) après avoir révoqué l'ancienne identité, via un processus sécurisé, impliquant une vérification d'identité et l'échange de secrets chiffrés conformément aux protocoles établis.

Une image de révocation est générée à la création d'une identité pour pouvoir dépenser un UTXO dit alors de révocation, avec les flux PCD et PRD correspondants.

12. Gestion de session basée sur un cache

Le système ne maintiendra pas de session traditionnelle sur le serveur. La navigation de l'utilisateur persiste grâce à un cache local dans IndexedDB ou en mémoire, avec une politique de sécurité stricte forçant la resaisie du mot de passe après un rafraîchissement de la page ou une inactivité prolongée, déterminée par une durée maximale sans login.

13. Gestion des clés de l'identité (aussi les clés des transactions SP)

13.1. Génération des clés privées (création des identités numériques)

13.1.1. HD Wallet (BIP32 + BIP44)

Les transactions SP ont besoin de 2 clés privées Bitcoin, l'une critique sur la dépense des jetons, l'autre qui lève la confidentialité (partageable dans certains cas) :

  • Clé de dépense : la clé qui prouve sa détention par la capacité de dépenser un UTXO d'une transaction SP.
  • Clé de scan : la clé qui permet de détecter qu'une transaction SP nous est destinée.

Il y a 3 paires de ces clés privées :

  • 2 paires pour les données exif de l'image de login : l'une pour les transactions sur le signet, l'autre pour le mainnet.
  • 1 paire pour les données exif de l'image de révocation : pour les transactions de révocation sur le signet.

Techniquement ces clés sont identiques et générées de la même manière.

Chaque clé possède un chemin de dérivation spécifique et propre à son réseau (/0 pour le mainnet, /44 pour le signet).

Afin de constituer un portefeuille unique de clés du signet et du mainnet on génère un HD Wallet.

L'aléatoire pour la génération des clés est critique, et il convient de choisir un aléatoire fourni par une librairie de référence (rand pour le Rust).

Dans l'ordre on génère donc :

  1. Clé privée de dépense du login du signet spend_recover.
  2. Clé privée de scan du login du signet scan_recover.
  3. Clé privée de dépense de révocation du signet spend_revoke.
  4. Clé privée de scan de révocation du signet scan_revoke.
  5. Clé privée de dépense mainnet spend_mainnet.
  6. Clé privée de scan du mainnet scan_mainnet.
Génération des adresses SP

Le relais partage leur liste de relais au setup du SDK (Wasm), cette liste est stockée en cache sous forme d'objets SharedPeer.

Afin d'obtenir les premiers UTXO indispensables pour créer les adresses SP, l'utilisateur parcourt la liste de relais SharedPeer et se connecte à chacun via un MessageConnect.

Ces relais envoient en retour quelques jetons sur une adresse dite de faucet faucet_sp_address (adresses publiques classiques générées depuis ces clés privées).

Avec ces UTXO et les clés de dépense et de scan, on génère 1 adresse SP pour le réseau signet et 1 pour le réseau mainnet et chacun pour leurs clés de login et de révocation.

Dans l'ordre on génère donc :

  1. Adresse faucet_sp_address de login du signet.
  2. Adresse faucet_sp_address de révocation du signet.
  3. Adresse faucet_sp_address du mainnet.

Puis on se connecte aux relais selon (on se connecte à plusieurs relais afin de pallier aux indisponibilités éventuelles ou au manque de jetons éventuel sur le relai) :

  1. MessageConnect sur le relai 1 avec l'adresse faucet_sp_address de login du signet.
  2. MessageConnect sur le relai 1 avec l'adresse faucet_sp_address de révocation du signet.
  3. MessageConnect sur le relai 1 avec l'adresse faucet_sp_address du mainnet.
  4. MessageConnect sur le relai 2 avec l'adresse faucet_sp_address de login du signet.
  5. MessageConnect sur le relai 2 avec l'adresse faucet_sp_address de révocation du signet.
  6. MessageConnect sur le relai 2 avec l'adresse faucet_sp_address du mainnet.
  7. MessageConnect sur le relai 3 avec l'adresse faucet_sp_address de login du signet.
  8. MessageConnect sur le relai 3 avec l'adresse faucet_sp_address de révocation du signet.
  9. MessageConnect sur le relai 3 avec l'adresse faucet_sp_address du mainnet.
  10. MessageConnect sur le relai 4 avec l'adresse faucet_sp_address de login du signet.
  11. MessageConnect sur le relai 4 avec l'adresse faucet_sp_address de révocation du signet.
  12. MessageConnect sur le relai 4 avec l'adresse faucet_sp_address du mainnet.

Puis on génère les adresses SP :

  1. Adresse id_SP de login du signet depuis spend_recover et scan_recover et une des transactions des faucets depuis une transaction vers faucet_sp_address de login du signet.
  2. Adresse id_SP de révocation du signet depuis spend_revoke et scan_revoke et une des transactions des faucets depuis une transaction vers faucet_sp_address de révocation du signet.
  3. Adresse id_SP du mainnet depuis spend_mainnet et scan_mainnet et une des transactions des faucets depuis une transaction vers faucet_sp_address du mainnet.
Clés de dépense du signet du login

Le relais partage leur liste de process au setup du SDK (Wasm), cette liste est stockée en cache sous forme d'objets SharedProcess.

La clé privée de dépense du signet du login est la clé principale pour forger les identités.

Cette clé est d'abord décomposée, avant d'être partiellement distribuée. Voici les principales étapes :

  1. Cette clé sera scindée en 2 parties (à la moitié de la longueur de leur représentation hexadécimale) :

    1.1. Part1, c'est la partie qui sera chiffrée (AES-GCM 256 bits) par le mot de passe et stockée en cache dans une image dite de login.

    1.2. Part2, c'est la partie qui sera décomposée par un Shamir Secret Sharing, chiffrée pour chaque partie par le mot de passe et distribuées en 1 pour 1 aux membres actuels du rôle de gestionnaire des membres du process.

  2. Une préimage Part1EncHash qui identifie l'utilisateur est générée par le hash (SHA 256) de la Part1 et du mot de passe de l'utilisateur.

  3. Création d'un PRDKeyBackup par membre (1 shard par membre), par PRD :

    3.1. Génération d'une clé de chiffrement dite sp_shared_secret qui sera transmise dans le Diffie-Hellman de la transaction SP.

    3.2. Définition de l'attribut device_footprint_enc_by_sp_shared_secret et chiffrement avec sp_shared_secret.

    3.3. Définition de l'attribut part_1_enc_hash_enc_by_sp_shared_secret et chiffrement avec sp_shared_secret.

    3.4. Définition de l'attribut shard_enc_by_sp_shared_secret et chiffrement avec sp_shared_secret.

  4. Création des messages de type Message correspondant aux PRD, envoi des messages aux relais connectés.

Dans l'ordre on réalise donc les opérations suivantes donc :

  1. Split de spend_recover.
  2. Chiffrement AES de Part1.
  3. Mise en cache de Part1Enc.
  4. Création de la préimage
  5. Chiffrement AES de Part2.
  6. Sharding de Part2Enc.

Puis (exemple avec 2 membres) :

  1. Création de PRDKeyBackup à destination de membre 1 de la liste des membres (adresse SP) du rôle Member du Process.
  2. Création de PRDKeyBackup à destination de membre 2 de la liste des membres (adresse SP) du rôle Member du Process.
  3. Création de Message du PRDKeyBackup à destination de membre 1.
  4. Création de Message du PRDKeyBackup à destination de membre 2.
  5. Envoi de la transaction SP du Message du PRDKeyBackup à destination de membre 1.
  6. Envoi de la transaction SP du Message du PRDKeyBackup à destination de membre 2.
  7. Envoi du Message du PRDKeyBackup à destination de membre 1 sur le relai 1.
  8. Envoi du Message du PRDKeyBackup à destination de membre 1 sur le relai 2.
  9. Envoi du Message du PRDKeyBackup à destination de membre 1 sur le relai 3.
  10. Envoi du Message du PRDKeyBackup à destination de membre 1 sur le relai 4.
  11. Envoi du Message du PRDKeyBackup à destination de membre 2 sur le relai 1.
  12. Envoi du Message du PRDKeyBackup à destination de membre 2 sur le relai 2.
  13. Envoi du Message du PRDKeyBackup à destination de membre 2 sur le relai 3.
  14. Envoi du Message du PRDKeyBackup à destination de membre 2 sur le relai 4.
Étape d'update et envoi de l'objet ItemMember pour Onboarding

Pour être onboard dans un process, c'est-à-dire avoir un rôle, il faut s'ajouter dans la liste des membres du process.

Cela signifie envoyer un PRDUpdate avec une nouvelle version du PCD de la liste des membres, contenant notre objet ItemMember complet. Ce PRD devra recevoir des membres du rôle Member du process les PRDResponse correspondant aux critères de validation du process.

C'est à ce moment-là que l'on transmet toutes les clés privées dans l'objet ItemMember, en tant que donnée privée (chiffrée par la clé de dépense du signet) dans un PCD (et les PRDUpdate correspondant).

Les adresses SP correspondantes sont aussi transmises en tant que données publiques, ainsi que l'adresse SP de la clé de dépense du login du signet.

Avant de choisir un process pour continuer l'update de la nouvelle identité :

  1. Scan Nakamoto des transactions, récupération dans les transactions SP sur Adresse id_SP de login du signet, lecture du RequestHash de loutput 3 correspondant aux PRDResponse à recevoir ou déjà reçus.
  2. Réception des PRDResponse et contrôle de la valeur des signatures (hash_sig_value), attente du validation_timeout du rôle Member du process et validation ou non des PRDKeyBackup.
  3. Attente et réception des pcd_reference_hash des PRDResponse reçus avec le PCD des membres du processus (liste de itemMember).
  4. Recomposition de la clé selon : 4.1. Déchiffrement par le mot de passe de Part1Enc depuis le cache. 4.2. Déchiffrement par secret partagé de chaque shard reçu dans id_shard_info_enc_by_shared_secret des PRDResponse de chaque member du role Memberdu process. 4.3 Recomposition de Part2Enc et déchiffrement par le mot de passe 4.4 Concaténation de Part1 et Part2

Demande d'update de la liste des membres (PCD) d'un process (exemple avec 2 membres):

  1. Création et envoi des PRDKeyHello. 1.1. Création de PRDKeyHello à destination de membre 1 de la liste des membres (adresse SP) du rôle Member du Process. 1.2. Création de PRDKeyHello à destination de membre 2 de la liste des membres (adresse SP) du rôle Member du Process. 1.3. Création de Message du PRDKeyHello à destination de membre 1. 1.4. Création de Message du PRDKeyHello à destination de membre 2. 1.5. Envoi de la transaction SP du Message du PRDKeyHello à destination de membre 1. 1.6. Envoi de la transaction SP du Message du PRDKeyHello à destination de membre 2. 1.7. Envoi du Message du PRDKeyHello à destination de membre 1 sur le relai 1. 1.8. Envoi du Message du PRDKeyHello à destination de membre 1 sur le relai 2. 1.9. Envoi du Message du PRDKeyHello à destination de membre 1 sur le relai 3. 1.10. Envoi du Message du PRDKeyHello à destination de membre 1 sur le relai 4. 1.11. Envoi du Message du PRDKeyHello à destination de membre 2 sur le relai 1. 1.12. Envoi du Message du PRDKeyHello à destination de membre 2 sur le relai 2. 1.13. Envoi du Message du PRDKeyHello à destination de membre 2 sur le relai 3. 1.14. Envoi du Message du PRDKeyHello à destination de membre 2 sur le relai 4.
  2. Réception des PRDResponse en réponse aux PRDKeyHello et mise à jour des listes depuis les PCD correspondants.
  3. Création d'un ItemMember correspondant à l'utilisateur avec les clés chiffrées (hors clés de révocation) dans la partie data des métadonnées privées et les adresses SP dans les données publiques.
  4. Création d'une nouvelle version du PCD avec l'ajout de l'ItemMember créé.
  5. Parcours des membres du rôle Member et envoi des PRDUpdate.
  6. Attente de la validation (PRDResponse) du PRDUpdate.
  7. Redirection vers la page du process sur le relai.
Clés de révocation (revoke)

Les clés de l'image de révocation sont chiffrées par le mot de passe (ou pas, en option) et stockées directement dans les données exifs de l'image de révocation. Les adresses SP correspondantes sont aussi inscrites dans les données exif.

L'envoi d'une révocation est identique à la création d'une nouvelle adresse via les PRDKeyBackup mais la transaction SP est envoyée depuis l'adresse de révocation (la clé aura dû être chargée au préalable depuis l'interface).

Clés de third parties

En plus, on peut générer d'autres paires de clés de dépense et de scan qui seront à exporter vers d'autres dispositifs pour du 2FA, avec leurs UTXO.

Pour cela, il faut se connecter aux relais avec les adresses de faucet de ces nouvelles clés (adresses publiques classiques générées depuis ces clés privées). Comme pour les clés de recover et de revoke.

Les adresses SP de ces clés sont ajoutées avec les labels et éventuellement les empreintes des dispositifs correspondants dans l'objet ItemMember.

Ces clés sont générées lors de l'update d'un membre, avec déjà une identité créée sur un process, à la validation de l'update il est possible de télécharger des images correspondantes (clés + hash du process) dans une interface 2FA.

Lorsqu'une transaction est reçue sur l'application de 2FA, celle-ci demande de confirmer ou non. Si il y a une confirmation dans l'interface alors une transaction SP est envoyée au dispositif initial, en dépensant l'UTXO reçue et avec les mêmes Hash dans les outputs que la transaction reçue afin que le dispositif initial puisse collecter les PRD concernés.

13.1.2. Connexions avec une identité crée (recover)

Comme pour la création de compte, les relais partagent leur liste de relais et de process au setup du SDK (Wasm), ces listes sont stockées en cache sous forme d'objets SharedPeer et SharedProcess.

Afin d'obtenir de nouveaux UTXO indispensables pour créer les adresses SP, l'utilisateur parcourt la liste de relais SharedPeer et se connecte à chacun via un MessageConnect.

Dans l'ordre on réalise les opérations suivantes :

  1. Récupération de Part1Enc en cache
  2. Création de la pré-image avec le mot de passe

Puis :

  1. Création de PRDKeyHello à destination de membre 1 de la liste des membres (adresse SP) du rôle Member du Process.

  2. Création de PRDKeyHello à destination de membre 2 de la liste des membres (adresse SP) du rôle Member du Process.

  3. Création de Message du PRDKeyHello à destination de membre 1.

  4. Création de Message du PRDKeyHello à destination de membre 2.

  5. Envoi de la transaction SP du Message du PRDKeyHello à destination de membre 1.

  6. Envoi de la transaction SP du Message du PRDKeyHello à destination de membre 2.

  7. Envoi du Message du PRDKeyHello à destination de membre 1 sur le relai 1.

  8. Envoi du Message du PRDKeyHello à destination de membre 1 sur le relai 2.

  9. Envoi du Message du PRDKeyHello à destination de membre 1 sur le relai 3.

  10. Envoi du Message du PRDKeyHello à destination de membre 1 sur le relai 4.

  11. Envoi du Message du PRDKeyHello à destination de membre 2 sur le relai 1.

  12. Envoi du Message du PRDKeyHello à destination de membre 2 sur le relai 2.

  13. Envoi du Message du PRDKeyHello à destination de membre 2 sur le relai 3.

  14. Envoi du Message du PRDKeyHello à destination de membre 2 sur le relai 4.

  15. Scan Nakamoto des transactions, récupération dans les transactions SP sur Adresse id_SP de login du signet, lecture du RequestHash de loutput 3 correspondant aux PRDResponse à recevoir ou déjà reçus.

  16. Réception des PRDResponse et contrôle de la valeur des signatures (hash_sig_value), attente du validation_timeout du rôle Member du process et validation ou non des PRDKeyHello.

  17. Attente et réception des pcd_reference_hash des PRDResponse reçus avec le PCD des membres du processus (liste de itemMember).

  18. Recomposition de la clé selon : 4.1. Déchiffrement par le mot de passe de Part1Enc depuis le cache. 4.2. Déchiffrement par secret partagé de chaque shard reçu dans id_shard_info_enc_by_shared_secret des PRDResponse de chaque member du role Memberdu process. 4.3 Recomposition de Part2Enc et déchiffrement par le mot de passe 4.4 Concaténation de Part1 et Part2

Demande d'update de la liste des membres (PCD) d'un process :

  1. Création et envoi des PRDList.
  2. Réception des PRDResponse en réponse aux PRDList et mise à jour des listes depuis les PCD correspondants.
  3. Création d'un ItemMember correspondant à l'utilisateur avec les clés chiffrées (hors clés de révocation) dans la partie data des métadonnées privées et les adresses SP dans les données publiques.
  4. Création d'une nouvelle version du PCD avec l'ajout de l'ItemMember créé.
  5. Redirection vers la page du process sur le relai.

13.1.3. Workflow des PRD et PCD

Voir PRD et PCD - Specs.

13.1.4. Workflow des Messages, transactions SP et connexion aux web sockets

Voir Specs - Messages et transactions SP.

14. Spécifications du code

Voir Specs - Code

14.1. Maintenance, environnement de déploiement

Voir Specs - Maintenance, environnement de déploiement

15. Annexe

15.1. Exemples de code

Extraits de code illustrant des aspects clés du système de login, tels que le hashing de mot de passe, ou la configuration du middleware de sécurité.

15.2. Références

Voir Specs - References