Skip to main content
Version: 0.7

Verifiable Presentations

A verifiable presentation is the recommended data format for sharing one or more verifiable credentials. It is constructed and signed by a holder to prove control over their credentials and can be presented to a verifier for validation.

For instance: after an issuer creates and issues a verifiable credential to a holder, such as a university issuing a degree to a graduate, the holder stores it securely until asked to present it. A company could then request proof of that university degree: the holder can create a verifiable presentation containing their credential, which is already signed by their university, and present it to the company to validate.

Note that verifiable presentations that contain personal data should, as with verifiable credentials, be transmitted and stored securely off-chain to satisfy data privacy regulations such as GDPR.

note

See the Verifiable Credentials Data Model Specification for more information on verifiable presentations.

Creation​

The IOTA Identity Framework enables holders to construct verifiable presentations easily. As demonstrated in the example, holders need only pass in their credentials to present and sign the presentation.

The following properties may be specified on a presentation:

  • ID: optional URI identifier for the presentation.
  • Context: list of JSON-LD context URIs. Includes "https://www.w3.org/2018/credentials/v1" by default.
  • Types: list of types describing the presentation. Includes "VerifiablePresentation" by default.
  • Credentials: list of verifiable credentials to present.
  • Holder: optional URI, typically a DID, of the entity that generated the presentation.
  • Refresh Service: optional link to a service where the recipient may refresh the included credentials.
  • Terms of Use: optional list of policies defining obligations, prohibitions, or permissions of the presentation recipient.

Of the above, only the list of credentials is required when creating a presentation using the framework. However, the holder property should be included to satisfy subject-holder relationship checks during validation.

After creation, the holder signs the verifiable presentation using a private key linked to one of the verification methods in their DID Document and transmits it to a verifier for validation.

Proof Options​

A digital signature on a verifiable presentation both provides data integrity and proves the DID of the holder. The proof section embedded in a presentation may also include additional metadata.

The following metadata properties can be configured by the framework and are optional and omitted by default:

  • Created: timestamp of when the presentation was signed.
  • Expires: timestamp after which the presentation is no longer considered valid.
  • Challenge: arbitrary random string. Sent by the verifier and mitigates replay attacks; should be sufficiently random and uniquely generated per presentation request.
  • Domain: arbitrary string. Sent by the verifier and can help mitigate replay attacks when used with a challenge.
  • Proof Purpose: indicates the purpose of the signature.
    • AssertionMethod: to assert a claim. The signing verification method must have an assertionMethod relationship to be valid.
    • Authentication: to authenticate the signer. The signing verification method must have an authentication relationship to be valid.
note

Verifiers should always send a challenge and domain to mitigate replay attacks, see Security Considerations.

A verifier could also choose to ignore some or all of these options. See Proof Verifier Options for more information.

Validation​

The IOTA Identity Framework provides several options for verifiers to validate various sections of a verifiable presentation. See the example for a demonstration of how to validate a presentation.

The framework checks:

  • Semantic structure: ensures the presentation and its credentials adhere to the specification.
  • Presentation proof: verifies the presentation signature against the DID Document of the holder.
  • Credential proofs: verifies the credential signatures against the DID Documents of their respective issuers.
  • Optional validations: additional checks on signatures and credential fields can be configured by the verifier.

Note that a verifier may specify which DID Documents to use for the holder and issuers, otherwise they are resolved from the Tangle automatically.

Currently, the following are not checked automatically:

  • Data schemas: credentials that specify a schema property should be examined to ensure conformance.
  • Fitness for purpose: whether the credentials in a presentation and the data within them are acceptable and valid depends on the context in which they are used. Verifiers should ensure that the credential types, subjects, and schemas sent by a holder match what was requested.
  • Issuer trustworthiness: verifiers must check that they trust the issuer on each individual credential in a presentation. The framework only verifies that the issuer's signature on each credential is current and valid against the given options.

The default validation behaviour may be modified by the following options.

Proof Verifier Options​

While the framework always verifies that the digital signature on a verifiable presentation is valid, a verifier may validate additional fields in the proof on a presentation. Notably, to mitigate potential replay attacks a verifier should always check that the challenge and domain fields match what was sent to the holder when requesting the presentation. See Security Considerations for more information.

The following options are available:

  • Method Scope: check the signing verification method has a particular verification relationship. Overridden by the proof purpose check.
  • Method Type: check the signing verification method has a particular type.
  • Challenge: check the challenge field matches this string.
  • Domain: check the domain field matches this string.
  • Proof Purpose: require a specific purpose on the proof. See Proof Options.
  • Allow Expired: accept proofs where the current datetime is after their expiration. Default is to reject expired proofs.

See Proof Options for more information on setting these properties as a holder when signing a verifiable presentation.

Subject-Holder Relationship​

Specifies the expected relationship between the holder that signed the verifiable presentation and the subject specified in each verifiable credential. This can be restricted by the nonTransferable property, which indicates that a verifiable credential must only be encapsulated into a verifiable presentation whose holder matches the credential subject.

By default, the framework always enforces that the holder matches the subject on all credentials. The following options are available to modify that behaviour:

  • AlwaysSubject (default): the holder DID that signed the presentation must match the credentialSubject id field in each of the attached credentials. This is the safest option which ensures holders may only present credentials that were directly issued to their DID. An error is thrown on a mismatch or if no subject id is present.
  • SubjectOnNonTransferable: the holder DID must match the subject only for credentials where the nonTransferable property is true. This is appropriate for accepting bearer credentials while still adhering to the specification.
  • Any: the holder DID is not required to have any kind of relationship to any credential subject. This option performs no checks and ignores the nonTransferable property.
note

See the Verifiable Credentials Data Model Specification for further discussion on the different subject-holder relationships.

Credential Validation Options​

These options specify conditions that all credentials in a verifiable presentation must satisfy.

  • Expiry Date: check that the expirationDate property, if present, is not before a specific datetime. Defaults to the current datetime if unset.
  • Issuance Date: check that the issuanceDate property, if present, is not after a specific datetime. Defaults to the current datetime if unset.
  • Verifier Options: see Proof Verifier Options for details.

Security Considerations​

Replay Attacks​

A verifiable presentation without challenge and domain properties could potentially be stored by a malicious actor and replayed to a different verifier, impersonating the holder. This is because the holder's signature on a presentation would still be seen as valid indefinitely, until they rotate the verification method used.

To mitigate this, verifiers should always send a unique challenge and domain when requesting a verifiable presentation. These properties are then included in the proof section of the presentation by the holder during signing using Proof Options. The digital signature prevents these properties from being altered as it would invalidate the signature, effectively preventing a malicious actor from injecting different values into old verifiable presentations. A presentation without a challenge and domain in its proof that matches what was sent by the verifier should be considered invalid.

The challenge string should be sufficiently random and unique for each verifiable presentation requested by a verifier to avoid being predicted. The domain, which does not need to be random, is an additional measure. In the unlikely occurrence of two verifiers generating the same random challenge, the domain would sufficiently distinguish those requests.

Holders may additionally specify that their signature on a verifiable presentation expires after a short duration, as per Proof Options. However, verifiers and different implementations could choose to ignore that property, so setting a signature expiration alone should not be relied upon.

Example​

The following code demonstrates how to use the IOTA Identity Framework end-to-end to create and sign a verifiable presentation as a holder, serialize it to JSON for transmission, deserialize it on the receiving side as a verifier, and finally validate it with various options.

examples/0_basic/6_create_vp.rs
loading...