sdk_common/doc/PRD-PCD-Specs.md

31 KiB
Raw Blame History

RequestPrd et RequestPcd - Specs

1. 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. 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. Documents de référence

Voir _Doc_references.md.

4. Encryption

Schema :

PCD_PRD_encryption

Les Metadata des Item des RequestPcd et les attributs des RequestPcd et RequestPrd sont chiffrés de la sorte :

  • Données publiques : Utilisent un chiffrement symétrique basé sur la ProcessKey de l'ItemProcess (cf. Specs-Definition). Ces données sont ainsi accessibles à tous pour le déchiffrement.

  • Données confidentielles destinées aux membres d'un role spécifique d'un ItemProcess dans les RequestPcd : Le chiffrement est réalisé symétriquement à partir d'une clé de chiffrement générée à la volée pour chaque champ et pour chaque item d'une liste d'un RequestPcd. Ces clés seront ensuite ajoutées aux RequestPrd dans l'attribut RequestPcd_keys_role_confidential_list_enc_by_shared_secret; lui même alors chiffré par la KeyConfidential.

  • Données confidentielles destinées aux membres d'un role spécifique d'un ItemProcess dans les RequestPrd : Utilisent un chiffrement symétrique basé sur les clés de chiffrement AES-GCM-256, générées à la volée dans les RequestPcd et transmises par le RequestPrd, chiffrées par la KeyConfidential du Diffie-Hellman de la transaction Silent Payment associée à ce RequestPrd (cf. Specs-Definition) d'une transaction SP.

  • Données privées : Chiffrées symétriquement en utilisant la clé de dépense de connexion (recover) du signet (voir Login - Specs).

