4nk/sdk_common
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
sdk_common/doc/Auth-Specs.md

22 KiB
Raw Blame History

Auth - Specifications

1. Autheurs, validations, dates, versions, changement and historique

Cf. Git SDK COMMON

2. Table des matières

3. 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 d'une Envelope (message JSON contenant de PRD ou des PCD) entre parties prenantes. Le concept de Silent Payments est employé pour authentifier les User 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 :

Wireframes

4. 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 users à travers des formats de conformité spécifiques (Portable Contract Document et Portable Request Document). Il intégrera également l'authentification des User, la connexion via des tiers, la récupération d'user, 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é.

5. Documents de référence

Wireframes :

Voir _Doc_references.md.

Indication génériques

Toutes les mentions de chiffrement et de déchiffrement implique l'algorithme AES-GCM 256 bits (soit des clés de 256 bits, ou 32 bytes).

Sauf mention contraire, tous les Hash désignent l'algorithme sha256.

Le tableau des notifications dans PCD/PRD indique quels flux font l'objet d'une notification. Les notification ne sont pas dépendantes des usages mais des types PCD/PRD (pour plus de facilité d’implémentation et éviter les spécifiques).

6. Schématisation des processus

6.1. Création d'un User

WalletCreate

Note: Comme la liste des Process, c’est une liste en cache fusioné avec les nouvelles liste reçues dans les enveloppes puis repartagé fusionné dans les enveloppes envoyées

6.2. Onboarding

WalletOnboard

Note: "Selected process" est le (ou les) process sélectionnés dans l’IHM (pour la cas d’une création via navigateur)

Note: "Member Managers" est la liste des adresses SP dans le rôle Member, ce seront les destinataires du PrdUpdate de la liste des membres et des transactions SP associées.

=> Un PCD est toujours une liste d’objets, ici la listes des membres du process.

6.3. Connexion avec un User créée (recover)

WalletRecover

L'image ImageRecover contient :

  • KeyRecoverScan: clé privée de scan des transaction SP de recover
  • Part1Enc: clé privée de dépense de l'User chiffrée par le mot de passe
  • SeedRand1: seed utilisée pour générer Part1Enc
  • SeedRand2: seed utilisée pour générer Part2Enc
  • PreId: identifiant de l'User généré par le hash de Part1Enc et du mot de passe de l'User

6.4. Extension de l'entropie du mot de passe (PBKDF2)

PBKDF2

6.5. Chiffrement AES quantique résistant (AES-GCM-256)

AES-GCM-256

6.6. Génération des clés privées

KeyGen

7. Authentification des User

Les User doivent pouvoir s'authentifier en utilisant un mot de passe et les données exif d'une image dite recover mise en cache dans IndexedDB (données chiffrées par le mot de passe cf. Chiffrement AES quantique résistant (AES-GCM-256)) pour les navigateurs et les applications mobiles, sinon chiffré de la même manière mais en mémoire pour tous autres dispositifs dont l'IoT et une partie venant de Members choisi par les gestionnaires des Members 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 Payments 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 (autres device de confirmation des actions en 2FA).

Les User sont reconnus par uneadresse SP 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 User. Par Process, les User appelées techniquement Member.

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

8. 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 User.

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. En parrallèle des flux existant, les hash des requêtes API et de leurs réponses sont signés des clés des parties prenantes pour une vérification de la conformité des données par rapport aux Process 4NK.

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

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

Une image de révocation est générée à la création d'un User pour pouvoir dépenser un UTXO dit alors de révocation pour signaler aux autres Members de Process de ne plus prendre en compte les transactions venant de l'adresse silent payment actuelle du User.

10. Gestion de session basée sur un cache

Le système ne maintiendra pas de session traditionnelle sur le serveur. La navigation de l'User 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.

11. Principe de fonctionnement

A la création d'un User, le SDK génère une clé privée Bitcoin pour les transactions SP (Silent Payments) et une clé privée pour la révocation de ce User. Ces clés sont stockées dans les données exif d'une image de login et d'une image de révocation, respectivement.

En fonction du Process choisi, l'User devra remplir un formulaire pour compléter son Member avec les champs requis par le Process. Ces champs sont définis dans le champs "render_template_list" de l'attribut metadata_contract_public du Item du Role Member du Process.

Des types de messages spécifiques sont utilisés au préalable :

  • Création d'un User : PRDUserCreate
  • Récupération de la clé d'un User : PRDUserRecover

