sdk_common/doc/Auth-Specs.md
2024-04-14 20:12:58 +02:00

327 lines
22 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Auth - Specifications
## 1. <a name='Autheursvalidationsdatesversionschangementandhistorique'></a>Autheurs, validations, dates, versions, changement and historique
Cf. [Git SDK COMMON](https://git.4nk.com/4nk/sdk_common/doc)
## 2. <a name='Tabledesmatires'></a>Table des matières
<!-- vscode-markdown-toc -->
* 1. [Autheurs, validations, dates, versions, changement and historique](#Autheursvalidationsdatesversionschangementandhistorique)
* 2. [Table des matières](#Tabledesmatires)
* 3. [Objectif](#Objectif)
* 4. [Portée](#Porte)
* 5. [Documents de référence](#Documentsderfrence)
* 6. [Indication génériques](#Indicationgnriques)
* 7. [Schématisation des processus](#Schmatisationdesprocessus)
* 7.1. [Création d'un `User`](#CrationdunUser)
* 7.2. [Onboarding](#Onboarding)
* 7.3. [Connexion avec un `User` créée (`recover`)](#ConnexionavecunUsercrerecover)
* 7.4. [Extension de l'entropie du mot de passe (PBKDF2)](#ExtensiondelentropiedumotdepassePBKDF2)
* 7.5. [Chiffrement AES quantique résistant (AES-GCM-256)](#ChiffrementAESquantiquersistantAES-GCM-256)
* 7.6. [Génération des clés privées](#Gnrationdesclsprives)
* 8. [Authentification des `User`](#AuthentificationdesUser)
* 9. [Connexion via des tiers](#Connexionviadestiers)
* 10. [Fonctionnalité de récupération de mot de passe](#Fonctionnalitdercuprationdemotdepasse)
* 11. [Gestion de session basée sur un cache](#Gestiondesessionbasesuruncache)
* 12. [Principe de fonctionnement](#Principedefonctionnement)
* 13. [Wallet](#Wallet)
* 13.1. [Récupération des jetons de faucet](#Rcuprationdesjetonsdefaucet)
* 14. [Gestion des clés du `User`](#GestiondesclsduUser)
* 14.1. [Génération des clés privées](#Gnrationdesclsprives-1)
* 14.1.1. [Gestion de la clé `spend_recover`](#Gestiondelaclspend_recover)
* 14.1.2. [Backup de `Part2Enc`](#BackupdePart2Enc)
* 14.1.3. [Onboarding](#Onboarding-1)
* 14.2. [Member complété des champs du process](#Membercompltdeschampsduprocess)
* 14.3. [Process complété de l'address SP de l'`User` et mise à jour de la liste des version du process](#ProcesscompltdeladdressSPdelUseretmisejourdelalistedesversionduprocess)
* 14.4. [Réception des Pcd et PrdResponse en tenant compte des mises à jours](#RceptiondesPcdetPrdResponseentenantcomptedesmisesjours)
* 15. [Clés de révocation (`revoke`)](#Clsdervocationrevoke)
* 16. [Clés de third parties](#Clsdethirdparties)
* 17. [Connexions avec un `User` (`recover`)](#ConnexionsavecunUserrecover)
* 18. [Exemples de Code](#ExemplesdeCode)
* 19. [Todo](#Todo)
<!-- vscode-markdown-toc-config
numbering=true
autoSave=true
/vscode-markdown-toc-config -->
<!-- /vscode-markdown-toc -->
## 3. <a name='Objectif'></a>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](diagrams/Login-Wireframes.png "Wireframes")
## 4. <a name='Porte'></a>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. <a name='Documentsderfrence'></a>Documents de référence
Wireframes :
Voir [_Doc_references.md](_Doc_references.md).
## 6. <a name='Indicationgnriques'></a>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é dimplémentation et éviter les spécifiques).
## 7. <a name='Schmatisationdesprocessus'></a>Schématisation des processus
### 7.1. <a name='CrationdunUser'></a>Création d'un `User`
![WalletCreate](diagrams/WalletCreate.png "WalletCreate")
**Note**: Comme la liste des `Process`, cest une liste en cache fusioné avec les nouvelles liste reçues dans les enveloppes puis repartagé fusionné dans les enveloppes envoyées
### 7.2. <a name='Onboarding'></a>Onboarding
![WalletOnboard](diagrams/WalletOnboard.png "WalletOnboard")
**Note**: "Selected process" est le (ou les) process sélectionnés dans lIHM (pour la cas dune 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 dobjets, ici la listes des membres du process.
### 7.3. <a name='ConnexionavecunUsercrerecover'></a>Connexion avec un `User` créée (`recover`)
![WalletRecover](diagrams/WalletRecover.png "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`
* `SpAddressRecover`: adresse SP de l'`User`
### 7.4. <a name='ExtensiondelentropiedumotdepassePBKDF2'></a>Extension de l'entropie du mot de passe (PBKDF2)
![PBKDF2](diagrams/PBKDF2.png "PBKDF2")
### 7.5. <a name='ChiffrementAESquantiquersistantAES-GCM-256'></a>Chiffrement AES quantique résistant (AES-GCM-256)
![AES-GCM-256](diagrams/AES-GCM-256.png "AES-GCM-256")
### 7.6. <a name='Gnrationdesclsprives'></a>Génération des clés privées
![KeyGen](diagrams/KeyGen.png "KeyGen")
## 8. <a name='AuthentificationdesUser'></a>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)](#ChiffrementAESquantiquersistantAES-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 une`adresse 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`).
## 9. <a name='Connexionviadestiers'></a>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.
## 10. <a name='Fonctionnalitdercuprationdemotdepasse'></a>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`.
## 11. <a name='Gestiondesessionbasesuruncache'></a>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.
## 12. <a name='Principedefonctionnement'></a>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 sarrêter à la création du `User` mais ce serait un peut étrange dans lexpérience car personne na besoin de créer un `User` sans aller sur `Process`.
## 13. <a name='Wallet'></a>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](https://en.bitcoin.it/wiki/BIP_0044)).
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`).
### 13.1. <a name='Rcuprationdesjetonsdefaucet'></a>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.
## 14. <a name='GestiondesclsduUser'></a>Gestion des clés du `User`
### 14.1. <a name='Gnrationdesclsprives-1'></a>Génération des clés privées
#### 14.1.1. <a name='Gestiondelaclspend_recover'></a>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
2. `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 :
```pseudo-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)
```
2. Création d'un `PrdList` par `Member` (1 shard par Member) par `Prd` cf [PRD-PCD](PRD-PCD-Specs.md PRD-PCD) :
#### 14.1.2. <a name='BackupdePart2Enc'></a>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é.
#### 14.1.3. <a name='Onboarding-1'></a>Onboarding
### 14.2. <a name='Membercompltdeschampsduprocess'></a>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`.
### 14.3. <a name='ProcesscompltdeladdressSPdelUseretmisejourdelalistedesversionduprocess'></a>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`.
### 14.4. <a name='RceptiondesPcdetPrdResponseentenantcomptedesmisesjours'></a>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é.
## 15. <a name='Clsdervocationrevoke'></a>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
## 16. <a name='Clsdethirdparties'></a>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.
## 17. <a name='ConnexionsavecunUserrecover'></a>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` `Member`du `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`
## 18. <a name='ExemplesdeCode'></a>Exemples de Code
## 19. <a name='Todo'></a>Todo
* [ ] Extraits de code illustrant l'utilisation des `Pcd` et `Prd` dans des scénarios réels.