sdk_common/doc/PRD-PCD-Specs.md

306 lines
21 KiB
Markdown

<!-- vscode-markdown-toc -->
* 1. [Objectif](#Objectif)
* 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)
* 5. [Fonction des RequestPcd](#FonctiondesRequestPcd)
* 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. [Fonction des transactions silent payment SP associées aux RequestPrd](#FonctiondestransactionssilentpaymentSPassociesauxRequestPrd)
* 6.3. [Création et envoi](#Crationetenvoi-1)
* 6.4. [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)
* 8. [RequestPrdMessage - Envoi de Messages](#RequestPrdMessage-EnvoideMessages)
* 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)
* 10. [RequestPrdConfirm - Confirmation de Réception](#RequestPrdConfirm-ConfirmationdeRception)
* 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)
* 12. [RequestPrdKeyHelloBakcup](#RequestPrdKeyHelloBakcup)
* 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)
* 14. [Exemples de Code](#ExemplesdeCode)
* 15. [Todo](#Todo)
<!-- vscode-markdown-toc-config
numbering=true
autoSave=true
/vscode-markdown-toc-config -->
<!-- /vscode-markdown-toc --># RequestPrd et RequestPcd - Specs
## 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
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
Voir [Doc_references.md](Doc_references.md).
## 4. <a name='CommunauxRequestPcdetRequestPrd'></a>Commun aux RequestPcd et RequestPrd
### 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.
Les messages contiennent des RequestPrd ou des RequestPcd encapsulés dans l'attribut `request_enc`, chiffré par la clé `ProcessKey` du `process` concerné.
**Création du message et envoi**: voir [Message-SP-Specs.md](Message-SP-Specs.md).
### 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.
Les messages contiennent des RequestPrd ou des RequestPcd encapsulés dans l'attribut `request_enc`, chiffré par la clé `ProcessKey` du `process` concerné.
A la réception des messages, ils sont tous déchiffrés puis conservés ou non en fonction du `process hash` du RequestPcd ou du RequestPrd (dans l'attribut `request`). Si le `process hash` n'est pas reconnu, le message est ignoré.
Les RequestPrd et RequestPcd sont au format JSON. Voir [Specs-Datamodel.md](Specs-Datamodel.md).
Les types RequestPrd et RequestPcd sont distingués par l'attribut `request_type` dans le `message`.
En cas de RequestPcd ou RequestPrd en relation via `RequestPcd_reference_hash` ou `RequestPrd_reference_hash` ou `RequestPcd_origin_hash` ou `RequestPrd_origin_hash` ou `item_reference_hash` (dans des RequestPcd), il avoir reçu ou attendre ces documents pour traiter le message.
**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
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 `process` et les `members` concernés.
### 5.1. <a name='Crationetenvoi-1'></a>Création et envoi
La création d'un RequestPcd suit plusieurs étapes :
1. **Chargement de la dernière version de la liste ( RequestPcd)**: Récupération de la dernière version de la liste du type d'`Item` à partir de la source de données, telle qu'une base de données ou un système de stockage.
2. **Mise à jour**: Ajouts et modifications eventuelles des `Item`
3. **Chiffrement des attributs**: Chiffrement des attributs de chaque Item selon les règles de confidentialité et de partage des clés (cf. [Specs-Security.md](Specs-Security.md)).
4. **Chiffrement du RequestPcd**: Chiffrement du RequestPcd avec la clé `ProcessKey` du `process` concerné.
5. Traitements communs aux RequestPcd et RequestPrd
### 5.2. <a name='Rception-1'></a>Réception
La réception d'un RequestPcd suit plusieurs étapes :
1. Traitements communs aux RequestPcd et RequestPrd
2. Recherche des RequestPrd en relation via `RequestPcd_reference_hash` et `RequestPcd_origin_hash` de ces RequestPrd et attente si nécessaire.
3. Déchiffrage des attributs publics des `Item` des RequestPcd avec la `ProcessKey` du `process` concerné.
4. Déchiffrage des attributs confidentiels des `Item` des RequestPcd avec les clés de déchiffrement depuis l'attribut `RequestPcd_keys_role_confidential_list_enc_by_shared_secret` des RequestPrd.
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
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.
Les clés de chiffrement des attributs confidentiels par rôles des `Item` des RequestPcd sont chiffrées dans les RequestPrd avec le chiffrement du RequestPrd par la clé `KeyConfidential` d'une transaction Silent Payment SP (cf. [Specs-Security.md](Specs-Security.md)). Ces clés ne sont distribués qu'aux `members` concernés par les `Item` des RequestPcd (rôles dans les `process`).
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
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`.
Lorsque que la réponse fait référence à un RequestPcd il est précisé dans `RequestPcd_reference_hash`, idem pour les RequestPrd avec `RequestPrd_reference_hash`.
Lorsque que la réponse fait suite directement à un RequestPcd il est précisé dans `RequestPcd_origin_hash`, idem pour les RequestPrd avec `RequestPrd_origin_hash`.
Les `RequestPrdResponse` signalent de façon confidentielle :
* soient des conditions ad'hoc déjà remplies via l'attribut `payment_method_enc_by_shared_secret`, `deposit_method_enc_by_shared_secret`, `commitment_method_enc_by_shared_secret`, `commitment_request_pcd_hash_list` pour les paiements et preuves ad'hoc éventuellements associés aux RequestPcd de la nouvelle version.
* soient des appels pour recevoir les moyens de satisfaire ces conditions via les attributs `ask_payment_method_enc_by_shared_secret`, `ask_deposit_method_enc_by_shared_secret`, `ask_commitment_method_enc_by_shared_secret`.
Les `Item` associés sont référencés dans des RequestPcd identifiés par `payment_request_pcd_hash_list_enc_by_shared_secret`, `cap_request_pcd_hash_list_enc_by_shared_secret` (cas des payments temporaires en l'attente du passage d'un cap), `deposit_request_pcd_hash_list_enc_by_shared_secret` et `commitment_request_pcd_hash_list_enc_by_shared_secret`.
Des champs messages peuvent accompagner les RequestPrd via `message_public`, `message_confidential`, `message_private`.
Il est aussi possible de partager des clés de chiffrement ad'hoc via `certif_key_enc_by_shared_secret`.
En plus des horodatages automatique, il est possible de déclarer un timestamp dans `timestamp_declared` qui ne sera pas pris en compte dans le traitement mais qui est ainsi tracé dans les éléments de preuves.
Les adresses et les roles sont précisés en cas d'utilisateurs ayant plusieurs roles dans les process et pour préciser les adresses de réponses en cas d'utilisations en multi-devices.
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='FonctiondestransactionssilentpaymentSPassociesauxRequestPrd'></a>Fonction des transactions silent payment SP associées aux RequestPrd
La clé `KeyConfidential` d'une transaction Silent Payment SP est utilisée pour chiffrer les RequestPrd. Cette clé est échangée avec le destinataire via un Diffie-Hellman (cf. [Specs-Security.md](Specs-Security.md)) dans la transaction. Cette information est parrallèle aux RequestPrd et permet une meilleur sécurité et confidentialité des échanges.
La transaction Silent Payment SP a aussi une fonction d'horodate et de preuve de publication des RequestPrd donc de la validation des données des RequestPcd. Les outputs de la transaction Silent Payment SP contiennent les empreintes cryptographiques des `messages` et RequestPrd (sauf `RequestPrdKeyBackup`) et des RequestPcd. Ainsi l'infrastructure blockchain de signet de 4NK permet de vérifier l'intégrité des flux, leur ordre de référence (horodatage) et leur preuve de publication.
Les `RequestPrdConfirm` qui sont des accusés automatiques de réception des RequestPrd sont aussi associés à une transaction Silent Payment SP, ce qui permet d'ajouter les preuves de réception des demandes et des validations (ou non).
### 6.3. <a name='Crationetenvoi-1'></a>Création et envoi
La création d'un RequestPrd suit plusieurs étapes :
1. **Chargement des clés de chiffrement confidentiel'**: Récupération des clés de chiffrement confidentiel des attributs des items d'un RequestPcd.
2. **Chiffrement du RequestPrd**: Chiffrement du RequestPrd avec la clé `ProcessKey` du `process` concerné.
3. **Création de l'adresse SP**: Création d'une adresse Silent Payment SP pour le paiement des frais de transaction depuis l'adresse signet de l'utilisateur décrit dans un objet `ItemMember` (cf. [Specs-Datamodel.md](Specs-Datamodel.md)) avec les outupts de la transaction Silent Payment SP correspondants au RequestPrd et aux éventuels RequestPcd associés.
4. **Création du message**: Création du `message` contenant le RequestPrd chiffré, la preuve de travail, l'adresse de faucet
5. **Sélection des relais pour le message**: Sélection de 4 relais pour le message selon l'historique des pings et des réponses retournées.
6. **Sélection des noeuds de signet pour la transaction silent Payment (SP)**: Sélection de 4 noeuds de signet pour l'envoi de la transaction Silent Payment SP.
7. **Envoi du message**: Envoi du message aux relais et des transactions aux noeuds de signet.
### 6.4. <a name='Rception-1'></a>Réception
La réception d'un RequestPcd suit plusieurs étapes :
1. Traitements communs aux RequestPcd et RequestPrd
2. Recherche des RequestPcd en relation via `RequestPcd_reference_hash` et `RequestPcd_origin_hash` et attente si nécessaire et traitement de ceux ci.
3. Vérification de la conformité des RequestPcd en relation.
4. Recherche des RequestPrd en relation via `RequestPrd_reference_hash` et `RequestPrd_origin_hash` et attente si nécessaire et traitement de ceux ci.
5. Vérification de la conformité des RequestPrd en relation.
6. Recherche de l'`Item` associé via `item_reference_hash` et attente si nécessaire et traitement de celui ci.
7. Déchiffrage des attributs confidentiels notés `<attribut>_enc_by_shared_secret` depuis la `KeyConfidential` de la transaction silent payment SP correspondante via hash du RequestPrd dans l'output `2` de la transaction.
8. Mise à jour du cache pour les traitement des RequestPrd.
9. Traitements spécifiques au type de RequestPrd.
## 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
L'envoi d'un `RequestPrdList` suit plusieurs étapes :
1. Traitements des RequestPrd, avec le `type_request` spécifique à `RequestPrdList`.
2. Envoi de la transaction Silent Payment SP.
### 7.2. <a name='Rception-1'></a>Réception
La réception d'un `RequestPrdList` suit plusieurs étapes :
1. Traitements des RequestPrd
2. Création et envoi d'un `RequestPrdConfirm` pour confirmer la réception du `RequestPrdList`.
3. Recherche en cache de la dernière version de la liste du type d'`Item` concerné.
4. Création et envoi d'un `RequestPcd` avec la dernière version de la liste du type d'`Item` concerné.
5. Création et envoi à l'émetteur du `RequestPrdList` d'un `RequestPrdRResponse` avec :
5.1. le hash du `RequestPcd` envoyé dans l'attribut `RequestPcd_reference_hash`
5.2. le hash du `RequestPrdList` reçu dans l'attribut `RequestPrd_origin_hash`
6. Mise à jour du cache avec les nouveaux `RequestPcd` et `RequestPrdResponse` et `RequestPrdConfirm` envoyés.
## 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.
Permet la communication directe et sécurisée au sein du réseau, supportant des échanges d'informations critiques ou des notifications entre parties.
Les `RequestPrdMessage` répondent aux `RequestPrdMessage`.
### 8.1. <a name='Crationetenvoi-1'></a>Création et envoi
Traitements des RequestPrd, avec le `type_request` spécifique à `RequestPrdMessage`.
### 8.2. <a name='Rception-1'></a>Réception
La réception d'un `RequestPrdMessage` suit plusieurs étapes :
1. Traitements des RequestPrd
2. Création et envoi d'un `RequestPrdConfirm` pour confirmer la réception du `RequestPrdList`.
3. Recherche en cache de la dernière version de la liste du type d'`Item` concerné.
4. Création et envoi d'un `RequestPcd` avec la dernière version de la liste du type d'`Item` concerné.
5. Création et envoi à l'émetteur du `RequestPrdList` d'un `RequestPrdRResponse` avec :
5.1. le hash du `RequestPcd` envoyé dans l'attribut `RequestPcd_reference_hash`
5.2. le hash du `RequestPrdList` reçu dans l'attribut `RequestPrd_origin_hash`
## 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`.
Basé sur le `RequestPrd`. avec des additions pour spécifier les modifications demandées, y compris de nouveaux attributs ou valeurs à mettre à jour :
Essentiel pour les utilisateurs ou les processus nécessitant de mettre à jour des informations contractuelles ou des attributs d'items, assurant la pertinence et l'actualité des données dans le système.
Par exemple, mettre à jour la liste des membres permet d'ajouter de nouveaux utilisateurs sur un `process`, la mise à jour de la liste des `process` permettra de leur affecter un nouveau role.
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
Traitements des RequestPrd, avec le `type_request` spécifique à `RequestPrdUpdate`.
### 9.2. <a name='Rception-1'></a>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.
Les `RequestPrdList`, `RequestPrdUpdate`, `RequestPrdMessage`, `RequestPrdResponse` et `RequestPrdKeyHello` reçoivent systématiquement un `RequestPrdConfirm` depuis leur réception par le destinataire.
`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.
Crucial pour les processus qui nécessitent une confirmation explicite de réception ou d'acceptation, comme la finalisation d'une transaction ou la validation d'un changement d'état dans un contrat.
### 10.1. <a name='Crationetenvoi-1'></a>Création et envoi
Traitements des RequestPrd, avec le `type_request` spécifique à `RequestPrdConfirm`.
### 10.2. <a name='Rception-1'></a>Réception
## 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.
Les `RequestPrdResponse` répondent aux `RequestPrdList`, `RequestPrdUpdate`, `RequestPrdKeyBackup` et `RequestPrdKeyHello`.
Utilisé pour fournir des feedbacks, des confirmations, ou des instructions supplémentaires en réponse à des demandes initiales, supportant une communication bidirectionnelle sécurisée et vérifiable.
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
Traitements des RequestPrd, avec le `type_request` spécifique à `RequestPrdResponse`.
### 11.2. <a name='Rception-1'></a>Réception
## 12. <a name='RequestPrdKeyHelloBakcup'></a>RequestPrdKeyHelloBakcup
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
Traitements des RequestPrd, avec le `type_request` spécifique à `RequestPrdRRequestPrdKeyHelloBakcupesponse`.
### 12.2. <a name='Rception-1'></a>Réception
## 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
Traitements des RequestPrd, avec le `type_request` spécifique à `RequestPrdKeyHello`.
### 13.2. <a name='Rception-1'></a>Réception
## 14. <a name='ExemplesdeCode'></a>Exemples de Code
## 15. <a name='Todo'></a>Todo
* [ ] Extraits de code illustrant l'utilisation des RequestPcd et RequestPrd dans des scénarios réels.
* [ ] Diagrammes de séquences