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

table for request created / received

Browse Source
This commit is contained in:
NicolasCantu 2024-02-17 22:31:51 +01:00
parent b3e5e081e6
commit 97a5b11ce6
1 changed files with 81 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -3,36 +3,36 @@
* 2. [Portée](#Porte)
* 3. [3. Documents de référence](#Documentsderfrence)
* 4. [Commun aux `RequestPcd` et RequestPrd](#CommunauxRequestPcdetRequestPrd)
* 4.1. [Création et envoi](#Crationetenvoi)
* 4.2. [Réception](#Rception)
* 4.1. [Création et envoi](#Crationetenvoi)
* 4.2. [Réception](#Rception)
* 5. [Fonction des RequestPcd](#FonctiondesRequestPcd)
* 5.1. [Création et envoi](#Crationetenvoi-1)
* 5.2. [Réception](#Rception-1)
* 5.1. [Création et envoi](#Crationetenvoi-1)
* 5.2. [Réception](#Rception-1)
* 6. [Fonction des RequestPrd](#FonctiondesRequestPrd)
* 6.1. [Fonctionnalités optionnelles](#Fonctionnalitsoptionnelles)
* 6.2. [Création et envoi](#Crationetenvoi-1)
* 6.3. [Réception](#Rception-1)
* 6.1. [Fonctionnalités optionnelles](#Fonctionnalitsoptionnelles)
* 6.2. [Création et envoi](#Crationetenvoi-1)
* 6.3. [Réception](#Rception-1)
* 7. [RequestPrdList - Demande de Listes ( RequestPcd)](#RequestPrdList-DemandedeListesRequestPcd)
* 7.1. [Création et envoi](#Crationetenvoi-1)
* 7.2. [Réception](#Rception-1)
* 7.1. [Création et envoi](#Crationetenvoi-1)
* 7.2. [Réception](#Rception-1)
* 8. [RequestPrdMessage - Envoi de Messages](#RequestPrdMessage-EnvoideMessages)
* 8.1. [Création et envoi](#Crationetenvoi-1)
* 8.2. [Réception](#Rception-1)
* 8.1. [Création et envoi](#Crationetenvoi-1)
* 8.2. [Réception](#Rception-1)
* 9. [RequestPrdUpdate - Mises à Jour de RequestPcd](#RequestPrdUpdate-MisesJourdeRequestPcd)
* 9.1. [Création et envoi](#Crationetenvoi-1)
* 9.2. [Réception](#Rception-1)
* 9.1. [Création et envoi](#Crationetenvoi-1)
* 9.2. [Réception](#Rception-1)
* 10. [RequestPrdConfirm - Confirmation de Réception](#RequestPrdConfirm-ConfirmationdeRception)
* 10.1. [Création et envoi](#Crationetenvoi-1)
* 10.2. [Réception](#Rception-1)
* 10.1. [Création et envoi](#Crationetenvoi-1)
* 10.2. [Réception](#Rception-1)
* 11. [RequestPrdResponse - Répondre à une Demande](#RequestPrdResponse-RpondreuneDemande)
* 11.1. [Création et envoi](#Crationetenvoi-1)
* 11.2. [Réception](#Rception-1)
* 11.1. [Création et envoi](#Crationetenvoi-1)
* 11.2. [Réception](#Rception-1)
* 12. [RequestPrdKeyBakcup](#RequestPrdKeyBakcup)
* 12.1. [Création et envoi](#Crationetenvoi-1)
* 12.2. [Réception](#Rception-1)
* 12.1. [Création et envoi](#Crationetenvoi-1)
* 12.2. [Réception](#Rception-1)
* 13. [RequestPrdKeyHello - Échange de Clés et d'Identités](#RequestPrdKeyHello-changedeClsetdIdentits)
* 13.1. [Création et envoi](#Crationetenvoi-1)
* 13.2. [Réception](#Rception-1)
* 13.1. [Création et envoi](#Crationetenvoi-1)
* 13.2. [Réception](#Rception-1)
* 14. [Exemples de Code](#ExemplesdeCode)
* 15. [Todo](#Todo)
@ -42,21 +42,21 @@
/vscode-markdown-toc-config -->
<!-- /vscode-markdown-toc --># `RequestPrd` et `RequestPcd` - Specs
## 1. <a name='Objectif'></a>Objectif
## 1. <a name='Objectif'></a>Objectif
Le but de cette section est d'introduire les Portable Contract Document (`RequestPcd`) et Portable Request Document (`RequestPrd`) comme éléments fondamentaux du système 4NK. Ces documents jouent un rôle crucial dans la sécurisation des échanges de données et la gestion des identités numériques au sein d'un réseau décentralisé. Ils permettent de définir des contrats numériques, de gérer les permissions d'accès, et de faciliter les communications et les opéraations sécurisées entre les différents acteurs du réseau.
## 2. <a name='Porte'></a>Portée
## 2. <a name='Porte'></a>Portée
La spécification couvre la conception, le développement, et l'application pratique des `RequestPcd` et `RequestPrd`.Elle vise à expliquer leur fonctionnement, leur structure, et la manière dont ils contribuent à l'écosystème 4NK en offrant une méthode sécurisée et efficace pour le partage d'informations et la validation des transactions. Les `RequestPcd` et `RequestPrd` encapsulent les données contractuelles et les requêtes dans un format standardisé, assurant l'intégrité, la confidentialité, l'authenticité et la validation des informations échangées.
## 3. <a name='Documentsderfrence'></a>3. Documents de référence
## 3. <a name='Documentsderfrence'></a>3. Documents de référence
Voir [_Doc_references.md](_Doc_references.md).
## 4. <a name='CommunauxRequestPcdetRequestPrd'></a>Commun aux `RequestPcd` et RequestPrd
## 4. <a name='CommunauxRequestPcdetRequestPrd'></a>Commun aux `RequestPcd` et RequestPrd
### 4.1. <a name='Crationetenvoi'></a>Création et envoi
### 4.1. <a name='Crationetenvoi'></a>Création et envoi
Les `RequestPcd` et les `RequestPrd` sont envoyés sous forme de `message` (JSON) depuis les websockets des relais.
@ -64,7 +64,17 @@ Les messages contiennent des `RequestPrd` ou des `RequestPcd` encapsulés dans l
**Création du message et envoi**: voir [Message-SP-Specs.md](Message-SP-Specs.md).
### 4.2. <a name='Rception'></a>Réception
| `request_type` | transaction SP | RequestPcd to send | send to | RequestPcd waiting | RequestPrdResponse waiting |
|-----------------------|------------------------------|--------------------|---------------------------------------------------------------|--------------------|----------------------------|
| `RequestPrdList` | Yes | No | all the members of the `item_name` role into to `ItemProcess` | Yes | Yes |
| `RequestPrdUpdate` | Yes | Yes | all the members of all role into to `ItemProcess` | No | Yes |
| `RequestPrdMessage` | if no `raw_transaction_list` | No | a member of the `ItemProcess` | No | No |
| `RequestPrdResponse` | Yes | No | See Received | No | No |
| `RequestPrdConfirm` | Yes | No | See Received | No | No |
| `RequestPrdKeyBackup` | No | No | all the members of the `SharedProcess` | No | Yes |
| `RequestPrdKeyHello` | Yes | No | all the members of all role into to `ItemProcess` | Yes | Yes |
### 4.2. <a name='Rception'></a>Réception
Les `RequestPcd` et les `RequestPrd` sont reçus sous forme de `message` (JSON) depuis les websockets des relais.
@ -78,17 +88,27 @@ Les types `RequestPrd` et `RequestPcd` sont distingués par l'attribut `request_
En cas de `RequestPcd` ou `RequestPrd` en relation via `RequestPcd_reference_hash` ou `request_prd_reference_hash` ou `RequestPcd_origin_hash` ou `request_prd_origin_hash` ou `item_reference_hash` (dans des RequestPcd), il avoir reçu ou attendre ces documents pour traiter le message.
| `request_type` | RequestPrdConfirm | RequestPcd to send | RequestPrdResponse to send |
|-----------------------|------------------------------|--------------------|---------------------------------------------------------------|
| `RequestPrdList` | Yes | Yes | all the members of the `item_name` role into to `ItemProcess` |
| `RequestPrdUpdate` | Yes | Yes | all the members of all role into to `ItemProcess` |
| `RequestPrdMessage` | if no `raw_transaction_list` | No | a member or reply |
| `RequestPrdResponse` | Yes | No | No |
| `RequestPrdConfirm` | No | No | No |
| `RequestPrdKeyBackup` | No | No | reply |
| `RequestPrdKeyHello` | Yes | Yes | reply |
**Réception du message**: voir [Message-SP-Specs.md](Message-SP-Specs.md).
Pour les `RequestPcd` et les `RequestPrd` il faut vérifier que le hash du document n'est pas déjà en cas, si c'est le cas, le message est ignoré.
## 5. <a name='FonctiondesRequestPcd'></a>Fonction des RequestPcd
## 5. <a name='FonctiondesRequestPcd'></a>Fonction des RequestPcd
Les Portable Contract Documents ( RequestPcd) sont des documents JSON qui encapsulent les listes versionnées d'`Item` dont les attributs sont chiffrés soit en public, soit en confidentiel par rôles soit en privé (cf. [Specs-Security.md](Specs-Security.md)).
Les `Item` ainsi échangés via les `RequestPcd` sont vérifiés par les `RequestPrdResponse` afin de vérifier les validations de ces données et leurs conformités avec les `ItemProcess` et les `members` concernés.
### 5.1. <a name='Crationetenvoi-1'></a>Création et envoi
### 5.1. <a name='Crationetenvoi-1'></a>Création et envoi
La création d'un `RequestPcd` suit plusieurs étapes :
@ -98,7 +118,7 @@ La création d'un `RequestPcd` suit plusieurs étapes :
4. Chiffrement du `RequestPcd` avec la clé `ProcessKey` du `ItemProcess` concerné.
5. Traitements communs aux `RequestPcd` et RequestPrd
### 5.2. <a name='Rception-1'></a>Réception
### 5.2. <a name='Rception-1'></a>Réception
La réception d'un `RequestPcd` suit plusieurs étapes :
@ -109,7 +129,7 @@ La réception d'un `RequestPcd` suit plusieurs étapes :
5. Déchiffrage des attributs privés des `Item` des `RequestPcd` avec la clé privée `KeyRecover`
6. Mise à jour du cache pour les traitement des RequestPrd.
## 6. <a name='FonctiondesRequestPrd'></a>Fonction des RequestPrd
## 6. <a name='FonctiondesRequestPrd'></a>Fonction des RequestPrd
Les Portable Request Documents ( RequestPrd) sont des documents JSON qui encapsulent les valeurs de signatures et les clés de déchiffrement nécessaires à l'interprétation des `RequestPcd` via l'attribut `RequestPcd_keys_role_confidential_list_enc_by_shared_secret`. Ils sont utilisés pour demander des actions spécifiques, telles que l'envoi de messages, la mise à jour des informations contractuelles, ou la confirmation de transactions.
@ -117,7 +137,7 @@ Les clés de chiffrement des attributs confidentiels par rôles des `Item` des `
Les `RequestPrd` sont de plusieurs types tels que `RequestPrdList`, `RequestPrdMessage`, `RequestPrdUpdate`, etc.: Variations de `RequestPrd` pour différentes actions, telles que l'envoi de messages, la mise à jour des informations contractuelles, ou la confirmation de transactions.
### 6.1. <a name='Fonctionnalitsoptionnelles'></a>Fonctionnalités optionnelles
### 6.1. <a name='Fonctionnalitsoptionnelles'></a>Fonctionnalités optionnelles
L'attribut `sig_value` permet de donner une valeur aux signatures. Les valeurs des signatures sont définies par rôles dans les `ItemProcess` avec des valeurs valant pour `OK` ou `KO` pour `none` pour les validations des `RequestPrd`.
@ -142,7 +162,7 @@ Les adresses et les roles sont précisés en cas d'utilisateurs ayant plusieurs
Tous les échanges sont complétés de l'empreinte du device de l'emetteur envoyée de façon confidentielle via `device_footprint_enc_by_shared_secret`.
### 6.2. <a name='Crationetenvoi-1'></a>Création et envoi
### 6.2. <a name='Crationetenvoi-1'></a>Création et envoi
La création d'un `RequestPrd` suit plusieurs étapes :
@ -159,7 +179,7 @@ La création d'un `RequestPrd` suit plusieurs étapes :
Voir [Silent-Payment-Specs.md](Silent-Payment-Specs.md).
### 6.3. <a name='Rception-1'></a>Réception
### 6.3. <a name='Rception-1'></a>Réception
La réception d'un `RequestPcd` suit plusieurs étapes :
@ -175,18 +195,18 @@ La réception d'un `RequestPcd` suit plusieurs étapes :
10. Validation des conditions définies dans le `ItemProcess` pour ce d'`Item` avec le `Role` correspondant dans le `ItemProcess` et dans ce rôles les conditions pour ce type de `RequestPrd` (dans l'attribut `request_prd_type`) telles que définies dans [Specs-Process-Roles-Specs.md](Specs-Process-Roles-Specs.md).
11. Traitements spécifiques au type de RequestPrd.
## 7. <a name='RequestPrdList-DemandedeListesRequestPcd'></a>RequestPrdList - Demande de Listes ( RequestPcd)
## 7. <a name='RequestPrdList-DemandedeListesRequestPcd'></a>RequestPrdList - Demande de Listes ( RequestPcd)
Utile pour les utilisateurs cherchant à consulter ou à explorer des listes de contrats, de membres, ou d'autres items dans le réseau. Chaque `RequestPcd` liste des `Item` d'un même type, par exemple les `ItemProcess`, les `ItemMember`, les `ItemPeer`, les `ItemPayment`, etc.
### 7.1. <a name='Crationetenvoi-1'></a>Création et envoi
### 7.1. <a name='Crationetenvoi-1'></a>Création et envoi
1. Traitements des `RequestPrd`, avec le `type_request` spécifique à `RequestPrdList` et envoi vers tous les `members` concernés par le `ItemProcess` pour le `Role` correspondant dans le `item_name`
2. Attente du `RequestPrdResponse` avec le `RequestPcd` demandés.
3. voir `RequestPrdResponse` réception.
4. Voir `RequestPcd` réception.
### 7.2. <a name='Rception-1'></a>Réception
### 7.2. <a name='Rception-1'></a>Réception
La réception d'un `RequestPrdList` suit plusieurs étapes :
@ -194,7 +214,11 @@ La réception d'un `RequestPrdList` suit plusieurs étapes :
2. Recherche en cache de la dernière version de la liste du type d'`Item` concerné.
3. Voir `RequestPcd` Création et envoi vers l'émetteur du `RequestPrdList`.
## 8. <a name='RequestPrdMessage-EnvoideMessages'></a>RequestPrdMessage - Envoi de Messages
| transaction SP | RequestPrdConfirm to send | RequestPcd to send | RequestPrdResponse to send |
|----------------|---------------------------|--------------------|----------------------------|
| Yes | Yes | Yes | to the sender |
## 8. <a name='RequestPrdMessage-EnvoideMessages'></a>RequestPrdMessage - Envoi de Messages
Le `RequestPrdMessage` facilite l'envoi de messages sécurisés entre utilisateurs ou entre utilisateurs et processus/contrats.
@ -204,13 +228,13 @@ Permet la communication des`transaction SP` au format `raw` dans l'attribut `raw
Les `RequestPrdMessage` répondent aux `RequestPrdMessage` sauf en cas d'envoi de `raw_transaction_list`.
### 8.1. <a name='Crationetenvoi-1'></a>Création et envoi
### 8.1. <a name='Crationetenvoi-1'></a>Création et envoi
1. Traitements des `RequestPrd`, avec le `type_request` spécifique à `RequestPrdMessage` vers l'emméteur du `RequestPrdMessage`.
2. Attente du `RequestPrdMessage` éventuel (sauf en cas d'envoi d'une `transaction SP`).
3. Le cas échéant : voir `RequestPrdMessage` Réception
### 8.2. <a name='Rception-1'></a>Réception
### 8.2. <a name='Rception-1'></a>Réception
La réception d'un `RequestPrdMessage` suit plusieurs étapes :
@ -218,7 +242,7 @@ La réception d'un `RequestPrdMessage` suit plusieurs étapes :
2. Notification et attente du retour de l'utilisateur (valeur de la signature et message de réponse)
3. Le cas échéant : voir `RequestPrdMessage` création et envoi vers l'emméteur du `RequestPrdMessage`.
## 9. <a name='RequestPrdUpdate-MisesJourdeRequestPcd'></a>RequestPrdUpdate - Mises à Jour de RequestPcd
## 9. <a name='RequestPrdUpdate-MisesJourdeRequestPcd'></a>RequestPrdUpdate - Mises à Jour de RequestPcd
`RequestPrdUpdate` est conçu pour demander des mises à jour des listes via des nouvelles versions de `RequestPcd`.
@ -230,7 +254,7 @@ Par exemple, mettre à jour la liste des membres permet d'ajouter de nouveaux ut
Les `RequestPrdUpdate` signalent au réseau via l'attribut `RequestPcd_new_version_hash` les nouvelles version des RequestPcd.
### 9.1. <a name='Crationetenvoi-1'></a>Création et envoi
### 9.1. <a name='Crationetenvoi-1'></a>Création et envoi
1. Création d'un nouveau `RequestPcd` avec les modifications demandées.
2. Envoi du `RequestPcd` vers les `members` concernés par le `ItemProcess` pour le `Role` correspondant dans le `item_name`.
@ -239,7 +263,7 @@ Les `RequestPrdUpdate` signalent au réseau via l'attribut `RequestPcd_new_versi
5. Voir `RequestPrdResponse` Réception
6. Voir `RequestPcd` Réception.
### 9.2. <a name='Rception-1'></a>Réception
### 9.2. <a name='Rception-1'></a>Réception
La réception d'un `RequestPrdUpdate` suit plusieurs étapes :
@ -247,7 +271,7 @@ La réception d'un `RequestPrdUpdate` suit plusieurs étapes :
2. Notification et attente du retour de l'utilisateur (valeur de la signature et message de réponse)
3. Voir `RequestPrdResponse` création et envoi vers tous les membres de tous les roles du `ItemProcess`.
## 10. <a name='RequestPrdConfirm-ConfirmationdeRception'></a>RequestPrdConfirm - Confirmation de Réception
## 10. <a name='RequestPrdConfirm-ConfirmationdeRception'></a>RequestPrdConfirm - Confirmation de Réception
Le `RequestPrdConfirm` est utilisé pour confirmer la réception et le traitement de demandes ou de transactions, jouant un rôle crucial dans la validation des actions au sein du réseau.
@ -255,15 +279,15 @@ Les `RequestPrdList`, `RequestPrdUpdate`, `RequestPrdMessage`, `RequestPrdRespon
`code_confirm_enc_by_shared_secret`: Un code de confirmation chiffré qui valide l'authenticité et l'intégrité de la réponse, assurant que la confirmation est sécurisée et provient de la source attendue. Dans ce cas un output spécifique chiffré par la clé `KeyConfidential` précise ce code, à confirmer dans le RequestPrdConfirm.
### 10.1. <a name='Crationetenvoi-1'></a>Création et envoi
### 10.1. <a name='Crationetenvoi-1'></a>Création et envoi
1. Traitements des RequestPrd, avec le `type_request` spécifique à `RequestPrdConfirm` envoi vers l'emméteur du `RequestPrd`.
### 10.2. <a name='Rception-1'></a>Réception
### 10.2. <a name='Rception-1'></a>Réception
Traitements des `RequestPrd`, pas de traitement suppplémentaire.
## 11. <a name='RequestPrdResponse-RpondreuneDemande'></a>RequestPrdResponse - Répondre à une Demande
## 11. <a name='RequestPrdResponse-RpondreuneDemande'></a>RequestPrdResponse - Répondre à une Demande
Le `RequestPrdResponse` permet de répondre spécifiquement à des `RequestPrd` reçus, facilitant un échange interactif d'informations ou de décisions entre les parties.
@ -273,21 +297,21 @@ Utilisé pour fournir des feedbacks, des confirmations, ou des instructions supp
Aussi le moyen de demander des moyens de paiement ou de dépot ou de preuve, puis de partager le payload de ces actions.
### 11.1. <a name='Crationetenvoi-1'></a>Création et envoi
### 11.1. <a name='Crationetenvoi-1'></a>Création et envoi
1. Traitements des RequestPrd, avec le `type_request` spécifique à `RequestPrdResponse` et envoi en fonction du type de `RequestPrd` d'origine.
2. Pas de traitement supplémentaire.
### 11.2. <a name='Rception-1'></a>Réception
### 11.2. <a name='Rception-1'></a>Réception
1. Traitements des `RequestPrd`
2. Notification de l'utilisateur.
## 12. <a name='RequestPrdKeyBakcup'></a>RequestPrdKeyBakcup
## 12. <a name='RequestPrdKeyBakcup'></a>RequestPrdKeyBakcup
Le RequestPrdKeyHelloBakcup permet de demander la stockage de nouveaux shards associés à une `pre-id` .
### 12.1. <a name='Crationetenvoi-1'></a>Création et envoi
### 12.1. <a name='Crationetenvoi-1'></a>Création et envoi
1. Voir [Auth-Specs.md](Auth-Specs.md) pour la création des shards et de la pré-image
2. Traitements des RequestPrd, avec le `type_request` spécifique à `RequestPrdKeyBakcup`
@ -298,35 +322,35 @@ Le RequestPrdKeyHelloBakcup permet de demander la stockage de nouveaux shards as
7. Voir `RequestPrdKeyHello` création et envoi
8. Mise à jour du cache
### 12.2. <a name='Rception-1'></a>Réception
### 12.2. <a name='Rception-1'></a>Réception
1. Traitements des `RequestPrd`
2. Récupération en cache des shards et de la pré-image
3. Création du `RequestPrdResponse` avec les shards et envoi vers l'emméteur du `RequestPrdKeyBakcup`.
4. Mis à jour du cache
## 13. <a name='RequestPrdKeyHello-changedeClsetdIdentits'></a>RequestPrdKeyHello - Échange de Clés et d'Identités
## 13. <a name='RequestPrdKeyHello-changedeClsetdIdentits'></a>RequestPrdKeyHello - Échange de Clés et d'Identités
RequestPrdKeyHello est conçu pour initier ou répondre à des demandes d'échange de clés ou d'informations d'identité, essentiel pour la gestion sécurisée des accès et des identités au sein du réseau.
Important pour les processus d'onboarding de nouveaux membres, de réinitialisation des accès, ou de renouvellement des clés, facilitant une intégration sécurisée et la mise à jour des identités dans le réseau.
### 13.1. <a name='Crationetenvoi-1'></a>Création et envoi
### 13.1. <a name='Crationetenvoi-1'></a>Création et envoi
1. Voir [Auth-Specs.md](Auth-Specs.md) pour la création des shards et de la pré-image
2. Traitements des RequestPrd, avec le `type_request` spécifique à `RequestPrdKeyHello`
3. Envoi vers tous les membres de décrits dans `SharedProcess` ou vers tous les membres de tous les roles du `ItemProcess` si celui ci est présent en cache.
### 13.2. <a name='Rception-1'></a>Réception
### 13.2. <a name='Rception-1'></a>Réception
1. Voir [Auth-Specs.md](Auth-Specs.md) pour la récupération des shards et de la pré-image
2. Traitements des RequestPrd, avec le `type_request` spécifique à `RequestPrdKeyHello`
3. Voir création et envoi de `RequestPcd` relatif au role de l'utilisateur dans le `ItemProcess`
4. Voir création et envoi de `RequestPrdResponse` avec les shards et les référence au `RequestPCD` vers l'emméteur du `RequestPrdKeyHello`.
## 14. <a name='ExemplesdeCode'></a>Exemples de Code
## 14. <a name='ExemplesdeCode'></a>Exemples de Code
## 15. <a name='Todo'></a>Todo
## 15. <a name='Todo'></a>Todo
* [ ] Ajouter un tableau : transaction SP, confirmation attendue, réponse attendue, création vers, réponse vers.
* [ ] Diagrammes de séquences