5. Définitions

  • 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 à 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.
    • RequestPrdConfirm: Confirmation de la réception des RequestPrd.
    • RequestPrdResponse: Réponse aux autres types de RequestPrd (à l'exception de RequestPrdConfirm et RequestPrdResponse).
  • Message: Enveloppe commune pour les RequestPrd et RequestPcd lors de leur transmission aux relais et de leur réception depuis les relais. Dans cette enveloppe les RequestPrd et RequestPcd sont chiffrés par la ProcessKey de l'ItemProcess (cf. Specs-Definition) et ajoutés au champs RequestEnc.

  • KeyConfidential: Clé AES-GCM-256 issue du Diffie-Hellman de la transaction Silent Payment correspondant à un RequestPrd.

  • ProcessKey: La clé publique de chiffrement d'un ItemProcess (trouvée dans un ItemProcess, dans son attribut Item, dans son attribut metadata_contract_public, dans son attribut meta_data, dans son attribut key_list au premier élément).

  • KeyRecover: La clé privée de dépense de recover du signet, utilisée comme référence pour l'identité.

  • pre-id: Pré-identifiant des utilisateurs, constitué du hash de la partie 1 de la KeyRecover.

6. Principe de messagerie

6.1. Création et envoi

Les RequestPcd et les RequestPrd sont envoyés sous forme de messages (JSON) via les websockets des relais.

Ces Message contiennent soit des RequestPrd, soit des RequestPcd, encapsulés dans l'attribut request_enc, lequel est chiffré à l'aide de la clé ProcessKey de l'ItemProcess concerné.

Les RequestPrd et RequestPcd sont au format JSON. Voir Specs-Datamodel.md.

Création du message et envoi: voir Message-SP-Specs.md.

6.2. Réception

Les RequestPcd et RequestPrd sont reçus sous forme de messages (JSON) via les websockets des relais.

Ces messages contiennent des RequestPrd ou des RequestPcd encapsulés dans l'attribut request_enc, lequel est chiffré avec la clé ProcessKey de l'ItemProcess concerné.

À la réception des Message, ceux-ci sont déchiffrés puis conservés ou non, selon le process_hash du RequestPcd ou du RequestPrd (dans l'attribut request). Si le process_hash n'est pas reconnu, le message est ignoré.

Les types RequestPrd et RequestPcd sont distingués par l'attribut request_type dans le Message.

En cas de RequestPcd ou RequestPrd liés via RequestPcd_reference_hash, request_prd_reference_hash, RequestPcd_origin_hash, request_prd_origin_hash ou item_reference_hash (dans des RequestPcd), il est nécessaire d'avoir reçu ou d'attendre ces documents pour traiter le message.

Les RequestPrd et RequestPcd sont au format JSON. Voir Specs-Datamodel.md.

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

Pour les RequestPcd et RequestPrd, il est nécessaire de vérifier si le hash du document est déjà enregistré ; si tel est le cas, le message est ignoré.

7. Fonction des RequestPcd

Les Portable Contract Documents (RequestPcd) sont des documents au format JSON encapsulant des listes versionnées d'Item, dont les attributs sont chiffsrés selon trois niveaux de confidentialité : public, par rôles spécifiques, ou privé. (cf. Specs-Security.md).

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

7.1. Schéma des flux

RequestPcd

7.2. Création et envoi

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

  1. 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. Ajouts et modifications éventuelles des Item.
  3. 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 RequestPcd avec la clé ProcessKey du ItemProcess concerné.
  5. Traitements communs aux RequestPcd et RequestPrd.

7.3. 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 ItemProcess concerné.
  4. Déchiffrage des attributs confidentiels des Item des RequestPcd avec les clés de déchiffrement fournies par 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 le traitement des RequestPrd.

8. Fonction desRequestPrd

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 solliciter des actions spécifiques, telles que l'envoi de messages, la mise à jour des informations contractuelles, ou la confirmation de transactions.

Les clés permettant le chiffrement des attributs confidentiels par rôles des Item dans les RequestPcd sont elles-mêmes chiffrées dans les RequestPrd au moyen du chiffrement du RequestPrd par la clé KeyConfidential d'une transaction SP (cf. Specs-Security.md). Ces clés sont uniquement distribuées aux members concernés par les Item des RequestPcd (rôles dans les ItemProcess).

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.

8.1. Schéma des flux

Pour simplifier, les RequestPrdConfirm n'ont pas été inclus dans le schéma.

RequestPrd

8.2. Fonctionnalités optionnelles

L'attribut sig_value permet d'attribuer une valeur aux signatures. Les valeurs des signatures sont définies par rôles dans les ItemProcess, avec des valeurs pouvant être OK, KO ou none pour les validations des RequestPrd.

Lorsque la réponse fait référence à un RequestPcd, cela est précisé dans RequestPcd_reference_hash; de même pour les RequestPrd avec request_prd_reference_hash.

Lorsque la réponse fait suite directement à un RequestPcd, cela est indiqué dans RequestPcd_origin_hash; idem pour les RequestPrd avec request_prd_origin_hash.

Les RequestPrdResponse signalent de façon confidentielle :

  • soit des conditions ad hoc déjà remplies via les attributs 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 les preuves ad hoc éventuellement associées aux RequestPcd de la nouvelle version.
  • soit des appels à 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 (dans le cas de paiements temporaires en 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 de messages peuvent accompagner les RequestPrd via message_public, message_confidential, message_private.

Il est également possible de partager des clés de chiffrement ad hoc via certif_key_enc_by_shared_secret.

En plus des horodatages automatiques, il est possible de déclarer un timestamp dans timestamp_declared, qui ne sera pas pris en compte dans le traitement mais sera ainsi tracé dans les éléments de preuve.

Les adresses et les rôles sont précisés en cas d'utilisateurs ayant plusieurs rôles dans les ItemProcess et pour préciser les adresses de réponse en cas d'utilisation sur plusieurs dispositifs.

Tous les échanges sont complétés par l'empreinte du dispositif de l'émetteur, envoyée de façon confidentielle via device_footprint_enc_by_shared_secret.

8.3. Création et envoi

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

  1. Récupération des clés de chiffrement confidentiel des attributs des items d'un RequestPcd.
  2. Chiffrement du RequestPrd avec la clé ProcessKey du ItemProcess concerné.
  3. Création d'une adresse SP pour le partage de la KeyConfidential et pour l'horodatage du hash du RequestPrd dans la side chain.
  4. Création du message contenant le RequestPrd chiffré, la preuve de travail, et l'adresse du faucet.
  5. Sélection de 4 relais pour le message selon l'historique des pings et des réponses obtenues.
  6. Sélection de 4 noeuds de signet pour l'envoi de la transaction SP.
  7. Chiffrement des données confidentielles du RequestPrd avec la KeyConfidential de la transaction SP.
  8. Envoi du message aux relais.
  9. Envoi de la transaction aux noeuds de signet à travers un RequestPrdMessage pour la publication de la transaction SP avec le hash du RequestPrd dans l'attribut request_prd_reference_hash.
  10. Mise à jour du cache avec les nouveaux RequestPrd envoyés (sans mise en cache du RequestPrdMessage).

Voir Silent-Payment-Specs.md.

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
RequestPrdResponse waiting sig_value Yes No See Received No No Yes
RequestPrdConfirm (option) Waiting code_confirm_enc_by_shared_secret Yes No See Received No No No

8.4. 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, 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 request_prd_reference_hash et request_prd_origin_hash, 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, 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 SP correspondante via le hash du RequestPrd dans l'output 2 de la transaction.
  8. Mise à jour du cache pour le traitement des RequestPrd.
  9. Consultation du RequestPrdConfirm pour création et envoi.
  10. Validation des conditions définies dans le ItemProcess pour cet Item, avec le Role correspondant dans le ItemProcess, et dans ces 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.
  11. Traitements spécifiques au type de RequestPrd.
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
RequestPrdResponse Info Yes No No No No
RequestPrdConfirm Info No No No No No

9. RequestPrdList - Demande de Listes ( RequestPcd)

Utile pour les utilisateurs souhaitant 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, tels que les ItemProcess, les ItemMember, les ItemPeer, les ItemPayment, etc.

9.1. Schéma des flux

Pour simplifier, les RequestPrdConfirm n'ont pas été inclus dans le schéma.

RequestPrdList

9.2. Création : Datas spécifiques

  1. Traitement des RequestPrd, avec le type_request.
  2. item_member_enc_by_sp_shared_secret en cas de création d'un nouvel ItemMember (création d'une identité numérique), uniquement destiné aux gestionnaires des membres.
  3. pre_id_sp_enc_by_shared_secret en cas de connexion avec une identité numérique existante, uniquement destiné aux gestionnaires des membres.

9.3. Réception : Datas spécifiques

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

  1. Traitement des RequestPrd.
  2. Recherche en cache de la dernière version de la liste du type d'Item concerné (voir RequestPcd pour la création et l'envoi vers l'émetteur du RequestPrdList).
  3. En cas de item_member_enc_by_sp_shared_secret, pour la création d'un nouvel ItemMember (création d'une identité numérique), cette étape est réservée uniquement aux gestionnaires des membres. L'ItemMember est ajouté au cache sans modifier la liste des membres et associé au pre_id contenu dans l'ItemMember créé.
  4. En cas de pre_id_sp_enc_by_shared_secret, pour la connexion avec une identité numérique existante, cette étape est destinée uniquement aux gestionnaires des membres pour le renvoi du shard correspondant dans le RequestPrdResponse.

10. RequestPrdMessage - Envoi de Messages

Le RequestPrdMessage facilite l'envoi de messages sécurisés entre utilisateurs ou entre utilisateurs et processus/contrats.

Il permet la communication :

  • Directe et sécurisée au sein du réseau, supportant des échanges d'informations critiques ou des notifications entre parties.
  • Des transaction SP au format raw dans l'attribut raw_transaction_list pour la publication de la transaction dans la side chain.

Les RequestPrdMessage peuvent répondre aux autres RequestPrdMessage, sauf en cas d'envoi de raw_transaction_list (dans le cas d'utilisation pour transférer la transaction SP depuis un autre RequestPrd).

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

