4nk/sdk_common
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
sdk_common/doc/PRD-PCD-Specs.md

18 KiB
Raw Blame History

# PRD et PCD - Specs

1. Objectif

Le but de cette section est d'introduire les Portable Contract Document (PCD) et Portable Request Document (PRD) 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. Portée

La spécification couvre la conception, le développement, et l'application pratique des PCD et PRD. 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 PCD et PRD 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. 3. Documents de référence

Voir Doc_references.md.

4. Commun aux PCD et PRD

4.1. Création et envoi

Les PCD et les PRD sont envoyés sous forme de message (JSON) depuis les websockets des relais.

Les messages contiennent des PRD ou des PCD 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.

4.2. Réception

Les PCD et les PRD sont reçus sous forme de message (JSON) depuis les websockets des relais.

Les messages contiennent des PRD ou des PCD 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 PCD ou du PRD (dans l'attribut request). Si le process hash n'est pas reconnu, le message est ignoré.

Les PRD et PCD sont au format JSON. Voir Specs-Datamodel.md.

Les types PRD et PCD sont distingués par l'attribut request_type dans le message.

En cas de PCD ou PRD en relation via pcd_reference_hash ou prd_reference_hash ou pcd_origin_hash ou prd_origin_hash ou item_reference_hash (dans des PCD), il avoir reçu ou attendre ces documents pour traiter le message.

Réception du message: voir Message-SP-Specs.md.

Pour les PCD et les PRD 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. Fonction des PCD

Les Portable Contract Documents (PCD) 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).

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.

5.1. Création et envoi

La création d'un PCD suit plusieurs étapes :

  1. Chargement de la dernière version de la liste (PCD): 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).
  4. Chiffrement du PCD: Chiffrement du PCD avec la clé ProcessKey du process concerné.
  5. Traitements communs aux PCD et PRD

5.2. Réception

La réception d'un PCD suit plusieurs étapes :

  1. Traitements communs aux PCD et PRD
  2. Recherche des PRD en relation via pcd_reference_hash ou pcd_origin_hash de ces PRD et attente si nécessaire.
  3. Déchiffrage des attributs publics des Item des PCD avec la ProcessKey du process concerné.
  4. Déchiffrage des attributs confidentiels des Item des PCD avec les clés de déchiffrement depuis l'attribut pcd_keys_role_confidential_list_enc_by_shared_secret des PRD.
  5. Déchiffrage des attributs privés des Item des PCD avec la clé privée KeyRecover
  6. Mise à jour du cache pour les traitement des PRD.

6. 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 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). 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.

6.1. 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.

6.2. 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) dans la transaction. Cette information est parrallèle aux PRD 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 PRD donc de la validation des données des PCD. Les outputs de la transaction Silent Payment SP contiennent les empreintes cryptographiques des messages et PRD (sauf PRDKeyBackup) et des PCD. 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 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).

6.3. Création et envoi

La création d'un PRD 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 PCD.
  2. Chiffrement du PRD: Chiffrement du PRD 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) avec les outupts de la transaction Silent Payment SP correspondants au PRD et aux éventuels PCD associés.
  4. Création du message: Création du message contenant le PRD 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. Réception

La réception d'un PCD suit plusieurs étapes :

  1. Traitements communs aux PCD et PRD
  2. Recherche des PCD en relation via pcd_reference_hash ou pcd_origin_hash et attente si nécessaire.
  3. Recherche des PRD en relation via prd_reference_hash ou prd_origin_hash et attente si nécessaire.
  4. Recherche de l'Item associé via item_reference_hash et attente si nécessaire.
  5. 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 PRD dans l'output 2 de la transaction.
  6. Mise à jour du cache pour les traitement des PRD.
  7. Traitements spécifiques au type de PRD.

7. 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.

8. 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 PRDMessage répondent aux PRDMessage.

9. RequestPrdUpdate - Mises à Jour de PCD

RequestPrdUpdate est conçu pour demander des mises à jour des listes via des nouvelles versions de PCD.

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 PRDUpdate signalent au réseau via l'attribut pcd_new_version_hash les nouvelles version des PCD.

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 appels pour recevoir les moyens de satisfaire ces conditions via les attributs ask_payment_method, ask_deposit_method, ask_commitment_method.

10. 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 PRDList, PRDUpdate, PRDMessage, PRDResponse et PRDKeyHello reçoivent systématiquement un PRDConfirm 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 PRDConfirm.

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.

11. 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.

Les PRDResponse répondent aux PRDList, PRDUpdate, PRDKeyBackup et PRDKeyHello.

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.

12. RequestPrdKeyHelloBakcup

Le RequestPrdKeyHelloBakcup permet de demander la stockage de nouveaux shards associés à une pre-id .

13. 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.

14. Gestion et Échange des Documents

14.1. 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.

14.2. 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.

15. Exemples de Code

16. Todo

  • Extraits de code illustrant l'utilisation des PCD et PRD dans des scénarios réels.
  • Diagrammes de séquences