Puis l'User envoi un PCD contenant la liste mise à jour des Member complété de son propre Member, des autres clés cryptographiques et des shards de sa clé de spend et un PRDUpdate à chaque Member de chaque Role de chaque Member pour leur demander de valider cette nouvelle version de la liste des Member (PCD).

Optionnellement, l'User envoi un PCD contenant la liste mise à jour des Process complété de son propre address Silent Payments dans un ou plusieurs Role du Process et un PRDUpdate à chaque Member de chaque Role de chaque Process pour leur demander de valider cette nouvelle version de la liste des Process (PCD).

En retour les PRDConfirm confirmeront la réception des PRDUpdate.

De même, les PRDResponse en réponse au PRDUpdate de la liste des Member contiendront les shards de clés de spend des Member de chaque Role de chaque Member pour permettre à l'User de recomposer sa clé de spend et la valeur de leur signature pour valider ou non la demande de mise à jourd de la liste des Member et les clés chiffrées des champs confidentiels des Member.

Si l'User a aussi envoyé un PRDUpdate de la liste des Process, les PRDResponse en réponse contiendront la valeur de leur signature pour valider ou non la demande de mise à jour de la liste des Process ainsi que les clés chiffrées des champs confidentiels des Process.

Note : Les User sont communs à tous les Process et décrits par Process avec leurs champs spéciifiques dans des Member de type Member gérés par les Member qui sont listés dans le Role Member du Process via leur adresse SP. Lors de la création d'un User, on utilise le plus souvent un Process existant. On pourrait aussi s’arrêter à la création du User mais ce serait un peut étrange dans l’expérience car personne n’a besoin de créer un User sans aller sur Process.

12. Wallet

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 'spend' : la clé qui prouve sa détention par la capacité de dépenser un UTXO d'une transaction SP.
  • Clé de scan '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, 1 pour le signet, voir le BIP pour la spécification exacte).

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. une seed de 512 bits pour les wallets recover et mainnet
  2. une pour le wallet revoke

La seed 1 permet de dériver :

  1. "m/352h/0h/0h/1h/0", "m/352h/0h/0h/0h/0"),
  2. Clé privée de dépense du login recover_spend (m/352h/1h/0h/0h/0)
  3. Clé privée de scan du login recover_spend (m/352h/1h/0h/1h/0).
  4. Clé privée de dépense mainnet mainnet_spend (m/352h/0h/0h/0h/0).
  5. Clé privée de scan du mainnet mainnet_scan(m/352h/0h/0h/1h/0).

La seed 2 permet de dériver :

  1. Clé privée de dépense de révocation revoke_spend (m/352h/1h/0h/0h/0).
  2. Clé privée de scan de révocation revoke_scan (m/352h/1h/0h/1h/0).

12.1. Récupération des jetons de faucet

Le relais retournent des jetons à la connexion et à l'envoi d'une Envelope afin de créer les UTXO nécessaires pour les transactions SP.

Pour revoir ces jetons l'User doit posséder une adresse silent payment.

A chaque nouveau message le relai génère de nouvelles addresses pour la clé fournie par l'utilisateur dans le champ faucet_sp_address des messages envoyés aux relais.

13. Gestion des clés du User

13.1. Génération des clés privées

13.1.1. Gestion de la clé spend_recover

La clé privée spend_recover est la clé principale qui définit un User sur le réseau 4nk.

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

Cette clé sera scindée en 2 parties de 128 bits (16B) dont une va être distribuée sur le réseau (sharding). Voici les principales étapes :

  1. part1_plaintext, qui sera stockée chiffrée en cache par l'utilisateur dans une image dite de login :
  • le mot de passe "hashé"
  • Génération de la clé utilisée pour le chiffrement de part1_plaintext :
    • récupération du mot de passe défini par l'utilisateur user_password (optionnel)
    • génération de 256 bits d'entropie entropy_1
    • Hash de user_password (si possible) | entropy_1 produit la clé aes_key_1
    • génération d'un nonce nonce_1
  • ajouté à l'une image de login
  1. part2_plaintext, qui sera répartie par un Shamir Secret Sharing, distribuée en 1 pour 1 aux membres actuels du rôle de gestionnaire des membres du ItemProcess :
  • le mot de passe "hashé"
  • part2_plaintext est chiffré exactement selon la même procédure que part1_plaintext pour produire part2_ciphertext
  • une seed de générée aléatoirement répartie par un Shamir Secret Sharing, chiffrée pour chaque partie par le mot de passe et distribuées en 1 pour 1 aux Members actuels du rôle de gestionnaire des Members.

Génération d'une pre-id qui identifie le User, générée par le hash (SHA 256) du mot de passe de l'utilisateur concaténé avec part1_ciphertext.

