Layering

This protocol specification is meant to sit atop the Verifiable Credentials v1.0 data format, the various Communication technologies and the transport layers. The following diagram is a visual (but not exhaustive) representation of how the various components in a Decentralized Identity ecosystem fit. Your mileage may vary.

When the protocol can be used in conjunction with a particular message transport technology, this is referred to as a binding. Sample bindings are included in the Annex, and may be expressed as separate specifications.

Issuance Flow

Invite Message (optional)

An entity is willing to provide verifiable credentials to qualified Holders. The Invitation message allows Holders to 'discover' how to communicate with an Issuer. "I invite Holders to Introduce themselves in this way."

Introduce Message

Holders Introduce themselves to Issuers by providing details about "who they are" and "how to communicate with them" - Identity and Location.

Bootstrap Trust

Holders and Issuers go through a process of establishing a Trust relationship. Examples include trusted TLS certificates in HTTPS protocols, Verifiable Credential exchange, or physical (in person) trust.

Create Credential

The Holder is requesting a Credential of a certain type, schema, and format. The Issuer processes the request and returns the Credential if possible. This message may be implied by the Issuer as Credential parameters may be determined out-of-band of this protocol (through user experience, for example).

Credential Params

This message may be sent if in order to create a credential an Issuer and Holder need exchange additional information. This message MAY be sent in response to either Create Credential or Store Credential messages, and MAY be exchanged as many times as necessary.

Store Credential

The Issuer is ready to provide a Verifiable Credential for use/storage at the Holder. The Holder can accept the Credential, or provide back a Credential Params response if necessary (for example, extra data to create the necessary cryptographic proofs).

Presentation Flow

Presentation Request

The Verifier makes a Presentation Request with the desired parameters to the Holder. A Presentation Request message may be referenced in other Presentation messages, but itself does not require a direct response. Presentation messages may be cached, physically printed, implied, and so on.

Presentation Response

The Holder's Response for a Presentation Request. This may contain the Credential Presentation, or provide information on how to get the Credential Presentation.

Presentation Params (optional)

The Holder and Verifier MAY provide additional parameters relative to the Presentation Response. Holders and Verifiers MAY exchange this message as many times as required.

I am not sure this message belongs as part of this protocol - during the Response these custom details may simply be negotiated for a particular Comm Channel.

Get Presentation (optional)

An optional step where the Verifier is required to call out to an external entity to collect the data. For example, an Encrypted Data Vault or an Identity Hub or a Web Service, etc... The Comm Channel requirements for this step are negotiated during the Response.

Invite

The purpose of the invite message is to publish basic trust credentials and service capabilities of the Issuer for the purposes of discovery and connection bootstrapping by a Holder.

This message may be static and generally available, or it may be generated in the context of a session, a transaction, or periodically.

Need to determine what belongs here and what remains the DID Document.

type

REQUIRED. MUST be set to "issuer-invite".

issuer

REQUIRED. MUST be set to a URI for the issuer. This MAY be a URL or MAY be a DID. If the iss is a URL, it MUST be "https://". DIDs MAY be did:peer DIDs or Resolvable DIDs.

How do did:key and did:web fit in here?

Using "issuer" not JOSE "iss" because issuer has specific semantics for VCs.

enk

OPTIONAL. MUST be a public key the Holder can use to encrypt messages to the Issuer. This MAY be a JWK or a did:key:...

formats

REQUIRED. An array of the supported formats of Verifiable Credential proof algorithms the issuer is able to support. This MUST contain one of:

• zkp: for zero knowledge proofs.
• ldsig: for LD-Signature proofs.
• jws: for inline JWS proofs.
• jwsd: for detached JWS signature proofs. (is this a defined thing in v1.0? Or just LD?)

bindings

REQUIRED. An array of VC-QL binding schemes this issuer supports, and their associated connection details.

Bindings may not make sense; this may be something that comes across in the DID Document.

credentials

REQUIRED. An array of credential types / schema definition DIDs. Schemas defined by URLs MUST used the did:web: method.

if we enforce did:web here, why not in the iss field?

