From 2177255e468d1cc2590e5a0d84a7cbf6e70d4752 Mon Sep 17 00:00:00 2001 From: Dave Longley Date: Mon, 9 Sep 2024 12:39:43 -0400 Subject: [PATCH 01/11] Add workflows and exchange exposition. --- index.html | 173 ++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 172 insertions(+), 1 deletion(-) diff --git a/index.html b/index.html index c4245c6..d6439bd 100644 --- a/index.html +++ b/index.html @@ -915,12 +915,183 @@

Get a Specific Presentation

Workflows and Exchanges

+A VC API workflow defines a particular set of steps for exchanging verifiable +credentials between two parties across a trust boundary. Each step can involve +the issuance, verification, transmission, or presentation of verifiable +credentials. Examples of VC API workflows include, but are not limited to: +

+ +

+Workflow instances are expected to be created by administrators, for use with, +for example, coordinator websites. A workflow instance is created by performing +an HTTP POST to the workflow service's `/workflows` endpoint. The HTTP request +body includes the configuration for the workflow instance. This includes, but +is not limited to, information about the steps that define the workflow and any +credential templates that will be used to issue verifiable credentials. The +steps that define the workflow might also be templates, enabling additional +flexibility. If a workflow involves the issuance of verifiable credentials, or +the verification presentations or credentials, then the workflow instance +configuration can include authorization capabilities to use one or more VC API +issuer and / or verification services. +

+

+Once a workflow instance exists, authorization to create and query particular +workflow interactions, called VC API exchanges, can be given to coordinators. +

+

+A VC API exchange represents a particular interaction based on a given VC API +workflow. The interaction will take place between an exchange client and the +workflow service. Exchanges are expected to be transitory, only existing as +long as the interaction takes to complete. The workflow service stores state +information about each exchange such as whether the exchange is pending, +active, or complete, as well as the current step in the workflow, any +workflow-specific variables and data, and any verifiable presentations and +credentials received while the exchange executes. +

+

+An issuer, verifier, or holder coordinator is responsible for creating +exchanges. The coordinator creates an exchange by performing an HTTP POST to +the `/exchanges` subpath of a chosen workflow, on the workflow service. The +HTTP request body includes a time-to-live (TTL) for the exchange and any +variables to be used to populate the workflow's templates for the particular +exchange. The request body can also include configuration options to enable the +exchange to be executed using additional protocols beyond VC API. Once the +exchange is created, an exchange URL that identifies the exchange and enables +interaction with it is returned to the coordinator. +

+

+The exchange URL is given to the exchange client so that it can initiate the +exchange. Initiating the exchange does not require any authorization beyond the +exchange URL. Depending on the workflow service implementation, exchange URLs +can also be capability URLs (i.e., the URL is an unguessable secret such that +only whomever is given the URL can initiate the exchange). If the workflow that +the exchange is based on requires any additional authorization beyond the +possession of the exchange URL, this is to be obtained during the exchange, +not at its initiation. +

+

+The exchange URL can also be used by the coordinator to query the current +state of the exchange as it progresses and to obtain information associated +with the exchange that the workflow service has stored. Querying the exchange +in this way requires additional authorization that the coordinator is expected +to have and that the exchange client is not. +

+

+How the exchange URL is transmitted from a coordinator to an exchange client is +out of scope for this specification. Known mechanisms for sharing the exchange +URL with the client include using the Credential Handler API (aka CHAPI), a QR +code, or a universal link. +

+

+VC API exchanges can be executed using the VC API exchange protocol but are +also designed to be executable with additional protocols. For example, an +exchange could potentially also be executable via protocols such as OID4VCI, +OID4VP, and DIDComm. Which protocols are supported depend on the workflow +service implementation, the complexity of the workflow the exchange is based +off of, and the options provided by the coordinator when the exchange was +created. +

+

+The exchange client is expected to initiate the exchange using a protocol that +is compatible with how the client received the exchange URL. For example, the +exchange URL could have been provided over CHAPI with a protocol identifier +indicating that the VC API protocol ought to be used. Alternatively, the +exchange URL could be included as the "credential_issuer" in an OID4VCI +credential offer, or as the "client_id" of an OID4VP authorization request, +indicating that OID4VCI or OID4VP, respectively, ought to be used. This section +focuses on how an exchange client uses VC API to interact with the exchange, +but see appendix X to see how to combine VC API exchanges with other protocols +such as OID4VCI, OID4VP, and DIDComm. +

+

