Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Credential Supplements #747

Merged
merged 11 commits into from
Oct 25, 2022
Merged

Credential Supplements #747

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
004eb07
First Draft of additional protocol attributes
TelegramSam Jul 26, 2022
4152336
update to issue to show difference in approach
TelegramSam Jul 29, 2022
c2ba57c
Update Present proof with reference to supplements
TelegramSam Aug 12, 2022
0c6c37e
Add new minor version numbers
TelegramSam Aug 12, 2022
8b24d94
Merge branch 'main' into credential_extras
TelegramSam Aug 29, 2022
5b4e506
Cleanup updates
TelegramSam Sep 1, 2022
0dcedd8
change @id to ref, correct examples for attr list
TelegramSam Sep 7, 2022
350f086
Merge branch 'main' into credential_extras
swcurran Sep 25, 2022
934980c
feat: add supplements, attachments to propose, offer, request credent…
cjhowland Sep 29, 2022
ca6d750
Merge pull request #14 from cjhowland/credential_extras_proposal_offer
TelegramSam Sep 29, 2022
6b475a8
Merge branch 'main' into credential_extras
swcurran Oct 20, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
118 changes: 112 additions & 6 deletions features/0453-issue-credential-v2/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@TelegramSam -- sorry for the delay in going through this, especially because I want to get this PR merged so that I can reference it in my own RFC :-).

I think this RFC needs more content here about what a supplement is for -- clarity. An example of how to use both of the types of supplements would be good -- especially a hashlink example, making clear how the key/value pair(s?) are used. An issuer-credential example would be good as well.


### 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.
Expand Down Expand Up @@ -159,7 +163,22 @@ Message format:
"base64": "<bytes for base64>"
}
}
]
],
"supplements": [
{
"type": "hashlink-data",
"ref": "<attachment identifier>",
"attrs": [{
"key": "field",
"value": "<fieldname>"
}]
},
{
"type": "issuer-credential",
"ref": "<attachment identifier>",
}
],
"~attach" : [] //attachments referred to in supplements
}
```

Expand All @@ -170,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

Expand Down Expand Up @@ -208,7 +229,22 @@ Message Format:
"base64": "<bytes for base64>"
}
}
]
],
"supplements": [
{
"type": "hashlink-data",
"ref": "<attachment identifier>",
"attrs": [{
"key": "field",
"value": "<fieldname>"
}]
},
{
"type": "issuer-credential",
"ref": "<attachment identifier>",
}
],
"~attach" : [] //attachments referred to in supplements
}
```

Expand All @@ -221,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.

Expand Down Expand Up @@ -262,7 +300,22 @@ Message Format:
"base64": "<bytes for base64>"
}
},
]
],
"supplements": [
{
"type": "hashlink-data",
"ref": "<attachment identifier>",
"attrs": [{
"key": "field",
"value": "<fieldname>"
}]
},
{
"type": "issuer-credential",
"ref": "<attachment identifier>",
}
],
"~attach" : [] //attachments referred to in supplements
}
```

Expand All @@ -272,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).

Expand Down Expand Up @@ -303,19 +358,34 @@ Message Format:
"more_available": "<count>",
"formats" : [
{
"attach_id" : "<attach@id value>",
"attach_id" : "<attachment identifier>",
"format" : "<format-and-version>",
}
],
"credentials~attach": [
{
"@id": "<attachment-id>",
"@id": "<attachment identifier>",
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are you taking into account the 3 types of attachments? For example, if the attachment type is "link", the inclusion of a hash is automatic. I'm wondering if we should minor-version update the attachment RFC to include an optional hash when base64url encoding is used.

I would think that we might also want to talk about the option of signing the attachment, as is possible with the attachment RFC. That would ensure that the supplement is signed in a way that both the holder and subsequent verifiers can verify.

"mime-type": "application/json",
"data": {
"base64": "<bytes for base64>"
}
}
]
],
"supplements": [
{
"type": "hashlink-data",
"ref": "<attachment identifier>",
"attrs": [{
"key": "field",
"value": "<fieldname>"
}]
},
{
"type": "issuer-credential",
"ref": "<attachment identifier>",
}
],
"~attach" : [] //attachments referred to in supplements
}
```

Expand All @@ -330,6 +400,8 @@ 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 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.

Expand Down Expand Up @@ -379,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": "<supplement_type>",
"ref": "<attachment_id>",
"attrs": [
{
"key": "<attr_key>",
"value": "<attr_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.
Expand Down
23 changes: 22 additions & 1 deletion features/0454-present-proof-v2/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -234,7 +238,22 @@ This message is a response to a Presentation Request message and contains signed
"links": ["https://ibb.co/TtgKkZY"]
}
}
]
],
"supplements": [
{
"type": "hashlink-data",
"ref": "<attachment identifier>",
"attrs": [{
"key": "field",
"value": "<fieldname>"
}]
},
{
"type": "issuer-credential",
"ref": "<attachment identifier>",
}
],
"~attach" : [] //attachments referred to in supplements
}
```

Expand All @@ -245,6 +264,8 @@ 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.
* `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.

Expand Down