Il est très important de ne pas réutiliser le nonce avec des clés de chiffrement et des messages différents

Une pre-id qui identifie l'User est générée par le hash (SHA 256) d'un scrypt de la Part1 et du mot de passe de l'User.

Encryption speudo code :

part1_spend_recover_enc=aes(sha(scrypt((MDP+random_seed1), part1)
part2_spend_recover_enc_shards=sss(aes(SHA256'srcypt(MDP+random_seed2), part2), nMembers, 0.8)
imageLogin.addExif(part1_spend_recover_enc, random_seed1, random_seed2)
pre_id=sha256(part1_spend_recover_enc, MDP, random_seed)
  1. Création d'un PrdList par Member (1 shard par Member) par Prd cf [PRD-PCD](PRD-PCD-Specs.md PRD-PCD) :

13.1.2. Backup de Part2Enc

Les relais initialisent le SDK (Wasm) par défaut avec une liste ProcessList contenant Process choisi.

Les managers des Member du Process seront responsables d'associer un shard de Part2Enc à une pre-id lorsqu'ils en recoivent la demande via un PrdUserCreate.

Les managers des Member du Process seront responsables d'associer un shard de Part2Enc à une pre-id et de revoyer des les shards dans un PrdResponse en réponse au PrdUserRecover envoyé.

13.1.3. Onboarding

13.2. Member complété des champs du process

Le role Member de Process sélectionné contient un Item avec des metadata_contract_public, metadata_role_confidential et metadata_private contenant chacun une render_template_list dont le premier élément du tableau est le formulaire de création du User pour champs concernés (publiques ou confidentiels ou privés).

Ces formulaires permettront de créé les champs attendus par condition_attribute_encryption_list dans le role Member de Process sélectionné, dans Member de l'User (champs dans data des attribut metadata_contract_public, metadata_role_confidential et metadata_private correpsondants).

Une fois Member complété, il est ajouté à la liste des Members pour créer un nouveau Pcd envoyé pour mises à jours aux managers du rôle Member du Process sélectionné via un PrdUpdate.

13.3. Process complété de l'address SP de l'User et mise à jour de la liste des version du process

Pour le ou les roles sélectionnés, l'attribut request_prd_sp_address_list de condition_prd_address_set_list est complété par l'adresse SP de l'User.

Une fois Process complété, il est ajouté à la liste des Members pour créer un nouveau Pcd envoyé pour mises à jours aux managers du rôle Process du Process sélectionné via un PrdUpdate.

13.4. Réception des Pcd et PrdResponse en tenant compte des mises à jours

Envoi d'un PrdList pour chaque Member de chaque rôle du process sélectionné.

14. Clés de révocation (revoke)

Les clés de l'image de révocation sont chiffrées par le mot de passe et stockées directement dans les données exifs de l'image de révocation.

L'envoi d'une révocation est identique à la création d'une nouvelle adresse via les PrdList 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).

L'image ImageRevoke contient :

  • KeyRevokeSpend: clé privée de dépense du mainnet
  • KeyRevokeScan: clé privée de scan du mainnet

15. Clés de third parties

Au moment de l'update de Member il est possible de charger des addresses SP de third parties pour lesquelles l'User a un rôle dans un Process. Ces adresses sont ajoutées avec les labels et éventuellement les empreintes des dispositifs correspondants dans l'objet Member.

Les clés privées associées sont générées lors de l'update d'un Member, à 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.

16. Connexions avec un User (recover)

Pour recrééer sa clé privée et envoyer un PrdUserRecover à chaque Member du rôle Member du Process, il faut réaliser les opérations suivantes :

  1. Récupération de Part1Enc en cache
  2. Création de la pre_id avec le mot de passe
  3. Création de PrdUserRecover à destination des Member.
  4. Réception des PrdResponse des gestionnaires des Member avec les shards.
  5. Recomposition de la clé pour confirmation depuis les shards reçus dans les PrdResponse. 5.1. Déchiffrement par le mot de passe de Part1Enc depuis le cache. 5.2. Déchiffrement par secret partagé de chaque shard reçu dans id_shard_info_confidential des PrdResponse de chaque Member du Role Memberdu Process. 5.3. Recomposition de Part2Enc et déchiffrement par le mot de passe 5.4. Concaténation de Part1 et Part2
  6. Création de PrdList à destination de tous les Member du Process.
  7. Réception des flux PCD et PRDResponse des gestionnaires de chaque Role

17. Exemples de Code

18. Todo

  • Extraits de code illustrant l'utilisation des Pcd et Prd dans des scénarios réels.