Revocation
Overview
Credential revocation is managed with on-chain revocation registries. To revoke a credential, its id (or hash of its id) must be added to the credential. It is advised to have one revocation registry per credential type. Each registry has a unique id and an associated policy. The policy determines who can update the revocation registry. The registry also has an "add-only" flag specifying whether an id once added to the registry can be removed (leading to undoing the revocation) or not. Similar to the replay protection mechanism for DIDs, for each registry, the last modified block number is kept which is updated each time a credential is revoked or unrevoked. For now, only one policy is supported which is that each registry is owned by a single DID. Also, neither the policy nor the "add-only" flag can be updated post the creation of the registry for now.
Registry creation
To create a registry, first a Policy
object needs to be created for which a DID is needed. It is advised that the DID
is registered on chain first (else someone can look at the registry a register the DID, thus controlling the registry).
import {OneOfPolicy} from '@docknetwork/sdk/utils/revocation';
const policy = new OneOfPolicy();
policy.addOwner(ownerDID);
// Or in a single step
const policy = new OneOfPolicy([ownerDID]);
Now create a random registry id. The registry id supposed to be unique among all registries on chain.
import {createRandomRegistryId} from '@docknetwork/sdk/utils/revocation';
const registryId = createRandomRegistryId();
Now send the transaction to create a registry on-chain using dock.revocation.newRegistry
. This method accepts the registry id,
the policy object and a boolean that specifies whether the registry is add-only or not meaning that whether undoing revocations
is allowed or not. Ifs true
, it makes the registry add-only meaning that undoing revocations is not allowed, if false
,
undoing is allowed.
// Setting the last argument to false to allow unrevoking the credential (undoing revocation)
await dock.revocation.newRegistry(registryId, policy, false);
Revoking a credential
Revoking a credential requires a signature from the owner of the registry.
Now get the registry id, registryId
and the revocation id (the hash of credential id), revokeId
and send the transaction on chain.
Revoking an already revoked credential has no effect.
await dock.revocation.revokeCredentialWithOneOfPolicy(registryId, revokeId, ownerDID, ownerKeypair, 1, {didModule: dock.did});
Revoking multiple ids in a single transaction is possible but with a lower level method dock.revocation.revoke
. See tests for its usage
Undoing a revocation
Similar to revocation, undoing the revocation also requires a signature from the owner of the registry.
Get the registry id, registryId
and the revocation id to undo, revokeId
and send the transaction on chain.
Unrevoking an unrevoked credential has no effect.
await dock.revocation.unrevokeCredentialWithOneOfPolicy(registryId, revokeId, ownerDID, ownerKeypair, 1, {didModule: dock.did});
Undoing revocation for multiple ids in a single transaction is possible but with a lower level method dock.revocation.unrevoke
. See tests for its usage
Checking the revocation status
To check an id is revoked or not, call dock.revocation.getIsRevoked
with the registry id and revocation id. Returns true
if revoked else false
.
const isRevoked = await dock.revocation.getIsRevoked(registryId, revokeId);
Fetching the registry details
To get the details of the registry like policy, add-only status and block number when it was last updated, use dock.revocation.getRegistryDetail
Removing the registry
A registry can be deleted leading to all the corresponding revocation ids being deleted as well. This requires the signature
from owner like other updates. Use the dock.revocation.removeRegistry
method to remove a registry.
await dock.revocation.removeRegistryWithOneOfPolicy(registryId, ownerDID, ownerKeypair, 1, {didModule: dock.did}, false);