From ebeeb756ed18173262dac27c6f9b4ab95011c34a Mon Sep 17 00:00:00 2001 From: mixmix Date: Mon, 18 Nov 2024 10:59:39 +1300 Subject: [PATCH 1/3] group "credentials" by didcomm/oid4vc/connectionless Signed-off-by: mixmix --- .../credentials/connectionless/issue.md | 0 .../connectionless/present-proof.md | 0 .../{ => didcomm}/anoncreds-setup.png | Bin .../{ => didcomm}/anoncreds-setup.puml | 0 .../issue-flow.anoncreds.png} | Bin .../issue-flow.anoncreds.puml} | 0 .../issue-flow.jwt.png} | Bin .../issue-flow.jwt.puml} | 0 .../credentials/{ => didcomm}/issue.md | 26 +++++++++--------- .../present-proof-flow.anoncreds.png} | Bin .../present-proof-flow.anoncreds.puml} | 0 .../present-proof-flow.jwt.png} | Bin .../present-proof-flow.jwt.puml} | 0 .../{ => didcomm}/present-proof.md | 15 ++++------ .../{oid4vci.md => oid4cv/issue.md} | 2 +- docs/docusaurus/sidebars.js | 6 ++-- 16 files changed, 22 insertions(+), 27 deletions(-) create mode 100644 docs/docusaurus/credentials/connectionless/issue.md create mode 100644 docs/docusaurus/credentials/connectionless/present-proof.md rename docs/docusaurus/credentials/{ => didcomm}/anoncreds-setup.png (100%) rename docs/docusaurus/credentials/{ => didcomm}/anoncreds-setup.puml (100%) rename docs/docusaurus/credentials/{anoncreds-issue-flow.png => didcomm/issue-flow.anoncreds.png} (100%) rename docs/docusaurus/credentials/{anoncreds-issue-flow.puml => didcomm/issue-flow.anoncreds.puml} (100%) rename docs/docusaurus/credentials/{issue-flow.png => didcomm/issue-flow.jwt.png} (100%) rename docs/docusaurus/credentials/{issue-flow.puml => didcomm/issue-flow.jwt.puml} (100%) rename docs/docusaurus/credentials/{ => didcomm}/issue.md (95%) rename docs/docusaurus/credentials/{anoncreds-present-proof-flow.png => didcomm/present-proof-flow.anoncreds.png} (100%) rename docs/docusaurus/credentials/{anoncreds-present-proof-flow.puml => didcomm/present-proof-flow.anoncreds.puml} (100%) rename docs/docusaurus/credentials/{present-proof-flow.png => didcomm/present-proof-flow.jwt.png} (100%) rename docs/docusaurus/credentials/{present-proof-flow.puml => didcomm/present-proof-flow.jwt.puml} (100%) rename docs/docusaurus/credentials/{ => didcomm}/present-proof.md (98%) rename docs/docusaurus/credentials/{oid4vci.md => oid4cv/issue.md} (99%) diff --git a/docs/docusaurus/credentials/connectionless/issue.md b/docs/docusaurus/credentials/connectionless/issue.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/docusaurus/credentials/connectionless/present-proof.md b/docs/docusaurus/credentials/connectionless/present-proof.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/docusaurus/credentials/anoncreds-setup.png b/docs/docusaurus/credentials/didcomm/anoncreds-setup.png similarity index 100% rename from docs/docusaurus/credentials/anoncreds-setup.png rename to docs/docusaurus/credentials/didcomm/anoncreds-setup.png diff --git a/docs/docusaurus/credentials/anoncreds-setup.puml b/docs/docusaurus/credentials/didcomm/anoncreds-setup.puml similarity index 100% rename from docs/docusaurus/credentials/anoncreds-setup.puml rename to docs/docusaurus/credentials/didcomm/anoncreds-setup.puml diff --git a/docs/docusaurus/credentials/anoncreds-issue-flow.png b/docs/docusaurus/credentials/didcomm/issue-flow.anoncreds.png similarity index 100% rename from docs/docusaurus/credentials/anoncreds-issue-flow.png rename to docs/docusaurus/credentials/didcomm/issue-flow.anoncreds.png diff --git a/docs/docusaurus/credentials/anoncreds-issue-flow.puml b/docs/docusaurus/credentials/didcomm/issue-flow.anoncreds.puml similarity index 100% rename from docs/docusaurus/credentials/anoncreds-issue-flow.puml rename to docs/docusaurus/credentials/didcomm/issue-flow.anoncreds.puml diff --git a/docs/docusaurus/credentials/issue-flow.png b/docs/docusaurus/credentials/didcomm/issue-flow.jwt.png similarity index 100% rename from docs/docusaurus/credentials/issue-flow.png rename to docs/docusaurus/credentials/didcomm/issue-flow.jwt.png diff --git a/docs/docusaurus/credentials/issue-flow.puml b/docs/docusaurus/credentials/didcomm/issue-flow.jwt.puml similarity index 100% rename from docs/docusaurus/credentials/issue-flow.puml rename to docs/docusaurus/credentials/didcomm/issue-flow.jwt.puml diff --git a/docs/docusaurus/credentials/issue.md b/docs/docusaurus/credentials/didcomm/issue.md similarity index 95% rename from docs/docusaurus/credentials/issue.md rename to docs/docusaurus/credentials/didcomm/issue.md index ff9beeae99..ff03f581b2 100644 --- a/docs/docusaurus/credentials/issue.md +++ b/docs/docusaurus/credentials/didcomm/issue.md @@ -23,24 +23,24 @@ Before using the Issuing Credentials protocol, the following conditions must be 1. Issuer and Holder Cloud Agents up and running -2. A connection must be established between the Issuer and Holder Cloud Agents (see [Connections](../connections/connection.md)) -3. The Issuer must have a published PRISM DID, and the [DID document](/docs/concepts/glossary#did-document) must have at least one `assertionMethod` key for issuing credentials (see [Create DID](../dids/create.md) and [Publish DID](../dids/publish.md)) +2. A connection must be established between the Issuer and Holder Cloud Agents (see [Connections](../../connections/connection.md)) +3. The Issuer must have a published PRISM DID, and the [DID document](/docs/concepts/glossary#did-document) must have at least one `assertionMethod` key for issuing credentials (see [Create DID](../../dids/create.md) and [Publish DID](../../dids/publish.md)) 4. The Holder must have a PRISM DID, and the DID document must have at least one `authentication` key for presenting the proof. 1. Issuer and Holder Cloud Agents up and running -2. A connection must be established between the Issuer and Holder Cloud Agents (see [Connections](../connections/connection.md)) -3. The Issuer must have created an AnonCreds Credential Definition as described [here](../credentialdefinition/create.md). +2. A connection must be established between the Issuer and Holder Cloud Agents (see [Connections](../../connections/connection.md)) +3. The Issuer must have created an AnonCreds Credential Definition as described [here](../../credentialdefinition/create.md). - 📌 **Note:** Currently we only support `Ed25519` curve 1. Issuer and Holder Cloud Agents up and running -2. A connection must be established between the Issuer and Holder Cloud Agents (see [Connections](../connections/connection.md)) -3. The Issuer must have a published PRISM DID, and the [DID document](/docs/concepts/glossary#did-document) must have at least one `assertionMethod` key for issuing credentials and the curve must be `Ed25519` (see [Create DID](../dids/create.md) and [Publish DID](../dids/publish.md)) +2. A connection must be established between the Issuer and Holder Cloud Agents (see [Connections](../../connections/connection.md)) +3. The Issuer must have a published PRISM DID, and the [DID document](/docs/concepts/glossary#did-document) must have at least one `assertionMethod` key for issuing credentials and the curve must be `Ed25519` (see [Create DID](../../dids/create.md) and [Publish DID](../../dids/publish.md)) 4. The Holder must have a PRISM DID, and the DID document must have at least one `authentication` key for presenting the proof and the curve must be `Ed25519`. @@ -95,7 +95,7 @@ To do this, make a `POST` request to the [`/issue-credentials/credential-offers` 4. `schemaId`: An optional field that, if specified, contains a valid URL to an existing VC schema. The Cloud Agent must be able to dereference the specified URL (i.e. fetch the VC schema content from it), in order to validate the provided claims against it. When not specified, the claims fields is not validated and can be any valid JSON object. - Please refer to the [Create VC schema](../schemas/create.md) doc for details on how to create a VC schema. + Please refer to the [Create VC schema](../../schemas/create.md) doc for details on how to create a VC schema. 5. `credentialFormat`: The format of the credential that will be issued - `JWT` in this case. When not specified, the default value is `JWT`. @@ -133,9 +133,9 @@ curl -X 'POST' \ 1. `claims`: The data stored in a verifiable credential. AnonCreds claims get expressed in a flat, "string -> string", key-value pair format. The claims contain the data that the issuer attests to, such as name, address, date of birth, and so on. 2. `connectionId`: The unique ID of the connection between the holder and the issuer to offer this credential over. -3. `credentialDefinitionId`: The unique ID of the [credential definition](../credentialdefinition/credential-definition.md) that has been created by the issuer as a prerequisite. Please refer to the [Create AnonCreds Credential Definition](../credentialdefinition/credential-definition.md) doc for details on how to create a credential definition. +3. `credentialDefinitionId`: The unique ID of the [credential definition](../../credentialdefinition/credential-definition.md) that has been created by the issuer as a prerequisite. Please refer to the [Create AnonCreds Credential Definition](../../credentialdefinition/credential-definition.md) doc for details on how to create a credential definition. :::note -📌 Note: If the credential definition was created via HTTP URL endpoint, then this credential definition will be referenced to that credential via HTTP URL, and if this credential definition was created via DID URL endpoint, then it will be referenced via DID URL, How to create credential definition for HTTP URL or DID URL is explained in [credential definition creation guide](../credentialdefinition/create.md) +📌 Note: If the credential definition was created via HTTP URL endpoint, then this credential definition will be referenced to that credential via HTTP URL, and if this credential definition was created via DID URL endpoint, then it will be referenced via DID URL, How to create credential definition for HTTP URL or DID URL is explained in [credential definition creation guide](../../credentialdefinition/create.md) ::: 4. `credentialFormat`: The format of the credential that will be issued - `AnonCreds` in this case. 5. `issuingDID`: The DID referring to the issuer to issue this credential from @@ -178,7 +178,7 @@ curl -X 'POST' \ 4. `schemaId`: An optional field that, if specified, contains a valid URL to an existing VC schema. The Cloud Agent must be able to dereference the specified URL (i.e. fetch the VC schema content from it), in order to validate the provided claims against it. When not specified, the claims fields is not validated and can be any valid JSON object. - Please refer to the [Create VC schema](../schemas/create.md) doc for details on how to create a VC schema. + Please refer to the [Create VC schema](../../schemas/create.md) doc for details on how to create a VC schema. 5. `credentialFormat`: The format of the credential that will be issued - `SDJWT` in this case. @@ -435,12 +435,12 @@ The following diagram shows the end-to-end flow for an issuer to issue a VC to a -![](issue-flow.png) +![](issue-flow.jwt.png) -![](anoncreds-issue-flow.png) +![](issue-flow.anoncreds.png) - \ No newline at end of file + diff --git a/docs/docusaurus/credentials/anoncreds-present-proof-flow.png b/docs/docusaurus/credentials/didcomm/present-proof-flow.anoncreds.png similarity index 100% rename from docs/docusaurus/credentials/anoncreds-present-proof-flow.png rename to docs/docusaurus/credentials/didcomm/present-proof-flow.anoncreds.png diff --git a/docs/docusaurus/credentials/anoncreds-present-proof-flow.puml b/docs/docusaurus/credentials/didcomm/present-proof-flow.anoncreds.puml similarity index 100% rename from docs/docusaurus/credentials/anoncreds-present-proof-flow.puml rename to docs/docusaurus/credentials/didcomm/present-proof-flow.anoncreds.puml diff --git a/docs/docusaurus/credentials/present-proof-flow.png b/docs/docusaurus/credentials/didcomm/present-proof-flow.jwt.png similarity index 100% rename from docs/docusaurus/credentials/present-proof-flow.png rename to docs/docusaurus/credentials/didcomm/present-proof-flow.jwt.png diff --git a/docs/docusaurus/credentials/present-proof-flow.puml b/docs/docusaurus/credentials/didcomm/present-proof-flow.jwt.puml similarity index 100% rename from docs/docusaurus/credentials/present-proof-flow.puml rename to docs/docusaurus/credentials/didcomm/present-proof-flow.jwt.puml diff --git a/docs/docusaurus/credentials/present-proof.md b/docs/docusaurus/credentials/didcomm/present-proof.md similarity index 98% rename from docs/docusaurus/credentials/present-proof.md rename to docs/docusaurus/credentials/didcomm/present-proof.md index 280fea81c5..406f9d1cd9 100644 --- a/docs/docusaurus/credentials/present-proof.md +++ b/docs/docusaurus/credentials/didcomm/present-proof.md @@ -1,7 +1,7 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# Present proof +# Present proof (DIDComm) The [Present Proof Protocol](/docs/concepts/glossary#present-proof-protocol) allows: - a [Verifier](/docs/concepts/glossary#verifier) to request a verifiable credential presentation from a Holder/Prover @@ -21,7 +21,7 @@ The present proof protocol has two roles: Before using the Proof Presentation protocol, the following conditions must be present: 1. Holder/Prover and Verifier Cloud Agents must be up and running -2. A connection must be established between the Holder/Prover and Verifier Cloud Agents (see [Connections](../connections/connection.md)) +2. A connection must be established between the Holder/Prover and Verifier Cloud Agents (see [Connections](../../connections/connection.md)) 3. The Holder/Prover should hold a [verifiable credential (VC)](/docs/concepts/glossary#verifiable-credential) received from an [Issuer](/docs/concepts/glossary#issuer) see [Issue](./issue.md). ## Overview @@ -323,20 +323,15 @@ stateDiagram-v2 The following diagram shows the end-to-end flow for a verifier to request and verify a proof presentation from a Holder/prover. -### JWT Present Proof Flow Diagram -![](present-proof-flow.png) -### Anoncreds Present Proof Flow Diagram -![](anoncreds-present-proof-flow.png) - -![](present-proof-flow.png) +![](present-proof-flow.jwt.png) -![](anoncreds-present-proof-flow.png) +![](present-proof-flow.anoncreds.png) - \ No newline at end of file + diff --git a/docs/docusaurus/credentials/oid4vci.md b/docs/docusaurus/credentials/oid4cv/issue.md similarity index 99% rename from docs/docusaurus/credentials/oid4vci.md rename to docs/docusaurus/credentials/oid4cv/issue.md index a84b7c7dfe..8bcf839b1c 100644 --- a/docs/docusaurus/credentials/oid4vci.md +++ b/docs/docusaurus/credentials/oid4cv/issue.md @@ -1,4 +1,4 @@ -# Issue credentials (OID4VCI) +# Issue credentials (OID4VC) [OID4VCI](/docs/concepts/glossary#oid4vci) (OpenID for Verifiable Credential Issuance) is a protocol that extends OAuth2 to issue credentials. It involves a Credential Issuer server and an Authorization server working together, diff --git a/docs/docusaurus/sidebars.js b/docs/docusaurus/sidebars.js index b746ea93f5..003b90fafb 100644 --- a/docs/docusaurus/sidebars.js +++ b/docs/docusaurus/sidebars.js @@ -19,9 +19,9 @@ const sidebars = { description: 'Credentials tutorials' }, items: [ - 'credentials/issue', - 'credentials/oid4vci', - 'credentials/present-proof', + 'credentials/didcomm/issue', + 'credentials/oid4ci/issue', + 'credentials/didcomm/present-proof', 'credentials/revocation' ] }, From 2d5d8f4fbe8b5d0dd1b318212ff1e3ed1172ad44 Mon Sep 17 00:00:00 2001 From: mixmix Date: Mon, 18 Nov 2024 15:49:03 +1300 Subject: [PATCH 2/3] add docs for connectionless issuing Signed-off-by: mixmix --- .../credentials/connectionless/issue.md | 450 ++++++++++++++++++ docs/docusaurus/credentials/didcomm/issue.md | 2 +- docs/docusaurus/sidebars.js | 1 + 3 files changed, 452 insertions(+), 1 deletion(-) diff --git a/docs/docusaurus/credentials/connectionless/issue.md b/docs/docusaurus/credentials/connectionless/issue.md index e69de29bb2..fc853fc42b 100644 --- a/docs/docusaurus/credentials/connectionless/issue.md +++ b/docs/docusaurus/credentials/connectionless/issue.md @@ -0,0 +1,450 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Issue credentials (Connectionless) + +In the Identus Platform, the [Issue Credentials Protocol](/docs/concepts/glossary#issue-credential-protocol) allows you to create, retrieve, and manage issued [verifiable credentials (VCs)](/docs/concepts/glossary#verifiable-credentials) between a VC issuer and a VC holder. + +## Roles + +In the Issue Credentials Protocol, there are two roles: + +1. The [Issuer](/docs/concepts/glossary#issuer) is responsible for creating a new credential offer, sending it to a Holder, and issuing the VC once the offer is accepted. +2. The [Holder](/docs/concepts/glossary#holder) is responsible for accepting a credential offer from an issuer and receiving the VC. + +The Issuer and Holder interact with the Identus Cloud Agent API to perform the operations defined in the protocol. + + +## Prerequisites + +Before using the "Connectionless" Issuing Credentials protocol, the following conditions must be present: + + + + +1. Issuer Cloud Agents is up and running +2. The Issuer has a published PRISM DID, and the [DID document](/docs/concepts/glossary#did-document) must have at least one `assertionMethod` key for issuing credentials (see [Create DID](../../dids/create.md) and [Publish DID](../../dids/publish.md)) +3. The Holder is either another Cloud Agent or Edge Agent SDK + + + + +1. Issuer Cloud Agents is up and running +2. The Issuer has a published PRISM DID, and the [DID document](/docs/concepts/glossary#did-document) must have at least one `assertionMethod` key for issuing credentials (see [Create DID](../../dids/create.md) and [Publish DID](../../dids/publish.md)) +3. The Issuer must have created an AnonCreds Credential Definition as described [here](../../credentialdefinition/create.md). +4. The Holder is either another Cloud Agent or Edge Agent SDK + + + + +- 📌 **Note:** Currently we only support `Ed25519` curve +1. Issuer Cloud Agents is up and running +2. The Issuer has a published PRISM DID, and the [DID document](/docs/concepts/glossary#did-document) must have at least one `assertionMethod` key for issuing credentials (see [Create DID](../../dids/create.md) and [Publish DID](../../dids/publish.md)) +3. The Holder is either another Cloud Agent or Edge Agent SDK +4. The Holder must have a PRISM DID, and the DID document must have at least one `authentication` key for presenting the proof and the curve must be `Ed25519`. + + + + +## Overview + +The protocol described is a VC issuance process between an Issuer (Identus Cloud Agent) and Holder (Identus Edge Agent SDK). + +The protocol consists of the following main parts: + +1. The Issuer creates a new credential offer using the [`/issue-credentials/credential-offers/invitation`](/identus-docs/agent-api/#tag/Issue-Credentials-Protocol/operation/createCredentialOffer) endpoint, which includes information such as the schema identifier and claims. This returns a unique OOB (out-of-band) invitate code for the prospective Holder. +2. The Holder accepts the OOB invite (see SDK `acceptInvitation`) +3. The Issuer responds by sending the actual Credential Offer +4. The Holder accepts the Credential Offer +5. The Issuer sends the Verifiable Credential + +The claims provide specific information about the individual, such as their name or qualifications. + +This protocol is applicable in various real-life scenarios, such as educational credentialing, employment verification, and more. +In these scenarios, the Issuer could be a school, an employer, etc., and the Holder could be a student or an employee. +The VCs issued during this protocol could represent a diploma, a certificate of employment, etc. + +## Endpoints + +| Endpoint | Description | Role | +|--------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------|----------------| +| [`/issue-credentials/credential-offers/invitation`](/agent-api/#tag/Issue-Credentials-Protocol/operation/createCredentialOffer) | This endpoint allows you to create a new credential offer invitation | Issuer | +| [`/issue-credentials/credential-offers/accept-invitation`](/agent-api/#tag/Issue-Credentials-Protocol/operation/acceptCredentialOfferInvitation) | This endpoint allows you to accept the invitation | Holder | +| [`/issue-credentials/records`](/agent-api/#tag/Issue-Credentials-Protocol/operation/getCredentialRecords) | This endpoint allows you to retrieve a collection of all the existing credential records | Issuer, Holder | +| [`/issue-credentials/records/{recordId}`](/agent-api/#tag/Issue-Credentials-Protocol/operation/getCredentialRecord) | This endpoint allows you to retrieve a specific credential record by its `id` | Issuer, Holder | +| [`/issue-credentials/records/{recordId}/accept-offer`](/agent-api/#tag/Issue-Credentials-Protocol/operation/acceptCredentialOffer) | This endpoint allows you to accept a credential offer | Holder | +| [`/issue-credentials/records/{recordId}/issue-credential`](/agent-api/#tag/Issue-Credentials-Protocol/operation/issueCredential) | This endpoint allows you to issue a VC for a specific credential record. | Issuer | + + +:::info +Please check the full [Cloud Agent API](/agent-api) specification for more detailed information. +::: + +## Issuer interactions + +This section describes the Issuer role's available interactions with the Cloud Agent. + +### Creating a Credential Offer + +To start the process, the issuer needs to create a credential offer invitation. +To do this, make a `POST` request to the [`/issue-credentials/credential-offers/invitation`](/agent-api/#tag/Issue-Credentials-Protocol/operation/createCredentialOffer) endpoint with a JSON payload that includes the following information: + + + + +1. `claims`: The data stored in a verifiable credential. Claims get expressed in a key-value format. The claims contain the data that the issuer attests to, such as name, address, date of birth, and so on. +2. `issuingDID`: The DID referring to the issuer to issue this credential from +3. `schemaId`: An optional field that, if specified, contains a valid URL to an existing VC schema. + The Cloud Agent must be able to dereference the specified URL (i.e. fetch the VC schema content from it), in order to validate the provided claims against it. + When not specified, the claims fields is not validated and can be any valid JSON object. + Please refer to the [Create VC schema](../../schemas/create.md) doc for details on how to create a VC schema. +4. `credentialFormat`: The format of the credential that will be issued - `JWT` in this case. When not specified, the default value is `JWT`. + +:::note +The `issuingDID` property comes from completing the pre-requisite steps listed above +::: + +Once the request initiates, a new credential record for the issuer gets created with a unique ID. The state of this record is now `OfferPending`. + +```shell +# Issuer POST request to create a new credential offer +curl -X 'POST' \ + 'http://localhost:8080/cloud-agent/issue-credentials/credential-offers/invitation' \ + -H 'accept: application/json' \ + -H 'Content-Type: application/json' \ + -H "apikey: $API_KEY" \ + -d '{ + "claims": { + "emailAddress": "alice@wonderland.com", + "givenName": "Alice", + "familyName": "Wonderland", + "dateOfIssuance": "2020-11-13T20:20:39+00:00", + "drivingLicenseID": "12345", + "drivingClass": 3 + }, + "credentialFormat": "JWT", + "issuingDID": "did:prism:9f847f8bbb66c112f71d08ab39930d468ccbfe1e0e1d002be53d46c431212c26", + "schemaId": "http://localhost:8080/cloud-agent/schema-registry/schemas/3f86a73f-5b78-39c7-af77-0c16123fa9c2" + }' +``` + + + + +1. `claims`: The data stored in a verifiable credential. AnonCreds claims get expressed in a flat, "string -> string", key-value pair format. The claims contain the data that the issuer attests to, such as name, address, date of birth, and so on. +2. `issuingDID`: The DID referring to the issuer to issue this credential from +3. `credentialDefinitionId`: The unique ID of the [credential definition](../../credentialdefinition/credential-definition.md) that has been created by the issuer as a prerequisite. Please refer to the [Create AnonCreds Credential Definition](../../credentialdefinition/credential-definition.md) doc for details on how to create a credential definition. +:::note +📌 Note: If the credential definition was created via HTTP URL endpoint, then this credential definition will be referenced to that credential via HTTP URL, and if this credential definition was created via DID URL endpoint, then it will be referenced via DID URL, How to create credential definition for HTTP URL or DID URL is explained in [credential definition creation guide](../../credentialdefinition/create.md) +::: +4. `credentialFormat`: The format of the credential that will be issued - `AnonCreds` in this case. + +:::note +The `issuingDID` and `credentialDefinitionId` properties come from completing the pre-requisite steps listed above +::: + +Once the request initiates, a new credential record for the issuer gets created with a unique ID. The state of this record is now `OfferPending`. + +```shell +# Issuer POST request to create a new credential offer +curl -X 'POST' \ + 'http://localhost:8080/cloud-agent/issue-credentials/credential-offers/invitation' \ + -H 'accept: application/json' \ + -H 'Content-Type: application/json' \ + -H "apikey: $API_KEY" \ + -d '{ + "claims": { + "emailAddress": "alice@wonderland.com", + "givenName": "Alice", + "familyName": "Wonderland", + "dateOfIssuance": "2020-11-13T20:20:39+00:00", + "drivingLicenseID": "12345", + "drivingClass": "3" + }, + "credentialFormat": "AnonCreds", + "issuingDID": "did:prism:9f847f8bbb66c112f71d08ab39930d468ccbfe1e0e1d002be53d46c431212c26", + "credentialDefinitionId": "5d737816-8fe8-3492-bfe3-1b3e2b67220b" + }' +``` + + + + + +1. `claims`: The data stored in a verifiable credential. Claims get expressed in a key-value format. The claims contain the data that the issuer attests to, such as name, address, date of birth, and so on. +2. `issuingDID`: The DID referring to the issuer to issue this credential from +4. `schemaId`: An optional field that, if specified, contains a valid URL to an existing VC schema. + The Cloud Agent must be able to dereference the specified URL (i.e. fetch the VC schema content from it), in order to validate the provided claims against it. + When not specified, the claims fields is not validated and can be any valid JSON object. + Please refer to the [Create VC schema](../../schemas/create.md) doc for details on how to create a VC schema. +5. `credentialFormat`: The format of the credential that will be issued - `SDJWT` in this case. + +:::note +The `issuingDID` property comes from completing the pre-requisite steps listed above +::: + +- 📌 **Note:** Claims can also include the `exp` Expiration Time attribute, which is part of JWT claims. `exp` attribute is disclosable if specified and can have a value in epoch time (in seconds), indicating when the SDJWT credential expires for more details +[RFC5719](https://datatracker.ietf.org/doc/html/rfc7519#page-9) + +Once the request initiates, a new credential record for the issuer gets created with a unique ID. The state of this record is now `OfferPending`. + +```shell +# Issuer POST request to create a new credential offer +curl -X 'POST' \ + 'http://localhost:8080/cloud-agent/issue-credentials/credential-offers/invitation' \ + -H 'accept: application/json' \ + -H 'Content-Type: application/json' \ + -H "apikey: $API_KEY" \ + -d '{ + "claims": { + "emailAddress": "alice@wonderland.com", + "givenName": "Alice", + "familyName": "Wonderland", + "dateOfIssuance": "2020-11-13T20:20:39+00:00", + "drivingLicenseID": "12345", + "drivingClass": 3, + "exp" : 1883000000 + }, + "credentialFormat": "SDJWT", + "issuingDID": "did:prism:9f847f8bbb66c112f71d08ab39930d468ccbfe1e0e1d002be53d46c431212c26", + "schemaId": "http://localhost:8080/cloud-agent/schema-registry/schemas/3f86a73f-5b78-39c7-af77-0c16123fa9c2" + }' +``` + + + + + +### Sending the Offer to the Holder + +The next step for the Issuer is to send the OOB invite Holder (by definition, this is "out of band", so not handled by Identus). +Common ways to convey such OOB invites might be a QR code that is scanned, or via an existing channel of connection in an application. + + +### Issuing the Credential + +Once the holder has approved the offer and sent a request to the Issuer, +the Issuer will receive the request via DIDComm and update the record state to `RequestReceived.` + +The Issuer can then use the [`/issue-credentials/records/{recordId}/issue-credential`](/agent-api/#tag/Issue-Credentials-Protocol/operation/issueCredential) endpoint to issue the credential to the holder. + +```shell +# Issuer POST request to issue the credential +# make sure you have `issuer_record_id` extracted from created credential offer +# and the record achieved `RequestReceived` state +curl -X POST \ + "http://localhost:8080/cloud-agent/issue-credentials/records/$issuer_record_id/issue-credential" \ + -H "Content-Type: application/json" \ + -H "apikey: $API_KEY" +``` + +When this endpoint gets called, the state of the record will change to `CredentialPending,` and after processing, it will change to `CredentialGenerated.` + +Finally, the Issuer agent will send the credential to the holder via DIDComm, +and the state of the record will change to `CredentialSent`. +At this point, the Issuer's interactions with the holder are complete. + +```mermaid +--- +title: Issuer flow +--- +stateDiagram-v2 + [*] --> OfferPending: create credential offer (`/issue-credentials/credential-offers`) + OfferPending --> OfferSent: send offer (auto via PRISM Agent DIDComm) + OfferSent --> RequestReceived: receive request (auto via PRISM Agent DIDComm) + RequestReceived --> CredentialPending: issue credential (`/issue-credentials/records/{recordId}/issue-credential`) + CredentialPending --> CredentialGenerated: process issued credential (auto via PRISM Agent) + CredentialGenerated --> CredentialSent: send credential (auto via PRISM Agent) +``` + +## Holder interactions + +This section describes the Holder role's available interactions with the Cloud Agent. + +### Receiving the VC Offer + +The Holder will receive the offer from the Issuer via DIDComm, +and a new credential record with a unique ID gets created in the `OfferReceived` state. + +This process is automatic for the Cloud Agent. + +You could check if a new credential offer is available using [`/issue-credentials/records`](/#tag/Issue-Credentials-Protocol/operation/getCredentialRecords) request and check for any records available in `OfferReceived` state: +```shell +# Holder GET request to retrieve credential records +curl "http://localhost:8090/cloud-agent/issue-credentials/records" \ + -H "Content-Type: application/json" \ + -H "apikey: $API_KEY" +``` + + +### Approving the VC Offer + +To accept the offer, the Holder can make a `POST` request to the [`/issue-credentials/records/{recordId}/accept-offer`](/agent-api/#tag/Issue-Credentials-Protocol/operation/acceptCredentialOffer) endpoint with a JSON payload that includes the following information: + + + + +1. `holder_record_id`: The unique identifier of the issue credential record known by the holder's Cloud Agent. +2. `subjectId`: This field represents the unique identifier for the subject of the verifiable credential. It is a short-form PRISM [DID](/docs/concepts/glossary#decentralized-identifier) string, such as `did:prism:subjectIdentifier`. + +```shell +# Holder POST request to accept the credential offer +curl -X POST "http://localhost:8090/cloud-agent/issue-credentials/records/$holder_record_id/accept-offer" \ + -H 'accept: application/json' \ + -H 'Content-Type: application/json' \ + -H "apikey: $API_KEY" \ + -d '{ + "subjectId": "did:prism:subjectIdentifier" + }' +``` + + + + +1. `holder_record_id`: The unique identifier of the issue credential record known by the holder's Cloud Agent. + +```shell +# Holder POST request to accept the credential offer +curl -X POST "http://localhost:8090/cloud-agent/issue-credentials/records/$holder_record_id/accept-offer" \ + -H 'accept: application/json' \ + -H 'Content-Type: application/json' \ + -H "apikey: $API_KEY" \ + -d '{}' +``` + + + + + +1. `holder_record_id`: The unique identifier of the issue credential record known by the holder's Cloud Agent. +2. `subjectId`: This field represents the unique identifier for the subject of the verifiable credential. It is a short-form PRISM [DID](/docs/concepts/glossary#decentralized-identifier) string, such as `did:prism:subjectIdentifier`. +3. `keyId` Option parameter + 1. when keyId is not provided the SDJWT VC is not binded to Holder/Prover key + ```shell + # Holder POST request to accept the credential offer + curl -X POST "http://localhost:8090/cloud-agent/issue-credentials/records/$holder_record_id/accept-offer" \ + -H 'accept: application/json' \ + -H 'Content-Type: application/json' \ + -H "apikey: $API_KEY" \ + -d '{ + "subjectId": "did:prism:subjectIdentifier" + }' + ``` + A SD-JWT Verifiable Credential (VC) without a `cnf` key could possibly look like below + + ```json + { + "_sd": [ + "CrQe7S5kqBAHt-nMYXgc6bdt2SH5aTY1sU_M-PgkjPI", + "JzYjH4svliH0R3PyEMfeZu6Jt69u5qehZo7F7EPYlSE", + "PorFbpKuVu6xymJagvkFsFXAbRoc2JGlAUA2BA4o7cI", + "TGf4oLbgwd5JQaHyKVQZU9UdGE0w5rtDsrZzfUaomLo", + "XQ_3kPKt1XyX7KANkqVR6yZ2Va5NrPIvPYbyMvRKBMM", + "XzFrzwscM6Gn6CJDc6vVK8BkMnfG8vOSKfpPIZdAfdE", + "gbOsI4Edq2x2Kw-w5wPEzakob9hV1cRD0ATN3oQL9JM", + "jsu9yVulwQQlhFlM_3JlzMaSFzglhQG0DpfayQwLUK4" + ], + "iss": "https://issuer.example.com", + "iat": 1683000000, + "exp": 1883000000, + "sub": "user_42", + "_sd_alg": "sha-256" + } + ``` + 2. `keyId`: This is optional field but must be specified to choose which key bounds to the verifiable credential. + For more information on key-binding, [ietf-oauth-selective-disclosure-jwt](https://datatracker.ietf.org/doc/draft-ietf-oauth-selective-disclosure-jwt). + Currently, we only support the EdDSA algorithm and curve Ed25519. + The specified keyId should be of type Ed25519. + The purpose of the keyId should be authentication. + + ```shell + # Holder POST request to accept the credential offer with keyId + curl -X POST "http://localhost:8090/cloud-agent/issue-credentials/records/$holder_record_id/accept-offer" \ + -H 'accept: application/json' \ + -H 'Content-Type: application/json' \ + -H "apikey: $API_KEY" \ + -d '{ + "subjectId": "did:prism:subjectIdentifier", + "keyId": "key-1" + }' + ``` + A SD-JWT Verifiable Credential (VC) that includes a `cnf` key could possibly look like below + ```json + { + "_sd": [ + "CrQe7S5kqBAHt-nMYXgc6bdt2SH5aTY1sU_M-PgkjPI", + "JzYjH4svliH0R3PyEMfeZu6Jt69u5qehZo7F7EPYlSE", + "PorFbpKuVu6xymJagvkFsFXAbRoc2JGlAUA2BA4o7cI", + "TGf4oLbgwd5JQaHyKVQZU9UdGE0w5rtDsrZzfUaomLo", + "XQ_3kPKt1XyX7KANkqVR6yZ2Va5NrPIvPYbyMvRKBMM", + "XzFrzwscM6Gn6CJDc6vVK8BkMnfG8vOSKfpPIZdAfdE", + "gbOsI4Edq2x2Kw-w5wPEzakob9hV1cRD0ATN3oQL9JM", + "jsu9yVulwQQlhFlM_3JlzMaSFzglhQG0DpfayQwLUK4" + ], + "iss": "https://issuer.example.com", + "iat": 1683000000, + "exp": 1883000000, + "sub": "user_42", + "_sd_alg": "sha-256", + "cnf": { + "jwk": { + "kty": "EC", + "crv": "P-256", + "x": "TCAER19Zvu3OHF4j4W4vfSVoHIP1ILilDls7vCeGemc", + "y": "ZxjiWWbZMQGHVWKVQ4hbSIirsVfuecCE6t4jT9F2HZQ" + } + } + } + ``` + + + + + +This request will change the state of the record to `RequestPending`. + +### Receiving the VC Credential + +Once the Holder has approved the offer and sent a request to the Issuer, the Holder agent will process the request and send it to the Issuer agent. +The state of the Holder's record will change to `RequestSent`. + +After the Issuer has issued the credential, the Holder will receive the credential via DIDComm, and the state of the Holder's record will change to `CredentialReceived`. +This process is automatic for the Cloud Agent. + +The Holder can check the achieved credential using a GET request to [`/issue-credentials/records/{recordId}/`](/agent-api/#tag/Issue-Credentials-Protocol/operation/getCredentialRecord) endpoint. + +```mermaid +--- +title: Holder Flow +--- +stateDiagram-v2 + [*] --> OfferReceived: receive offer (auto via PRISM Agent) + OfferReceived --> RequestPending: accept offer (`/issue-credentials/records/{recordId}/accept-offer`) + RequestPending --> RequestSent: send request (auto via PRISM Agent) + RequestSent --> CredentialReceived: receive credential (auto via PRISM Agent) +``` + +## Sequence diagram + +TODO + + diff --git a/docs/docusaurus/credentials/didcomm/issue.md b/docs/docusaurus/credentials/didcomm/issue.md index ff03f581b2..dfe4a887a5 100644 --- a/docs/docusaurus/credentials/didcomm/issue.md +++ b/docs/docusaurus/credentials/didcomm/issue.md @@ -3,7 +3,7 @@ import TabItem from '@theme/TabItem'; # Issue credentials (DIDComm) -In the Identus Platform, the [Issue Credentials Protocol](/docs/concepts/glossary#issue-credentials-protocol) allows you to create, retrieve, and manage issued [verifiable credentials (VCs)](/docs/concepts/glossary#verifiable-credentials) between a VC issuer and a VC holder. +In the Identus Platform, the [Issue Credentials Protocol](/docs/concepts/glossary#issue-credential-protocol) allows you to create, retrieve, and manage issued [verifiable credentials (VCs)](/docs/concepts/glossary#verifiable-credentials) between a VC issuer and a VC holder. ## Roles diff --git a/docs/docusaurus/sidebars.js b/docs/docusaurus/sidebars.js index 003b90fafb..56d5dfca37 100644 --- a/docs/docusaurus/sidebars.js +++ b/docs/docusaurus/sidebars.js @@ -20,6 +20,7 @@ const sidebars = { }, items: [ 'credentials/didcomm/issue', + 'credentials/connectionless/issue', 'credentials/oid4ci/issue', 'credentials/didcomm/present-proof', 'credentials/revocation' From b5efc5f62c12dc712458a58c38e0b43f26ae1251 Mon Sep 17 00:00:00 2001 From: mixmix Date: Mon, 18 Nov 2024 22:52:55 +1300 Subject: [PATCH 3/3] docs: add connectionless present-proof documentation Signed-off-by: mixmix --- .../connectionless/present-proof.md | 339 ++++++++++++++++++ docs/docusaurus/sidebars.js | 1 + 2 files changed, 340 insertions(+) diff --git a/docs/docusaurus/credentials/connectionless/present-proof.md b/docs/docusaurus/credentials/connectionless/present-proof.md index e69de29bb2..77922d8beb 100644 --- a/docs/docusaurus/credentials/connectionless/present-proof.md +++ b/docs/docusaurus/credentials/connectionless/present-proof.md @@ -0,0 +1,339 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Present proof (Connectionless) + +The [Present Proof Protocol](/docs/concepts/glossary#present-proof-protocol) allows: +- a [Verifier](/docs/concepts/glossary#verifier) to request a verifiable credential presentation from a Holder/Prover +- a [Holder/Prover](/docs/concepts/glossary#holder) responds by presenting a cryptographic proof to the Verifier + +The protocol provides endpoints for a Verifier to request new proof presentations from Holder/Provers and for a Holder/Prover to respond to the presentation request using a specific verifiable credential they own. + +## Roles + +The present proof protocol has two roles: + +1. Verifier: A subject requesting a proof presentation by sending a request presentation message, then verifying the presentation. +2. Holder/Prover: A [subject](/docs/concepts/glossary#subject) that receives a [proof presentation](/docs/concepts/glossary#proof-presentation) request, prepares a proof, and sends it to the verifier by sending a proof presentation message. + +## Prerequisites + +Before using the Proof Presentation protocol, the following conditions must be present: + +1. Holder/Prover and Verifier Cloud Agents must be up and running +2. The Holder/Prover should hold a [verifiable credential (VC)](/docs/concepts/glossary#verifiable-credential) received from an [Issuer](/docs/concepts/glossary#issuer) see [Issue](./issue.md). + +## Overview + +This protocol supports the presentation of verifiable claims between two Agents, the Holder/Prover and the Verifier. + +The protocol consists of the following main parts: + +1. The Verifier creates a new proof presentation request invite using the [`/present-proof/presentations/invitation`](/agent-api/#tag/Present-Proof/operation/createOOBRequestPresentationInvitation) endpoint. This returns a unique out-of-band (OOB) invite code which can be used to intiated a presentation request. +2. The Holder/Prover receives the OOB invite code (via some communication channel), and accepts the invitation, triggering a presentation request. +3. The Holder/Prover receives the presentation request from the Verifier and can retrieve the list of existing requests using the [`/present-proof/presentations`](/agent-api/#tag/Present-Proof/operation/getAllPresentation) endpoint. +4. The Holder/Prover can then review and accept a specific request using the [`/present-proof/presentations/{presentationId}`](/agent-api/#tag/Present-Proof/operation/updatePresentation) endpoint, providing the identifier of the `credential` record to use in the proof presentation. +5. The Verifier receives the proof presentation from the Holder/Prover and can accept it using the [`/present-proof/presentations/{presentationId}`](/agent-api/#tag/Present-Proof/operation/updatePresentation) endpoint, specifying `presentation-accept` as the action type. + +## Endpoints + +| Endpoint | Method | Description | Role | +|---------------------------------------------------------------------------------------------------|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------| +| [`/present-proof/presentations/invitation`](/agent-api/#tag/Present-Proof/operation/createOOBRequestPresentationInvitation) | POST | Creates a new proof presentation request invitation. | Verifier | +| [`/present-proof/presentations`](/agent-api/#tag/Present-Proof/operation/getAllPresentation) | GET | Retrieves the collection of all the existing presentation proof records - sent or received. | Verifier, Holder/Prover | +| [`/present-proof/presentations/{id}`](/agent-api/#tag/Present-Proof/operation/getPresentation) | GET | Retrieves a specific presentation proof record by `id`. | Verifier, Holder/Prover | +| [`/present-proof/presentations/{id}`](/agent-api/#tag/Present-Proof/operation/updatePresentation) | PATCH | Updates an existing presentation proof record to, e.g., accept the request on the Holder/Prover side or accept the presentation on the Verifier side. | Verifier, Holder/Prover | + +:::info +For more detailed information, please, check the full [Cloud Agent API](/agent-api). +::: + +## Verifier interactions + +This section describes the interactions available to the Verifier with the Cloud Agent. + +### Creating and sending a Presentation Request + +The Verifier needs to create a proof presentation request invite to start the process. +To do this, he makes a `POST` request to the [`/present-proof/presentations/invitation`](/agent-api/#tag/Present-Proof/operation/createOOBRequestPresentationInvitation) endpoint with a JSON payload that includes the following information: + +1. `challenge` and `domain`: The Verifier provides the random seed challenge and operational domain, and the Holder/Prover must sign the generated proof to protect from replay attacks. + + + + +```bash +curl -X 'POST' 'http://localhost:8070/cloud-agent/present-proof/presentations/invitation' \ + -H 'accept: application/json' \ + -H 'Content-Type: application/json' \ + -H "apikey: $API_KEY" \ + -d '{ + "proofs":[], + "options": { + "challenge": "11c91493-01b3-4c4d-ac36-b336bab5bddf", + "domain": "https://prism-verifier.com" + } + }' +``` + + + + +```bash +curl -X 'POST' 'http://localhost:8070/cloud-agent/present-proof/presentations/invitation' \ + -H 'accept: application/json' \ + -H 'Content-Type: application/json' \ + -H "apikey: $API_KEY" \ + -d '{ + "anoncredPresentationRequest": { + "requested_attributes": { + "attribute1": { + "name": "Attribute 1", + "restrictions": [ + { + "cred_def_id": "credential_definition_id_of_attribute1" + } + ], + "non_revoked": { + "from": 1635734400, + "to": 1735734400 + } + } + }, + "requested_predicates": { + "predicate1": { + "name": "age", + "p_type": ">=", + "p_value": 18, + "restrictions": [ + { + "schema_id": "schema_id_of_predicate1" + } + ], + "non_revoked": { + "from": 1635734400 + } + } + }, + "name": "Example Presentation Request", + "nonce": "1234567890", + "version": "1.0" + }, + "credentialFormat": "AnonCreds" + }' +``` + + + +a. `SD-JWT` The absence of the `cnf` key claim in the SD-JWT Verifiable Credential (VC) means that the Holder/Prover is unable to create a presentation and sign the `challenge` and `domain` supplied by the verifier + +```bash +curl -X 'POST' 'http://localhost:8070/cloud-agent/present-proof/presentations/invitation' \ + -H 'accept: application/json' \ + -H 'Content-Type: application/json' \ + -H "apikey: $API_KEY" \ + -d '{ + "proofs":[], + "credentialFormat": "SDJWT", + "claims": { + "emailAddress": {}, + "givenName": {}, + ` "region": {}, + "country": {}` + } + }' +``` + +b. `SD-JWT` The presence of the `cnf` key as a disclosable claim in the SD-JWT Verifiable Credential (VC) allows the Holder/Prover to create a presentation and sign the `challenge` and `domain` given by the verifier. +```bash +curl -X 'POST' 'http://localhost:8070/cloud-agent/present-proof/presentations/invitation' \ + -H 'accept: application/json' \ + -H 'Content-Type: application/json' \ + -H "apikey: $API_KEY" \ + -d '{ + "proofs":[], + "options": { + "challenge": "11c91493-01b3-4c4d-ac36-b336bab5bddf", + "domain": "https://prism-verifier.com" + }, + "credentialFormat": "SDJWT", + "claims": { + "emailAddress": {}, + "givenName": {}, + "region": {}, + "country": {} + } + }' +``` +SDJWT Specific attributes +1. `credentialFormat`: SDJWT. +2. `claims`: The claims to be disclosed by Holder/Prover. + + + + +Upon execution, a new presentation request invite gets created. This invite is an out-of-band code which must be delivered to the Holder/Prover through some alternative messaging layer. Once a the invte is accepted, the Verifier Cloud Agent will send the presentation request message to the Holder/Prover via DIDComm. The record state then is updated to `RequestSent`. + +The Verifier can retrieve the list of presentation records by making a `GET` request to the [`/present-proof/presentations`](/agent-api/#tag/Present-Proof/operation/getAllPresentation) endpoint: +```bash +curl -X 'GET' 'http://localhost:8070/cloud-agent/present-proof/presentations' \ + -H 'accept: application/json' \ + -H "apikey: $API_KEY" +``` + +### Accept presentation proof received from the Holder/prover + +Once the Holder/Prover has received a proof presentation request, he can accept it using an appropriate verifiable credential. The Cloud Agent of the Verifier will receive that proof and verify it. Upon successful verification, the presentation record state gets updated to `PresentationVerified`. + +The Verifier can then explicitly accept the specific verified proof presentation to change the record state to `PresentationAccepted` by making a `PATCH` request to the [`/present-proof/presentations/{id}`](/agent-api/#tag/Present-Proof/operation/updatePresentation) endpoint: + +```bash +curl -X 'PATCH' 'http://localhost:8070/cloud-agent/present-proof/presentations/{PRESENTATION_ID}' \ + -H 'Content-Type: application/json' \ + -H "apikey: $API_KEY" \ + -d '{ + "action": "presentation-accept" + }' +``` + +```mermaid +--- +title: Verifier Flow +--- +stateDiagram-v2 + [*] --> RequestPending: new presentation request invite created by the Verifier + RequestPending --> RequestSent: presentation request sent to the Holder/Prover PRISM Agent + RequestSent --> PresentationReceived: presentation proof received from the Holder/Prover + PresentationReceived --> PresentationVerified: presentation proof verified by the Verifier PRISM Agent + PresentationVerified --> PresentationAccepted: verified presentation proof explicitly accepted by the Verifier +``` + +## Holder/Prover + +This section describes the interactions available to the Holder/Prover with his Cloud Agent. + +### Reviewing and accepting a received presentation request + +The Holder/Prover can retrieve the list of presentation requests received by its Cloud Agent from different Verifiers making a `GET` request to the [`/present-proof/presentations`](/agent-api/#tag/Present-Proof/operation/getAllPresentation) endpoint: + +```bash +curl -X 'GET' 'http://localhost:8090/cloud-agent/present-proof/presentations' \ + -H 'accept: application/json' \ + -H "apikey: $API_KEY" +``` + +The Holder/Prover can then accept a specific request, generate the proof, and send it to the Verifier Cloud Agent by making a `PATCH` request to the [`/present-proof/presentations/{id}`](/agent-api/#tag/Present-Proof/operation/updatePresentation) endpoint: + + + + +```bash +curl -X 'PATCH' 'http://localhost:8090/cloud-agent/present-proof/presentations/{PRESENTATION_ID}' \ + -H 'Content-Type: application/json' \ + -H "apikey: $API_KEY" \ + -d '{ + "action": "request-accept", + "proofId": ["{CRED_RECORD_ID}"] + }' +``` + +The Holder/Prover will have to provide the following information: +1. `presentationId`: The unique identifier of the presentation record to accept. +2. `proofId`: The unique identifier of the verifiable credential record to use as proof. + + + + +```bash +curl -X 'PATCH' 'http://localhost:8090/cloud-agent/present-proof/presentations/{PRESENTATION_ID}' \ + -H 'Content-Type: application/json' \ + -H "apikey: $API_KEY" \ + -d '{ + "action": "request-accept", + "anoncredPresentationRequest":{ + "credentialProofs":[ + { + "credential":"3e849b98-f0fd-4cb4-ae96-9ea527a76267", + "requestedAttribute":[ + "age" + ], + "requestedPredicate":[ + "age" + ] + } + ] + } + }' +``` + + + + +```bash +curl -X 'PATCH' 'http://localhost:8090/cloud-agent/present-proof/presentations/{PRESENTATION_ID}' \ + -H 'Content-Type: application/json' \ + -H "apikey: $API_KEY" \ + -d '{ + "action": "request-accept", + "proofId": ["{CRED_RECORD_ID}"] + "claims": { + "emailAddress": {}, + "givenName": {}, + "address": { + "region": {}, + "country": {} + } + }, + "credentialFormat": "SDJWT" + }' +``` + +The Holder/Prover will have to provide the following information: +1. `presentationId`: The unique identifier of the presentation record to accept. +2. `proofId`: The unique identifier of the verifiable credential record to use as proof. +3. `credentialFormat`: SDJWT. +4. `claims`: The Verifier requests specific claims to disclose. The path of these claims must match exactly with those in the SD-JWT Verifiable Credential (VC). +- 📌 **Note:** When a SD-JWT Verifiable Credential (VC) has nested claims such as region and country within an address object, as shown in the example above, it falls under the Holder's responsibility to supply the correct nested JSON structure for the claims attribute(s) that is being disclosed. +- 📌 **Note:** The holder or prover of the claims is only required to disclose the attribute names and the correct JSON path. The actual values are not necessary. A special JSON placeholder `{}`, can be used instead. + + + + + +The Holder/Prover will have to provide the following information: +1. `presentationId`: The unique identifier of the presentation record to accept. +2. `anoncredPresentationRequest`: A list of credential unique identifier with the attribute and predicate the credential is answering for. + +The record state is updated to `PresentationPending` and processed by the Holder/Prover Cloud Agent. The agent will automatically generate the proof presentation, change the state to `PresentationGenerated`, and will eventually send it to the Verifier Agent, and change the state to `PresentationSent`. + +```mermaid +--- +title: Holder/Prover Flow +--- +stateDiagram-v2 + [*] --> RequestReceived: presentation request received by the PRISM Agent + RequestReceived --> PresentationPending: request accepted by the Holder/Prover + PresentationPending --> PresentationGenerated: presentation proof generated by the PRISM Agent + PresentationGenerated --> PresentationSent: generated proof sent to the Verifier PRISM Agent +``` + +## Sequence diagram + +TODO + + diff --git a/docs/docusaurus/sidebars.js b/docs/docusaurus/sidebars.js index 56d5dfca37..592b85affd 100644 --- a/docs/docusaurus/sidebars.js +++ b/docs/docusaurus/sidebars.js @@ -23,6 +23,7 @@ const sidebars = { 'credentials/connectionless/issue', 'credentials/oid4ci/issue', 'credentials/didcomm/present-proof', + 'credentials/connectionless/present-proof', 'credentials/revocation' ] },