diff --git a/.github/workflows/autopublish.yaml b/.github/workflows/autopublish.yaml index b451546..69e8e8b 100644 --- a/.github/workflows/autopublish.yaml +++ b/.github/workflows/autopublish.yaml @@ -24,7 +24,6 @@ jobs: run: sudo npx puppeteer browsers install chrome npx respec --src index.html --out index.html.build.html -t 60 --disable-sandbox --verbose -# - uses: w3c/spec-prod@v2 - uses: actions/upload-pages-artifact@v3 with: path: . diff --git a/.gitignore b/.gitignore index 0eb354e..b94e4c5 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,3 @@ .idea/ -index.html \ No newline at end of file +index.html +/*.png \ No newline at end of file diff --git a/scripts/replace.sh b/scripts/replace.sh index f09146c..f38a114 100644 --- a/scripts/replace.sh +++ b/scripts/replace.sh @@ -1,4 +1,5 @@ cp scripts/respec-template.html index.html +cp specifications/*.png . index=`cat index.html` top=`cat specifications/tx.dataspace.topology.md` topph="THIS IS THE PLACEHOLDER FOR THE DATASPACE TOPOLOGY" diff --git a/specifications/credential.issuance.protocol.md b/specifications/credential.issuance.protocol.md index 1b540e9..a97d3d1 100644 --- a/specifications/credential.issuance.protocol.md +++ b/specifications/credential.issuance.protocol.md @@ -1,13 +1,15 @@ -# 1. Introduction +# Credential Issuance Protocol + +## Introduction This specification defines a protocol for Verifiable Credential (VC) issuance. Specifically, the Credential Issuance Protocol (CIP) defines the endpoints and message types for requesting credentials to be issued from a `Credential Issuer.` -This specification relies on the [Base Identity Protocol](identity.protocol.base.md) and -the [Verifiable Presentation Protocol](verifiable.presentation.protocol.md). +This specification relies on sections [[[#identity-protocol-base]]] and +[[[#verifiable-presentation-protocol]]]. -## 1.1. Motivation +### Motivation Verifiable Credentials enable a holder to present claims directly to a Relying Party (RP) without the involvement or knowledge of the `Credential Issuer`. The Credential Issuance Protocol (CIP) provides an @@ -20,15 +22,14 @@ but differs in its focus on service-to-service interactions where end-user devic protocol flow. Moreover, the current specification accommodates the requirement for long-running interactions typically associated with manual workflows that are best modelled using asynchronous messaging paradigms. -## 1.2 Terms +### Terms -- ***DID*** - A decentralized identifier as defined by the [DID specification](https://github.com/w3c/did-core). +- ***DID*** - A decentralized identifier as defined by [[[did-core]]]. -# 2. Overview +## Overview The Credential Issuance Protocol is designed to be used in conjunction with -the [Base Identity Protocol](identity.protocol.base.md) and the -[Verifiable Presentation Protocol](verifiable.presentation.protocol.md). This issuance interaction flow is expressed +[[[#identity-protocol-base]]] and [[[#verifiable-presentation-protocol]]]. This issuance interaction flow is expressed in the following diagram: ![Issuance Flow](issuance.flow.png) @@ -38,22 +39,22 @@ includes in its request to the `Credential Issuer.` If the VC request is approve be written to the client's `Credential Service` using the `Verifiable Presentation Protocol.` The operation is performed asynchronously from the client request, resulting in non-blocking behavior. -## 2.1. The Issuer Base URL +### The Issuer Base URL All endpoint addresses are defined relative to the base URL of the issuer service. The base URL MUST use the HTTPS scheme. The issuer will use the base URL for the `issuer` field in all VCs it issues as defined by -the [issuer property](https://www.w3.org/TR/vc-data-model/#dfn-property). +the `issuer` property ([[vc-data-model]]). This specification makes no assumption about the base URL, for example, if it is a domain, subdomain, or contains a path. -# 3. Credential Request Flow +## Credential Request Flow The `credential request flow` is initiated by a client making a request for one or more VCs to an issuer's `Credential Request Endpoint`. If the request is valid, the issuer endpoint will send an acknowledgement to the client. If the request is approved, the VC will be issued to the client asynchronously. -## 3.1. Credential Request Endpoint +### Credential Request Endpoint Communication with the `Credential Request Endpoint` MUST utilize TLS. @@ -62,26 +63,27 @@ the issuer. The request MUST include an ID Token in the HTTP `Authorization` header prefixed with `Bearer` as defined in -the [Base Identity Protocol Specification](identity.protocol.base.md#411-vp-access-token). The `issuer` claim can be +the [[[#vp-access-token]]]. The `issuer` claim can be + used by the Credential Issuer to resolve the client's DID to obtain cryptographic material for validation and credential binding. The ID Token MUST contain a `token` claim that is a bearer token granting write privileges for the requested VCs into the client's `Credential Service` as defined by -the [Verifiable Presentation Protocol specification](verifiable.presentation.protocol.md) +[[[#verifiable-presentation-protocol]]] The ID Token MAY contain an `token` claim as defined in -the [Base Identity Protocol Specification](identity.protocol.base.md) claim that can be used by the issuer to resolve +[[[#identity-protocol-base]]] claim that can be used by the issuer to resolve Verifiable Presentations (VP) the client is required to hold for issuance of the requested VCs. If the issuer supports a pre-authorization code flow, the client must use the `pre-authorized_code` claim in the ID Token to provide the pre-authorization code to the issuer. -### 3.1.1. Credential Request Parameters +#### Credential Request Parameters The Credential Request `POST` body MUST be a `CredentialRequestMessage` JSON object with the following properties: -- `@context`: REQUIRED. Specifies a valid [Json-Ld context](https://www.w3.org/TR/json-ld11/#the-context). +- `@context`: REQUIRED. Specifies a valid Json-Ld context ([[json-ld11]], sect. 3.1). - `@type`: REQUIRED. A string specifying the `CredentialRequestMessage` type. - `format`: REQUIRED. A JSON string that describes the format of the credential to be issued. Implementations MUST support the `ldp_vc` format as defined by @@ -112,23 +114,22 @@ Authorization: Bearer ...... ``` On successful receipt of the request, the Credential Issuer MUST respond with a `201 CREATED` with the `Location` -header set to the location of the request status. See -the [Credential Request Status](#credential-request-status-endpoint) section. +header set to the location of the request status ([[[#credential-request-status-endpoint]]]) The issuer MAY respond with `401 Not Authorized` if the request is unauthorized or other `HTTP` status codes to indicate an exception. If the VC request is approved, the issuer will respond with a write-request to the client's `Credential Service` using -the Storage API defined in the [Verifiable Presentation Protocol](verifiable.presentation.protocol.md#5-storage-api). +the Storage API defined in [[[#storage-api]]]. -# 4. Credential Offer Flow +## Credential Offer Flow Some scenarios involve the Credential Issuer making an initial offer. For example, an out-of-band process may result in a credential offer. Or, a Credential Issuer may start a key rotation process which involves sending updated credentials to holders signed with the issuer's new key. In this case, the issuer can proactively prompt holders to request a new credential during the key rotation period. -## 4.1. Credential Offer Endpoint +### Credential Offer Endpoint Communication with the `Credential Offer Endpoint` MUST utilize TLS. @@ -136,16 +137,17 @@ The credential offer endpoint MUST be available under the `POST` method at `/off holder's `Credential Service` base URL. Issuers can obtain this URL by resolving the holder's DID and inspecting its `CredentialService` service entry. -### 4.1.1. Credential Offer Parameters +#### Credential Offer Parameters The Credential Offer `POST` body MUST be a `CredentialOfferMessage` JSON object with the following properties: -- `@context`: REQUIRED. Specifies a valid [Json-Ld context](https://www.w3.org/TR/json-ld11/#the-context). +- `@context`: REQUIRED. Specifies a valid Json-Ld context ([[json-ld11]], sect. 3.1). - `@type`: REQUIRED. A string specifying the `CredentialOfferMessage` type. - `credentialIssuer`: REQUIRED. The identifier of the Credential Issuer, the `Credential Service` is requested to obtain one or more credentials from. - `credentials`: REQUIRED. A JSON array, where every entry is a JSON object or a JSON string. - - entry type object: data MUST adhere to the [Credentials Object](#412-the-credentialobject) + - entry type object: data MUST adhere to [[[#the-credentialobject]]] + - entry type string: value MUST be one of the id values in one of the objects in the `credentials_supported`. - When processing, the `Credential Service` MUST resolve this string value to the respective object. @@ -169,7 +171,7 @@ Authorization: Bearer ...... } ``` -#### 4.1.2. The `CredentialObject` +##### The `CredentialObject` The `CredentialObject` defines the following properties: @@ -181,14 +183,13 @@ The `CredentialObject` defines the following properties: _Open ID for Verifiable Credential Issuance_ specification. - `cryptographicSuites`: OPTIONAL. Binding methods supported as defined by `cryptographic_suites_supported` in the _Open ID for Verifiable Credential Issuance_ specification. -- `issuancePolicy`: OPTIONAL. An [ODRL Policy](https://www.w3.org/TR/odrl-model/). Note that the ODRL policy MUST not +- `issuancePolicy`: OPTIONAL. An ODRL Policy [[odrl-model]]. Note that the ODRL Policy MUST not contain `target` attributes. Implementations MAY not support ODRL issuance policies. - `offerReason`: OPTIONAL. A reason for the offer as a string. Valid values may include `reissue` and `proof-key-revocation`. > Note: Properties mapped to the _Open ID for Verifiable Credential Issuance_ specification are defined in -> -the [Credential Issuer Metadata](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html#section-10.2.3.1) +> the [Credential Issuer Metadata](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html#section-10.2.3.1) > section. The following is a non-normative example of a `CredentialObject`: @@ -231,18 +232,18 @@ The following is a non-normative example of a `CredentialObject`: } ``` -# 5. Issuer Metadata endpoint +## Issuer Metadata endpoint A credential issuer MUST support the Issuer Metadata endpoint using the HTTPS scheme and the `GET method`. The URL of the endpoint is the base issuer url with the appended path `/.well-known/vci`. The response is a `IssuerMetadata` JSON object with the following properties: -- `@context`: REQUIRED. Specifies a valid [Json-Ld context](https://www.w3.org/TR/json-ld11/#the-context). +- `@context`: REQUIRED. Specifies a valid Json-Ld context ([[json-ld11]], sect. 3.1). - `@type`: REQUIRED. A string specifying the `IssuerMetadata` type. - `credentialIssuer`: REQUIRED. A unique identifier of the issuer, for example, a DID. - `credentialsSupported`: OPTIONAL. A Json Array containing a list of `CredentialObject` JSON objects with properties - corresponding to [Credential Objects](#412-the-credentialobject). + corresponding to [[[#the-credentialobject]]]. The following is a non-normative example of a `IssuerMetadata` response object: @@ -288,7 +289,7 @@ The following is a non-normative example of a `IssuerMetadata` response object: } ``` -# 6. Credential Request Status Endpoint +## Credential Request Status Endpoint The issuer MUST provide an `HTTPS GET` endpoint for retrieving the status of a credential at the base issuer url with the appended path `/requests/`. The issuer SHOULD implement access control such that only the client that @@ -299,9 +300,9 @@ values: `RECEIVED` | `REJECTED` | `ISSUED` will be returned. The response is a `CredentialStatus` JSON object with the following properties: -- `@context`: REQUIRED. Specifies a valid [Json-Ld context](https://www.w3.org/TR/json-ld11/#the-context). +- `@context`: REQUIRED. Specifies a valid Json-Ld context ([[json-ld11]], sect. 3.1). - `@type`: REQUIRED. A string specifying the `CredentialStatus` type. -- `requestId`: REQUIRED. A string corresponding to the request id +- `requestId`: REQUIRED. A string corresponding to the request id - `status`: REQUIRED. A string equal to the one of the values: `RECEIVED`, `REJECTED`, or `ISSUED`. The following is a non-normative example of a `CredentialStatus` response object: @@ -317,7 +318,7 @@ The following is a non-normative example of a `CredentialStatus` response object } ``` -# 7. Key Rotation and Revocation +## Key Rotation and Revocation Issuer implementations SHOULD support rotation and revocation of keys used to create VC proofs. Key rotation and revocation may be supported in the following way: @@ -334,16 +335,16 @@ revocation may be supported in the following way: Implementors following this sequence should set the `expirationDate` property of issued VCs to less than the rotation period of the keys used to sign their proofs. -# 8. VC Revocation +## VC Revocation -VC revocation MUST be supported using the [Status List](https://www.w3.org/TR/vc-status-list/) specification. Note that +VC revocation MUST be supported using the [[[vc-bitstring-status-list-20230427]]] specification. Note that implementations MAY support multiple lists. -# 9. Issuer Endpoint resolution through DID Documents +## Issuer Endpoint resolution through DID Documents Different methods may be used to resolve the base location of an issuer service. One way is through DID documents. If a DID document is used, the client `DID document` MUST contain at least -one [service entry](https://www.w3.org/TR/did-core/#services) of type `IssuerService`: +one service entry ([[did-core]], sect. 5.4) of type `IssuerService`: ``` { @@ -361,12 +362,12 @@ The `serviceEndpoint` URL is the base URL for the Issuer Service. > TODO: Add `IssuerService` namespace -10. ODRL (Open Digital Rights Language) Profile +## ODRL (Open Digital Rights Language) Profile An ODRL issuance and re-issuance policy may be associated with a set of `scopes` or a [DIF Presentation Exchange presentation definition](https://identity.foundation/presentation-exchange/spec/v2.0.0/#presentation-definition). -This specification defines two ODRL attributes for the [Policy class](https://www.w3.org/TR/odrl-model/#policy) under +This specification defines two ODRL attributes for the Policy class [[odrl]] sect. 2.1) under the `iatp` namespace: - **scope** - Either a single `string` or an `array` of strings containing `scope` values @@ -424,4 +425,4 @@ and } } } -``` +``` \ No newline at end of file diff --git a/specifications/identity.protocol.base.md b/specifications/identity.protocol.base.md index 78a5430..c199c44 100644 --- a/specifications/identity.protocol.base.md +++ b/specifications/identity.protocol.base.md @@ -1,9 +1,11 @@ -# 1. Introduction +# Identity Protocol Base + +## Introduction This document defines a base protocol for communicating participant identities and claims in a Tractus-X dataspace. This specification assumes familiarity with the [Tractus-X Dataspace Topology Specification](tx.dataspace.topology.md). -# 2. Motivation +## Motivation The key goal of this protocol specification is to minimize the risk of business disruption related to the failure of identity and credential systems in a Tractus-X dataspace. As such, it provides a design for a decentralized system to @@ -15,7 +17,7 @@ communicate participant identities and [Verifiable Credentials](https://www.w3.o > for organizational security (the field of participants can be restricted through a verification process) and greatly > simplifies the technical problem at hand. -## 2.1. Decentralization +### Decentralization Decentralization is achieved in the following ways: @@ -29,10 +31,10 @@ Decentralization is achieved in the following ways: - **Multiple Trust Anchors** - Participant VCs are signed by a third-party issuer acting as a trust anchor using a cryptographic proof. The identity protocol allows for multiple trust anchors in a dataspace. -# 3. Identities and Identifiers +## Identities and Identifiers Each participant MUST have a unique, immutable **_identity_** provided by the `Registration Service` and -a [DID](https://github.com/w3c/did-core) that it chooses. This relationship is expressed as: +a [DID] [[did-core]] that it chooses. This relationship is expressed as: ``` ID ------ Can resolve to -----> DID @@ -44,14 +46,14 @@ ID ------ Can resolve to -----> DID This immutable identity is termed the `participant id`. In some dataspaces, the `participant id` may be a `DID`; otherwise there must be a mechanism to resolve a `DID` from a `participant id`. -## 3.1.The Membership VC +### The Membership VC In the case where the `participant id` is not a `DID`, dataspaces which implement the TX identity protocol MUST define a -VC that adheres to the [Verifiable Credentials Data Model v1.1](https://www.w3.org/TR/vc-data-model/) and +VC that adheres to the [[[vc-data-model]]] and cryptographically binds the `participant id` to its `DID`. This VC is termed the `Membership VC`. The VC issuer's cryptographic material MUST be resolvable via a `DID`. -# 4. Self-Issued ID Tokens +## Self-Issued ID Tokens A Self-Issued ID Token is defined in the [Self-Issued OpenID Provider v2 specification](https://openid.net/specs/openid-connect-self-issued-v2-1_0.html#section-1.1) : @@ -63,12 +65,12 @@ the [Self-Issued OpenID Provider v2 specification](https://openid.net/specs/open A client may obtain a Self-Issued ID Token using a variety or OAuth grant types. If the OAuth 2.0 Client Credential Grant type is used, the client MUST conform -to [Section 6](#6-using-the-oauth-2-client-credential-grant-to-obtain-access-tokens-from-an-sts). +to [the section on obtaining STS-issued access tokens](#using-the-oauth-2-client-credential-grant-to-obtain-access-tokens-from-an-sts). -# 4.1. Self-Issued ID Token Contents +### Self-Issued ID Token Contents The Self-Issued ID Token MUST adhere -to [JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens](https://datatracker.ietf.org/doc/html/rfc9068) and MUST +to JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens [[rfc9068]] and MUST include the following claims: - The `iss` and `sub` claims MUST be equal and set to the bearer's (participant's) DID. @@ -76,7 +78,7 @@ include the following claims: - The `aud` set to the `participant_id` of the relying party (RP) - The `jti` claim that is used to mitigate against replay attacks -## 4.1.1. VP Access Token +#### VP Access Token A Self-Issued ID Token MAY contain an access token as a `token` claim that can be used by the relying party to obtain additional VPs from a service under the control of the ID token issuer. The format of the `token` is @@ -84,18 +86,18 @@ implementation-specific and therefore must be treated as an opaque string by the > TODO: determine claim name -# 4.2. Validating Self-Issued ID Tokens +### Validating Self-Issued ID Tokens The relying party MUST follow the steps specified in the [Self-Issued OpenID Provider v2 specification](https://openid.net/specs/openid-connect-self-issued-v2-1_0.html#section-11.1). -# 5. Verifiable Presentations +## Verifiable Presentations Additional client metadata such as Verifiable Presentations can be obtained by a relying party (RP) using the client's `DID`, typically specified in the `sub` claim of a Self-Issued ID Token. The DID document may contain `service` entries that can be used to resolve metadata. -# 6. Using the OAuth 2 Client Credential Grant to Obtain Access Tokens from an STS +## Using the OAuth 2 Client Credential Grant to Obtain Access Tokens from an STS A Self-Issued ID Token MAY be obtained by a participant agent executing an [OAuth 2.0 Client Credential Grant](https://www.rfc-editor.org/rfc/rfc6749.html#section-4.4) against a Secure Token @@ -114,9 +116,9 @@ present, the `token` claim MUST not be included. > A non-normative OpenAPI spec of an STS implementing client credentials flow is > provided [here](identity-trust-sts-api.yaml) -# 7. The Identity and Trust Protocol Context +## The Identity and Trust Protocol Context -The `Json-ld context` URI for the all identity and trust specifications is: +The [[[json-ld11]]] context URI for the all identity and trust specifications is: `https://w3id.org/tractusx-trust/v[version]` diff --git a/specifications/tx.dataspace.topology.md b/specifications/tx.dataspace.topology.md index fed527d..70ab1ae 100644 --- a/specifications/tx.dataspace.topology.md +++ b/specifications/tx.dataspace.topology.md @@ -1,8 +1,9 @@ -# 1. Introduction +# Dataspace Topology + +## Introduction This document details the systems topology that Tractus-X dataspaces employ. This topology adheres to the model defined -by the [Dataspace Protocol Specifications](https://docs.internationaldataspaces.org/dataspace-protocol/overview/model) ( -DSP): +by the [Dataspace Protocol Specifications](https://docs.internationaldataspaces.org/dataspace-protocol/overview/model) (DSP): - The **Dataspace Authority** manages the dataspace. In a Tractus-X dataspace, this role may be federated across multiple operating companies responsible for registration, onboarding, and operations management. @@ -16,21 +17,21 @@ DSP): - A **Credential Issuer** issues Verifiable Credentials (VC) used by participant agents to allow access to assets and verify usage control. -## 1.1. Scope +### Scope This specification does not cover dataspace registration systems managed by a Dataspace Authority (operating company) as the participant registration and discovery process is out-of-scope. -## 1.2. Identities +### Identities The DSP specifications are based on the concept that all participants have a stable identifier (ID). This ID is typically a number assigned to the participant business entity. In this scheme, participant agent identities may be ephemeral since all operations such as signing `contract agreements`are associated with the participant identity. -This specification will also make use of [DIDs](https://github.com/w3c/did-core), which can be employed to +This specification will also make use of DIDs [[did-core]], which can be employed to cryptographically verify a participant identity. These are related as follows: -``` +```text ID ------ Can resolve to -----> DID ^ | | | @@ -42,19 +43,19 @@ participant may opt to change its hosting environment, resulting in a change to its DID in the case of `did:web` or its DID method. Since its Identifier remains stable, existing signed contracts will not be impacted. -# 2. Systems +## Systems -## 2.1. Registration System +### Registration System The registration system is responsible for participant registration, onboarding, and management. -### 2.1.1. Registration Process +#### Registration Process When a participant is onboarded, it will be assigned an ID and either a **secret token/code** or **Membership VC** that will allow the participant to bootstrap its systems. If provided a secret token, the participant will be able to exchange it for a Membership VC with a Credential Issuer. -## 2.2. Participant Agent Systems +### Participant Agent Systems Participants will run one or more agent systems that interact in the dataspace. These systems may offer data catalogs, perform data transfers or provide application functionality. @@ -62,28 +63,27 @@ perform data transfers or provide application functionality. A participant may run the following identity-related agents. Note that this is a logical description and may not represent an actual deployment topology. -### 2.2.1 Security Token Service (STS). +#### Security Token Service (STS). The STS creates self-issued authorization tokens that contain identity claims used by participant agents under the control of the same participant. -### 2.2.2 Credential Service (CS) +#### Credential Service (CS) -The CS manages [Verifiable Credentials](https://www.w3.org/TR/vc-data-model/). This includes read and write endpoints +The CS manages Verifiable Credentials [[vc-data-model]]. This includes read and write endpoints for Verifiable Presentations (VPs) and Verifiable Credentials (VCs). -### 2.2.3 DID Service (DIDS). +#### DID Service (DIDS). The DIDS Creates, signs and publishes DID documents. -## 2.3. Issuer Service (IS) +### Issuer Service (IS) The Issuer Service is run by trust anchor and manages the lifecycle of Verifiable Credentials in a dataspace. A dataspace may contain multiple Issuer Services run by different trust anchors. The Issuer Service: - Issues VCs for dataspace participants - Manages revocation lists for VC types it issues based - on [Verifiable Credentials Status List v2021](https://www.w3.org/TR/vc-status-list/). + on [[[vc-bitstring-status-list-20230427]]]. - Provides cryptographic material used to verify VPs and VCs. If this is in the form of a DID, the Issuer Service may use the Identity Hub DID Service. - diff --git a/specifications/verifiable.presentation.protocol.md b/specifications/verifiable.presentation.protocol.md index 1a9c6d7..60c3655 100644 --- a/specifications/verifiable.presentation.protocol.md +++ b/specifications/verifiable.presentation.protocol.md @@ -1,4 +1,6 @@ -# 1. Introduction +# Verifiable Presentation Protocol + +## Introduction This specification defines a protocol for storing and presenting Verifiable Credentials (VC) and other identity-related resources. The Verifiable Presentation Protocol (VPP) covers the following aspects: @@ -10,7 +12,7 @@ resources. The Verifiable Presentation Protocol (VPP) covers the following aspec > Note that management endpoints for creating resource contexts, deleting resources, and defining access control are > outside the scope of this protocol. -## 1.1. Motivation +### Motivation The Verifiable Presentation Protocol (VPP) is designed to address the problem of resolving Verifiable Presentations and other claims when they cannot be passed as part of a client request. For example, VPs often cannot be passed as part of @@ -18,34 +20,33 @@ an HTTP message header due to size restrictions. The protocol provides a secure client resources. As part of this issue, the VPP also addresses how VC issuers can request the holder's CS to store issued credentials. -## 1.2. Terms +### Terms - **Credential Service** - A network-accessible service that manages identity resources. - **Holder** - An entity that possesses a set of identity resources as defined by - the [W3C VC Data Model](https://www.w3.org/TR/vc-data-model/#dfn-holders). The holder will typically be the subject of + the W3C [[[vc-data-model]]]. The holder will typically be the subject of a VC. - **Resource** - A resource is an entity managed by the Credential Service such as a Verifiable Credential ( VC) or Verifiable Presentation (VP). - **Subject** - The target of a set of claims contained in a VC as defined by - the [W3C VC Data Model](https://www.w3.org/TR/vc-data-model/#dfn-subjects). In a dataspace, a subject will be a - participant. -- ***DID*** - A decentralized identifier as defined by the [DID specification](https://github.com/w3c/did-core). + the [[[vc-data-model]]]. In a dataspace, a subject will be a participant. +- ***DID*** - A decentralized identifier as defined by [[[did-core]]]. -## 1.3. Json-Ld Context +### Json-Ld Context The VPP is based on Json-Ld message types. The CS Json-Ld context is: `https://w3id.org/tractusx-trust/v0.8` -## 1.4. The Base URL +### The Base URL All endpoint URLs in this specification are relative. The base URL is implementation specific and may include additional context information such as a sub-path that disambiguates a holder. -# 2. Presentation Flow +## Presentation Flow Below is a sequence where the client uses the OAuth 2 client credential grant flow as defined in -the [Identity Protocol Base Specification](identity.protocol.base.md): +section [[[#identity-protocol-base]]] Specification: ![](auth.flow.png) @@ -58,18 +59,19 @@ The client receives the Self-Issued ID Token (containing an access token based o provides it with a request to access protected resources to the verifier. The verifier extracts the access token and uses it to request VPs from the client's CS. The verifier may resolve the CS endpoint through a variety of methods, for example, by resolving the client's DID document and using a service entry as described -in [Section](#6-cs-endpoint-resolution-through-did-documents). The VPs are then returned to the Verifier. +in section [[[#cs-endpoint-resolution-through-did-documents]]]. The VPs are then returned to the Verifier. + -# 3. Security +## Security CS endpoints may require an access token obtained from the resource owner. For example, a client (the resource owner) that needs to present a VP to an endpoint will provide an access token to the endpoint. The endpoint server will in turn use the access token when resolving the VP through a request to the client's Credential Service. The format of the access token is not defined. The only requirement is that the token can be used by the Credential -Service to perform an access control check as defined in [Section 3.1](#31-access-scopes) . +Service to perform an access control check as defined in section [[[#access-scopes]]] . -## 3.1. Access Scopes +### Access Scopes Scopes are used to specify access privileges. A scope is a string value in the form: @@ -77,7 +79,7 @@ Scopes are used to specify access privileges. A scope is a string value in the f The `[alias]` value may be implementation-specific. The `all` value indicates both read and write access. -### 3.1.1. The `org.eclipse.tractusx.vc.type` Alias +#### The `org.eclipse.tractusx.vc.type` Alias The `vc.type` alias value must be supported and is used to specify access to a verifiable credential by type. For example: @@ -86,7 +88,7 @@ example: denotes read-only access to the VC type `Member` and may be used to request a VC or VP. -### 3.1.2. The `org.eclipse.tractusx.vc.id` Alias +#### The `org.eclipse.tractusx.vc.id` Alias The `org.eclipse.tractusx.vc.id` alias value must be supported and is used to specify access to a verifiable credential by id. For example: @@ -96,7 +98,7 @@ by id. For example: denotes read-only access to the VC identified by `8247b87d-8d72-47e1-8128-9ce47e3d829d` and may be used to request a VC or VP. -### 3.1.3. The `*` Wildcard Alias +#### The `*` Wildcard Alias Implementations must also support the `*` wildcard: @@ -104,29 +106,29 @@ Implementations must also support the `*` wildcard: The above expression enables write-only access to all VCs. -## 3.2. Access Control +### Access Control How access control is defined in a Credential Service is implementation-specific. Implementations may provide the ability to selectively restrict access to resources. The access control mechanism must support the scope -restrictions defined in [Section 3.1](#31-access-scopes). Implementations may support additional restriction methods, +restrictions defined in section [[[#access-scopes]]]. Implementations may support additional restriction methods, + including requiring the requester to present its own VPs. -# 3.2.1 Submitting an Access Token +## Submitting an Access Token Implementations that support access control require an access token. To provide the opportunity for `Credential Service` implementations to enforce proof-of-possession, the access token MUST be contained in the `token` -claim of a self-issued identity token as defined -in [Base Identity Protocol Section 4](identity.protocol.base.md#4-self-issued-id-tokens). The self-issued token MUST +claim of a self-issued identity token as definedin section [[[#self-issued-id-tokens]]]. The self-issued token MUST be submitted in the HTTP `Authorization` header prefixed with `Bearer` of the request. -# 4. Resolution API +## Resolution API If a client is not authorized for an endpoint request, the Credential Service may return `4xx Client Error`. The exact error code is implementation-specific. -## 4.1. Presentations +### Presentations -### 4.1.1. Query For Presentations +#### Query For Presentations Presentations can be queried by POSTing a `PresentationQueryMessage` message to the query endpoint: @@ -134,7 +136,7 @@ Presentations can be queried by POSTing a `PresentationQueryMessage` message to The POST body is a `CredentialMessage` JSON object with the following properties: -- `@context`: REQUIRED. Specifies a valid [Json-Ld context](https://www.w3.org/TR/json-ld11/#the-context). +- `@context`: REQUIRED. Specifies a valid Json-Ld context ([[json-ld11]], sect. 3.1). - `@type`: REQUIRED. A string specifying the `PresentationQueryMessage` type. - `presentationDefinition`: OPTIONAL. A valid `Presentation Definition` according to the [Presentation Exchange Specification](https://identity.foundation/presentation-exchange/spec/v2.0.0/#presentation-definition). @@ -167,7 +169,7 @@ The following are non-normative examples of the JSON body: } ``` -### 4.1.1.1. Presentation Definitions +##### Presentation Definitions Implementations MAY support the `presentationDefinition` parameter. If they do not, they MUST return `501 Not Implemented`. The `presentationDefinition` parameter contains a valid `Presentation Definition` @@ -176,18 +178,18 @@ the [Presentation Exchange Specification](https://identity.foundation/presentati The CS may require an authorization token to authorize the request and uses the presentation definition to return a set of matching VPs in the format specified by the definition. -### 4.1.1.2. Scopes +##### Scopes Implementations MAY support requesting presentation of Verifiable Credentials using OAuth 2.0 OAuth 2.0 scope values. Such a scope value MUST be an alias for a well-defined Presentation Definition. The specific scope values, and the mapping between a certain scope value and the respective Presentation Definition is out of scope of this specification. -### 4.1.1.3. Response +##### Response The response type of a presentation query is a `PresentationResponseMessage` with the following parameters: -- `@context`: REQUIRED. Specifies a valid [Json-Ld context](https://www.w3.org/TR/json-ld11/#the-context). +- `@context`: REQUIRED. Specifies a valid Json-Ld context ([[json-ld11]], sect. 3.1). - `@type`: REQUIRED. A string specifying the `PresentationResponseMessage` type. - `presentation`: REQUIRED. An array of Verifiable Presentations. The Verifiable Presentations may be strings, JSON objects, or a combination of both depending on the format. @@ -204,10 +206,10 @@ The following are non-normative examples of the JSON response body: } ``` -# 5. Storage API +## Storage API VCs can be written to the Credential Service by POSTing a `CredentialMessage` containing an array -of [Verifiable Credentials]() to the `credentials` endpoint: +of Verifiable Credentials ([[vc-data-model]]) to the `credentials` endpoint: `POST /credentials` @@ -215,10 +217,10 @@ If the POST is successful, credentials will be created and a HTTP `2XX` is retur The POST body is a `CredentialMessage` JSON object with the following properties: -- `@context`: REQUIRED. Specifies a valid [Json-Ld context](https://www.w3.org/TR/json-ld11/#the-context). +- `@context`: REQUIRED. Specifies a valid Json-Ld context ([[json-ld11]], sect. 3.1). - `@type`: REQUIRED. A string specifying the `CredentialMessage` type. - `credentials`: REQUIRED. An array of `CredentialContainer` Json objects corresponding to the schema - specified [below](#the-credentialcontainer-object). + specified in section [[[#the-credentialcontainer-object]]]. The following is a non-normative example of the JSON body: @@ -237,20 +239,20 @@ The following is a non-normative example of the JSON body: } ``` -## The `CredentialContainer` Object +### The `CredentialContainer` Object The `credentials` property contains an array of `CredentialContainer` objects. The `CredentialContainer` object contains the following properties: - `@type`: REQUIRED. A string specifying the `CredentialContainer` type. -- `payload`: REQUIRED. A [Json Literal](https://www.w3.org/TR/json-ld11/#json-literals) containing the verifiable +- `payload`: REQUIRED. A [Json Literal]([[json-ld11]], sect. 4.2.2) containing the verifiable credential (VC). -# 6. CS Endpoint Resolution through DID Documents +## CS Endpoint Resolution through DID Documents Different methods may be used by a Relying Party (as defined by the OAuth2 specification, link TBD) to resolve the Credential Service for a client. One way is through DID documents. If a DID document is used, the client `DID document` -MUST contain at least one [service entry](https://www.w3.org/TR/did-core/#services) of type `CredentialService`: +MUST contain at least one `Service` entry ([[did-core]], sect. 5.4) of type `CredentialService`: ```json { @@ -266,4 +268,4 @@ MUST contain at least one [service entry](https://www.w3.org/TR/did-core/#servic } ] } -``` +``` \ No newline at end of file