diff --git a/features/0037-present-proof/README.md b/features/0037-present-proof/README.md index 562cd59ae..1d7559495 100644 --- a/features/0037-present-proof/README.md +++ b/features/0037-present-proof/README.md @@ -35,11 +35,11 @@ Diagrams in this protocol were made in draw.io. To make changes: - export the picture and HTML to your local copy of this repo, and - submit a pull request. -#### Choreography Diagram: +### Choreography Diagram: ![present proof](credential-presentation.png) -#### Propose Presentation +### 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: @@ -57,7 +57,7 @@ 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](#presentation-preview); -#### Request Presentation +### 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: @@ -84,7 +84,7 @@ Description of fields: * `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, as returned from `libindy`. For more information see the [Libindy API](https://github.com/hyperledger/indy-sdk/blob/57dcdae74164d1c7aa06f2cccecaae121cefac25/libindy/src/api/anoncreds.rs#L1214). -#### Presentation +### Presentation This message is a response to a Presentation Request message and contains signed presentations. Schema: @@ -111,66 +111,88 @@ Description of fields: * `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, as returned from `libindy`. For more information see the [Libindy API](https://github.com/hyperledger/indy-sdk/blob/57dcdae74164d1c7aa06f2cccecaae121cefac25/libindy/src/api/anoncreds.rs#L1404). -#### Presentation Preview +### Presentation Preview This is not a message but an inner object for other messages in this protocol. It is used to construct a preview of the data for the presentation. Its schema follows: ```json { "@type": "did:sov:BzCbsNYhMrjHiqZDTUASHg;spec/present-proof/1.0/presentation-preview", - "attributes": { - "": { - "": { - "mime-type": "", - "encoding": "", - "value": "" - } - }, - ... - }, - "predicates": { - "": { - "": { - "": "", - ... - }, - ... - }, - ... - }, - "non_revocation_times": { - "": "", - ... - } + "attributes": [ + { + "name": "", + "cred_def_id": "", + "mime-type": "", + "encoding": "", + "value": "" + } + ], + "predicates": [ + { + "name": "", + "cred_def_id": "", + "predicate": "", + "threshold": + } + ] } ``` -The preview identifies attributes, predicates, and non-revocation timestamps by credential definition identifier. Note that this composition assumes that any presentation can include information from at most one credential per credential definition; such an approach mitigates corroboration risk. +The preview identifies attributes and predicates to present. + +#### Attributes + +The mandatory `"attributes"` key maps to a list (possibly empty to propose a presentation with no attributes) of specifications, one per attribute. Each such specification proposes its attribute's characteristics for creation within a presentation. + +##### Attribute Name + +The mandatory `"name"` key maps to the name of the attribute. + +##### Credential Definition Identifier + +The optional `"cred_def_id"` key maps to the credential definition identifier of the credential with the current attribute. If the key is absent, the preview specifies attribute's posture in the presentation as a self-attested attribute. + +##### Attribute Metadata (MIME Type and Encoding) + +The optional `"mime-type"` and `"encoding"` keys specify any MIME type and encoding metadata pertaining to the attribute. Their values default to `"text/plain"` and `null` respectively. + +##### Value + +The `"value"` key maps to the proposed value of the attribute to reveal within the presentation. An attribute specification must specify a `"value"`, a `"cred_def_id"`, or both: + +* if the `"value"` key is present and the `"cred_def_id"` key is absent, the preview proposes a self-attested attribute; +* if the `"value"` key and the `"cred_def_id"` are both present, the preview proposes verifiable claim to reveal in the presentation; +* if the `"value"` key is absent and the `"cred_def_id"` key is present, the preview proposes verifiable claim not to reveal in the presentation. + +#### Predicates + +The mandatory `"predicates"` key maps to a list (possibly empty to propose a presentation with no predicates) of predicate specifications, one per predicate. Each such specification proposes its predicate's characteristics for creation within a presentation. -##### Attributes +##### Attribute Name -The `"attributes"` key maps zero or more credential definition identifiers to one or more inner objects; each such inner object maps an attribute name to its respective MIME types, encodings, and values (all optional) for the presentation: +The mandatory `"name"` key maps to the name of the attribute germane to the predicate. -* the prover may include a MIME type and/or encoding per attribute in the preview for verifier information on how to interpret its value -* the value itself may be absent at this stage; its omission in the preview indicates its ultimate inclusion in the presentation itself. +##### Credential Definition Identifier -Any attribute specified per credential definition identifier must belong to its corresponding credential definition. In this way the structure excludes a bait-and-switch where the prover has credentials on multiple credential definitions with common attribute names (e.g., `name`, `score`). +The mandatory `"cred_def_id"` key maps to the credential definition identifier of the credential with the current attribute. -For consistency and completeness, an empty production `"{}"` as the value for the `"attributes"` key denotes that the preview specifies zero attributes. +##### Predicate -##### Predicates +The mandatory `"predicate"` key maps to the predicate operator: `"<"`, `"<="`, `">="`, `">"`. -The `"predicates"` key maps zero or more credential definition identifiers to one or more inner objects; each such inner object maps predicate names to their respective attributes and thresholds for the presentation. Each predicate name identifies its comparison operator: `"<"`, `"<="`, `">"`, `">="`. Each attribute so specified per credential definition identifier must belong to its corresponding credential definition. +##### Threshold Value -For consistency and completeness, an empty production `"{}"` as the value for the `"predicates"` key denotes that the preview specifies zero predicates. +The mandatory `"threshold"` key maps to the threshold value for the predicate. -##### Non-Revocation Timestamps +##### Filter -The `"non_revocation_times"` key maps zero or more credential definition identifiers to ISO 8601 datetimes, each of which offers an instant where the prover or verifier proposes inclusion of proof of the non-revocation of its corresponding credential in the presentation. +The mandatory `"filter"` key maps to an object with one or more criteria disjunctively (via "or") applicable to the attribute as a claim. -Non-revocation timestamps apply only to credentials on credential definitions that support revocation. +Filter keys include: -For consistency and completeness, an empty production `"{}"` as the value for the `"non_revocation_times"` key denotes that the preview specifies zero non-revocation timestamps. +* `"cred_def_id"` to specify a credential definition identifier +* `"schema_id"` to specify a schema identifier +* any other criteria that both the holder and verifier understand in the context of presentation creation. ## Negotiation and Preview @@ -187,7 +209,7 @@ The presentation preview as proposed above does not allow nesting of predicate l The presentation preview may be indy-centric, as it assumes the inclusion of at most one credential per credential definition. In addition, it prescribes exactly four predicates and assumes mutual understanding of their semantics (e.g., could `">="` imply a lexicographic order for non-integer values, and if so, where to specify character collation algorithm?). -Finally, the inclusion of a non-revocation timestamp may be premature at the preview stage. +Finally, the inclusion of non-revocation timestamps may become desirable at the preview stage; the standard as proposed does not accommodate such. ## Rationale and alternatives