sdk_common/doc/PRD-PCD-Specs.md

• 1. Objectif
• 2. Portée
• 3. 3. Documents de référence
• 4. Commun aux RequestPcd et RequestPrd
  • 4.1. Création et envoi
  • 4.2. Réception
• 5. Fonction des RequestPcd
  • 5.1. Schéma des flux
  • 5.2. Création et envoi
  • 5.3. Réception
• 6. Fonction des RequestPrd
  • 6.1. Schéma des flux
  • 6.2. Fonctionnalités optionnelles
  • 6.3. Création et envoi
  • 6.4. Réception
• 7. RequestPrdList - Demande de Listes ( RequestPcd)
  • 7.1. Schéma des flux
  • 7.2. Création : Datas spécifiques
  • 7.3. Réception : Datas spécifiques
• 8. RequestPrdMessage - Envoi de Messages
  • 8.1. Schéma des flux
  • 8.2. Création : Datas spécifiques
  • 8.3. Réception : Datas spécifiques
• 9. RequestPrdUpdate - Mises à Jour de RequestPcd
  • 9.1. Schéma des flux
  • 9.2. Création : Datas spécifiques
  • 9.3. Réception : Datas spécifiques
• 10. RequestPrdConfirm - Confirmation de Réception
  • 10.1. Schéma des flux
  • 10.2. Création : Datas spécifiques
  • 10.3. Réception : Datas spécifiques
• 11. RequestPrdResponse - Répondre à une Demande
  • 11.1. Schéma des flux
  • 11.2. Création : Datas spécifiques
  • 11.3. Réception : Datas spécifiques
• 12. Exemples de Code
• 13. Todo

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

Voir _Doc_references.md.

4. Commun aux RequestPcd et RequestPrd

Encryption :

4.1. Création et envoi

w 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 ItemProcess concerné.

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

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

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

Réception du message: voir 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. 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).

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. Schéma des flux

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

5.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 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. 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'unetransaction SP (cf. Specs-Security.md). Ces clés ne sont distribués qu'aux members concernés par les Item des RequestPcd (rôles dans les ItemProcess ).

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. Schéma des flux

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

6.2. 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 request_prd_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 request_prd_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 ItemProcess 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.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'uneadresse SP 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, l'adresse de faucet
5. Sélection de 4 relais pour le message selon l'historique des pings et des réponses retournées.
6. Sélection de 4 noeuds de signet pour l'envoi de latransaction SP.
7. Chiffrement des données confidentielles du request_prd avec la KeyConfidential de latransaction SP.
8. Envoi du message aux relais
9. Envoi de la transaction aux noeuds de signet à travers un RequestPrdMessage pour la publication de latransaction SP avec le hash du RequestPrd dans l'attribut request_prd_reference_hash.
10. Mis à jour du cache avec les nouveaux RequestPrd envoyé (pas de mis 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

6.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 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 request_prd_reference_hash et request_prd_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 latransaction SP correspondante via hash du RequestPrd dans l'output 2 de la transaction.
8. Mise à jour du cache pour les traitement des RequestPrd.
9. Voir RequestPrdConfirm création et envoi.
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.
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

7. 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ésweau. Chaque RequestPcd liste des Item d'un même type, par exemple les ItemProcess, les ItemMember, les ItemPeer, les ItemPayment, etc.

7.1. Schéma des flux

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

7.2. Création : Datas spécifiques

1. Traitements des RequestPrd, avec le type_request
2. item_member_enc_by_sp_shared_secret en cas de création d'un nouveau ItemMember (création d'un identité numérique), uniquement vers les gestionnaires des membres
3. pre_id_sp_enc_by_shared_secret en cas de connexion avec une identité numérique existante, uniquement ver les gestionnaires des membres

7.3. Réception : Datas spécifiques

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

1. Traitements des RequestPrd
2. Recherche en cache de la dernière version de la liste du type d'Item concerné (voir RequestPcd Création et envoi vers l'émetteur du RequestPrdList)
3. Si item_member_enc_by_sp_shared_secret en cas de création d'un nouveau ItemMember (création d'un identité numérique), uniquement vers les gestionnaires des membres et ajout en cache sans modifier la liste des membres et associé au pre_id contenu dans l'ItemMember créé.
4. Si pre_id_sp_enc_by_shared_secret en cas de connexion avec une identité numérique existante, uniquement ver les gestionnaires des membres pour renvoi du shard correspondant dans le RequestPrdResponse

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.
• destransaction SP au format raw dans l'attribut raw_transaction_list pour la publication de la transaction dans la side chain.

Les RequestPrdMessage répondent aux RequestPrdMessage sauf en cas d'envoi de raw_transaction_list (cas d'utilisation du afin de transaférer la transaction SP d'un autre RequestPrd).

8.1. Schéma des flux

Pour simplifier les RequestPrdConfirm n'ont pas été représentés dans le schéma. Cas d'un RequestPrdMesage avec raw_transaction_list vide (et son RequestPrdMessage avec raw_transaction_list non vide).

8.2. Création : Datas spécifiques

1. Traitements des RequestPrd, avec le type_request spécifique à RequestPrdMessage
2. Cas de la transmission d'une Transaction SP d'un autre vRequestPrdau formatrawdans l'attributraw_transaction_list` pour la publication de la transaction dans la side chain.

8.3. Réception : Datas spécifiques

1. Traitements des RequestPrd

9. 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 ItemProcess , la mise à jour de la liste des ItemProcess 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. Schéma des flux

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

9.2. Création : Datas spécifiques

1. Traitements des RequestPrd, avec le type_request spécifique à RequestPrdUpdate
2. Pas de data spécifiques.

9.3. Réception : Datas spécifiques

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

1. Traitements des RequestPrd
2. Comparaison de la dernirère version du RequestPcd en cache et de nouvelle version du RequestPcd associé via RequestPcd_new_version_hash et attente si nécessaire.

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

10.1. Schéma des flux

10.2. Création : Datas spécifiques

1. Traitements des RequestPrd, avec le type_request spécifique à RequestPrdConfirm
2. Communication éventuelle d'un code_confirm_enc_by_shared_secret à confirmer dans le RequestPrdConfirm.

10.3. Réception : Datas spécifiques

1. Traitements des RequestPrd, pas de traitement suppplémentaire.
2. Vérification du code_confirm_enc_by_shared_secret dans le RequestPrdConfirm reçu.

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

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. Schéma des flux

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

11.2. Création : Datas spécifiques

1. Traitements des RequestPrd, avec le type_request spécifique à RequestPrdResponse
2. Attente de la valeur de la signature de l'utilisateur sig_value (si non automatique)
3. En cas de réponse à RequestPrdKeyList :pre_id_enc_by_sp_shared_secret avec les shards correspondants à la pre-id demandée.
4. (option) shared_secret_key paratage d'une clé de chiffrement ad'hoc

11.3. Réception : Datas spécifiques

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

12. Exemples de Code

13. Todo

• Diagrammes de séquences