4nk/sdk_common
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

updates (doc)

Browse Source
This commit is contained in:
NicolasCantu 2024-03-20 12:44:31 +01:00
parent c00390822f
commit 7a1550811b
3 changed files with 75 additions and 204 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
doc/Auth-Specs.md
View File

@ -1,4 +1,5 @@
<!-- vscode-markdown-toc -->
* 1. [Objectif](#Objectif)
* 2. [Portée](#Porte)
* 3. [Documents de référence](#Documentsderfrence)
@ -30,6 +31,7 @@
numbering=true
autoSave=true
/vscode-markdown-toc-config -->
<!-- /vscode-markdown-toc --># Auth - Specs
## 1. <a name='Objectif'></a>Objectif
@ -218,10 +220,10 @@ Dans l'ordre on réalise donc les opérations suivantes pour chaque membres :
4. Envoi du `Message` du `RequestPrdList` à destination du membre.
5. Atttente de la réception des `RequestPrdResponse` en réponse aux `RequestPrdList` (confirmations).
6. Recomposition de la clé pour confirmation depuis les shards reçus dans les `RequestPrdResponse`.
6.1. Déchiffrement par le mot de passe de `Part1Enc` depuis le cache.
6.2. Déchiffrement par secret partagé de chaque shard reçu dans `id_shard_info_enc_by_shared_secret` des `RequestPrdResponse` de chaque member du `Role` `Member`du `ItemProcess`.
6.3. Recomposition de `Part2Enc` et déchiffrement par le mot de passe
6.4. Concaténation de `Part1` et `Part2`
6.1. Déchiffrement par le mot de passe de `Part1Enc` depuis le cache.
6.2. Déchiffrement par secret partagé de chaque shard reçu dans `id_shard_info_enc_by_shared_secret` des `RequestPrdResponse` de chaque member du `Role` `Member`du `ItemProcess`.
6.3. Recomposition de `Part2Enc` et déchiffrement par le mot de passe
6.4. Concaténation de `Part1` et `Part2`
#### 10.1.3. <a name='Onboarding-1'></a>Onboarding
@ -272,10 +274,10 @@ Puis depuis la liste des membres du process, pour chacun des membres :
4. Envoi du `Message` du `RequestPrdList` à destination du membre.
5. Attente de la validation (`RequestPrdResponse`) du `RequestPrdUpdate`.
6. Recomposition de la clé pour confirmation depuis les shards reçus dans les `RequestPrdResponse`.
6.1. Déchiffrement par le mot de passe de `Part1Enc` depuis le cache.
6.2. Déchiffrement par secret partagé de chaque shard reçu dans `id_shard_info_enc_by_shared_secret` des `RequestPrdResponse` de chaque member du `Role` `Member`du `ItemProcess`.
6.3. Recomposition de `Part2Enc` et déchiffrement par le mot de passe
6.4. Concaténation de `Part1` et `Part2`
6.1. Déchiffrement par le mot de passe de `Part1Enc` depuis le cache.
6.2. Déchiffrement par secret partagé de chaque shard reçu dans `id_shard_info_enc_by_shared_secret` des `RequestPrdResponse` de chaque member du `Role` `Member`du `ItemProcess`.
6.3. Recomposition de `Part2Enc` et déchiffrement par le mot de passe
6.4. Concaténation de `Part1` et `Part2`
7. Réception des flux PCD et PRDResponse des gestionnaires des membres
## 14. <a name='ExemplesdeCode'></a>Exemples de Code

156
doc/PRD-PCD-Specs.md
View File

@ -1,4 +1,5 @@
<!-- vscode-markdown-toc -->
* 1. [Objectif](#Objectif)
* 2. [Portée](#Porte)
* 3. [Documents de référence](#Documentsderfrence)
@ -60,6 +61,7 @@ Voir [_Doc_references.md](_Doc_references.md).
* **Portable Contract Document (`RequestPcd`)**: Un format `JSON` chiffré conçu pour contenir des listes d'éléments d'un type spécifique, attachées à un processus (`process_hash`) et soumises aux règles de validation décrites dans le rôle correspondant à ce type d'`Item` dans le `ItemProcess` (`item_type`).
* **Portable Request Document (`RequestPrd`)**: Format `JSON` chiffré contenant les valeurs de signatures et les clés de déchiffrement nécessaires à l'exploitation (requêtes et validation) des `RequestPcd`. Les `RequestPrdResponse` sont collectés pour vérifier le respect des conditions de l'`ItemProcess`. D'autres types de `RequestPrd` incluent :
* `RequestPrdList`: Demande de listes d'`Item`. En réponse, une `RequestPcd` est reçue avec les `RequestPrdResponse` correspondants.
* `RequestPrdMessage`: Envoi de messages publics, confidentiels ou privés et/ou de transactions Silent Payments des autres `RequestPrd` à diffuser sur le réseau des nœuds de la side chain. Les `RequestPrdMessage` peuvent répondre les uns aux autres.
* `RequestPrdUpdate`: Demande de mise à jour d'une liste d'`Item` (publiée via un `RequestPCD`), qui sera déchiffrée et validée ou non par des `RequestPrdResponse` en retour.
@ -118,7 +120,7 @@ Les traitements pour l'envoi des `RequestPrd` varient selon leur type, principal
Ce qui est résumé pour l'envoi :
| `request_type` | Notification user | `transaction SP` + `RequestPrdMessage` | `RequestPcd` to send | `request_type` send to | `RequestPcd` reply waiting | `RequestPrdResponse` reply waiting | `RequestPrdConfirm` reply waiting |
|----------------------|-----------------------------------------------------------------------------------|----------------------------------------|----------------------|-----------------------------------------------------------------|----------------------------|------------------------------------|-----------------------------------|
| -------------------- | --------------------------------------------------------------------------------- | -------------------------------------- | -------------------- | --------------------------------------------------------------- | -------------------------- | ---------------------------------- | --------------------------------- |
| `RequestPrdList` | No | Yes | No | all the members of the `item_name` `Role` into to `ItemProcess` | Yes | Yes | Yes |
| `RequestPrdUpdate` | waiting `sig_value` | Yes | Yes | all the members of all `Role` into to `ItemProcess` | No | Yes | Yes |
| `RequestPrdMessage` | waiting `sig_value` + `message_public`, `message_confidential`, `message_private` | if no `raw_transaction_list` | No | a member of the `ItemProcess` | No | No | if no `raw_transaction_list` |
@ -136,7 +138,7 @@ Les traitements pour la réception des `RequestPrd` varient selon leur type, pri
Ce qui est résumé Pour la réception :
| `request_type` | Notification user | `RequestPrdConfirm` to send | `RequestPcd` to send | `RequestPrdResponse` to send | `RequestPrdResponse` reply waiting | `RequestPrdConfirm` reply waiting (from `RequestPrdResponse` send ) |
|----------------------|-----------------------------------|------------------------------|----------------------|-----------------------------------------------------------------|------------------------------------|---------------------------------------------------------------------|
| -------------------- | --------------------------------- | ---------------------------- | -------------------- | --------------------------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------- |
| `RequestPrdList` | No | Yes | Yes | all the members of the `item_name` `Role` into to `ItemProcess` | No | Yes |
| `RequestPrdUpdate` | Info | Yes | No | all the members of all `Role` into to `ItemProcess` | Yes (other members) | Yes |
| `RequestPrdMessage` | Waiting `RequestPrdMessage` reply | if no `raw_transaction_list` | No | No | No | No |
@ -159,18 +161,6 @@ Les `Metadata` des `Item` des `RequestPcd` et les attributs des `RequestPcd` et
* **Données privées** : Chiffrées symétriquement en utilisant la clé de dépense de connexion (`recover`) du signet (voir Login - Specs).
Principaux champs des `Request` contenus dans les `RequestPcd` et `RequestPrd` chiffrés :
* **`request_type`** : Type de requête : `RequestPcd`, `RequestPrdList`, `RequestPrdMessage`, `RequestPrdUpdate`, `RequestPrdConfirm`, `RequestPrdResponse`.
* **`item_name`** : Noms des items : `peer`, `member`, `process`, `payment`, `deposit`, `commitment`, et les `artefact` personnalisés.
* **`version`** : Version de la requête.
* **`process_hash`** : Hash de l'`ItemProcess` concerné.
* **`request_pcd_reference_hash`** : Hash du `RequestPcd` auquel le `RequestPrd` fait référence.
* **`request_pcd_origin_hash`** : Hash du `RequestPcd` à l'origine du `RequestPrd`.
* **`request_prd_reference_hash`** : Hash du `RequestPrd` auquel le `RequestPrd` fait référence.
* **`request_prd_origin_hash`** : Hash du `RequestPrd` à l'origine du `RequestPrd`.
* **`item_reference_hash`** : Hash de l'`Item` auquel le `RequestPcd` fait référence.
### 6.1. <a name='Crationetenvoi'></a>Création et envoi
Les `RequestPcd` et les `RequestPrd` sont envoyés sous forme de messages (`JSON`) via les `websockets` des relais.
@ -205,49 +195,6 @@ Les Portable Contract Documents (`RequestPcd`) sont des documents au format `JSO
Les `Item` échangés via les `RequestPcd` sont soumis à une vérification par les `RequestPrdResponse` dans le but de contrôler la validité de ces données et leur conformité avec les `ItemProcess` et les `member` du `Role` concerné.
Principaux champs des `RequestPcd` :
* **`request`** : cf la descripton de la structure `Request`.
* **`item_enc_list`** : Les `Item` chiffrés par une clé symétrique générée à la volée pour chaque champ et pour chaque item d'une liste.
* **`pagination`** : La pagination de la liste des `Item`.
Principaux champs de la structure `Pagination` :
* **`start`** : Index du premier `Item` de la liste.
* **`number`** : Nombre d'`Item` à afficher.
* **`page_index`** : Index de la page.
* **`page_total`** : Nombre total de pages.
Principaux champs de la structure `RequestPcdItemGenericEnc` :
* **`version`** : Version de l'`Item`.
* **`item_type`** : Type de l'`Item`.
* **`name`** : Nom de l'`Item`.
* **`request_pcd_item_enc_attribute_public_list`** : Liste d'objets `RequestPcdItemEncAttributePublic` des attributs publics de l'`Item` chiffré.
* **`request_pcd_item_enc_attribute_role_confidential_list`** : Liste d'objets `RequestPcdItemEncAttributeRoleConfidential` des attributs confidentiels de l'`Item` chiffré.
* **`request_pcd_item_enc_attribute_private_list`** : Liste d'objets `RequestPcdItemEncAttributePrivate` des attributs privés de l'`Item` chiffré.
Principaux champs de la structure `RequestPcdItemEncAttributePublic` :
* **`attribute_name`** : Nom de l'attribut.
* **`data_enc`** : Données chiffrées par la clé `ProcessKey` de l'`ItemProcess` concerné.
* **`key`** : [PRIVE] Clé de chiffrement, non partagée dans les messages. Données en clair.
* **`data`** : [PRIVE] Non partagé dans les messages. Données en clair.
Principaux champs de la structure `RequestPcdItemEncAttributeRoleConfidential` :
* **`attribute_name`** : Nom de l'attribut.
* **`data_enc`** : Données chiffrées par une clé symétrique générée à la volée pour chaque champ et pour chaque item d'une liste.
* **`key`** : [PRIVE] Clé de chiffrement, non partagée dans les messages. Données en clair.
* **`data`** : [PRIVE] Non partagé dans les messages. Données en clair.
Principaux champs de la structure `RequestPcdItemEncAttributePrivate` :
* **`attribute_name`** : Nom de l'attribut.
* **`data_enc`** : Données chiffrées par la clé privée `KeyRecover`.
* **`key`** : [PRIVE] Clé de chiffrement, non partagée dans les messages. Données en clair.
* **`data`** : [PRIVE] Non partagé dans les messages. Données en clair.
### 7.1. <a name='Schmadesflux'></a>Schéma des flux
![RequestPcd](diagrams/PCD.png "RequestPcd")
@ -281,34 +228,6 @@ Les clés permettant le chiffrement des attributs confidentiels par rôles des `
Les `RequestPrd` se déclinent en plusieurs types, tels que `RequestPrdList`, `RequestPrdMessage`, `RequestPrdUpdate`, etc., correspondant à différentes actions comme l'envoi de messages, la mise à jour des informations contractuelles, ou la confirmation de transactions.
Principaux champs des `RequestPcd` :
* **`request`** : cf la descripton de la structure `Request`.
* **`sig_value`** : Valeur de la signature (parmi les valeurs valant pour `OK`, `KO` ou `none` telles que définies dans l'`ItemProcess`).
* **`request_pcd_reference_keys_role_confidential_list_enc_by_shared_secret`** : Clés de déchiffrement des attributs confidentiels des `Item` des `RequestPcd` chiffrées par la clé `KeyConfidential` d'une `transaction SP`.
* **`request_pcd_origin_hash_keys_role_confidential_list_enc_by_shared_secret`** : Clés de déchiffrement des attributs confidentiels des `Item` des `RequestPcd` du `RequestPCD` de référence, chiffrées par la clé `KeyConfidential` d'une `transaction SP`.
* **`message_public`** : Message public, chiffré par la clé `ProcessKey` du `ItemProcess` concerné.
* **`message_confidential`** : Message confidentiel, chiffré par la clé `ProcessKey` du `ItemProcess` concerné.
* **`message_private`** : Message privé, chiffré par la clé privée `KeyRecover`.
* **`sp_address_to`** : Adresse du destinataire.
* **`sp_address_from`** : Adresse de l'émetteur.
* **`sp_address_reply`** : Adresse de réponse à l'émetteur.
* **`timestamp_declared`** : Horodatage déclaré.
* **`role_name_from`** : Nom du rôle de l'émetteur.
* **`role_name_to`** : Nom du rôle du destinataire.
* **`payment_request_pcd_hash_list_enc_by_shared_secret`** : Liste des `RequestPcd` d'`Item` de nom `paiement` chiffrée par la clé `KeyConfidential` d'une `transaction SP`.
* **`cap_request_pcd_hash_list_enc_by_shared_secret`** : Liste des `RequestPcd` d'`Item` de nom `deposit` chiffrée par la clé `KeyConfidential` d'une `transaction SP` servant à la validation des paiements temporaires en attente du passage d'un cap.
* **`deposit_request_pcd_hash_list_enc_by_shared_secret`** : Liste des `RequestPcd` d'`Item` de nom `deposit` chiffrée par la clé `KeyConfidential` d'une `transaction SP`.
* **`commitment_request_pcd_hash_list_enc_by_shared_secret`** : Liste des `RequestPcd` d'`Item` de nom `commitment` chiffrée par la clé `KeyConfidential` d'une `transaction SP`.
* **`ask_payment_method_enc_by_shared_secret`** : Demande de méthode de paiement chiffrée par la clé `KeyConfidential` d'une `transaction SP`.
* **`ask_deposit_method_enc_by_shared_secret`** : Demande de méthode de dépôt chiffrée par la clé `KeyConfidential` d'une `transaction SP`.
* **`ask_commitment_method_enc_by_shared_secret`** : Demande de méthode d'engagement chiffrée par la clé `KeyConfidential` d'une `transaction SP`.
* **`payment_method_enc_by_shared_secret`** : Méthode de paiement chiffrée par la clé `KeyConfidential` d'une `transaction SP`, en réponse à une demande.
* **`deposit_method_enc_by_shared_secret`** : Méthode de dépôt chiffrée par la clé `KeyConfidential` d'une `transaction SP`, en réponse à une demande.
* **`commitment_method_enc_by_shared_secret`** : Méthode d'engagement chiffrée par la clé `KeyConfidential` d'une `transaction SP`, en réponse à une demande.
* **`certif_key_enc_by_shared_secret`** : Clé de certification chiffrée par la clé `KeyConfidential` d'une `transaction SP`.
* **`device_footprint_enc_by_sp_shared_secret`** : Empreinte du dispositif de l'émetteur, chiffrée par la clé `KeyConfidential` d'une `transaction SP`.
### 8.1. <a name='Schmadesflux-1'></a>Schéma des flux
Pour simplifier, les `RequestPrdConfirm` n'ont pas été inclus dans le schéma.
@ -381,39 +300,6 @@ Workflow:
![PRDListFlows](diagrams/PRDListFlows.png "PRDListFlows")
Principaux champs des `RequestPrdList` :
* **`request_prd`** : cf la descripton de la structure `RequestPrd`.
Dans le cas d'une création de compte :
* **`item_member_enc_by_sp_shared_secret`** : Nouvel `ItemMember` temporaire,chiffrée par la clé `KeyConfidential` d'une `transaction SP`.
L'`ItemMember` temporaire contient les métadonnées de type `Metadata` suivantes :
* **`MetadataProcessPublic` de type `ItemMemberPublicAttributeGroup`** :
* **`sp_address_public`** : Adresse publique de l'utilisateur, chiffré par la `ProcessKey` de l'`ItemProcess`.
* **`sp_address_public_sig`** : Signature de l'adresse publique de l'utilisateur par la clé `recover`, chiffré par la `ProcessKey` de l'`ItemProcess`.
* **`sp_address_revoke_public`** : Adresse publique de révocation de l'utilisateur, chiffré par la `ProcessKey` de l'`ItemProcess`.
* **`sp_address_revoke_public_sig`** : Signature de l'adresse publique de révocation de l'utilisateur par la clé de spend de `revoke`, chiffré par la `ProcessKey` de l'`ItemProcess`.
* **`third_sp_address_list_public`** : Liste des adresses publiques de devices tiers, chiffré par la `ProcessKey` de l'`ItemProcess`.
* **`data_size_max`** : Taille maximale des données acceptée par l'utilisateur (par flux), chiffré par la `ProcessKey` de l'`ItemProcess`.
* **`payment_method_list_public`** : Liste des méthodes de paiement acceptées par l'utilisateur, chiffré par la `ProcessKey` de l'`ItemProcess`.
* **`succession_process_hash`** : Hash du processus de succession de l'utilisateur (transmission de l'identité numérique et donc de tous les flux associés), chiffré par la `ProcessKey` de l'`ItemProcess`.
* **`device_footprint`** : Empreinte du dispositif de l'utilisateur, chiffré par la `ProcessKey` de l'`ItemProcess`.
* **`MetadataRoleConfidential` de type `ItemMemberRoleConfidentialAttributeGroup`** :
* **`shard_confidential`** : Shard de l'utilisateur, chiffré par la clé `KeyConfidential` d'une `transaction SP`.
* **`pre_id_confidential`** : Pré empreinte de l'identité numérique de l'utilisateur, chiffrée par la clé `KeyConfidential` d'une `transaction SP`.
* **`MetadataPrivate` de type `ItemMemberRolePrivateAttributeGroup`** :
* **`priv_key_mainnet_spend`** : Clé de dépense de l'utilisateur, chiffrée par la clé privée du mainnet, chiffrée par `KeyRecover`.
* **`priv_key_mainnet_scan`** : Clé de scan de l'utilisateur, chiffrée par la clé privée du mainnet, chiffrée par `KeyRecover`.
* **`priv_key_signet_scan`** : Clé de scan du signet de `recover`de l'utilisateur, chiffrée `KeyRecover`.
### 9.1. <a name='Schmadesflux-1'></a>Schéma des flux
Pour simplifier, les `RequestPrdConfirm` n'ont pas été inclus dans le schéma.
@ -449,11 +335,6 @@ Les `RequestPrdMessage` peuvent répondre aux autres `RequestPrdMessage`, sauf e
Workflow :
![PRDMessageFlows](diagrams/PRDMessageFlows.png "PRDMessageFlows")
Principaux champs des `RequestPrdMessage` :
* **`request_prd`** : cf la descripton de la structure `RequestPrd`.
* **`raw_transaction_list`** : Liste des `transaction SP` au format `raw` pour la publication de la transaction dans la side chain.
### 10.1. <a name='Schmadesflux-1'></a>Schéma des flux
Pour simplifier, les `RequestPrdConfirm` n'ont pas été inclus dans le schéma. Exemple d'un `RequestPrdMessage` avec `raw_transaction_list` vide, et son cas correspondant où le `RequestPrdMessage` contient une `raw_transaction_list` non vide.
@ -485,10 +366,6 @@ Workflow:
![PRDUpdateFlows](diagrams/PRDUpdateFlows.png "PRDUpdateFlows")
Principaux champs des `RequestPrdUpdate` :
* **`request_prd`** : cf la descripton de la structure `RequestPrd`.
### 11.1. <a name='Schmadesflux-1'></a>Schéma des flux
Pour simplifier, les `RequestPrdConfirm` n'ont pas été représentés dans le schéma.
@ -519,11 +396,6 @@ Worflow:
Voir les diagrammes `PRDUpdateFlows`, `PRDUpdateFlows` et `PRDMessageFlows`.
Principaux champs des `RequestPrdConfirm` :
* **`request_prd`** : cf la descripton de la structure `RequestPrd`.
* **`code_confirm_enc_by_shared_secret`** : Code de confirmation chiffré par la clé `KeyConfidential` d'une `transaction SP` dans le cas d'un 2FA.
### 12.1. <a name='Schmadesflux-1'></a>Schéma des flux
![RequestPrdConfirm](diagrams/PRDConfirm.png "RequestPrdConfirm")
@ -550,12 +422,6 @@ Workflow:
Voir les diagrammes `PRDUpdateFlows` et `PRDUpdateFlows`.
Principaux champs des `RequestPrdResponse` :
* **`request_prd`** : cf la descripton de la structure `RequestPrd`.
* **`shared_secret_key_enc_by_sp_shared_secret`** : Clé de chiffrement partagée chiffrée par la clé `KeyConfidential` d'une `transaction SP`.
* **`shard_enc_by_sp_shared_secret`** : Shard chiffré par la clé `KeyConfidential` d'une `transaction SP`.
### 13.1. <a name='Schmadesflux-1'></a>Schéma des flux
Pour simplifier, les `RequestPrdConfirm` n'ont pas été représentés dans le schéma.
@ -580,11 +446,11 @@ Pour simplifier, les `RequestPrdConfirm` n'ont pas été représentés dans le s
## 15. <a name='Todo'></a>Todo
[ ] Description détaillée de tous les éléments (attributs) qui composent le ‘request-type’:
[x] Qu’y a-t-il dans le ‘request-type’?
[x] A quoi sert l’attribut X du ‘request-type’?
[x] Description un par un des contextes où le ‘request-type’ est utilisé.
[x] Description pas à pas de l’envoi du ‘request-type’.
[ ] Qu’y a-t-il dans le ‘request-type’?
[ ] A quoi sert l’attribut X du ‘request-type’?
[ ] Description un par un des contextes où le ‘request-type’ est utilisé.
[ ] Description pas à pas de l’envoi du ‘request-type’.
[ ] Que se passe-t-il dans le système lorsque le ‘request-type est envoyé?
[x] Description pas à pas de la réception du ‘request-type’.
[x] Que se passe-t-il dans le système lorsque le ‘request-type est reçu?
[x] Exemple d’utilisation.
[ ] Description pas à pas de la réception du ‘request-type’.
[ ] Que se passe-t-il dans le système lorsque le ‘request-type est reçu?
[ ] Exemple d’utilisation.

5
doc/_Doc_references.md
View File

@ -1,4 +1,5 @@
<!-- vscode-markdown-toc -->
* 1. [Worfklows](#Worfklows)
* 2. [Transverse](#Transverse)
* 3. [Diagrammes d'architecture](#Diagrammesdarchitecture)
@ -8,7 +9,9 @@
numbering=true
autoSave=true
/vscode-markdown-toc-config -->
<!-- /vscode-markdown-toc -->
# <a name='Documentsderfrence'></a>Documents de référence
## 1. <a name='Worfklows'></a>Worfklows
@ -32,6 +35,6 @@
## 3. <a name='Diagrammesdarchitecture'></a>Diagrammes d'architecture
* **Diagramme d'architecture montrant les composants principaux du système de login.**
[SheatSheet 4NK](https://cryptpad.fr/diagram/#/2/diagram/view/3UG+7ccutUvJlwJ1-bR40RhgOA+rb5eEmw42wtkN19A)
[SheatSheet 4NK](https://cryptpad.fr/diagram/#/2/diagram/view/3UG+7ccutUvJlwJ1-bR40RhgOA+rb5eEmw42wtkN19A)
## 4. <a name='Todo'></a>Todo