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

Add optional Credential_Manifest method to CAIP-169 #195

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Add optional Credential_Manifest method to CAIP-169 #195

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c417301
rearrange method and add manifest method
Dec 16, 2022
8f6a2d3
typo in references
Dec 19, 2022
6810fbe
to add preferred_proof explanation
Dec 19, 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
212 changes: 128 additions & 84 deletions CAIPs/caip-169.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -134,90 +134,6 @@ Claim Format registry][] if they are expecting reasonable interoperability in
the near term, and to carefully construct their [presentation_definition
object][] accordingly.

### Store

Stores the given VC in the CP.

#### Method:

`wallet_creds_store`

##### Params:

- `vc` - A Verifiable Credential.

##### Returns:

- `error` - OPTIONAL. If `vc` was malformed or does not comply with the
Verifiable Credentials Profile defined in this specification. Note that some
wallets will call `wallet_creds_verify` locally or remotely and pass back an
error message received thereby, depending on security context.
+ 400 - invalid parameters
+ 500 - processing or internal error
+ 501 - invalid cryptographic primitives (see `wallet_creds_metadata`)

### Verify

Verifies the proof section of a single verifiable credential after dereferencing
its `issuer` property for key material. Note that in an application<>wallet
connection, the application calls the wallet for the wallet to either perform
verification locally or remotely; in either case, the application will await
asynchronously for a success or error code, regardless of how the wallet
verifies the passed credential. Wallets that cannot return appropriate error
codes back MUST NOT authorize apps to call this method as undefined behavior may
occur.

#### Method:

`wallet_creds_verify`

##### Params:

- `vc` - A Verifiable Credential.

##### Returns:

- `error` - OPTIONAL. If `vc` was malformed or does not comply with the
Verifiable Credentials Profile defined in this specification.

### Issue

Called **by the wallet** to the application, providing the parameters needed for
a credential issuance and expecting back a verifiable credential OR an error.
The parameters are formated as a [credential_application object][] as specified
in the [Credential Manifest][] specification.

#### Method:

`wallet_creds_issue`

##### Params:

