From d61b3355a73319bdb823dd00745a6926a1ba87d1 Mon Sep 17 00:00:00 2001 From: NicolasCantu Date: Tue, 19 Mar 2024 13:28:36 +0100 Subject: [PATCH] Principles of Messaging added (doc) --- doc/Item-Specs.md | 6 +- doc/PRD-PCD-Specs.md | 160 +++++++++++++++++++++++++--------------- doc/Specs-Datamodel.md | 5 -- doc/Specs-Definition.md | 2 +- 4 files changed, 101 insertions(+), 72 deletions(-) diff --git a/doc/Item-Specs.md b/doc/Item-Specs.md index 2240fbf..35552c4 100644 --- a/doc/Item-Specs.md +++ b/doc/Item-Specs.md @@ -12,11 +12,7 @@ * 5. [Exemples de Code](#ExemplesdeCode) * 6. [Todo](#Todo) - -# Item - Specs +# Item - Specs ## 1. Objectif diff --git a/doc/PRD-PCD-Specs.md b/doc/PRD-PCD-Specs.md index 4e5ab74..ba202f7 100644 --- a/doc/PRD-PCD-Specs.md +++ b/doc/PRD-PCD-Specs.md @@ -2,40 +2,42 @@ * 1. [Objectif](#Objectif) * 2. [Portée](#Porte) * 3. [Documents de référence](#Documentsderfrence) -* 4. [Encryption](#Encryption) -* 5. [Définitions](#Dfinitions) -* 6. [Principe de messagerie](#Principedemessagerie) -* 6.1. [Création et envoi](#Crationetenvoi) -* 6.2. [Réception](#Rception) +* 4. [Définitions](#Dfinitions) +* 5. [Principes de messagerie](#Principesdemessagerie) + * 5.1. [`RequestPrdConfirm`](#RequestPrdConfirm) + * 5.2. [`RequestPrdResponse`](#RequestPrdResponse) +* 6. [Encryption](#Encryption) + * 6.1. [Création et envoi](#Crationetenvoi) + * 6.2. [Réception](#Rception) * 7. [Fonction des RequestPcd](#FonctiondesRequestPcd) -* 7.1. [Schéma des flux](#Schmadesflux) -* 7.2. [Création et envoi](#Crationetenvoi-1) -* 7.3. [Réception](#Rception-1) + * 7.1. [Schéma des flux](#Schmadesflux) + * 7.2. [Création et envoi](#Crationetenvoi-1) + * 7.3. [Réception](#Rception-1) * 8. [Fonction des`RequestPrd`](#FonctiondesRequestPrd) -* 8.1. [Schéma des flux](#Schmadesflux-1) -* 8.2. [Fonctionnalités optionnelles](#Fonctionnalitsoptionnelles) -* 8.3. [Création et envoi](#Crationetenvoi-1) -* 8.4. [Réception](#Rception-1) + * 8.1. [Schéma des flux](#Schmadesflux-1) + * 8.2. [Fonctionnalités optionnelles](#Fonctionnalitsoptionnelles) + * 8.3. [Création et envoi](#Crationetenvoi-1) + * 8.4. [Réception](#Rception-1) * 9. [RequestPrdList - Demande de Listes ( RequestPcd)](#RequestPrdList-DemandedeListesRequestPcd) -* 9.1. [Schéma des flux](#Schmadesflux-1) -* 9.2. [Création : Datas spécifiques](#Cration:Datasspcifiques) -* 9.3. [Réception : Datas spécifiques](#Rception:Datasspcifiques) + * 9.1. [Schéma des flux](#Schmadesflux-1) + * 9.2. [Création : Datas spécifiques](#Cration:Datasspcifiques) + * 9.3. [Réception : Datas spécifiques](#Rception:Datasspcifiques) * 10. [RequestPrdMessage - Envoi de Messages](#RequestPrdMessage-EnvoideMessages) -* 10.1. [Schéma des flux](#Schmadesflux-1) -* 10.2. [Création : Datas spécifiques](#Cration:Datasspcifiques-1) -* 10.3. [Réception : Datas spécifiques](#Rception:Datasspcifiques-1) + * 10.1. [Schéma des flux](#Schmadesflux-1) + * 10.2. [Création : Datas spécifiques](#Cration:Datasspcifiques-1) + * 10.3. [Réception : Datas spécifiques](#Rception:Datasspcifiques-1) * 11. [RequestPrdUpdate - Mises à Jour de RequestPcd](#RequestPrdUpdate-MisesJourdeRequestPcd) -* 11.1. [Schéma des flux](#Schmadesflux-1) -* 11.2. [Création : Datas spécifiques](#Cration:Datasspcifiques-1) -* 11.3. [Réception : Datas spécifiques](#Rception:Datasspcifiques-1) + * 11.1. [Schéma des flux](#Schmadesflux-1) + * 11.2. [Création : Datas spécifiques](#Cration:Datasspcifiques-1) + * 11.3. [Réception : Datas spécifiques](#Rception:Datasspcifiques-1) * 12. [RequestPrdConfirm - Confirmation de Réception](#RequestPrdConfirm-ConfirmationdeRception) -* 12.1. [Schéma des flux](#Schmadesflux-1) -* 12.2. [Création : Datas spécifiques](#Cration:Datasspcifiques-1) -* 12.3. [Réception : Datas spécifiques](#Rception:Datasspcifiques-1) + * 12.1. [Schéma des flux](#Schmadesflux-1) + * 12.2. [Création : Datas spécifiques](#Cration:Datasspcifiques-1) + * 12.3. [Réception : Datas spécifiques](#Rception:Datasspcifiques-1) * 13. [RequestPrdResponse - Répondre à une Demande](#RequestPrdResponse-RpondreuneDemande) -* 13.1. [Schéma des flux](#Schmadesflux-1) -* 13.2. [Création : Datas spécifiques](#Cration:Datasspcifiques-1) -* 13.3. [Réception : Datas spécifiques](#Rception:Datasspcifiques-1) + * 13.1. [Schéma des flux](#Schmadesflux-1) + * 13.2. [Création : Datas spécifiques](#Cration:Datasspcifiques-1) + * 13.3. [Réception : Datas spécifiques](#Rception:Datasspcifiques-1) * 14. [Exemples de Code](#ExemplesdeCode) * 15. [Todo](#Todo) @@ -53,7 +55,76 @@ La spécification couvre la conception, le développement, et l'application prat Voir [_Doc_references.md](_Doc_references.md). -## 4. Encryption +## 4. 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 des autres `RequestPrd` à 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` (à l'exception de `RequestPrdConfirm` eux-même). + * `RequestPrdResponse`: Réponse aux autres types de `RequestPrd` (à l'exception de `RequestPrdConfirm`, `RequestPrdResponse` et `RequestPrdMessage`). + +* **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](SpecsDefinition.md)) 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`. + +## 5. Principes de messagerie + +Les `RequestPcd` sont envoyés à tous les participants connectés sans attente de retour spécifique et ne sont pas associés à une `transaction SP`. + +Les `RequestPrd` sont toujours accompagnés d'une `transaction SP`, transmise dans l'attribut `raw_transaction_list` d'un `RequestPrdMessage` associé (à l'exception des `RequestPrdMessage` eux-mêmes). + +Les `RequestPrd` sont des demandes d'actions ou des réponses à ces demandes, interagissant de la manière suivante : + +* `RequestPrdList` : Constitue généralement la première requête d'un workflow et ne répond pas à un autre `RequestPrd`. +* `RequestPrdMessage`, avec 2 cas de figure : + * Demande de relais d'une `transaction SP`, dans ce cas, le `RequestPrdMessage` ne répond pas à un autre `RequestPrd`. + * Envoi de message, pouvant initier un échange de messagerie ou répondre à un autre `RequestPrdMessage`. +* `RequestPrdUpdate` : Souvent la première requête d'un workflow, un `RequestPrdUpdate` ne répond pas à un autre `RequestPrd`. +* `RequestPrdConfirm` : Répond à tous les autres types de `RequestPrd` (à l'exception des `RequestPrdConfirm` eux-mêmes). +* `RequestPrdResponse` : Répond à tous les autres types de `RequestPrd` (à l'exception des `RequestPrdConfirm`, `RequestPrdMessage` et `RequestPrdResponse` eux-mêmes). Dans le cas d'une réponse à un `RequestPrdList` ou d'un `RequestPrdUpdate`, le `RequestPrdResponse` doit obligatoirement être accompagné d'un `RequestPcd`. + +On fonction des `RequestPrd` les demandes vont d'adresser à tous les membres de l'`ItemProcess`, ou aux gestionnaires du type d'`Item` concerné ou simplement à l'émetteur, selon : + +* `RequestPrdList` : Envoyé aux gestionnaires du type d'`Item` concerné +* `RequestPrdMessage`, avec 2 cas de figure : + * Demande de relais d'une `transaction SP`, dans ce cas, le destinaire du `RequestPrd`assiocié. + * Envoi de message au destinaire du message. +* `RequestPrdUpdate` : Envoyé aux gestionnaires du type d'`Item` concerné +* `RequestPrdConfirm` : Envoyé à l'emetteur du `RequestPrd`assiocié. +* `RequestPrdResponse`, avec 2 cas de figure : + * Réponse à un `RequestPrdList`: envoie à l'emetteur du `RequestPrdList` + * Réponse à un `RequestPrdUpdate`: envoue à tous les membres et à l'émetteur du `RequestPrdUpdate` + +Les traitements des `RequestPrd` varient selon leur type, principalement autour des aspects suivants : + +* **Notification utilisateur** : Nécessité de notifier l'utilisateur courant, ou non. +* **`transaction SP` + `RequestPrdMessage`** : Envoi d'une `transaction SP` dans un `RequestPrdMessage`, ou non. +* **`RequestPcd` à envoyer** : Envoi d'un `RequestPcd` en complément du `RequestPrd`. +* **`request_type` envoyé à** : Membres qui recevront les `transaction SP` et les `RequestPrdMessage` correspondants, avec les clés de déchiffrement pour les champs confidentiels. +* **Attente d'une réponse `RequestPcd`** : Attente d'un `RequestPcd` en retour, ou non. +* **Attente d'une réponse `RequestPrdResponse`** : Attente d'un ou de plusieurs `RequestPrdResponse` en retour, ou non. +* **Attente d'une réponse `RequestPrdConfirm`** : Attente d'un `RequestPrdConfirm` en retour, ou non. + +Ce qui est résumé ici : + +| `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. Encryption Schema : @@ -69,31 +140,6 @@ Les `Metadata` des `Item` des `RequestPcd` et les attributs des `RequestPcd` et * **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` (à l'exception de `RequestPrdConfirm` eux-même). - * `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](SpecsDefinition.md)) 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. Principes 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. @@ -209,14 +255,6 @@ La création d'un `RequestPrd` suit plusieurs étapes : Voir [Silent-Payment-Specs.md](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 : diff --git a/doc/Specs-Datamodel.md b/doc/Specs-Datamodel.md index 7d0d769..36b1373 100644 --- a/doc/Specs-Datamodel.md +++ b/doc/Specs-Datamodel.md @@ -110,11 +110,6 @@ * 14.6. [PartialOrd, Ord](#PartialOrdOrd) * 15. [Todo](#Todo) - - # Specs - Datas ## 1. Documents de référence diff --git a/doc/Specs-Definition.md b/doc/Specs-Definition.md index 1d00475..9b24974 100644 --- a/doc/Specs-Definition.md +++ b/doc/Specs-Definition.md @@ -25,7 +25,7 @@ Voir [_Doc_references.md](_Doc_references.md). * **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. + * `RequestPrdMessage`: Envoi de messages publics, confidentiels ou privés et/ou de transactions Silent Payments des autres `RequestPrd` à 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` (à l'exception de `RequestPrdConfirm` eux-même). * `RequestPrdResponse`: Réponse aux autres types de `RequestPrd` (à l'exception de `RequestPrdConfirm` et `RequestPrdResponse`).