Credential Exchange

Stephen Curran - based on the Indy Agent WG call from 2019.03.20, I propose that we use the following messages for the 0.1 Version of the Credential Exchange Protocol. This is to make some things work for IIW. The in-process HIPE will be the ongoing HIPE that will be (eventually accepted).

Update - 2019.03.28 - We are not going to be using the proposal messages for our IIW demo, and so have indicated they are off the table in this document. We look forward to adding them post-IIW.

Issue Credential Protocol

The process can begin with either a credential-offer or a credential-proposal message. In some cases - and specifically, the case of Indy Catalyst Credential Registry (aka OrgBook), many credentials can be issued (via credential-issue messages) based on the same credential-request.

The thread decorator is implied for all messages except the first.

The <libindy json string> element is used in most messages and is the string returned from libindy for the given purpose - an escaped JSON string. The agent must process the string if there is a need to extract a data element from the JSON - for example to get the cred-def-id from the credential-offer.

Acknowledgments and Errors should be signalled via adopting the standard ack and problem-report message types, respectively.

Credential Offer

The credential_preview attribute is optional.

{
    "@type": "did:sov:BzCbsNYhMrjHiqZDTUASHg;spec/credential-issuance/0.1/credential-offer",
    "@id": "<uuid-offer>",
    "comment": "some comment",
    "credential_preview": <json-ld object>,
    "offer_json": <libindy json string>
}

The credential_preview JSON-LD object will be:


{
    "@type": "did:sov:BzCbsNYhMrjHiqZDTUASHg;spec/credential-issuance/0.1/credential-preview",
    "@context": string,
    "@id": string,
    "attributes": [
        {
            "name": "attribute name",
            "mime-type": "type",
            "value": "value"
        },
        ...
    ]
}

Credential Proposal

~~This is a message from the Prover to the Issuer indicating the credential data wanted. This message can be sent in response to a credit offer or to initiate a request.~~

IDEA: If the message is sent to initiate a request, the data in the comment or credential preview (which one makes sense? either?) could be used as input parameters for a search to get the data for a credential.

~~Use Case: When requesting a "verified email address" credential, the proposal is used to send to the issuer the email address to be verified.~~

~~The credential_preview attribute is optional~~

{
    "@type": "did:sov:BzCbsNYhMrjHiqZDTUASHg;spec/credential-issuance/0.1/credential-proposal",
    "@id": "<uuid-offer>",
    "comment": "some comment",
    "credential_preview": "<json-ld object>",
    "proposal" : {
        "cred_def_id": string,
        "schema_id": string
    }
}

~~Either a cred_def_id or a schema_id can be included, but there should not be both.~~

Credential Request

{
    "@type": "did:sov:BzCbsNYhMrjHiqZDTUASHg;spec/credential-issuance/0.1/credential-request",
    "@id": "<uuid-request>",
    "comment": "some comment",
    "request": <libindy json string>
}

Credential Issue

{
    "@type": "did:sov:BzCbsNYhMrjHiqZDTUASHg;spec/credential-issuance/0.1/credential-issue",
    "@id": "<uuid-credential>",
    "issue": <libindy json string>
}

Presentation Protocol

Switch terminology now to use "Presentation" instead of "Proof" to align with W3C.

The message family to initiate a presentation. Either party (prover or verifier) can initiate the process.

The thread decorator is implied on every message other than the first message.

The ack and problem-report messages are to be adopted by this message family.

Presentation Request

{
    "@type": "did:sov:BzCbsNYhMrjHiqZDTUASHg;spec/credential-presentation/0.1/presentation-request",
    "@id": "<uuid-request>",
    "comment": "some comment",
    "request": <libindy json string>
}

Presentation Proposal

~~Negotiation message from the Prover to the Verifier. This could be used to initiate a presentation or to provide a counter offer to a presentation request.~~

{
    "@type": "did:sov:BzCbsNYhMrjHiqZDTUASHg;spec/credential-presentation/0.1/presentation-proposal",
    "@id": "<uuid-request>",
    "comment": "some comment",
    "proposalemail ": <libindy json string>
}

Credential-Presentation

{
    "@type": "did:sov:BzCbsNYhMrjHiqZDTUASHg;spec/credential-presentation/0.1/credential-presentation",
    "@id": "<uuid-presentation>",
    "comment": "some comment",
    "presentation": <libindy json string>
}

Kyle Den Hartog

2019/03/22 02:42:10

How do you perform negotiation of the credential data if the preview is optional? (Edited)

2019/03/22 03:10:44

If we make the `@type` attribute in here set to a credential format, then we can support multiple credential formats, and the data necessary to produce those credential formats (e.g. nonce) would be defined by the message type. (Edited)

Tomislav Markovski

2019/03/22 18:16:57

You make a good point. The offer needs to be parsed anyway to get cred_def and schema. I think I'd prefer the object to be as is for now, but if you guys want to make it LD compliant, that would work as well. Just please make sure to use JSON LD library that supports different notation of the LD format: expanded, compacted, flattened, etc. (https://json-ld.org/playground/) In light of finalizing things, I'm really open to anything that helps make a decision. (Edited)

2019/03/22 18:21:13

I believe `@context` and `@id` are required by JSON LD 1.1. If this would be LD compliant, we should add the full context in the spec. (Edited)

2019/03/22 18:25:41

Stephen, I apologize, I missed the threading note. I think a thread cannot have more than one Offer, Request and Credential because if how unique they are to libindy. A new offer should start a new thread. Between parties, there can be multiple threads for different credentials (regardless of cred_def_id and so on). Nick, ordering cannot be used to associate request/offer since I can receive two offers in one order but decide to respond to them in a different order. (Edited)

Stephen Curran

2019/03/25 19:25:56

> **Nick**: If you are referring to libindy message types here, the flow cannot start with a `credential-request` since a `credential-offer` is required to create one. So I believe the flow can only start with a `credential-offer` from the issuer or a `credential-proposal` from the holder. From a workflow standpoint, a `credential-proposal` is essentially requesting a `credential-offer` from the issuer. > **Stephen**: `credential-proposal` is also a way to negotiate, so it can also be a response (Edited)

2019/03/25 19:26:14

Corrected to remove Credential-Request as an initial message (Edited)

2019/03/25 19:27:47

In some use cases, there is no need for negotiation, and no need for a preview. Enterprise to enterprise agents likely don't need that all the time. For sure the OrgBook use case does not require it. (Edited)

2019/03/25 19:29:58

That's the intention. For the short term we'll use an agreed to string (e.g. "libindy") and we'll let the Agent Group define the official type. (Edited)

2019/03/25 19:33:45

OK (Edited)

2019/03/25 19:37:24

I agree - cannot have more than one libindy offer, but it could have a libindy and uport offer. That's the point of the array here. (Edited)

2019/04/04 20:27:05

OK to change "mime-type" to "mime_type" to keep naming convention consistent? (Edited)