- `credential_application` - REQUIRED. This can vary from the full contents of
the payload of the to-be-issued credential to a mere consent event per
use-case, but in either case MUST be formated as a valid
[credential_application object][] as specified in the [Credential Manifest][]
specification.
- `preferred_proofs` - OPTIONAL. An **ordered** array (from most to least
preferred) of preferred proof formats and types for the VC to be issued. Each
array item is an object with two properties, `format` and `type`. `format`
indicates the preferred proof type, which is either `jwt` for (External
Proofs) or `ldp` for (Embedded Proofs). The `type` refers to proof type of the
VC (see [Verifiable Credentials Proofs](#Verifiable-Credentials-Proofs) for a
list of valid combinations). If the wallet does not support any of the
preferred proofs, the wallet can select a format and type from the list
defined in [Verifiable Credentials Proofs](#Verifiable-Credentials-Proofs) as
a fallback.

##### Returns:

- `vc` - OPTIONAL. Present if the call was successful. A Verifiable Credential
that was issued to the CP by the application.
- `error` - OPTIONAL. If `payload` was malformed, or does not comply with the
Verifiable Credentials Profile defined in this specification.
+ 400 - invalid `credential_application` or payload construction
+ 500 - processing or internal error

### Present

The application calls the wallet to request verifiable claims from the CP. For
Expand Down Expand Up @@ -308,6 +224,93 @@ Optionally, holder binding can also be requested.
}
}
```


### Store

Stores the given VC in the CP.

#### Method:

`wallet_creds_store`

##### Params:

- `vc` - A Verifiable Credential.

##### Returns:

- `error` - OPTIONAL. If `vc` was malformed or does not comply with the
Verifiable Credentials Profile defined in this specification. Note that some
wallets will call `wallet_creds_verify` locally or remotely and pass back an
error message received thereby, depending on security context.
+ 400 - invalid parameters
+ 500 - processing or internal error
+ 501 - invalid cryptographic primitives (see `wallet_creds_metadata`)

### Verify

Verifies the proof section of a single verifiable credential after dereferencing
its `issuer` property for key material. Note that in an application<>wallet
connection, the application calls the wallet for the wallet to either perform
verification locally or remotely; in either case, the application will await
asynchronously for a success or error code, regardless of how the wallet
verifies the passed credential. Wallets that cannot return appropriate error
codes back MUST NOT authorize apps to call this method as undefined behavior may
occur.

#### Method:

`wallet_creds_verify`

##### Params:

- `vc` - A Verifiable Credential.

##### Returns:

- `error` - OPTIONAL. If `vc` was malformed or does not comply with the
Verifiable Credentials Profile defined in this specification.

### Issue

Called **by the wallet** to the application, providing the parameters needed for
a credential issuance and expecting back a verifiable credential OR an error.
The parameters are formated as a [credential_application object][] as specified
in the [Credential Manifest][] specification.

#### Method:

`wallet_creds_issue`

##### Params:

- `credential_application` - REQUIRED. This can vary from the full contents of
the payload of the to-be-issued credential to a mere consent event per
use-case, but in either case MUST be formated as a valid
[credential_application object][] as specified in the [Credential Manifest][]
specification.
- `preferred_proofs` - OPTIONAL. An **ordered** array (from most to least
Copy link

Choose a reason for hiding this comment

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

[Note: this is hard to review -- I can't figure out what's going on with the diffs. Visually it looks like there's no difference between store and verify, but they are getting pulled in. I tried messing with whitespace settings but no dice.]

I think there may be collision with this and credential application's format property:

The object MUST have a format property if the related [Credential Manifest](https://identity.foundation/credential-manifest/#term:credential-manifest) specifies a format property. Its value MUST be a subset of the format property in the [Credential Manifest](https://identity.foundation/credential-manifest/#term:credential-manifest) that this [Credential Submission](https://identity.foundation/credential-manifest/#term:credential-submission) is related to. This object informs the [Issuer](https://identity.foundation/credential-manifest/#term:issuer) which formats the [Holder](https://identity.foundation/credential-manifest/#term:holder) wants to receive the [Claims](https://identity.foundation/credential-manifest/#term:claims) in.

It looks like this spec is assuming the presence of a credential manifest, I think it shouldn't need preferred_proofs.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Agreed -- I think that was an OIDC interop thing, like the wallet metadata getter.

@awoie would it make sense to warn readers of the spec that preferred_proofs is ONLY required for OIDC backwards compat and that the preferred way of communicating this is in the
formats property of the credential_application?

Copy link
Collaborator Author

@bumblefudge bumblefudge Dec 19, 2022 •
edited
Loading

Choose a reason for hiding this comment

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

(review most recent commit-- i may be confused about what the use-case for this redundant/fallback object is, let me know if i am!)

preferred) of preferred proof formats and types for the VC to be issued. Each
array item is an object with two properties, `format` and `type`. `format`
indicates the preferred proof type, which is either `jwt` for (External
Proofs) or `ldp` for (Embedded Proofs). The `type` refers to proof type of the
VC (see [Verifiable Credentials Proofs](#Verifiable-Credentials-Proofs) for a
list of valid combinations). If the wallet does not support any of the
preferred proofs, the wallet can select a format and type from the list
defined in [Verifiable Credentials Proofs](#Verifiable-Credentials-Proofs) as
a fallback.

##### Returns:

- `vc` - OPTIONAL. Present if the call was successful. A Verifiable Credential
that was issued to the CP by the application.
- `error` - OPTIONAL. If `payload` was malformed, or does not comply with the
Verifiable Credentials Profile defined in this specification.
+ 400 - invalid `credential_application` or payload construction
+ 500 - processing or internal error


### Wallet Metadata

Called by the application to fetch a configuration object describing signing and
Expand Down Expand Up @@ -367,6 +370,47 @@ NOTE: `alg` value `none` SHOULD NOT be accepted.
}
```

### Issuer Metadata

Called by the application to **send** a configuration object describing the
specific credentials an issuer can issue to a wallet, including required user
inputs or triggers if applicable and including default values or values already
known to the application (i.e. "preview" of issuable credential). This method
is an optional way for CAIP-169 supporting applications to enable wallets to
interact with variable or complex issuance processes.

The formatting and values of the metadata object are taken verbatim from the
`credential_manifest` object defined in the DIF [Credential Manifest][]
specification. Note that as per the [Credential Manifest][] specification, some
issuers will require a `credential_application` object to be passed in the
issuance method based on the contents of a `credential_manifest` object sent by
this optional method; thus, a wallet signaling support for this method in a
CAIP-25 response implies the capacity to form a complex `credential_application`
object from a `credential_manifest` object.

#### Method:

`wallet_creds_manifest`

##### Params:

- `credential_manifest` object, defined in the DIF [Credential Manifest][]
specification

##### Returns:

- `error` - OPTIONAL.
+ 400 - invalid request
+ 500 - error parsing manifest object
+ 501 - unrecognized or unsupported manifest version

#### Example

See [Credential Manifest
section](https://verite.id/verite/appendix/messages#credential-manifest) of
Verite.id developer documentation for an example of `credential_manifest` object
design.

## Rationale

<!--The rationale fleshes out the specification by describing what motivated the design and why particular design decisions were made. It should describe alternate designs that were considered and related work, e.g. how the feature is supported in other languages. The rationale may also provide evidence of consensus within the community, and should discuss important objections or concerns raised during discussion.-->
Expand Down