RequestPrdMessage

10.2. Création : Datas spécifiques

  1. Traitement des RequestPrd, avec le type_request spécifiquement attribué au RequestPrdMessage.
  2. Cas de la transmission d'une Transaction SP depuis un autre RequestPrd au format raw dans l'attribut raw_transaction_list, pour la publication de la transaction dans la side chain.

10.3. Réception : Datas spécifiques

  1. Traitements des RequestPrd

11. RequestPrdUpdate - Mises à Jour de RequestPcd

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

Basé sur le RequestPrd, avec des ajouts 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, la mise à jour de la liste des membres permet d'ajouter de nouveaux utilisateurs à un ItemProcess, et la mise à jour de la liste des ItemProcess permet de leur affecter un nouveau Role.

Les RequestPrdUpdate signalent au réseau, via l'attribut RequestPcd_new_version_hash, les nouvelles versions des RequestPcd.

11.1. Schéma des flux

Pour simplifier, les RequestPrdConfirm n'ont pas été représentés dans le schéma.

RequestPrdUpdate

11.2. Création : Datas spécifiques

  1. Traitement des RequestPrd, avec le type_request spécifiquement attribué aux RequestPrdUpdate.
  2. Pas de données spécifiques.

11.3. Réception : Datas spécifiques

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

  1. Traitement des RequestPrd.
  2. Comparaison de la dernière version du RequestPcd en cache avec la nouvelle version du RequestPcd associée, via RequestPcd_new_version_hash, et attente si nécessaire.

