Skip to main content
Version: 0.6

Revocation

info

The IOTA DIDComm Specification is in the RFC phase and may undergo changes. Suggestions are welcome at GitHub #464.

  • Version: 0.1
  • Status: IN-PROGRESS
  • Last Updated: 2021-10-18

Overview​

Allows to request revocation of an issued verifiable credential, either by the holder or a trusted-party. If the revoker is unable to revoke the credential themselves, they may delegate the revocation to the issuer, in which case they take on the role of trusted-party in their request.

Relationships​

Example Use-Cases​

  • A member of an organisation asks the organisation to revoke their membership.
  • A subsidiary of a company asks central to revoke a credential concerning one of their customers.

Roles​

  • Trusted-Party: has the authority to request the revocation of verifiable credentials. May also be the holder of the credential but not necessarily.
  • Revoker: able to revoke the verifiable credential. May also be the issuer of the credential but not necessarily.

Interaction​

RevocationDiagram

For guidance on diagrams see the corresponding section in the overview.

Messages​

1. revocation-request​

Sent by the trusted-party or holder to request revocation of an issued verifiable credential. This message conveys which credential should be revoked and which method should be used. The revoker MAY require this to be a signed DIDComm message for auditing purposes and reject unsigned requests.

Structure​

{
  "revocationInfo": RevocationInfo, // REQUIRED
}
FieldDescriptionRequired
revocationInfoContains information sufficient to specify which credential should be revoked. See revocationInfo.1✔

1 If an unsupported revocationInfo type is received, the revoker MUST issue a problem-report. The specific problem-report descriptor is invalid-revocation-type but if privacy is a concern, a revoker may send a more generic descriptor such as reject-request to avoid disclosing its capabilities more than the revocation-options protocol would reveal.

Examples​

  1. Request to revoke a credential by identifier using "CredentialRevocation2021":
{
  "revocationInfo": {
    "revocationInfoType": "CredentialRevocation2021",
    "credentialId": "0495e938-3cb7-4228-bb73-c642ec6390c8"
  }
}
  1. Request to revoke all credentials signed by a specific verification method identified by #keys2 using "KeyRevocation2021":
{
  "revocationInfo": {
    "revocationInfoType": "KeyRevocation2021",
    "key": "did:example:76e12ec712ebc6f1c221ebfeb1f#keys-2"
  }
}

2. revocation-response​

  • Type: iota/revocation/0.1/revocation-response
  • Role: revoker

Sent by the revoker as soon as the revocation is performed to indicate the current status.

Structure​

{
  "status": "revoked" | "pending",
}
FieldDescriptionRequired
statusCurrent status of the revocation, either revoked or pending.1✔

1 The status should be revoked if the credential or signing key is confirmed to be revoked, and pending if the revocation has been accepted but not yet performed or committed. For instance, a revocation that updates a DID document may require waiting for the update transaction to be confirmed, or it could be queued for a batch update. If the revoker is unable to perform the revocation or rejects the request for any reason, they MUST instead respond with a problem-report. Care should be taken not to reveal which credentials are under the control of the revoker to prevent privacy-revealing brute-force attacks.

The trusted-party SHOULD verify that the credential is actually revoked after this message is received. The revocation protocol MAY be polled by a trusted-party by re-sending the same request to confirm revocation if the status of pending is received. In the case of a public ledger, however, the trusted-party can query the public state of the verification method themselves to confirm revocation.

Examples​

  1. Response to a revocation-request where the revoker confirms revocation directly:
{
  "status": "revoked"
}
  1. Response to a revocation-request where the revoker confirms the revocation was scheduled, but can only be confirmed at a later point:
{
  "status": "pending"
}

RevocationInfo​

The RevocationInfo object contains the information necessary for a revoker to revoke a verifiable credential. For instance, this may include the id field of the credential, in which case a revoker must maintain a map to the signing key used for each credential to revoke them. It could also be the identifier for the signing key itself on the DID document of the issuer. Implementors are free to construct their own RevocationInfo types as different singing schemes may require different information for revocation.

Implementors MUST adhere to at least one of the types below, either KeyRevocation2021 or CredentialRevocation2021. Implementors MAY define additional types as-needed. A valid RevocationInfo type MUST have a revocationInfoType field.

KeyRevocation2021​

  • Type: KeyRevocation2021

Allows a particular cryptographic public key linked as a verification method to be specified for revocation. This may reference any singular verification method such as Ed25519VerificationKey2018 or RsaVerificationKey2018. Verification methods that hold multiple keys as a collection could, for example, encode the index of the key to be revoked in the query of the DIDUrl.

See the DID Spec Registry for more verification method types.

Note that revoking a verification method revokes all verifiable credentials signed with its key.

Structure​