+Exchanges that are executed using the VC API protocol involve messages sent as +request and response bodies over HTTP. Each message consists of a simple JSON +object that includes zero or more of the following properties and values: +

+ +

+To initiate the exchange using the VC API protocol, the exchange client +performs an HTTP POST sending a JSON object as the request body. In the +simplest case, the JSON object is empty (`{}`), for the case when the client +has no constraints of its own on the exchange, i.e., it has nothing to request +from the other party. The workflow service responds with its own JSON object +in the response body. +

+

+If that object is empty, the exchange is complete and nothing is requested nor +offered to the exchange client. If the object includes +`verifiablePresentationRequest`, then the exchange is not yet complete and +some additional information is requested, based on the contents of the +associated verifiable presentation request. If the object includes +`verifiablePresentation`, then some information is offered, such as issued +verifiable credentials or verifiable credentials provided in response to the +exchange client's request. If the object includes `redirectUrl`, the exchange +is complete and the workflow service recommends that the client proceed to +another place to continue the interaction in another form. +

+

+Using these basic primitives, many verifiable credential use cases can be +implemented. Either exchange party is capable of requesting verifiable +presentations with one or more verifiable credentials that are required to +establish trust or gain authorization capabilities and either party is +capable of presenting credentials of their own or that they have issued. +Specific workflows can be configured to expect specific presentations and +credentials and reject deviations from the expected flow of information. When +a workflow service determines that a particular message is not acceptable, it +raises an error by responding with a `4xx` HTTP status message and a JSON error +object that expresses information about the error. +

+

+Therefore, the VC API exchange design approach is layered: it aims to provide +a minimal communication message layer and set of primitives that enable most +use cases to be implemented via specific verifiable presentation requests and +verifiable credentials at a layer above. See the appendices below for examples +of workflows and exchanges that use specific verifiable presentation requests +and verifiable credentials. These examples will be +added later. +

+

The following APIs are defined for using workflows and exchanges for credential use cases that require crossing trust boundaries:

- +

Create Workflow

From e087be9f5bbc3208c64a714897f9f43c7f28e2f1 Mon Sep 17 00:00:00 2001 From: Dave Longley Date: Mon, 9 Sep 2024 12:43:43 -0400 Subject: [PATCH 02/11] Remove extra empty bullet. --- index.html | 1 - 1 file changed, 1 deletion(-) diff --git a/index.html b/index.html index d6439bd..6d7ef2a 100644 --- a/index.html +++ b/index.html @@ -1042,7 +1042,6 @@

Workflows and Exchanges

