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

Wip (doc)

Browse Source
This commit is contained in:
NicolasCantu 2024-02-15 15:51:53 +01:00
parent b6abd5867e
commit 24ecde047b
1 changed files with 57 additions and 117 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -3,19 +3,23 @@
* 2. [Portée](#Porte) * 2. [Portée](#Porte)
* 3. [3. Documents de référence](#Documentsderfrence) * 3. [3. Documents de référence](#Documentsderfrence)
* 4. [Fonction des PCD](#FonctiondesPCD) * 4. [Fonction des PCD](#FonctiondesPCD)
* 4.1. [Création et envoi](#Crationetenvoi)
* 5. [Fonction des PRD](#FonctiondesPRD) * 5. [Fonction des PRD](#FonctiondesPRD)
* 5.1. [RequestPrdList - Demande de Listes (PCD)](#RequestPrdList-DemandedeListesPCD) * 5.1. [Fonctionnalités optionnelles](#Fonctionnalitsoptionnelles)
* 5.2. [RequestPrdMessage - Envoi de Messages](#RequestPrdMessage-EnvoideMessages) * 5.2. [Création et envoi](#Crationetenvoi-1)
* 5.3. [RequestPrdUpdate - Mises à Jour de PCD](#RequestPrdUpdate-MisesJourdePCD) * 6. [Fonction des transactions silent payment SP associées aux PRD](#FonctiondestransactionssilentpaymentSPassociesauxPRD)
* 5.4. [RequestPrdConfirm - Confirmation de Réception](#RequestPrdConfirm-ConfirmationdeRception) * 7. [RequestPrdList - Demande de Listes (PCD)](#RequestPrdList-DemandedeListesPCD)
* 5.5. [RequestPrdResponse - Répondre à une Demande](#RequestPrdResponse-RpondreuneDemande) * 8. [RequestPrdMessage - Envoi de Messages](#RequestPrdMessage-EnvoideMessages)
* 5.6. [RequestPrdKeyHelloBakcup](#RequestPrdKeyHelloBakcup) * 9. [RequestPrdUpdate - Mises à Jour de PCD](#RequestPrdUpdate-MisesJourdePCD)
* 5.7. [RequestPrdKeyHello - Échange de Clés et d'Identités](#RequestPrdKeyHello-changedeClsetdIdentits) * 10. [RequestPrdConfirm - Confirmation de Réception](#RequestPrdConfirm-ConfirmationdeRception)
* 6. [Gestion et Échange des Documents](#GestionetchangedesDocuments) * 11. [RequestPrdResponse - Répondre à une Demande](#RequestPrdResponse-RpondreuneDemande)
* 6.1. [Création et Distribution](#CrationetDistribution) * 12. [RequestPrdKeyHelloBakcup](#RequestPrdKeyHelloBakcup)
* 6.2. [Validation et Mise à Jour](#ValidationetMiseJour) * 13. [RequestPrdKeyHello - Échange de Clés et d'Identités](#RequestPrdKeyHello-changedeClsetdIdentits)
* 7. [Exemples de Code](#ExemplesdeCode) * 14. [Gestion et Échange des Documents](#GestionetchangedesDocuments)
* 8. [Todo](#Todo) * 14.1. [Création et Distribution](#CrationetDistribution)
* 14.2. [Validation et Mise à Jour](#ValidationetMiseJour)
* 15. [Exemples de Code](#ExemplesdeCode)
* 16. [Todo](#Todo)
<!-- vscode-markdown-toc-config <!-- vscode-markdown-toc-config
numbering=true numbering=true
@ -41,7 +45,7 @@ Les Portable Contract Documents (PCD) sont des documents JSON qui encapsulent le
Les `Item` ainsi échangés via les PCD sont vérifiés par les `PRDResponse` afin de vérifier les validations de ces données et leurs conformités avec les `process` et les `members` concernés. Les `Item` ainsi échangés via les PCD sont vérifiés par les `PRDResponse` afin de vérifier les validations de ces données et leurs conformités avec les `process` et les `members` concernés.
### Création et envoi ### 4.1. <a name='Crationetenvoi'></a>Création et envoi
La création d'un PCD suit plusieurs étapes : La création d'un PCD suit plusieurs étapes :
@ -55,13 +59,38 @@ La création d'un PCD suit plusieurs étapes :
## 5. <a name='FonctiondesPRD'></a>Fonction des PRD ## 5. <a name='FonctiondesPRD'></a>Fonction des PRD
Les Portable Request Documents (PRD) sont des documents JSON qui encapsulent les valeurs de signatures et les clés de déchiffrement nécessaires à l'interprétation des PCD. 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 Portable Request Documents (PRD) sont des documents JSON qui encapsulent les valeurs de signatures et les clés de déchiffrement nécessaires à l'interprétation des PCD via l'attribut `pcd_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 PCD sont chiffrées dans les PRD avec le chiffrement du PRD 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 PCD (rôles dans les `process`). Les clés de chiffrement des attributs confidentiels par rôles des `Item` des PCD sont chiffrées dans les PRD avec le chiffrement du PRD 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 PCD (rôles dans les `process`).
Les PRD sont de plusieurs types tels que `RequestPrdList`, `RequestPrdMessage`, `RequestPrdUpdate`, etc.: Variations de `PRD` pour différentes actions, telles que l'envoi de messages, la mise à jour des informations contractuelles, ou la confirmation de transactions. Les PRD sont de plusieurs types tels que `RequestPrdList`, `RequestPrdMessage`, `RequestPrdUpdate`, etc.: Variations de `PRD` pour différentes actions, telles que l'envoi de messages, la mise à jour des informations contractuelles, ou la confirmation de transactions.
### Création et envoi ### 5.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 `PRD`.
Lorsque que la réponse fait référence à un PCD il est précisé dans `pcd_reference_hash`, idem pour les prd avec `prd_reference_hash`.
Lorsque que la réponse fait suite directement à un PCD il est précisé dans `pcd_origin_hash`, idem pour les prd avec `prd_origin_hash`.
Les `PrdResponse` 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_pcd_hash_list` pour les paiements et preuves ad'hoc éventuellements associés aux PCD 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 PCD identifiés par `payment_pcd_hash_list_enc_by_shared_secret`, `cap_pcd_hash_list_enc_by_shared_secret` (cas des payments temporaires en l'attente du passage d'un cap), `deposit_pcd_hash_list_enc_by_shared_secret` et `commitment_pcd_hash_list_enc_by_shared_secret`.
Des champs messages peuvent accompagner les PRD 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`.
### 5.2. <a name='Crationetenvoi-1'></a>Création et envoi
La création d'un PRD suit plusieurs étapes : La création d'un PRD suit plusieurs étapes :
@ -73,7 +102,7 @@ La création d'un PRD suit plusieurs étapes :
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. 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. 7. **Envoi du message**: Envoi du message aux relais et des transactions aux noeuds de signet.
## Fonction des transactions silent payment SP associées aux PRD ## 6. <a name='FonctiondestransactionssilentpaymentSPassociesauxPRD'></a>Fonction des transactions silent payment SP associées aux PRD
La clé `KeyConfidential` d'une transaction Silent Payment SP est utilisée pour chiffrer les PRD. 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 PRD et permet une meilleur sécurité et confidentialité des échanges. La clé `KeyConfidential` d'une transaction Silent Payment SP est utilisée pour chiffrer les PRD. 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 PRD et permet une meilleur sécurité et confidentialité des échanges.
@ -81,11 +110,11 @@ La transaction Silent Payment SP a aussi une fonction d'horodate et de preuve de
Les `PRDConfirm` qui sont des accusés automatiques de réception des PRD 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). Les `PRDConfirm` qui sont des accusés automatiques de réception des PRD 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).
## 5.1. <a name='RequestPrdList-DemandedeListesPCD'></a>RequestPrdList - Demande de Listes (PCD) ## 7. <a name='RequestPrdList-DemandedeListesPCD'></a>RequestPrdList - Demande de Listes (PCD)
Utile pour les utilisateurs cherchant à consulter ou à explorer des listes de contrats, de membres, ou d'autres items dans le réseau. Chaque PCD liste des `Item` d'un même type, par exemple les `ItemProcess`, les `ItemMember`, les `ItemPeer`, les `ItemPayment`, etc. Utile pour les utilisateurs cherchant à consulter ou à explorer des listes de contrats, de membres, ou d'autres items dans le réseau. Chaque PCD liste des `Item` d'un même type, par exemple les `ItemProcess`, les `ItemMember`, les `ItemPeer`, les `ItemPayment`, etc.
## 5.2. <a name='RequestPrdMessage-EnvoideMessages'></a>RequestPrdMessage - Envoi de Messages ## 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. Le RequestPrdMessage facilite l'envoi de messages sécurisés entre utilisateurs ou entre utilisateurs et processus/contrats.
@ -93,7 +122,7 @@ Permet la communication directe et sécurisée au sein du réseau, supportant de
Les `PRDMessage` répondent aux `PRDMessage`. Les `PRDMessage` répondent aux `PRDMessage`.
## 5.3. <a name='RequestPrdUpdate-MisesJourdePCD'></a>RequestPrdUpdate - Mises à Jour de PCD ## 9. <a name='RequestPrdUpdate-MisesJourdePCD'></a>RequestPrdUpdate - Mises à Jour de PCD
`RequestPrdUpdate` est conçu pour demander des mises à jour des listes via des nouvelles versions de `PCD`. `RequestPrdUpdate` est conçu pour demander des mises à jour des listes via des nouvelles versions de `PCD`.
@ -110,7 +139,7 @@ Les `PRDUpdate` signalent de façon confidentielle :
* soient des conditions ad'hoc déjà remplies via l'attribut `payment_pcd_hash_list`, `cap_pcd_hash_list`, `deposit_pcd_hash_list`, `commitment_pcd_hash_list` pour les paiements et preuves ad'hoc éventuellements associés aux PCD de la nouvelle version. * soient des conditions ad'hoc déjà remplies via l'attribut `payment_pcd_hash_list`, `cap_pcd_hash_list`, `deposit_pcd_hash_list`, `commitment_pcd_hash_list` pour les paiements et preuves ad'hoc éventuellements associés aux PCD de la nouvelle version.
* soient des appels pour recevoir les moyens de satisfaire ces conditions via les attributs `ask_payment_method`, `ask_deposit_method`, `ask_commitment_method`. * soient des appels pour recevoir les moyens de satisfaire ces conditions via les attributs `ask_payment_method`, `ask_deposit_method`, `ask_commitment_method`.
## 5.4. <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. 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.
@ -120,7 +149,7 @@ Les `PRDList`, `PRDUpdate`, `PRDMessage`, `PRDResponse` et `PRDKeyHello` reçoiv
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. 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.
## 5.5. <a name='RequestPrdResponse-RpondreuneDemande'></a>RequestPrdResponse - Répondre à une Demande ## 11. <a name='RequestPrdResponse-RpondreuneDemande'></a>RequestPrdResponse - Répondre à une Demande
Le `PrdResponse` permet de répondre spécifiquement à des PRD reçus, facilitant un échange interactif d'informations ou de décisions entre les parties. Le `PrdResponse` permet de répondre spécifiquement à des PRD reçus, facilitant un échange interactif d'informations ou de décisions entre les parties.
@ -130,118 +159,29 @@ 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. Aussi le moyen de demander des moyens de paiement ou de dépot ou de preuve, puis de partager le payload de ces actions.
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 `PRD`. ## 12. <a name='RequestPrdKeyHelloBakcup'></a>RequestPrdKeyHelloBakcup
Lorsque que la réponse fait référence à un PCD il est précisé dans `pcd_origin_hash`.
Les `PrdResponse` 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_pcd_hash_list` pour les paiements et preuves ad'hoc éventuellements associés aux PCD de la nouvelle version.
* soient des appels pour recevoir les moyens de satisfaire ces conditions via les attributs `ask_payment_method`, `ask_deposit_method`, `ask_commitment_method`.
certif_key_enc_by_shared_secret
Option
Yes
Encrypted certification key, encrypted with a shared secret.
shared_secret_key
Option
Yes
Optional encryption key used for shared secrets.
pcd_new_version_hash
String
The hash of the new version of the PCD.
payment_pcd_hash_list
Vec
A list of hashes for payment-related PCDs.
cap_pcd_hash_list
Vec
A list of hashes for capability-related PCDs.
deposit_pcd_hash_list
Vec
A list of hashes for deposit-related PCDs.
commitment_pcd_hash_list
Vec
A list of hashes for commitment-related PCDs.
ask_payment_method
String
The requested payment method.
ask_deposit_method
String
The requested deposit method.
ask_commitment_method
String
The requested commitment method.
device_footprint_enc_by_sp_shared_secret
String
The device footprint encrypted by a service provider's shared secret.
part_1_enc_hash_enc_by_sp_shared_secret
String
The first part of the hash encrypted by a service provider's shared secret.
shard_enc_by_sp_shared_secret
String
The shard encrypted by a service provider's shared secret.
## 5.6. <a name='RequestPrdKeyHelloBakcup'></a>RequestPrdKeyHelloBakcup
Le RequestPrdKeyHelloBakcup permet de demander la stockage de nouveaux shards associés à une `pre-id` . Le RequestPrdKeyHelloBakcup permet de demander la stockage de nouveaux shards associés à une `pre-id` .
## 5.7. <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. 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. 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.
## 6. <a name='GestionetchangedesDocuments'></a>Gestion et Échange des Documents ## 14. <a name='GestionetchangedesDocuments'></a>Gestion et Échange des Documents
### 6.1. <a name='CrationetDistribution'></a>Création et Distribution ### 14.1. <a name='CrationetDistribution'></a>Création et Distribution
Procédure de création des PCD et PRD, leur chiffrement, et les mécanismes de distribution sécurisée à travers le réseau 4NK. Procédure de création des PCD et PRD, leur chiffrement, et les mécanismes de distribution sécurisée à travers le réseau 4NK.
### 6.2. <a name='ValidationetMiseJour'></a>Validation et Mise à Jour ### 14.2. <a name='ValidationetMiseJour'></a>Validation et Mise à Jour
Processus de validation des informations contenues dans les PCD et PRD, ainsi que les procédures de mise à jour et de versioning des documents. Processus de validation des informations contenues dans les PCD et PRD, ainsi que les procédures de mise à jour et de versioning des documents.
## 7. <a name='ExemplesdeCode'></a>Exemples de Code ## 15. <a name='ExemplesdeCode'></a>Exemples de Code
## 8. <a name='Todo'></a>Todo ## 16. <a name='Todo'></a>Todo
* [ ] Extraits de code illustrant l'utilisation des PCD et PRD dans des scénarios réels. * [ ] Extraits de code illustrant l'utilisation des PCD et PRD dans des scénarios réels.
* [ ] Diagrammes de séquences * [ ] Diagrammes de séquences