{
  "revocationInfoType": string, // REQUIRED
  "key": DIDUrl,                // REQUIRED
}
FieldDescriptionRequired
revocationInfoTypeString indicating the RevocationInfo type, MUST be "KeyRevocation2021".✔
keyString conforming to the DIDUrl syntax identifying a verification method to be revoked.1✔

1 the fragment MUST reference a valid verification method. The DID document referenced need not belong to the revoker necessarily, as they could forward or delegate the request to the actual owner or controller. The query MAY include extra information needed to identify the particular signing key.

Example​

  1. Specify a single key or verification method to revoke:
{
  "revocationInfoType": "KeyRevocation2021",
  "key": "did:example:76e12ec712ebc6f1c221ebfeb1f#keys-1"
}

CredentialRevocation2021​

  • Type: CredentialRevocation2021

Allows requesting the revocation of a verifiable credential by its identifier field. This implies that the revoker needs to keep track of the relevant method of revocation and additional information such as the verification method used to sign it to be able to revoke the credential.

{
  "revocationInfoType": string, // REQUIRED
  "credentialId": string,       // REQUIRED
}
FieldDescriptionRequired
revocationInfoTypeString indicating the RevocationInfo type, MUST be "CredentialRevocation2021".✔
credentialIdA URI corresponding to the id property of a verifiable credential.✔

Examples​

  1. Specify the identifier of the credential to revoke:
{
  "revocationInfoType": "CredentialRevocation2021",
  "credentialId": "1dd5bbc6-b0bc-4f82-94a9-c723e11075b5"
}

CredentialStatusRevocation2021​

  • Type: CredentialStatusRevocation2021

Request the revocation of a verifiable credential by sending its corresponding credential status information. The revoker should ensure that this information is correct and that the requester is authorized.

{
  "revocationInfoType": string,          // REQUIRED
  "credentialStatus": CredentialStatus,  // REQUIRED
}
FieldDescriptionRequired
revocationInfoTypeString indicating the RevocationInfo type, MUST be "CredentialStatusRevocation2021".✔
credentialStatusA credential status object.1✔

1 This SHOULD correspond with one of the supported credential status methods in the verifiable credentials extension registry.

Examples​

  1. Specifying a Credential Status List 2017 entry:
{
  "revocationInfoType": "CredentialStatusRevocation2021",
  "credentialStatus": {
    "id": "https://example.edu/status/24",
    "type": "CredentialStatusList2017"
  }
}
  1. Specifying a Revocation List 2020 entry:
{
  "revocationInfoType": "CredentialStatusRevocation2021",
  "credentialStatus": {
    "id": "https://dmv.example.gov/credentials/status/3#94567",
    "type": "RevocationList2020Status",
    "revocationListIndex": "94567",
    "revocationListCredential": "https://example.com/credentials/status/3"
  }
}

Problem Reports​

The following problem-report codes may be raised in the course of this protocol and are expected to be recognised and handled in addition to any general problem-reports. Implementers may also introduce their own application-specific problem-reports.

For guidance on problem-reports and a list of general codes see problem reports.

CodeMessageDescription
e.p.msg.iota.revocation.reject-requestrevocation-requestThe revoker rejects a request for any reason, e.g. the revoker does not have the authority to revoke the particular credential or key, or a relayed revocation request to another revoker failed.
e.p.msg.iota.revocation.reject-request.invalid-revocation-typerevocation-requestThe revoker rejects a request due to an unrecognised, unsupported, or otherwise invalid revocationInfoType.
e.p.msg.iota.revocation.reject-request.invalid-revocation-inforevocation-requestThe revoker rejects a request due to a malformed or otherwise invalid revocationInfo.
e.p.msg.iota.revocation.presentation-failedrevocation-requestThe revoker terminates the protocol due to a failed presentation from the trusted-party, e.g. failed to prove permission to revoke the particular credential.

Considerations​

This section is non-normative.

The revoker needs to check if the credential may actually be revoked and if the trusted party actually has the authority to request the revocation.

Unresolved Questions​

  • Should the trusted party be able to prove that the revoker claimed to have revoked the credential by making him include a signature in the revocation-response, or is it sufficient that they can query the signing key or revocation material in the case of a public ledger?
  • Should revocation-options include the credential status sub-types for CredentialStatusRevocation2021?
  • Separate revocation-notification (https://github.com/hyperledger/aries-rfcs/blob/main/features/0183-revocation-notification/README.mdx) flow for notifying the holder that their credential was revoked, optionally including the reason? Dual entry for a holder to request the revocation reason?
  • Include reason-code/reason-comment in the request? Could be used by the revoker for auditing/validating the request but overall seems not useful - trusted-party would store those reasons internally, holder comments aren't very useful. Can be achieved via embedded presentation and self-signed credentials?

Further Reading​