From 004eb0771808e2d7cd577eb4e1f7b14d96935d0a Mon Sep 17 00:00:00 2001 From: Sam Curren Date: Tue, 26 Jul 2022 15:22:08 -0600 Subject: [PATCH 1/7] First Draft of additional protocol attributes Signed-off-by: Sam Curren --- features/0453-issue-credential-v2/README.md | 17 ++++++++++++++++- features/0454-present-proof-v2/README.md | 18 +++++++++++++++++- 2 files changed, 33 insertions(+), 2 deletions(-) diff --git a/features/0453-issue-credential-v2/README.md b/features/0453-issue-credential-v2/README.md index 1c8f05f0f..eb9012d1c 100644 --- a/features/0453-issue-credential-v2/README.md +++ b/features/0453-issue-credential-v2/README.md @@ -315,7 +315,19 @@ Message Format: "base64": "" } } - ] + ], + "issuer_credentials" : [ + { + "@id": "" + } + ], + "hashlink_data": [ + { + "@id": "", + "field": "" + } + ], + "~attach" : [] //attachments referred to in message attributes } ``` @@ -330,6 +342,9 @@ Description of fields: * When the Holder receives this message with the field set to a positive integer, the Holder's state moves to the `offer-received` state. * `formats` -- contains an entry for each `credentials~attach` array entry, providing the the value of the attachment `@id` and the verifiable credential format and version of the attachment. Accepted values for the `format` items are provided in the per format "Attachment" sections immediately below. * `credentials~attach` -- an array of attachments containing the issued credential in the format(s) requested by the Holder. +* `issuer_credentials` -- an array of references to credentials related to the issuer. +* `hashlink_data` -- an array linking attachments to the appropriate credential attribute with a hashlink. +* `~attach` -- attachments related to the issued credential. Each attachment should be represented in the appropriate message attributes and referenced by attachment id. If the issuer wants an acknowledgement that the last issued credential was accepted, this message must be decorated with the `~please-ack` decorator using the `OUTCOME` acknowledgement request. Outcome in the context of this protocol means the acceptance of the credential in whole, i.e. the credential is verified and the contents of the credential are acknowledged. Note that this is different from the default behavior as described in [0317: Please ACK Decorator](../0317-please-ack/README.md). It is then best practice for the new Holder to respond with an explicit `ack` message as described in the please ack decorator RFC. diff --git a/features/0454-present-proof-v2/README.md b/features/0454-present-proof-v2/README.md index 9ac19ebdc..43f7505d1 100644 --- a/features/0454-present-proof-v2/README.md +++ b/features/0454-present-proof-v2/README.md @@ -234,7 +234,19 @@ This message is a response to a Presentation Request message and contains signed "links": ["https://ibb.co/TtgKkZY"] } } - ] + ], + "issuer_credentials" : [ + { + "@id": "" + } + ], + "hashlink_data": [ + { + "@id": "", + "field": "" + } + ], + "~attach" : [] //attachments referred to in message attributes } ``` @@ -245,6 +257,10 @@ Description of fields: * `last_presentation` -- an optional field that defaults to `true` to indicate this is the last presentation message to be sent in satisfying the presentation request. If the value is `false`, the Prover MUST send another presentation message with an additional presentation(s). The Prover's last `presentation` message MUST have a `last_presentation` value of `false` (explicitly or by default). If the `present_multiple` field is absent or `false` in the `request_presentation` message from the Verifier, the `last_presentation` field on the first/only `presentation` message MUST be true (explicitly or by default). * `formats` -- contains an entry for each `presentations~attach` array entry, providing the the value of the attachment `@id` and the verifiable presentation format and version of the attachment. Accepted values for the `format` items are provided in the per format [Attachment](#presentation-request-attachment-registry) registry immediately below. * `presentations~attach` -- an array of attachments containing the presentation in the requested format(s). If the `present_multiple` field is `true` in the `request_presentation` message from the Verifier, the Prover MAY include multiple presentations of the same format that satisfy the Presentation request from the Verifier. +* `issuer_credentials` -- an array of references to credentials related to the issuer. +* `hashlink_data` -- an array linking attachments to the appropriate credential attribute with a hashlink. +* `~attach` -- attachments related to the issued credential. Each attachment should be represented in the appropriate message attributes and referenced by attachment id. + If the `last_presentation` field is `false`, the Verifier's state SHOULD remain in the `request-sent` state (barring an error), with the expectation that additional `presentation` messages will be coming from the prover. If the `last_presentation` value is `true` (explicitly or by default) the Verifier MUST transition to their next appropriate state. From 4152336b16ec60d041335b083e6f9c6db656c132 Mon Sep 17 00:00:00 2001 From: Sam Curren Date: Fri, 29 Jul 2022 10:45:01 -0600 Subject: [PATCH 2/7] update to issue to show difference in approach Signed-off-by: Sam Curren --- features/0453-issue-credential-v2/README.md | 54 +++++++++++++++++---- 1 file changed, 44 insertions(+), 10 deletions(-) diff --git a/features/0453-issue-credential-v2/README.md b/features/0453-issue-credential-v2/README.md index eb9012d1c..451165368 100644 --- a/features/0453-issue-credential-v2/README.md +++ b/features/0453-issue-credential-v2/README.md @@ -316,15 +316,18 @@ Message Format: } } ], - "issuer_credentials" : [ + "supplements": [ { - "@id": "" - } - ], - "hashlink_data": [ + "type": "hashlink_data", + "@id": "", + "attrs": { + "key": "field", + "value": "" + } + }, { - "@id": "", - "field": "" + "type": "issuer_credential", + "@id": "", } ], "~attach" : [] //attachments referred to in message attributes @@ -342,12 +345,43 @@ Description of fields: * When the Holder receives this message with the field set to a positive integer, the Holder's state moves to the `offer-received` state. * `formats` -- contains an entry for each `credentials~attach` array entry, providing the the value of the attachment `@id` and the verifiable credential format and version of the attachment. Accepted values for the `format` items are provided in the per format "Attachment" sections immediately below. * `credentials~attach` -- an array of attachments containing the issued credential in the format(s) requested by the Holder. -* `issuer_credentials` -- an array of references to credentials related to the issuer. -* `hashlink_data` -- an array linking attachments to the appropriate credential attribute with a hashlink. -* `~attach` -- attachments related to the issued credential. Each attachment should be represented in the appropriate message attributes and referenced by attachment id. +* `supplements` -- an array of attachment descriptors detailing credential supplements. See the Supplements Section for details. +* `~attach` -- attachments related to the issued credential. Each attachment should be detailed in a `supplements` entry, referenced by attachment id. If the issuer wants an acknowledgement that the last issued credential was accepted, this message must be decorated with the `~please-ack` decorator using the `OUTCOME` acknowledgement request. Outcome in the context of this protocol means the acceptance of the credential in whole, i.e. the credential is verified and the contents of the credential are acknowledged. Note that this is different from the default behavior as described in [0317: Please ACK Decorator](../0317-please-ack/README.md). It is then best practice for the new Holder to respond with an explicit `ack` message as described in the please ack decorator RFC. +##### Supplements +Supplements are used to provide information related to credentials. Each supplement must be included as a message attachment in the `~attach` array, and have a descriptor contained in the `supplements` array with the following structure: + +```json +{ + "type": "", + "@id": "", + "attrs": [ + { + "key": "", + "value": "" + } + ] +} +``` +- `type` SHOULD be from the following list. Compliance with this RFC indicates support of the official listed supplement types below. +- `@id` is the id of the attachment within the `~attach` list. +- `attrs` is a list of key/value pairs, used with supplement types that need additional information for processing. If no key/value pairs are needed, `attrs` may be omitted. + + +Official Supplement Types: +- `issuer_credential` + - Contains a credential related to the Issuer of the credential being presented. +- `hashlink_data` + - Contains binary data who's hashlink is contained within a presented credential. + - This binary data MUST only be transmitted if the associated credential attribute containing the hashlink is also transmitted. + - An attr key value pair of "field", and value of the attribute name must be sent in the attrs structure. + +Holder Behavior + +It is expected that a holder retain supplements provided during issuance, and present them as appropriate during presentation. Some supplements (such as `hashlink_data`) require understanding of when to include, as noted in the Supplment details. Supplements of an unknown type SHOULD NOT be automatically be presented + ##### Credentials Attachment Registry Credential Format | Format Value | Link to Attachment Format | Comment | From c2ba57c0408a1acf5237985fddb96be9843f69f0 Mon Sep 17 00:00:00 2001 From: Sam Curren Date: Fri, 12 Aug 2022 13:21:35 -0600 Subject: [PATCH 3/7] Update Present proof with reference to supplements Signed-off-by: Sam Curren --- features/0454-present-proof-v2/README.md | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/features/0454-present-proof-v2/README.md b/features/0454-present-proof-v2/README.md index 43f7505d1..1641c4da7 100644 --- a/features/0454-present-proof-v2/README.md +++ b/features/0454-present-proof-v2/README.md @@ -235,18 +235,21 @@ This message is a response to a Presentation Request message and contains signed } } ], - "issuer_credentials" : [ + "supplements": [ { - "@id": "" - } - ], - "hashlink_data": [ + "type": "hashlink_data", + "@id": "", + "attrs": { + "key": "field", + "value": "" + } + }, { - "@id": "", - "field": "" + "type": "issuer_credential", + "@id": "", } ], - "~attach" : [] //attachments referred to in message attributes + "~attach" : [] //attachments referred to in supplements } ``` @@ -258,9 +261,8 @@ Description of fields: * `formats` -- contains an entry for each `presentations~attach` array entry, providing the the value of the attachment `@id` and the verifiable presentation format and version of the attachment. Accepted values for the `format` items are provided in the per format [Attachment](#presentation-request-attachment-registry) registry immediately below. * `presentations~attach` -- an array of attachments containing the presentation in the requested format(s). If the `present_multiple` field is `true` in the `request_presentation` message from the Verifier, the Prover MAY include multiple presentations of the same format that satisfy the Presentation request from the Verifier. * `issuer_credentials` -- an array of references to credentials related to the issuer. -* `hashlink_data` -- an array linking attachments to the appropriate credential attribute with a hashlink. -* `~attach` -- attachments related to the issued credential. Each attachment should be represented in the appropriate message attributes and referenced by attachment id. - +* `supplements` -- an array of attachment descriptors detailing credential supplements. See the Supplements Section in [0453: Issue Credential v2 Protocol](../0453-issue-credential-v2/README.md#supplements) for details. +* `~attach` -- attachments related to the issued credential. Each attachment should be detailed in a `supplements` entry, referenced by attachment id. If the `last_presentation` field is `false`, the Verifier's state SHOULD remain in the `request-sent` state (barring an error), with the expectation that additional `presentation` messages will be coming from the prover. If the `last_presentation` value is `true` (explicitly or by default) the Verifier MUST transition to their next appropriate state. From 0c6c37e9bfa21cb38a32a3eef98692bdbf6d75c8 Mon Sep 17 00:00:00 2001 From: Sam Curren Date: Fri, 12 Aug 2022 13:23:41 -0600 Subject: [PATCH 4/7] Add new minor version numbers Signed-off-by: Sam Curren --- features/0453-issue-credential-v2/README.md | 6 +++++- features/0454-present-proof-v2/README.md | 4 ++++ 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/features/0453-issue-credential-v2/README.md b/features/0453-issue-credential-v2/README.md index 451165368..de2e24190 100644 --- a/features/0453-issue-credential-v2/README.md +++ b/features/0453-issue-credential-v2/README.md @@ -10,6 +10,10 @@ ## Version Change Log +### 2.2 - Addition of Supplements + +An optional mechanism for providing credential supplements during issuance. Supplements are also used in credential presentation. + ### 2.1 - Add ability to issue multiple credentials A minor update to add a mechanism for an Issuer to indicate to the Holder that multiple credentials of the same type but with different claim values are available to be issued as part of the execution of the protocol instance. @@ -330,7 +334,7 @@ Message Format: "@id": "", } ], - "~attach" : [] //attachments referred to in message attributes + "~attach" : [] //attachments referred to in supplements } ``` diff --git a/features/0454-present-proof-v2/README.md b/features/0454-present-proof-v2/README.md index 1641c4da7..f77b3c118 100644 --- a/features/0454-present-proof-v2/README.md +++ b/features/0454-present-proof-v2/README.md @@ -10,6 +10,10 @@ ## Version Change Log +### 2.2 - Addition of Supplements + +An optional mechanism for providing credential supplements during presentation. + ### 2.1 - Add ability to request multiple presentations A minor update to add mechanism for a Verifier to request the Prover submit multiple presentations in the "presentation" message(s), each presentation sourced from different credentials that satisfy the presentation request. From 5b4e50676a6e296633925ea790e4c48bbcaf4c27 Mon Sep 17 00:00:00 2001 From: Sam Curren Date: Wed, 31 Aug 2022 19:32:36 -0600 Subject: [PATCH 5/7] Cleanup updates Mention 641, kebab-case the supplement types, verifier responsibilities, and example consistency Signed-off-by: Sam Curren --- features/0453-issue-credential-v2/README.md | 22 +++++++++++---------- features/0454-present-proof-v2/README.md | 11 +++++------ 2 files changed, 17 insertions(+), 16 deletions(-) diff --git a/features/0453-issue-credential-v2/README.md b/features/0453-issue-credential-v2/README.md index de2e24190..b7169ce35 100644 --- a/features/0453-issue-credential-v2/README.md +++ b/features/0453-issue-credential-v2/README.md @@ -307,13 +307,13 @@ Message Format: "more_available": "", "formats" : [ { - "attach_id" : "", + "attach_id" : "", "format" : "", } ], "credentials~attach": [ { - "@id": "", + "@id": "", "mime-type": "application/json", "data": { "base64": "" @@ -322,16 +322,16 @@ Message Format: ], "supplements": [ { - "type": "hashlink_data", - "@id": "", + "type": "hashlink-data", + "@id": "", "attrs": { "key": "field", "value": "" } }, { - "type": "issuer_credential", - "@id": "", + "type": "issuer-credential", + "@id": "", } ], "~attach" : [] //attachments referred to in supplements @@ -373,18 +373,20 @@ Supplements are used to provide information related to credentials. Each supplem - `@id` is the id of the attachment within the `~attach` list. - `attrs` is a list of key/value pairs, used with supplement types that need additional information for processing. If no key/value pairs are needed, `attrs` may be omitted. - Official Supplement Types: -- `issuer_credential` +- `issuer-credential` - Contains a credential related to the Issuer of the credential being presented. -- `hashlink_data` +- `hashlink-data` - Contains binary data who's hashlink is contained within a presented credential. - This binary data MUST only be transmitted if the associated credential attribute containing the hashlink is also transmitted. - An attr key value pair of "field", and value of the attribute name must be sent in the attrs structure. + - During presentation, the verifier MUST check the validity of the hashlink in the presented credential against the associated message attachment prior to use. If the verification fails, the verifier MUST consider the attachment invalid. Holder Behavior -It is expected that a holder retain supplements provided during issuance, and present them as appropriate during presentation. Some supplements (such as `hashlink_data`) require understanding of when to include, as noted in the Supplment details. Supplements of an unknown type SHOULD NOT be automatically be presented +It is expected that a holder retain supplements provided during issuance, and present them as appropriate during presentation. Some supplements (such as `hashlink-data`) require understanding of when to include, as noted in the Supplment details. Supplements of an unknown type SHOULD NOT be automatically be presented + +> Note: Credential Supplements are a generalized form of the linked binary attachments detailed in [RFC 0641](../0641-linking-binary-objects-to-credentials/README.md). Though the methods of linking attributes differ, they may be used in combination by linking via ID _and_ the appropriate supplement metadata. ##### Credentials Attachment Registry diff --git a/features/0454-present-proof-v2/README.md b/features/0454-present-proof-v2/README.md index f77b3c118..5da97a222 100644 --- a/features/0454-present-proof-v2/README.md +++ b/features/0454-present-proof-v2/README.md @@ -241,16 +241,16 @@ This message is a response to a Presentation Request message and contains signed ], "supplements": [ { - "type": "hashlink_data", - "@id": "", + "type": "hashlink-data", + "@id": "", "attrs": { "key": "field", "value": "" } }, { - "type": "issuer_credential", - "@id": "", + "type": "issuer-credential", + "@id": "", } ], "~attach" : [] //attachments referred to in supplements @@ -264,8 +264,7 @@ Description of fields: * `last_presentation` -- an optional field that defaults to `true` to indicate this is the last presentation message to be sent in satisfying the presentation request. If the value is `false`, the Prover MUST send another presentation message with an additional presentation(s). The Prover's last `presentation` message MUST have a `last_presentation` value of `false` (explicitly or by default). If the `present_multiple` field is absent or `false` in the `request_presentation` message from the Verifier, the `last_presentation` field on the first/only `presentation` message MUST be true (explicitly or by default). * `formats` -- contains an entry for each `presentations~attach` array entry, providing the the value of the attachment `@id` and the verifiable presentation format and version of the attachment. Accepted values for the `format` items are provided in the per format [Attachment](#presentation-request-attachment-registry) registry immediately below. * `presentations~attach` -- an array of attachments containing the presentation in the requested format(s). If the `present_multiple` field is `true` in the `request_presentation` message from the Verifier, the Prover MAY include multiple presentations of the same format that satisfy the Presentation request from the Verifier. -* `issuer_credentials` -- an array of references to credentials related to the issuer. -* `supplements` -- an array of attachment descriptors detailing credential supplements. See the Supplements Section in [0453: Issue Credential v2 Protocol](../0453-issue-credential-v2/README.md#supplements) for details. +* `supplements` -- an array of attachment descriptors detailing credential supplements. See the Supplements Section in [0453: Issue Credential v2 Protocol](../0453-issue-credential-v2/README.md#supplements) for details, including the responsibilities of the verifier for various supplement types. * `~attach` -- attachments related to the issued credential. Each attachment should be detailed in a `supplements` entry, referenced by attachment id. If the `last_presentation` field is `false`, the Verifier's state SHOULD remain in the `request-sent` state (barring an error), with the expectation that additional `presentation` messages will be coming from the prover. If the `last_presentation` value is `true` (explicitly or by default) the Verifier MUST transition to their next appropriate state. From 0dcedd82826824fc138420fc141f6d4fa2b542dd Mon Sep 17 00:00:00 2001 From: Sam Curren Date: Wed, 7 Sep 2022 15:33:26 -0600 Subject: [PATCH 6/7] change @id to ref, correct examples for attr list Signed-off-by: Sam Curren --- features/0453-issue-credential-v2/README.md | 12 ++++++------ features/0454-present-proof-v2/README.md | 8 ++++---- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/features/0453-issue-credential-v2/README.md b/features/0453-issue-credential-v2/README.md index b7169ce35..2ae34d7f4 100644 --- a/features/0453-issue-credential-v2/README.md +++ b/features/0453-issue-credential-v2/README.md @@ -323,15 +323,15 @@ Message Format: "supplements": [ { "type": "hashlink-data", - "@id": "", - "attrs": { + "ref": "", + "attrs": [{ "key": "field", "value": "" - } + }] }, { "type": "issuer-credential", - "@id": "", + "ref": "", } ], "~attach" : [] //attachments referred to in supplements @@ -360,7 +360,7 @@ Supplements are used to provide information related to credentials. Each supplem ```json { "type": "", - "@id": "", + "ref": "", "attrs": [ { "key": "", @@ -370,7 +370,7 @@ Supplements are used to provide information related to credentials. Each supplem } ``` - `type` SHOULD be from the following list. Compliance with this RFC indicates support of the official listed supplement types below. -- `@id` is the id of the attachment within the `~attach` list. +- `ref` is the id of the attachment within the `~attach` list. - `attrs` is a list of key/value pairs, used with supplement types that need additional information for processing. If no key/value pairs are needed, `attrs` may be omitted. Official Supplement Types: diff --git a/features/0454-present-proof-v2/README.md b/features/0454-present-proof-v2/README.md index 5da97a222..723ff5c35 100644 --- a/features/0454-present-proof-v2/README.md +++ b/features/0454-present-proof-v2/README.md @@ -242,15 +242,15 @@ This message is a response to a Presentation Request message and contains signed "supplements": [ { "type": "hashlink-data", - "@id": "", - "attrs": { + "ref": "", + "attrs": [{ "key": "field", "value": "" - } + }] }, { "type": "issuer-credential", - "@id": "", + "ref": "", } ], "~attach" : [] //attachments referred to in supplements From 934980c0ee66277a3e70148c95da5a93c911b3c3 Mon Sep 17 00:00:00 2001 From: Char Howland Date: Thu, 29 Sep 2022 11:21:02 -0600 Subject: [PATCH 7/7] feat: add supplements, attachments to propose, offer, request credential messages Signed-off-by: Char Howland --- features/0453-issue-credential-v2/README.md | 129 ++++++++++++++------ 1 file changed, 90 insertions(+), 39 deletions(-) diff --git a/features/0453-issue-credential-v2/README.md b/features/0453-issue-credential-v2/README.md index 2ae34d7f4..68244e65a 100644 --- a/features/0453-issue-credential-v2/README.md +++ b/features/0453-issue-credential-v2/README.md @@ -163,7 +163,22 @@ Message format: "base64": "" } } - ] + ], + "supplements": [ + { + "type": "hashlink-data", + "ref": "", + "attrs": [{ + "key": "field", + "value": "" + }] + }, + { + "type": "issuer-credential", + "ref": "", + } + ], + "~attach" : [] //attachments referred to in supplements } ``` @@ -174,6 +189,8 @@ Description of attributes: * `credential_preview` -- an optional JSON-LD object that represents the credential data that Prover wants to receive. It matches the schema of [Credential Preview](#preview-credential). * `formats` -- contains an entry for each `filters~attach` array entry, providing the the value of the attachment `@id` and the verifiable credential format and version of the attachment. Accepted values for the `format` items are provided in the per format "Attachment" sections immediately below. * `filters~attach` -- an array of attachments that further define the credential being proposed. This might be used to clarify which formats or format versions are wanted. +* `supplements` -- an optional array of attachment descriptors detailing credential supplements. See the [Supplements Section](#supplements) for details. +* `~attach` -- optional attachments related to the proposed credential. Each attachment should be detailed in a `supplements` entry, referenced by attachment identifier. ##### Propose Attachment Registry @@ -212,7 +229,22 @@ Message Format: "base64": "" } } - ] + ], + "supplements": [ + { + "type": "hashlink-data", + "ref": "", + "attrs": [{ + "key": "field", + "value": "" + }] + }, + { + "type": "issuer-credential", + "ref": "", + } + ], + "~attach" : [] //attachments referred to in supplements } ``` @@ -225,6 +257,8 @@ Description of fields: * `credential_preview` -- a JSON-LD object that represents the credential data that Issuer is willing to issue. It matches the schema of [Credential Preview](#preview-credential); * `formats` -- contains an entry for each `offers~attach` array entry, providing the the value of the attachment `@id` and the verifiable credential format and version of the attachment. Accepted values for the `format` items are provided in the per format "Attachment" sections immediately below. * `offers~attach` -- an array of attachments that further define the credential being offered. This might be used to clarify which formats or format versions will be issued. +* `supplements` -- an optional array of attachment descriptors detailing credential supplements. See the [Supplements Section](#supplements) for details. +* `~attach` -- optional attachments related to the offered credential. Each attachment should be detailed in a `supplements` entry, referenced by attachment identifier. The Issuer may add a [`~payment-request` decorator](../0075-payment-decorators/README.md#payment_request) to this message to convey the need for payment before issuance. See the [payment section below](#payments-during-credential-exchange) for more details. @@ -266,7 +300,22 @@ Message Format: "base64": "" } }, - ] + ], + "supplements": [ + { + "type": "hashlink-data", + "ref": "", + "attrs": [{ + "key": "field", + "value": "" + }] + }, + { + "type": "issuer-credential", + "ref": "", + } + ], + "~attach" : [] //attachments referred to in supplements } ``` @@ -276,6 +325,8 @@ Description of Fields: * `comment` -- an optional field that provides human readable information about this Credential Request, so it can be evaluated by human judgment. Follows [DIDComm conventions for l10n](../0043-l10n/README.md). * `formats` -- contains an entry for each `requests~attach` array entry, providing the the value of the attachment `@id` and the verifiable credential format and version of the attachment. Accepted values for the `format` items are provided in the per format "Attachment" sections immediately below. * `requests~attach` -- an array of [attachments](../../concepts/0017-attachments/README.md) defining the requested formats for the credential. +* `supplements` -- an optional array of attachment descriptors detailing credential supplements. See the [Supplements Section](#supplements) for details. +* `~attach` -- optional attachments related to the requested credential. Each attachment should be detailed in a `supplements` entry, referenced by attachment identifier. This message may have a [`~payment-receipt` decorator](../0075-payment-decorators/README.md#payment_receipt) to prove to the Issuer that the potential Holder has satisfied a payment requirement. See the [payment section below](#payments-during-credential-exchange). @@ -349,45 +400,11 @@ Description of fields: * When the Holder receives this message with the field set to a positive integer, the Holder's state moves to the `offer-received` state. * `formats` -- contains an entry for each `credentials~attach` array entry, providing the the value of the attachment `@id` and the verifiable credential format and version of the attachment. Accepted values for the `format` items are provided in the per format "Attachment" sections immediately below. * `credentials~attach` -- an array of attachments containing the issued credential in the format(s) requested by the Holder. -* `supplements` -- an array of attachment descriptors detailing credential supplements. See the Supplements Section for details. -* `~attach` -- attachments related to the issued credential. Each attachment should be detailed in a `supplements` entry, referenced by attachment id. +* `supplements` -- an optional array of attachment descriptors detailing credential supplements. See the [Supplements Section](#supplements) for details. +* `~attach` -- optional attachments related to the issued credential. Each attachment should be detailed in a `supplements` entry, referenced by attachment identifier. If the issuer wants an acknowledgement that the last issued credential was accepted, this message must be decorated with the `~please-ack` decorator using the `OUTCOME` acknowledgement request. Outcome in the context of this protocol means the acceptance of the credential in whole, i.e. the credential is verified and the contents of the credential are acknowledged. Note that this is different from the default behavior as described in [0317: Please ACK Decorator](../0317-please-ack/README.md). It is then best practice for the new Holder to respond with an explicit `ack` message as described in the please ack decorator RFC. -##### Supplements -Supplements are used to provide information related to credentials. Each supplement must be included as a message attachment in the `~attach` array, and have a descriptor contained in the `supplements` array with the following structure: - -```json -{ - "type": "", - "ref": "", - "attrs": [ - { - "key": "", - "value": "" - } - ] -} -``` -- `type` SHOULD be from the following list. Compliance with this RFC indicates support of the official listed supplement types below. -- `ref` is the id of the attachment within the `~attach` list. -- `attrs` is a list of key/value pairs, used with supplement types that need additional information for processing. If no key/value pairs are needed, `attrs` may be omitted. - -Official Supplement Types: -- `issuer-credential` - - Contains a credential related to the Issuer of the credential being presented. -- `hashlink-data` - - Contains binary data who's hashlink is contained within a presented credential. - - This binary data MUST only be transmitted if the associated credential attribute containing the hashlink is also transmitted. - - An attr key value pair of "field", and value of the attribute name must be sent in the attrs structure. - - During presentation, the verifier MUST check the validity of the hashlink in the presented credential against the associated message attachment prior to use. If the verification fails, the verifier MUST consider the attachment invalid. - -Holder Behavior - -It is expected that a holder retain supplements provided during issuance, and present them as appropriate during presentation. Some supplements (such as `hashlink-data`) require understanding of when to include, as noted in the Supplment details. Supplements of an unknown type SHOULD NOT be automatically be presented - -> Note: Credential Supplements are a generalized form of the linked binary attachments detailed in [RFC 0641](../0641-linking-binary-objects-to-credentials/README.md). Though the methods of linking attributes differ, they may be used in combination by linking via ID _and_ the appropriate supplement metadata. - ##### Credentials Attachment Registry Credential Format | Format Value | Link to Attachment Format | Comment | @@ -434,6 +451,40 @@ The mandatory `value` holds the attribute value: * if `mime-type` is missing (null), then `value` is a string. In other words, implementations interpret it the same as any other key+value pair in JSON * if `mime-type` is not null, then `value` is always a base64url-encoded string that represents a binary BLOB, and `mime-type` tells how to interpret the BLOB after base64url-decoding. +#### Supplements +Supplements are used to provide information related to credentials. Each supplement must be included as a message attachment in the `~attach` array, and have a descriptor contained in the `supplements` array with the following structure: + +```json +{ + "type": "", + "ref": "", + "attrs": [ + { + "key": "", + "value": "" + } + ] +} +``` +- `type` SHOULD be from the following list. Compliance with this RFC indicates support of the official listed supplement types below. +- `ref` is the id of the attachment within the `~attach` list. +- `attrs` is a list of key/value pairs, used with supplement types that need additional information for processing. If no key/value pairs are needed, `attrs` may be omitted. + +Official Supplement Types: +- `issuer-credential` + - Contains a credential related to the Issuer of the credential being presented. +- `hashlink-data` + - Contains binary data who's hashlink is contained within a presented credential. + - This binary data MUST only be transmitted if the associated credential attribute containing the hashlink is also transmitted. + - An attr key value pair of "field", and value of the attribute name must be sent in the attrs structure. + - During presentation, the verifier MUST check the validity of the hashlink in the presented credential against the associated message attachment prior to use. If the verification fails, the verifier MUST consider the attachment invalid. + +Holder Behavior + +It is expected that a holder retain supplements provided during issuance, and present them as appropriate during presentation. Some supplements (such as `hashlink-data`) require understanding of when to include, as noted in the Supplement details. Supplements of an unknown type SHOULD NOT be automatically be presented. + +> Note: Credential Supplements are a generalized form of the linked binary attachments detailed in [RFC 0641](../0641-linking-binary-objects-to-credentials/README.md). Though the methods of linking attributes differ, they may be used in combination by linking via ID _and_ the appropriate supplement metadata. + ## Threading Threading can be used to initiate a [sub-protocol](../../concepts/0003-protocols/README.md#composable) during an issue credential protocol instance. For example, during credential issuance, the Issuer may initiate a child message thread to execute the `Present Proof` sub-protocol to have the potential Holder (now acting as a Prover) prove attributes about themselves before issuing the credential. Depending on circumstances, this might be a best practice for preventing credential fraud at issuance time.