Any custom properties and values might also be included, but are expected to trigger errors in implementations if they are not recognized. -

  • To initiate the exchange using the VC API protocol, the exchange client From a3ad3359d31611e191c241ef134b2b4fe4286acd Mon Sep 17 00:00:00 2001 From: Dave Longley Date: Mon, 9 Sep 2024 17:40:42 -0400 Subject: [PATCH 03/11] Apply grammatical suggestions from code review. Co-authored-by: Ted Thibodeau Jr --- index.html | 88 +++++++++++++++++++++++++++--------------------------- 1 file changed, 44 insertions(+), 44 deletions(-) diff --git a/index.html b/index.html index 6d7ef2a..84046e5 100644 --- a/index.html +++ b/index.html @@ -922,11 +922,11 @@

    Workflows and Exchanges

    • -Issuing an employee membership credential to an employee who has logged into a +Issuing an employee membership credential to an employee who has logged in to a coordinator website.
    • -Issuing a vehicle title credential in exchange for the presentation of a +Issuing a vehicle title credential after receiving a presentation of a driver's license credential.
    • @@ -945,9 +945,9 @@

      Workflows and Exchanges

      credential templates that will be used to issue verifiable credentials. The steps that define the workflow might also be templates, enabling additional flexibility. If a workflow involves the issuance of verifiable credentials, or -the verification presentations or credentials, then the workflow instance +the verification of presentations or credentials, then the workflow instance configuration can include authorization capabilities to use one or more VC API -issuer and / or verification services. +issuer and/or verification services.

      Once a workflow instance exists, authorization to create and query particular @@ -994,7 +994,7 @@

      Workflows and Exchanges

      How the exchange URL is transmitted from a coordinator to an exchange client is out of scope for this specification. Known mechanisms for sharing the exchange -URL with the client include using the Credential Handler API (aka CHAPI), a QR +URL with the client include the Credential Handler API (aka CHAPI), a QR code, or a universal link.

      @@ -1003,7 +1003,7 @@

      Workflows and Exchanges

      exchange could potentially also be executable via protocols such as OID4VCI, OID4VP, and DIDComm. Which protocols are supported depend on the workflow service implementation, the complexity of the workflow the exchange is based -off of, and the options provided by the coordinator when the exchange was +on, and the options provided by the coordinator when the exchange was created.

      @@ -1014,8 +1014,8 @@

      Workflows and Exchanges

      exchange URL could be included as the "credential_issuer" in an OID4VCI credential offer, or as the "client_id" of an OID4VP authorization request, indicating that OID4VCI or OID4VP, respectively, ought to be used. This section -focuses on how an exchange client uses VC API to interact with the exchange, -but see appendix X to see how to combine VC API exchanges with other protocols +focuses on how an exchange client uses VC API to interact with the exchange; +see appendix __** fill me in! **__ to see how to combine VC API exchanges with other protocols such as OID4VCI, OID4VP, and DIDComm.

      @@ -1025,37 +1025,37 @@

      Workflows and Exchanges

      • -`verifiablePresentationRequest`: A Verifiable Presentation Request. This is -used by one party in the exchange to request information from the other party. +`redirectUrl`: A URL that can be used to continue an interaction at another +location. One use case for this is to send the user of an exchange client +back to a coordinator website after an exchange has completed.
      • `verifiablePresentation`: A Verifiable Presentation. This is used by one party -to provide information requested by the other party or simply offered by the -sender. -
        • -
      • -`redirectUrl`: A URL that can be used to continue an interaction at another -location. One use case for this is to redirect the user of an exchange client -back to a coordinator website after an exchange has completed. +in an exchange to provide information to the other party, either because the +latter requested it or because the former is simply offering it.
      • -Any custom properties and values might also be included, but are expected to -trigger errors in implementations if they are not recognized. +`verifiablePresentationRequest`: A Verifiable Presentation Request. This is +used by one party in an exchange to request information from the other party.

      -To initiate the exchange using the VC API protocol, the exchange client +Custom properties and values might also be included, but are expected to +trigger errors in implementations that do not recognize them. +

      +

      +To initiate an exchange using the VC API protocol, an exchange client performs an HTTP POST sending a JSON object as the request body. In the -simplest case, the JSON object is empty (`{}`), for the case when the client -has no constraints of its own on the exchange, i.e., it has nothing to request -from the other party. The workflow service responds with its own JSON object -in the response body. +simplest case, when the client has no constraints of its own on the exchange +— i.e., it has nothing to request from the other party — the +JSON object is empty (`{}`). The workflow service responds with its own JSON +object in the response body.

      -If that object is empty, the exchange is complete and nothing is requested nor -offered to the exchange client. If the object includes +If that response object is empty, the exchange is complete and nothing is +requested from nor offered to the exchange client. If the object includes `verifiablePresentationRequest`, then the exchange is not yet complete and -some additional information is requested, based on the contents of the +some additional information is requested, as specified by the contents of the associated verifiable presentation request. If the object includes `verifiablePresentation`, then some information is offered, such as issued verifiable credentials or verifiable credentials provided in response to the @@ -1064,26 +1064,26 @@

      Workflows and Exchanges

      another place to continue the interaction in another form.

      -Using these basic primitives, many verifiable credential use cases can be -implemented. Either exchange party is capable of requesting verifiable -presentations with one or more verifiable credentials that are required to -establish trust or gain authorization capabilities and either party is -capable of presenting credentials of their own or that they have issued. -Specific workflows can be configured to expect specific presentations and -credentials and reject deviations from the expected flow of information. When -a workflow service determines that a particular message is not acceptable, it -raises an error by responding with a `4xx` HTTP status message and a JSON error -object that expresses information about the error. +Many verifiable credential use cases can be implemented using these basic +primitives. Either party to an exchange is capable of requesting verifiable +presentations and of providing one or more verifiable credentials that might +be necessary to establish trust and/or gain authorization capabilities, and +either party is capable of presenting credentials that they hold or that they +have issued. Specific workflows can be configured to expect specific +presentations and credentials and to reject deviations from the expected flow +of information. When a workflow service determines that a particular message +is not acceptable, it raises an error by responding with a `4xx` HTTP status +message and a JSON error object that expresses information about the error.

      -Therefore, the VC API exchange design approach is layered: it aims to provide -a minimal communication message layer and set of primitives that enable most -use cases to be implemented via specific verifiable presentation requests and -verifiable credentials at a layer above. See the appendices below for examples -of workflows and exchanges that use specific verifiable presentation requests -and verifiable credentials. These examples will be -added later. +The VC API exchange design approach is layered: it aims to provide a minimal +communication message layer and a set of primitives that enable most use cases +to be implemented via specific verifiable presentation requests and verifiable +credentials at a layer above. See the appendices that follow for examples of +workflows and exchanges that use specific verifiable presentation requests and +verifiable credentials.

      + These examples will be added later.

      The following APIs are defined for using workflows and exchanges for credential use cases that require crossing trust boundaries:

      From 97a228b1e9f185f512208f8e8e72e818b690619f Mon Sep 17 00:00:00 2001 From: Dave Longley Date: Mon, 9 Sep 2024 17:43:58 -0400 Subject: [PATCH 04/11] Use `either party` instead of `one party`. --- index.html | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/index.html b/index.html index 84046e5..4eebdd6 100644 --- a/index.html +++ b/index.html @@ -1030,13 +1030,14 @@

      Workflows and Exchanges

      back to a coordinator website after an exchange has completed.
    • -`verifiablePresentation`: A Verifiable Presentation. This is used by one party -in an exchange to provide information to the other party, either because the -latter requested it or because the former is simply offering it. +`verifiablePresentation`: A Verifiable Presentation. This is used by either +party in an exchange to provide information to the other party, either because +the latter requested it or because the former is simply offering it.
    • `verifiablePresentationRequest`: A Verifiable Presentation Request. This is -used by one party in an exchange to request information from the other party. +used by either party in an exchange to request information from the other +party.

    From e262af3ec4129a6b81bc2b7ee2115d6466e45d46 Mon Sep 17 00:00:00 2001 From: Dave Longley Date: Mon, 9 Sep 2024 17:51:21 -0400 Subject: [PATCH 05/11] Clarify VP contents example during a VC API exchange. --- index.html | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/index.html b/index.html index 4eebdd6..81534f7 100644 --- a/index.html +++ b/index.html @@ -1058,11 +1058,12 @@

    Workflows and Exchanges

    `verifiablePresentationRequest`, then the exchange is not yet complete and some additional information is requested, as specified by the contents of the associated verifiable presentation request. If the object includes -`verifiablePresentation`, then some information is offered, such as issued -verifiable credentials or verifiable credentials provided in response to the -exchange client's request. If the object includes `redirectUrl`, the exchange -is complete and the workflow service recommends that the client proceed to -another place to continue the interaction in another form. +`verifiablePresentation`, then some information is offered, such as +verifiable credentials issued to the holder operating the exchange client or +verifiable credentials with information about the exchange server's operator +based on the exchange client's request. If the object includes `redirectUrl`, +the exchange is complete and the workflow service recommends that the client +proceed to another place to continue the interaction in another form.

    Many verifiable credential use cases can be implemented using these basic From 598f3a9a0fe1fb0c90d870603ba3c35208df488b Mon Sep 17 00:00:00 2001 From: Dave Longley Date: Tue, 10 Sep 2024 15:06:20 -0400 Subject: [PATCH 06/11] Add improved exchange language from code review. Co-authored-by: Ted Thibodeau Jr --- index.html | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/index.html b/index.html index 81534f7..3875ff9 100644 --- a/index.html +++ b/index.html @@ -933,7 +933,7 @@

    Workflows and Exchanges

    Verification of the presentation of a permanent resident credential.
  • -Receipt of newly issued, single use proof of age credentials. +Receipt of one or more newly-issued single-use proof of age credentials.

    • @@ -998,13 +998,13 @@

    Workflows and Exchanges

    code, or a universal link.

    -VC API exchanges can be executed using the VC API exchange protocol but are -also designed to be executable with additional protocols. For example, an -exchange could potentially also be executable via protocols such as OID4VCI, -OID4VP, and DIDComm. Which protocols are supported depend on the workflow -service implementation, the complexity of the workflow the exchange is based -on, and the options provided by the coordinator when the exchange was -created. +VC API exchanges are designed to be executable using other protocols in +addition to the VC API exchange protocol; for example, an exchange could +potentially be executable with any of the OID4VCI, OID4VP, DIDComm, and +VC API exchange protocols. Which protocols are supported by a given workflow +depend on the workflow service implementation, the complexity of the workflow +the exchange is based on, and the options provided by the coordinator when +the exchange was created.

    The exchange client is expected to initiate the exchange using a protocol that From 9b901d64acd920b6d92475241450465fcf9c799e Mon Sep 17 00:00:00 2001 From: Dave Longley Date: Tue, 10 Sep 2024 15:14:31 -0400 Subject: [PATCH 07/11] Clarify JSON object error response. Co-authored-by: BigBlueHat --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index 3875ff9..c4819b2 100644 --- a/index.html +++ b/index.html @@ -1075,7 +1075,7 @@

    Workflows and Exchanges

    presentations and credentials and to reject deviations from the expected flow of information. When a workflow service determines that a particular message is not acceptable, it raises an error by responding with a `4xx` HTTP status -message and a JSON error object that expresses information about the error. +message and a JSON object that expresses information about the error.

    The VC API exchange design approach is layered: it aims to provide a minimal From 8f59fb6d30de9aeb4c734c0e7f91010db478ee42 Mon Sep 17 00:00:00 2001 From: Dave Longley Date: Tue, 10 Sep 2024 15:57:32 -0400 Subject: [PATCH 08/11] Fix typo. Co-authored-by: Ted Thibodeau Jr --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index c4819b2..602f054 100644 --- a/index.html +++ b/index.html @@ -1002,7 +1002,7 @@

    Workflows and Exchanges

    addition to the VC API exchange protocol; for example, an exchange could potentially be executable with any of the OID4VCI, OID4VP, DIDComm, and VC API exchange protocols. Which protocols are supported by a given workflow -depend on the workflow service implementation, the complexity of the workflow +depends on the workflow service implementation, the complexity of the workflow the exchange is based on, and the options provided by the coordinator when the exchange was created.

    From 429bde09b43c5bac9ddb4a626c96a2cf4adf7e44 Mon Sep 17 00:00:00 2001 From: Dave Longley Date: Wed, 11 Sep 2024 15:07:48 -0400 Subject: [PATCH 09/11] Apply grammar improvements from code review. Co-authored-by: Ted Thibodeau Jr --- index.html | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/index.html b/index.html index 602f054..9bea776 100644 --- a/index.html +++ b/index.html @@ -1001,7 +1001,8 @@

    Workflows and Exchanges

    VC API exchanges are designed to be executable using other protocols in addition to the VC API exchange protocol; for example, an exchange could potentially be executable with any of the OID4VCI, OID4VP, DIDComm, and -VC API exchange protocols. Which protocols are supported by a given workflow +VC API exchange protocols. The protocols supported by a given workflow depend +on the implementation of the workflow service, the complexity of the workflow depends on the workflow service implementation, the complexity of the workflow the exchange is based on, and the options provided by the coordinator when the exchange was created. From 9644efd888564c7833866d4debe521210d861808 Mon Sep 17 00:00:00 2001 From: Dave Longley Date: Wed, 11 Sep 2024 15:12:55 -0400 Subject: [PATCH 10/11] Improve grammar in protocol support description. --- index.html | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/index.html b/index.html index 9bea776..14e3121 100644 --- a/index.html +++ b/index.html @@ -1001,11 +1001,9 @@

    Workflows and Exchanges

    VC API exchanges are designed to be executable using other protocols in addition to the VC API exchange protocol; for example, an exchange could potentially be executable with any of the OID4VCI, OID4VP, DIDComm, and -VC API exchange protocols. The protocols supported by a given workflow depend -on the implementation of the workflow service, the complexity of the workflow -depends on the workflow service implementation, the complexity of the workflow -the exchange is based on, and the options provided by the coordinator when -the exchange was created. +VC API exchange protocols. The protocols supported depends on the complexity +of the workflow the exchange is based on, and the options provided by the +coordinator when the exchange was created.

    The exchange client is expected to initiate the exchange using a protocol that From b028d5aaac55a530d14bf103ee74b947bf9112cf Mon Sep 17 00:00:00 2001 From: Manu Sporny Date: Wed, 11 Sep 2024 15:37:49 -0400 Subject: [PATCH 11/11] Add issue marker for TBD Appendix. --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index 14e3121..6e53312 100644 --- a/index.html +++ b/index.html @@ -1014,7 +1014,7 @@

    Workflows and Exchanges

    credential offer, or as the "client_id" of an OID4VP authorization request, indicating that OID4VCI or OID4VP, respectively, ought to be used. This section focuses on how an exchange client uses VC API to interact with the exchange; -see appendix __** fill me in! **__ to see how to combine VC API exchanges with other protocols +see Appendix TBD to see how to combine VC API exchanges with other protocols such as OID4VCI, OID4VP, and DIDComm.