# Verifiable Credentials as part of the iSHARE Framework

The iSHARE Framework contains specifications for a Verifiable Credentials based implementation. Verifiable Credentials (VCs) provide a standardized, cryptographically secure way to represent claims about an entity in a digital form.

The specifications consist of the following:

* Formal adoption of the [W3C VC Data Model 2.0](https://www.w3.org/TR/vc-data-model-2.0/).
* Formal adoption of the [Bitstring Status List v1.0](#bitstring-status-list-v1.0).
* A set of credential definitions defined by the Scheme Owner in the form of JSON schemas. See [credential-schemas](https://dev.ishare.eu/reference/credential-schemas "mention").
* The formal adoption of three Verifiable Credentials exchange protocols, including requirements for implementing these in an iSHARE Framework context:
  * [Decentralized Claims Protocol (DCP) v1.0](#decentralized-claims-protocol-dcp)
  * [OpenID4VCI v1.0](#openid4vci)
  * [OpenID4VP v1.0](#openid4vp)

## Bitstring Status List v1.0

The [Bitstring Status List](https://app.gitbook.com/u/n5NNJEApbfWSwLgV92u5lt4CPcl1) standard describes a privacy-preserving, space-efficient, and high-performance mechanism for publishing status information such as suspension or revocation of Verifiable Credentials through use of bitstrings. This method is formally adopted in the iSHARE Framework for the use of VC status. It is applied by:

* The addition of a credentialStatus property in each credential [schema](https://dev.ishare.eu/reference/credential-schemas) that is maintained by the Scheme Owner (required for all credentials, except the Data Rights Credential).
* The definition of a [Bitstring Status List Credential](https://schemas.ishare.eu/v3/common/bitstring-status-list-credential.json), that must be issued by credential issuers.

## Decentralized Claims Protocol (DCP) v1.0

The [Decentralized Claims Protocol (DCP)](https://eclipse-dataspace-dcp.github.io/decentralized-claims-protocol/v1.0/) defines a set of protocols for asserting participant identities, issuing verifiable credentials, and presenting verifiable credentials using a decentralized architecture for verification and trust. The Decentralized Claims Protocol (DCP) is well-suited for machine-to-machine (M2M) scenarios, where systems exchange verifiable credentials without human intervention.

The DCP has been integrated in the iSHARE Framework by including the endpoint requirements for every role. Endpoints that are part of the DCP are marked with <i class="fa-credit-card-blank">:credit-card-blank:</i>, and clustered in the folder "M2M Verifiable Credential Endpoints". If a participant wants to support DCP, then it MUST implement all endpoints that are required for the role(s) of the participant).

### Requirements for using DCP with iSHARE DID

The DCP requires the discovery of the [Credential Service](https://eclipse-dataspace-dcp.github.io/decentralized-claims-protocol/v1.0/#credential-service-endpoint-discovery) and [Issuer Service](https://eclipse-dataspace-dcp.github.io/decentralized-claims-protocol/v1.0/#issuer-service-endpoint-discovery) endpoints. According to the protocol, the client DID Service must make these services available as `service` entries ([*Decentralized Identifiers (DIDs) v1.0*](https://www.w3.org/TR/did-core/), sect. 5.4) in the DID document.

An [iSHARE-ID](https://framework.ishare.eu/detailed-descriptions/functional/functional-requirements-per-role/party-identification) (containing an [iSHARE DID](https://app.gitbook.com/u/n5NNJEApbfWSwLgV92u5lt4CPcl1)), does not allow the publication of a full DID document. To comply with DCP within iSHARE, using the iSHARE-ID as identifier, the service endpoints MUST instead be provided as [capabilities](https://dev.ishare.eu/all-roles-common-endpoints/capabilities).

Requirements for all roles:

* The Credential Service endpoint MUST be provided under `publicServices`
* The `identifier` of the service MUST be `"CredentialService"`
* The `endpointURL` MUST contain the base URL of the Credential Service.

Requirements for [credential issuing roles](https://dev.ishare.eu/roles/verifiable-credential-support-per-role):

* The issuer service endpoint MUST be provided under `publicServices`
* The `identifier` of the service MUST be `"IssuerService"`
* The `endpointURL` MUST contain the [base URL of the Issuer Service](https://app.gitbook.com/u/n5NNJEApbfWSwLgV92u5lt4CPcl1).

The capabilities endpoint itself is available in the Framework Compliance Claim or Dataspace Membership Claim, which can be obtained from a Participant Registry.

## OpenID4VCI v1.0

[OpenID for Verifiable Credential Issuance (OpenID4VCI)](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html) defines a protocol for credential issuance, specifying how holders can request and receive verifiable credentials from an issuer using OAuth 2.0–based flows. OpenID4VCI is designed to support human-in-the-loop (H2M) scenarios, where a user interacts with a holder application to obtain verifiable credentials

OpenID4VCI has been integrated into the iSHARE Framework by defining the required endpoints for credential-issuing participants. Endpoints that are part of OpenID4VCI are marked with <i class="fa-credit-card-blank">:credit-card-blank:</i> , and clustered in a folder "OpenID4VCI Endpoints". If a participant wants to support OpenID4VCI, it MUST implement all endpoints required for its role(s), including the credential issuance and token endpoints.

### Using OpenID4VCI with iSHARE

OpenID4VCI specifies that [Credential Issuer Metadata](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html#name-credential-issuer-metadata-) (containing for instance the URL to the Credential Issuer's Credential Endpoint) may be retrieved from the `/.well-known/openid-credential-issuer` endpoint. How the base url for this endpoint is shared between issuer and holder is not specified.

The iSHARE Framework improves discoverablity by allowing participants to publish the Issuer Base Url as a capability through the [capabilities](https://dev.ishare.eu/all-roles-common-endpoints/capabilities) endpoint.

Requirements for [credential issuing roles](https://dev.ishare.eu/roles/verifiable-credential-support-per-role):

* The issuer service endpoint MUST be provided under `publicServices`
* The `identifier` of the service MUST be `"OpenID4VCICredentialIssuerBaseUrl"`
* The `endpointURL` MUST contain the base URL for the openid-credential-issuer well-known endpoint. Example: `{OpenID4VCICredentialIssuerBaseUrl}/.well-known/openid-credential-issuer`

## OpenID4VP v1.0

[OpenID for Verifiable Presentations (OpenID4VP)](https://openid.net/specs/openid-4-verifiable-presentations-1_0.html) defines a protocol for verifiable presentation, specifying how holders can present verifiable credentials to verifiers using OAuth 2.0–based flows. OpenID4VP is designed to support human-in-the-loop (H2M) scenarios, where a user interacts with a holder application to present verifiable credentials

OpenID4VP has been integrated into the iSHARE Framework by defining the required endpoints for verifier and holder participants. Endpoints that are part of OpenID4VP are marked with <i class="fa-credit-card-blank">:credit-card-blank:</i> , and clustered in a folder "OpenID4VP Endpoints". If a participant wants to support OpenID4VP, it MUST implement all endpoints required for its role(s), including the authorization and presentation endpoints.

### Using OpenID4VP with iSHARE

OpenID4VP specifies that [Verifier Metadata](https://openid.net/specs/openid-4-verifiable-presentations-1_0.html#name-verifier-metadata) (containing for instance the URL to the Verifier's Authorization Endpoint and Presentation Endpoint) may be retrieved from the `/.well-known/openid-verifier` endpoint. How the base url for this endpoint is shared between verifier and holder is not specified.

The iSHARE Framework improves discoverablity by allowing participants to publish the Verifier Base Url as a capability through the [capabilities](https://dev.ishare.eu/all-roles-common-endpoints/capabilities) endpoint.

Requirements for [verifier roles](https://dev.ishare.eu/roles/verifiable-credential-support-per-role):

* The verifier service endpoint MUST be provided under `publicServices`
* The `identifier` of the service MUST be `"OpenID4VPVerifierBaseUrl"`
* The `endpointURL` MUST contain the base URL for the openid-verifier well-known endpoint. Example: `{OpenID4VPVerifierBaseUrl}/.well-known/openid-verifier`