From 45d9c5bc9d0932e65723de7ab39befc1aab98e0e Mon Sep 17 00:00:00 2001 From: Markus Sabadello <markus@danubetech.com> Date: Fri, 29 Mar 2024 11:10:36 +0100 Subject: [PATCH] Various additional information about states. --- index.html | 33 +++++++++++++++++++++++---------- spec/spec.md | 33 +++++++++++++++++++++++---------- 2 files changed, 46 insertions(+), 20 deletions(-) diff --git a/index.html b/index.html index 01b767b..8020c85 100644 --- a/index.html +++ b/index.html @@ -450,6 +450,19 @@ <h3 id="jobid"><a class="toc-anchor" href="#jobid" >§</a> <code>jobId</code></h <span class="token punctuation">}</span> </code></pre> <h3 id="didstate"><a class="toc-anchor" href="#didstate" >§</a> <code>didState</code></h3> +<p>This output field contains an object with the following fields:</p> +<ul> +<li><a href="#didstatestate" ><code>didState.state</code></a>: The current state of DID operations.</li> +<li><a href="#didstatedid" ><code>didState.did</code></a>: The DID at the end of the DID operation.</li> +<li><a href="#didstatesecret" ><code>didState.secret</code></a>: An object with DID controller keys and other secrets.</li> +<li><a href="#didstatediddocument" ><code>didState.didDocument</code></a>: The DID document after the DID operation has been successfully executed.</li> +</ul> +<p>In <a href="#client-managed-secret-mode" >Client-managed Secret Mode</a>, this output field MAY contain one or more of the following:</p> +<ul> +<li>A <code>verificationMethodTemplate</code> property with a JSON array containing one or more <a href="#verification-method-template" >Verification Method Template</a> objects.</li> +<li>A <code>signingRequest</code> property with a <a href="#signing-request-set" >Signing Request Set</a>.</li> +<li>A <code>decryptionRequest</code> property with a <a href="#decryption-request-set" >Decryption Request Set</a>.</li> +</ul> <h4 id="didstatestate"><a class="toc-anchor" href="#didstatestate" >§</a> <code>didState.state</code></h4> <p>This output field contains the current state of the DID operations. It is used to indicate if a DID operation is finished, failed, or if a longer-running “job” has been created that requires additional steps.</p> @@ -773,11 +786,11 @@ <h3 id="didstatestatewait"><a class="toc-anchor" href="#didstatestatewait" >§</ <h2 id="data-structures"><a class="toc-anchor" href="#data-structures" >§</a> Data Structures</h2> <p>This specification defines a number of data structures that appear in the <a href="#input-fields" >input fields</a> and <a href="#output-fields" >output fields</a>.</p> <h3 id="verification-method-public-data"><a class="toc-anchor" href="#verification-method-public-data" >§</a> Verification Method Public Data</h3> -<p>This data structure is used when public data about a verification method is exchanged between the client and the DID Registrar, as follows:</p> +<p>This data structure is used as follows, when public data about a verification method is exchanged between the client and the DID Registrar:</p> <ul> -<li>In <a href="#client-managed-secret-mode" >Client-managed Secret Mode</a> inside the <a href="#secret" ><code>secret</code> input field</a>, +<li>In <a href="#client-managed-secret-mode" >Client-managed Secret Mode</a> as a <code>verificationMethod</code> field inside the <a href="#secret" ><code>secret</code> input field</a>, when the client invokes the DID Registrar again after it received a <a href="#didstateactiongetverificationmethod" ><code>didState.action="getVerificationMethod"</code> output field</a>.</li> -<li>In <a href="#client-managed-secret-mode" >Client-managed Secret Mode</a> inside the <a href="#didstatesecret" ><code>didState.secret</code> output field</a>, +<li>In <a href="#client-managed-secret-mode" >Client-managed Secret Mode</a> as a <code>verificationMethod</code> field inside the <a href="#didstatesecret" ><code>didState.secret</code> output field</a>, when the DID Registrar responds to a client request.</li> </ul> <p>A <strong>Verification Method Public Data</strong> structure is a JSON object based on the verification method @@ -817,11 +830,11 @@ <h3 id="verification-method-public-data"><a class="toc-anchor" href="#verificati <span class="token punctuation">}</span> </code></pre> <h3 id="verification-method-private-data"><a class="toc-anchor" href="#verification-method-private-data" >§</a> Verification Method Private Data</h3> -<p>This data structure is used when private data about a verification method is exchanged between the client and the DID Registrar, as follows:</p> +<p>This data structure is used as follows, when private data about a verification method is exchanged between the client and the DID Registrar:</p> <ul> -<li>In <a href="#internal-secret-mode" >Internal Secret Mode</a> inside the <a href="#secret" ><code>secret</code> input field</a>, +<li>In <a href="#internal-secret-mode" >Internal Secret Mode</a> as a <code>verificationMethod</code> field inside the <a href="#secret" ><code>secret</code> input field</a>, when the client invokes the DID Registrar again after it received a <a href="#didstateactiongetverificationmethod" ><code>didState.action="getVerificationMethod"</code> output field</a>.</li> -<li>In <a href="#internal-secret-mode" >Internal Secret Mode</a> inside the <a href="#didstatesecret" ><code>didState.secret</code> output field</a>, +<li>In <a href="#internal-secret-mode" >Internal Secret Mode</a> as a <code>verificationMethod</code> field inside the <a href="#didstatesecret" ><code>didState.secret</code> output field</a>, when the DID Registrar responds to a client request.</li> </ul> <p>A <strong>Verification Method Private Data</strong> structure is a JSON object based on the <a href="#verification-method-public-data" >Verification Method Public Data</a> @@ -857,7 +870,7 @@ <h3 id="verification-method-private-data"><a class="toc-anchor" href="#verificat <h3 id="verification-method-template"><a class="toc-anchor" href="#verification-method-template" >§</a> Verification Method Template</h3> <p>This data structure is used as follows:</p> <ul> -<li>In <a href="#client-managed-secret-mode" >Client-managed Secret Mode</a> inside the <a href="#didstatestate" ><code>didState.state</code> output field</a>, +<li>In <a href="#client-managed-secret-mode" >Client-managed Secret Mode</a> as <code>verificationMethodTemplate</code> field inside the <a href="#didstate" ><code>didState</code> output field</a>, when the DID Registrar responds to a client request with a <a href="#didstateactiongetverificationmethod" ><code>didState.action="getVerificationMethod"</code> output field</a>.</li> </ul> <p>A <strong>Verification Method Template</strong> structure is a JSON object based on the verification method @@ -892,7 +905,7 @@ <h3 id="verification-method-template"><a class="toc-anchor" href="#verification- <h3 id="signing-request-set"><a class="toc-anchor" href="#signing-request-set" >§</a> Signing Request Set</h3> <p>This data structure is used as follows:</p> <ul> -<li>In <a href="#client-managed-secret-mode" >Client-managed Secret Mode</a> as a <code>signingRequest</code> field inside the <a href="#didstatestate" ><code>didState.state</code> output field</a>, +<li>In <a href="#client-managed-secret-mode" >Client-managed Secret Mode</a> as a <code>signingRequest</code> field inside the <a href="#didstate" ><code>didState</code> output field</a>, when the DID Registrar responds to a client request with a <a href="#didstateactionsignpayload" ><code>didState.action="signPayload"</code> output field</a>.</li> </ul> <p>A <strong>Signing Request Set</strong> structure is a JSON object. Each property name in that JSON object is called a <em>signing request ID</em>, and @@ -959,7 +972,7 @@ <h3 id="signing-response-set"><a class="toc-anchor" href="#signing-response-set" <h3 id="decryption-request-set"><a class="toc-anchor" href="#decryption-request-set" >§</a> Decryption Request Set</h3> <p>This data structure is used as follows:</p> <ul> -<li>In <a href="#client-managed-secret-mode" >Client-managed Secret Mode</a> inside the <a href="#didstatestate" ><code>didState.state</code> output field</a>, +<li>In <a href="#client-managed-secret-mode" >Client-managed Secret Mode</a> as a <code>decryptionRequest</code> field inside the <a href="#didstate" ><code>didState</code> output field</a>, when the DID Registrar responds to a client request with a <a href="#didstateactiondecryptpayload" ><code>didState.action="decryptPayload"</code> output field</a>.</li> </ul> <p>A <strong>Decryption Request Set</strong> structure is a JSON object. Each property name in that JSON object is called a <em>decryption request ID</em>, and @@ -989,7 +1002,7 @@ <h3 id="decryption-request-set"><a class="toc-anchor" href="#decryption-request- <h3 id="decryption-response-set"><a class="toc-anchor" href="#decryption-response-set" >§</a> Decryption Response Set</h3> <p>This data structure is used as follows:</p> <ul> -<li>In <a href="#client-managed-secret-mode" >Client-managed Secret Mode</a> inside the <a href="#secret" ><code>secret</code> input field</a>, +<li>In <a href="#client-managed-secret-mode" >Client-managed Secret Mode</a> as a <code>decryptionResponse</code> field inside the <a href="#secret" ><code>secret</code> input field</a>, when the client invokes the DID Registrar again after it received a <a href="#didstateactiondecryptpayload" ><code>didState.action="decryptPayload"</code> output field</a>.</li> </ul> <p>A <strong>Decryption Response Set</strong> structure is a JSON object. Each property name MUST match a <em>decryption request ID</em> which was previously received by the diff --git a/spec/spec.md b/spec/spec.md index f049bc5..a291615 100644 --- a/spec/spec.md +++ b/spec/spec.md @@ -482,6 +482,19 @@ Example: ### `didState` +This output field contains an object with the following fields: + +* [`didState.state`](#didstatestate): The current state of DID operations. +* [`didState.did`](#didstatedid): The DID at the end of the DID operation. +* [`didState.secret`](#didstatesecret): An object with DID controller keys and other secrets. +* [`didState.didDocument`](#didstatediddocument): The DID document after the DID operation has been successfully executed. + +In [Client-managed Secret Mode](#client-managed-secret-mode), this output field MAY contain one or more of the following: + +* A `verificationMethodTemplate` property with a JSON array containing one or more [Verification Method Template](#verification-method-template) objects. +* A `signingRequest` property with a [Signing Request Set](#signing-request-set). +* A `decryptionRequest` property with a [Decryption Request Set](#decryption-request-set). + #### `didState.state` This output field contains the current state of the DID operations. It is used to indicate if a DID operation @@ -901,11 +914,11 @@ This specification defines a number of data structures that appear in the [input ### Verification Method Public Data -This data structure is used when public data about a verification method is exchanged between the client and the DID Registrar, as follows: +This data structure is used as follows, when public data about a verification method is exchanged between the client and the DID Registrar: -- In [Client-managed Secret Mode](#client-managed-secret-mode) inside the [`secret` input field](#secret), +- In [Client-managed Secret Mode](#client-managed-secret-mode) as a `verificationMethod` field inside the [`secret` input field](#secret), when the client invokes the DID Registrar again after it received a [`didState.action="getVerificationMethod"` output field](#didstateactiongetverificationmethod). -- In [Client-managed Secret Mode](#client-managed-secret-mode) inside the [`didState.secret` output field](#didstatesecret), +- In [Client-managed Secret Mode](#client-managed-secret-mode) as a `verificationMethod` field inside the [`didState.secret` output field](#didstatesecret), when the DID Registrar responds to a client request. A **Verification Method Public Data** structure is a JSON object based on the verification method @@ -949,11 +962,11 @@ Example: ### Verification Method Private Data -This data structure is used when private data about a verification method is exchanged between the client and the DID Registrar, as follows: +This data structure is used as follows, when private data about a verification method is exchanged between the client and the DID Registrar: -- In [Internal Secret Mode](#internal-secret-mode) inside the [`secret` input field](#secret), +- In [Internal Secret Mode](#internal-secret-mode) as a `verificationMethod` field inside the [`secret` input field](#secret), when the client invokes the DID Registrar again after it received a [`didState.action="getVerificationMethod"` output field](#didstateactiongetverificationmethod). -- In [Internal Secret Mode](#internal-secret-mode) inside the [`didState.secret` output field](#didstatesecret), +- In [Internal Secret Mode](#internal-secret-mode) as a `verificationMethod` field inside the [`didState.secret` output field](#didstatesecret), when the DID Registrar responds to a client request. A **Verification Method Private Data** structure is a JSON object based on the [Verification Method Public Data](#verification-method-public-data) @@ -996,7 +1009,7 @@ Example: This data structure is used as follows: -- In [Client-managed Secret Mode](#client-managed-secret-mode) inside the [`didState.state` output field](#didstatestate), +- In [Client-managed Secret Mode](#client-managed-secret-mode) as `verificationMethodTemplate` field inside the [`didState` output field](#didstate), when the DID Registrar responds to a client request with a [`didState.action="getVerificationMethod"` output field](#didstateactiongetverificationmethod). A **Verification Method Template** structure is a JSON object based on the verification method @@ -1035,7 +1048,7 @@ Example **Verification Method Template** containing properties `purpose` and `ty This data structure is used as follows: -- In [Client-managed Secret Mode](#client-managed-secret-mode) as a `signingRequest` field inside the [`didState.state` output field](#didstatestate), +- In [Client-managed Secret Mode](#client-managed-secret-mode) as a `signingRequest` field inside the [`didState` output field](#didstate), when the DID Registrar responds to a client request with a [`didState.action="signPayload"` output field](#didstateactionsignpayload). A **Signing Request Set** structure is a JSON object. Each property name in that JSON object is called a _signing request ID_, and @@ -1112,7 +1125,7 @@ Example **Signing Response Set** containing two **Signing Responses**: This data structure is used as follows: -- In [Client-managed Secret Mode](#client-managed-secret-mode) inside the [`didState.state` output field](#didstatestate), +- In [Client-managed Secret Mode](#client-managed-secret-mode) as a `decryptionRequest` field inside the [`didState` output field](#didstate), when the DID Registrar responds to a client request with a [`didState.action="decryptPayload"` output field](#didstateactiondecryptpayload). A **Decryption Request Set** structure is a JSON object. Each property name in that JSON object is called a _decryption request ID_, and @@ -1147,7 +1160,7 @@ Example **Decryption Request Set** containing two **Decryption Requests** with I This data structure is used as follows: -- In [Client-managed Secret Mode](#client-managed-secret-mode) inside the [`secret` input field](#secret), +- In [Client-managed Secret Mode](#client-managed-secret-mode) as a `decryptionResponse` field inside the [`secret` input field](#secret), when the client invokes the DID Registrar again after it received a [`didState.action="decryptPayload"` output field](#didstateactiondecryptpayload). A **Decryption Response Set** structure is a JSON object. Each property name MUST match a _decryption request ID_ which was previously received by the