"vc-ql": {
    "type": "issuer-invite",
    "issuer" : "did:example:IiI",
    "enk": "did:key:z6eu48rjfdi39djdiod9de9wjwid9d",
    "formats" : [ "zkp", "ldsig", "jws", "jwsd" ],
    "bindings": [
        { "scheme": "https", "params" : { "endpoint: "https://issuer.org/request"} },
        { "scheme": "didcomm", "params" : { "@type" : "https://didcomm.org/didexchange/1.0/invitation", ...} },
        { "scheme": "oauth3", "params" : { "txnreq" : "https://issuer.org/oauth3/req"}},
        { "scheme": "js-inline"}
    ],
    "credentials": [ "did:web:https://schema.org/Person" ]
}
        

Issuers MAY publish this invite for general public access, or it MAY generate specific invite messages for given scenarios, sessions, or use cases.

How an issuer provides this message to a Holder is out of scope for this specification, but examples include hosting this information on a .well-known/ URL, printing a barcode Holders can scan, or providing it out of band to Holder developers in a published API specification.

Holders that receive this message MUST process it in the following manner:

1. MUST check the type is "issuer-invite".
2. MUST verify the signature belongs to the iss by either resolving the signing key from the DID document, or verifying the host TLS certificate if the iss is a URL.
3. MUST process the enk as an algorithm the Holder can support and the key is valid.
4. MUST process the proofs list to ensure the Holder can support at least one format. If the Holder is unable to support at least one format, the Holder MUST inform the user of the error and stop processing.
5. MUST process the binding array and find at least one supported binding the Holder can support. If there is no compatible binding, the Holder MUST inform the user of the error and stop processing.
6. MUST process the credentials array and determine if those Credential types are applicable for the Holder.

Introduce

Introduction is a request/response protocol message. Holders introduce their subjects (and possibly themselves) to the Issuer, and the Issuer MUST indicate if the introduction was accepted, rejected, or needs more information.

"vc-ql" : {
    "type" : "issuer-introduce",
    "sub" : "did:example:Udid99",
    "aud" : "did:example:IiI",
    "enk" : "did:example:Udid99#key-2",
    "params" : { }
}
            

"vc-ql": {
    "type" : "issuer-introduce-accepted"
}
            

"vc-ql": {
    "type" : "issuer-introduce-continue",
    "params" : { }
}
            

Bootstrapping Trust

Bootstrapping trust refers to the exchange of messages required for the Issuer and Subject/Holder to establish the required trust assurance to Issue (and accept) the Credential. A trivial example would be in the case of a driver's license:

• How does the Subject and Holder trust they are getting a Credential from their DMV?
• How does the DMV Issuer know it is issuing the credential to the right Driver, and to a trusted Holder software product?

Trust Frameworks and their governance are outside the scope of this specification. For the purposes of this specification it is sufficient to note that profiles of this protocol MUST define the requirements of how trust is established between Issuer, Holder and Subject before Issuance can occur.

Examples include the use of TLS certificates, providing Verifiable Credentials issued from a shared Trust authority, providing attestation certificates such as in [[Web AuthN]], the exchange of shared secrets or other credentials, or even in-person, physical trust establishment (like a certification sticker on a barcode reader).

Create Credenital

This is a message for a Holder to request a credential of a certain type from an Issuer. This message is OPTIONAL in a workflow.

In workflows where a Holder is actively trying to collect credentials from Issuers and the Comm Channel allows for the Holder to reach out to the Issuer, this message MAY be used. This message MAY be used in scenarios where additional Holder to Issuer messages are required to generate the Credential, for example in Zero Knowledge Proof scenarios.

In workflows where the Issuer is interacting with the user and then offers to provide a Credential to the user's Holder, for example at a physical kiosk or a website, the Issuer may interact with the user to determine the parameters of the Credential it is willing to issue, then skip right to the Store Credential message.

"vc-ql": {
    "type" : "issue-credential-request",
    "sub" : "did:example:Udid99",
    "aud" : "did:example:IiI",
    "format" : "ld-proof",
    "credentials" : [ 
        { 
            "type" : [ "VerifiableCredential", "UniversityDegreeCredential" ],
            "id" : "did:example:Udid99",
            "params" : { } 
        },
        {
            "type" : [ "VerifiableCredential", "UniversityTranscriptCredential" ],
            "id" : "did:example:Udid99",
            "claims" : [ "final_gpa" ]
            "params" : { }
        }
     ]
}
            

"vc-ql": {
    "type" : "issue-credentials-params",
    "aud" : "did:example:Udid99",
    "issuer" : "did:example:IiI",
    "credentials" : [ 
        { 
            "type" : [ "VerifiableCredential", "UniversityDegree" ],
            "id" : "did:example:Udid99",
            "params" : { 
                "myparam1" : { "type: : "present-credential-request", ... }
            } 
        },
        {
            "type" : [ "VerifiableCredential", "UniversityTranscript" ],
            "id" : "did:example:Udid99",
            "params" : { 
                "redirect" : { "type" : "url_interaction", ... } 
            }
        }
     ]
}
            

Store Credential

This message is from the Issuer to the Holder containing the issued Verifiable Credential.

This message SHOULD be trusted and secured over the Comm Channel. If the Comm Channel cannot provide enough trust or security, this message MUST be wrapped in JOSE or COSE signing and/or encryption payloads. This message MUST be encrypted directly to the Holder or the Holder's EDV.

Same issue as above on how a processing agent can easily detect if the payload is plain, jose, or cose?

vc-ql : {
    "type" : "issuer-store-credential"
    "vcs" : [ 
        { 
            "@context": [
              "https://www.w3.org/2018/credentials/v1",
              "https://www.w3.org/2018/credentials/examples/v1"
            ],
            "id": "UniqueIdentifierGoesHere",
            "type": [ "VerifiableCredential", "UniversityDegreeCredential"],
            "issuer": "did:example:IiI",
            "issuanceDate": "2010-01-01T19:73:24Z",
            "credentialSubject": {
              "id": "did:example:Udid99",
              "degree": {
                "type": "BachelorDegree",
                "name": "Bachelor of Science and Arts"
            },
            "proof": {
              "type": "RsaSignature2018",
              "created": "2017-06-18T21:19:10Z",
              "proofPurpose": "assertionMethod",
              "verificationMethod": "did:example:IiI#key-1",
              "jws": "eyJhbGciOiJSUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..TCYt5X
                sITJX1CxPCT8yAV-TVkIEq_PbChOMqsLfRoPsnsgw5WEuts01mq-pQy7UJiN5mgRxD-WUc
                X16dUEMGlv50aqzpqh4Qktb3rk-BuQy72IFLOqV0G_zS245-kronKb78cPN25DGlcTwLtj
                PAYuNzVBAh4vGHSrQyHUdBBPM"
            }
        }
    ]
}
        

Processing agents should probably also check that the DIDs and Keys the thing was issued to match what the Holder asked for...

Holders (or EDVs) SHOULD iterate through the vcs array and store the associated credentials.

Do we want to include a 'revocation' field, where a previous VC ID can be indicated as 'revoked'? This would be an OPTIONAL field, and complicate the processing of these messages...

Presentation Request

A Verifier first needs to generate Verifiable Presentation request to provide to the Holder to process. The format of the request is as follows:

Unorganized notes. Verifier instead of classic JSON "iss" because "issuer" is an overloaded term. returnURI - this can be a DID or a URL -- is this part of the Comm Layer? purposeURI - did or URL with standard language. "reason" - do we really need a reason for each schema? delegated flag? using credential.name instead of ID because processing the response will be code looking for different credential types, not unique IDs.

"vq-rl" : {
    "type" : "verifier-request",
    "id" : "uuid:8D9FA614-71DC-4B4B-A243-5696FD98C408",
    "verifier" : "did:example:VeR66"
    "returnURI" : "did:example:VeR66/callback",
    "purposeURI" : "did:example:3483898298381/purpose1",
    "purposeText" : {
        "en_ca" : "Membership Sign Up",
        "en_fr" : "S'inscrire à l'adhésion"
        "es_mx" : "Inscripción de membresía"
    }
    "formats" : [ "zkp","ldsig" ],
    "genericParams" : { ... }
    "strict" : true
    "credentials" : [
        {
            "name" : "uniqueStringAssignedByVerifier",
            "reason" : { 
                "en_ca" : "Because I want it.",
                "en_fr" : "parce que je le veux.",
                "es_mx" : "Porque lo quiero"
            },
            "issuers" : [ "did:example:3483898298381/institution_list", "did:example:IiI" ],
            "@context" : [ " "https://w3.org/2018/credentials/v1" ],
            "type" : [ "VerifiableCredential", "UniversityDegree" ],
            "claims" : [ "degree" ],
            "required" : true,
            "issuer_source" : true
            "params" : { .. },
        },
        {
            "name" : "AnotheruniqueStringAssignedByVerifier",
            "issuers" : [ "did:example:3483898298381/passport_issuers" ],
            "@context" : [ ],
            "type" : [ "VerifiableCredential", "Personal" ],
            "required" : true,
        }
    ],
}

        

This spec does not allow for a rich query language, because it forces Holders to implement complex UIs. Verifiers either need the information they are asking for, or they have determined through a UI session what this query must contain. Verifiers own their business logic, not Holders.

Presentation Parameters

In cases where the Holder requires more information from the Verifier to proceed with the Presentation. This could be parameters for the proof objects or to establish trust.

"vq-rl" : {
    "type" : "verifier-params",
    "id" : "uuid:50AD9BCF-4D88-4605-9F9B-378A939F7999",
    "requestId" : "uuid:8D9FA614-71DC-4B4B-A243-5696FD98C408",
    "genericParams" : {
        "myparam1" : { .. }
    },
    "presentationParams" : [
        {
            "name" : "uniqueStringAssignedByVerifier",
            "params" : { ... }
        },
        {
            "name" : "AnotheruniqueStringAssignedByVerifier",
            "params" : { .. }
        }
    ]
}
    

Verifiers receiving a verifier-params response MUST re-issue a verifier-request with the required parameters to the Holder if they can support the request.

Presentation Response

This message contains the response to a Presentation Request (a verifier-request). In some cases "unsuccessful" responses can be ignored, as the Verifier cannot proceed without the required data. In other cases an unsuccessful response MAY be provided to the Verifier for cases where the Verifier is capable of alternate business logic and success paths.

"vr-ql" : {
    "type" : "verifier-response",
    "id" : "uuid:50768C74-0D43-431C-B735-C26F37F58AF6",
    "requestId" : "uuid:8D9FA614-71DC-4B4B-A243-5696FD98C408",
    "result" : enum ["fail", "partial", "complete"],
    "credentials" : [
        {
            "name" : "uniqueStringAssignedByVerifier",
            "vp" : { ... },
            "vpURI" : " my_edv_uri"
        },
        {
            "name" : "AnotheruniqueStringAssignedByVerifier",
            "error" : "unavailable"
        }
    ]
}