From 5e10b6b10f4577d9a567a3ef266a94e5da773fe4 Mon Sep 17 00:00:00 2001 From: FabioPinheiro Date: Thu, 7 Mar 2024 21:30:42 +0000 Subject: [PATCH] Improve the provecontrol protocol documentation --- .../protocol/provecontrol/ProveControl.md | 122 ++++++++++++------ .../protocol/provecontrol/ProveControl.scala | 8 +- .../protocol/provecontrol/UserRegister.md | 41 ++++++ 3 files changed, 127 insertions(+), 44 deletions(-) create mode 100644 did/shared/src/main/scala/fmgp/did/comm/protocol/provecontrol/UserRegister.md diff --git a/did/shared/src/main/scala/fmgp/did/comm/protocol/provecontrol/ProveControl.md b/did/shared/src/main/scala/fmgp/did/comm/protocol/provecontrol/ProveControl.md index 0f7677db..3be89494 100644 --- a/did/shared/src/main/scala/fmgp/did/comm/protocol/provecontrol/ProveControl.md +++ b/did/shared/src/main/scala/fmgp/did/comm/protocol/provecontrol/ProveControl.md @@ -1,47 +1,64 @@ # Prove Control Protocol +This protocol is used a proof control of external identities. --> Request verification -<- Verification Challenge --> Prove -<- Confirm Verification - -type verificationType: -- Email -- DID -- Discord -- Tel -- Domain -- IP -- Address - -fmgp.app/1/requestverification - - `to` - - `from` - - `verificationType` - - `subject` -fmgp.app/1/verificationchallenge - - `to` - - `from` - - `verificationType` - - `subject` - - `secret` (only the 'to' can see) -fmgp.app/1/prove - - `to` - - `from` - - `verificationType` - - `subject` - - `proof` -fmgp.app/1/confirmverification - - `to` - - `from` - - `verificationType` - - `subject` - - `attachments` +- **Verifier** - The Verifier is a well-known DID that is trusted and the provides a verification service. It will challenge the User to prove the control over other identity. It then issues a statement (VC) as the User was control over that external identity. +- **User** - The User is another DID that they have other identities (like an email) and wants to prove control over it. + +## Type verificationType: + - Email (read) + > User proof is able to read email on a specific email address. By receiving an email that contains an encrypted message for the User, which the user can create the message `prove` to send directly Verifier. Note: it can be a shared email + - Domain + > User proof that it's in control of the Domain by being able to edit the content in the DNS server. + By creating a new entry of the type `TXT` when the key is the `id` of the message `verificationchallenge`, and the value is the `proof` of the message `prove`. + - Discord (read) + > User proof is able to read direct message on a specific account. + - Tel (read) + > User proof that the able to receive SMS to a specific number. + Note: An encrypted message is probably too big for a SMS + - DID + > User proof is in possession of the private keys of (other) DID by reading and signing a statement with one of those keys. + - IP (read) + > Note: The IP probably too ephemeral + - Address (read) + > User proof is able to receive physical mail. Like Google use case to verify shop owners. + +## message structure + +- fmgp.app/provecontrol/1/requestverification + > This message is a request from the User to Verifier. To start the verification process over some specific subject (liek an email address, a domain, etc) + - `to` + - `from` + - `verificationType` + - `subject` +- fmgp.app/provecontrol/1/verificationchallenge + > This is encrypted message from the Verifier to the User. That challenge the User according to the `verificationType`. + - `to` + - `from` + - `verificationType` + - `subject` + - `secret` (only the 'to' can see, because the message is encrypted) +- fmgp.app/provecontrol/1/prove + > This message is from the User to the Verifier. + - `to` + - `from` + - `verificationType` + - `subject` + - `proof` +- fmgp.app/provecontrol/1/confirmverification + > This is a sign message from the Verifier to the User. It works like a VC verifiable credential. It's a statement from the Verifier that confirms that the User proofed the `verificationType` about the subject to him. The user can use this statement (VC) to show other DIDs that trust this Verifier. + - `to` + - `from` + - `verificationType` + - `subject` ## Calculate Proof +The `proof` is a string (in the message `prove`) that can only be generated. From the decrypted `verificationchallenge` message type. + +Should be calculated according to the following: + ```scala def calculateProof( verifier: DIDSubject, // TO in Prove == FROM in VerificationChallenge @@ -52,7 +69,32 @@ def calculateProof( ) = SHA256.digestToHex(s"$verifier|$hoder|$verificationType|$subject|$secret") ``` -# Connection Gateway Protocol --> Register -<- Registration \ No newline at end of file +## Flow + +1. `User -> Verifier` (optional) : requestverification +2. `User <- Verifier` : verificationchallenge +3. `User -> Verifier` : prove +4. `User <- Verifier` : confirmverification + +```mermaid +sequenceDiagram + participant I as Extrenal_Identity + participant W as Wallet + participant V as Verifier + + Note over W: User wallet + Note over I: User Identity to verify like Email/Tel/Discord/etc + Note over V: A DID that provide a service to verify control of external identity. + + %%rect rgb(191, 223, 255) + W->>+V: 'request verification' DID Comm over http + V->>-I: 'verification_challenge' DID Comm over Email + I-->>W: open the encryted DID Comm Msg + W-->>W: decrypt the message and generate + W-->>W: generate a proof that you were able to read the message + W->>+V: 'prove' (DID Comm Msg over http) + V->>-W: 'confirm_verification' sign DID Comm Msg over http + W-->>W: Store the 'confirm_verification' sign DID Comm Msg as a VC + %%end +``` diff --git a/did/shared/src/main/scala/fmgp/did/comm/protocol/provecontrol/ProveControl.scala b/did/shared/src/main/scala/fmgp/did/comm/protocol/provecontrol/ProveControl.scala index ec240e68..b448ad72 100644 --- a/did/shared/src/main/scala/fmgp/did/comm/protocol/provecontrol/ProveControl.scala +++ b/did/shared/src/main/scala/fmgp/did/comm/protocol/provecontrol/ProveControl.scala @@ -53,7 +53,7 @@ case class RequestVerification( } object RequestVerification { - def piuri = PIURI("https://fmgp.app/provecontrol/0.1/requestverification") + def piuri = PIURI("https://fmgp.app/provecontrol/1/requestverification") protected final case class Body(verificationType: VerificationType, subject: String) { @@ -133,7 +133,7 @@ case class VerificationChallenge( /** This message MUST be send using the transport in 'verificationType' */ object VerificationChallenge { - def piuri = PIURI("https://fmgp.app/provecontrol/0.1/verificationchallenge") + def piuri = PIURI("https://fmgp.app/provecontrol/1/verificationchallenge") export Prove.calculateProof @@ -198,7 +198,7 @@ case class Prove( } object Prove { - def piuri = PIURI("https://fmgp.app/provecontrol/0.1/prove") + def piuri = PIURI("https://fmgp.app/provecontrol/1/prove") def calculateProof( verifier: DIDSubject, // TO in Prove == FROM in VerificationChallenge @@ -273,7 +273,7 @@ case class ConfirmVerification( } object ConfirmVerification { - def piuri = PIURI("https://fmgp.app/provecontrol/0.1/confirmverification") + def piuri = PIURI("https://fmgp.app/provecontrol/1/confirmverification") protected final case class Body(verificationType: VerificationType, subject: String) { diff --git a/did/shared/src/main/scala/fmgp/did/comm/protocol/provecontrol/UserRegister.md b/did/shared/src/main/scala/fmgp/did/comm/protocol/provecontrol/UserRegister.md new file mode 100644 index 00000000..a574ec39 --- /dev/null +++ b/did/shared/src/main/scala/fmgp/did/comm/protocol/provecontrol/UserRegister.md @@ -0,0 +1,41 @@ +# User Register Protocol + +TODO + +## User Registration process of Extrenal Identity + +```mermaid +sequenceDiagram + participant W as Wallet + participant R as Registy + participant O as Another_DID + + Note over R: A DID that provide a service of connecting + + %% rect rgb(191, 180, 255) + Note over W,O: Registration logic TODO + W->>+R: 'registar' DID Comm over http + R->>-W: 'registration_status' + + Note over W,O: Add Information logic + W->>+R: 'add' DID Comm over http + R->>R: check the VC ('fmgp.app/provecontrol/1/confirmverification') inside 'add' message. Must be valid and from a DID that is trust worth. + R->>-W: 'registration_status' + %% end + + %% rect rgb(191, 223, 200) + Note over W,O: Query Logic + O->>+R: Ask to get in connect with the extrenal Identity + R->>+W: Infor the DID that controls the external identity + R->>-O: Informed that external identity is or not Registered + W->>-O: Start a conversation + %% end + +%% rect rgb(191, 180, 255) +%% end + +%% rect rgb(250, 223, 200) +%% loop Do (M) Operations +%% end +%% end +``` \ No newline at end of file