0037: Present Proof Protocol 1.0

• Author: Nikita Khateev
• Start Date: 2019-01-30

Status

• Status: PROPOSED
• Status Date: 2019-05-28
• Status Note: This supersedes the Present Proof part of Indy HIPE PR #89. See RFC 0036 for the issue credential part of the same Indy HIPE PR.

Summary

Formalization and generalization of existing message formats used for presenting a proof according to existing RFCs about message formats.

Motivation

We need to define a standard protocol for presenting a proof.

Tutorial

The present proof protocol consists of these messages:

• Propose Proof - Prover to Verifier (optional)
• Request Proof - Verifier to Prover
• Present Proof - Prover to Verifier

In addition, the ack and problem-report messages are adopted into the protocol for confirmation and error handling.

Choreography Diagram:

Propose Presentation

An optional message sent by the Prover to the verifier to initiate a proof presentation process, or in response to a request-presentation message when the Prover wants to propose using a different presentation format. Schema:

{
    "@type": "did:sov:BzCbsNYhMrjHiqZDTUASHg;spec/present-proof/1.0/propose-presentation",
    "@id": "<uuid-propose-presentation>",
    "comment": "some comment",
    "presentation_proposal": <json-ld object>
}

Description of attributes:

• comment -- a field that provides some human readable information about the proposed presentation.
• presentation_proposal -- a JSON-LD object that represents the presentation example that Prover wants to provide. It should follow the schema of Presentation Preview;

Request Presentation

Request presentation is a message from a verifier to a prover that describes values that need to be revealed and predicates that need to be fulfilled. Schema:

{
    "@type": "did:sov:BzCbsNYhMrjHiqZDTUASHg;spec/present-proof/1.0/request-presentation",
    "@id": "<uuid-request>",
    "comment": "some comment",
    "request_presentations~attach": [
        {
            "@id": "libindy-request-presentation-0",
            "mime-type": "application/json",
            "data":  {
                "base64": "<bytes for base64>"
            }
        }
    ]
}

Description of fields:

• comment -- a field that provides some human readable information about this request for a presentation.
• request_presentations~attach -- an array of attachments defining the acceptable formats for the presentation.
• For Indy, the attachment contains data from libindy about the presentation request, base64 encoded. The following JSON is an example of the libindy-request-presentation-0 attachment content. For more information see the Libindy API.

{
     "name": string,
     "version": string,
     "nonce": string,
     "requested_attributes": {
          "<attr_referent>": <attr_info>,
     },
     "requested_predicates": {
          "<predicate_referent>": <predicate_info>,
     },
     "non_revoked": Optional<<non_revoc_interval>>,
}

Presentation

This message is a response to a Presentation Request message and contains signed presentations. Schema:

{
    "@type": "did:sov:BzCbsNYhMrjHiqZDTUASHg;spec/present-proof/1.0/presentation",
    "@id": "<uuid-presentation>",
    "comment": "some comment",
    "presentations~attach": [
        {
            "@id": "libindy-presentation-0",
            "mime-type": "application/json",
            "data": {
                "base64": "<bytes for base64>"
            }
        },
    ]
}

Description of fields:

• comment -- a field that provides some human readable information about this presentation.
• presentations~attach -- an array of attachments containing the presentation in the requested format(s).
• For Indy, the attachment contains data from libindy that is the presentation, base64 encoded. The following JSON is an example of the libindy-presentation-0 attachment content. For more information see the Libindy API.

{
     "requested_proof": {
         "revealed_attrs": {
             "requested_attr1_id": {sub_proof_index: number, raw: string, encoded: string},
             "requested_attr4_id": {sub_proof_index: number: string, encoded: string},
         },
         "unrevealed_attrs": {
             "requested_attr3_id": {sub_proof_index: number}
         },
         "self_attested_attrs": {
             "requested_attr2_id": self_attested_value,
         },
         "requested_predicates": {
             "requested_predicate_1_referent": {sub_proof_index: int},
             "requested_predicate_2_referent": {sub_proof_index: int},
         }
     }
     "proof": {
         "proofs": [ <credential_proof>, <credential_proof>, <credential_proof> ],
         "aggregated_proof": <aggregated_proof>
     }
     "identifiers": [{schema_id, cred_def_id, Optional<rev_reg_id>, Optional<timestamp>}]
}

Presentation Preview

This is not a message but an inner object for other messages in this protocol. It is used construct a preview of the data for the presentation. Schema:

{
    "@type": "did:sov:BzCbsNYhMrjHiqZDTUASHg;spec/present-proof/1.0/presentation-preview",
    "attributes": [
        {
            "name": "attribute name",
            "mime-type": "type",
            "encoding": "encoding",
            "value": "value"
        },
        ...
    ]
}

The main element is attributes. It is an array of objects, each with the following fields:

• name -- string with attribute name;
• mime-type -- type of attribute
• encoding -- encoding of value, if applicable: "base64" indicates base64
• value -- value of credential

Negotiation and Preview

Negotiation prior to the presentation can be done using the propose-presentation and request-presentation messages. A common negotiation use case would be about the data to go into the presentation. For that, the presentation-preview element is used.

Reference

• VCX -- this implementation might not be perfect and needs to be improved, you can gather some info on parameters purpose from it
• A pre-RFC (labeled version 0.1) implementation of the protocol was implemented by a number of groups in the Hyperledger Indy community leading up to IIW28 in April 2019. The protocol can be found here. It was the basis of the IIWBook demo from BC Gov and collaborators.

Drawbacks

Why should we not do this?

Rationale and alternatives

• Why is this design the best in the space of possible designs?
• What other designs have been considered and what is the rationale for not choosing them?
• What is the impact of not doing this?

Prior art

Similar (but simplified) credential exchanged was already implemented in von-anchor.

Unresolved questions

• We might need some explicit documentation for nested @type fields.
• There might need to be a way to associate a payment with the present proof protocol.