12. 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 suite à 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, lequel doit être confirmé dans le RequestPrdConfirm.

12.1. Schéma des flux

RequestPrdConfirm

12.2. Création : Datas spécifiques

  1. Traitement des RequestPrd, avec le type_request spécifiquement attribué aux RequestPrdConfirm.
  2. Communication éventuelle d'un code_confirm_enc_by_shared_secret à confirmer dans le RequestPrdConfirm.

12.3. Réception : Datas spécifiques

  1. Traitement des RequestPrd, sans traitement supplémentaire.
  2. Vérification du code_confirm_enc_by_shared_secret dans le RequestPrdConfirm reçu.

13. 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 sont utilisés pour répondre aux RequestPrdList, RequestPrdUpdate, facilitant la fourniture de feedbacks, de confirmations, ou d'instructions supplémentaires en réponse aux demandes initiales. Ils supportent une communication bidirectionnelle sécurisée et vérifiable.

C'est également le moyen par lequel demander des moyens de paiement, de dépôt, ou de preuve, puis de partager le payload de ces actions.

13.1. Schéma des flux

Pour simplifier, les RequestPrdConfirm n'ont pas été représentés dans le schéma.

RequestPrdResponse

13.2. Création : Datas spécifiques

  1. Traitement des RequestPrd, avec le type_request spécifiquement attribué à RequestPrdResponse.
  2. Attente de la valeur de la signature de l'utilisateur sig_value (si celle-ci n'est pas automatique).
  3. En cas de réponse à un RequestPrdKeyList, fourniture de pre_id_enc_by_sp_shared_secret avec les shards correspondant à la pre-id demandée.
  4. (Optionnel) Partage d'une clé de chiffrement ad hoc via shared_secret_key.

13.3. Réception : Datas spécifiques

  1. Traitement des RequestPrd.
  2. Vérification des conditions de validation des RequestPcd associés.
  3. En cas de réponse reçue pour un RequestPrdList : récupération des shards correspondant à la pre-id demandée et génération de la clé KeyRecover.

14. Exemples de Code

15. Todo

[ ] Définition claire de request-type [ ] Description détaillée de tous les éléments (attributs) qui composent le request-type: [ ] Quy a-t-il dans le request-type? [ ] A quoi sert lattribut X du request-type? [ ] Description un par un des contextes où le request-type est utilisé. [ ] Description pas à pas de lenvoi du request-type. [ ] Que se passe-t-il dans le système lorsque le request-type est envoyé? [ ] 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 dutilisation.