RFC013 Verifiable Credential IRMA Proof Type
Request for Comments: 013
This RFC describes requirements for a Verifiable Credential Proof using IRMA signatures. It also specifies the requirements for Verifiable Credentials that support this proof type. An IRMA proof type acts as bridge between the IRMA ecosystem and Nuts ecosystem. Nuts uses DIDs, DID Documents and Verifiable Credentials as its base. Nuts node operators must trust specific DIDs. IRMA publishes public keys of its issuers on Github. By trusting that specific repository and by running the IRMA server, a Nuts node operator can trust all Verifiable Credentials signed by IRMA. Verifiable Credentials with an IRMA proof are still issued to DIDs but not issued by DIDs. The trust in the issuer is replaced by the trust in the IRMA ecosystem.
This document describes a Nuts standards protocol.
This document is released under the Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) license.
A Nuts network relies on trust. Verifiable Credentials only have value when their issuer is trusted. Without trusting any issuers, a Nuts node will just be a collection of identifiers and public keys. Not all desired issuers support DID and VC technology. Some of these trusted third parties do support the IRMA ecosystem. IRMA does not support DIDs and/or VCs but is capable of generating zero knowledge proof signatures. Using IRMA could therefore support adaption of Nuts until DIDs and VCs are widely accepted as the technology of choice. The IRMA ecosystem consists of a server and a mobile app. The existence of this mobile app makes it possible for a person to be in control of setting a signature. This is also needed since VC wallets are not yet widely available.
- holder: The party that receives a VC from an issuer.
- IRMA credential holder: The IRMA user that issues a Verifiable Credential using the app on his phone.
- issuer: The party that issues a VC.
- implementing party: Organization or person that creates software that adheres to the Nuts specs.
- proof: Proof asserting that a VC is valid using cryptography.
This RFC introduces a new proof type. Any Verifiable Credential type that supports this proof type MUST state this in the corresponding RFC. The proof type identifier is:
credentialSubjectpart of the VerifiableCredential MUST have an
idMUST be a Nuts DID. The
idcontains the holder of the Verifiable Credential. Since the proof is unrelated to Nuts DIDs, the
issuerMUST be the same as
credentialSubject.id. Trust with this type of proof is not placed in a specific DID but in an IRMA issuer from a specific IRMA scheme. Any implementing party MUST state how different IRMA schemes are supported.
Other attributes in the
credentialSubjectMUST relate to attributes from an IRMA scheme. For example the irma-demo scheme contains the credential
sidn-pbdf. This credential contains the attributes
domain. All entries in the
credentialSubjectMUST follow the same hierarchy. It MUST be a JSON object and MUST contain the scheme, the issuer, the credential and attribute name. The
domainattributes would be included as:
"email": "[email protected]",
All attributes in the
credentialSubjectMUST also be part of the IRMA signature.
As stated at the beginning of this chapter, the
proofMUST also contain a
proofValueMUST contain a base64 encoded IRMA signature. The proof does not contain a signature created with an
assertionMethodkey from the DID Document.
An IRMA signature is represented as:
This paper contains an explanation on how the cryptographic scheme works. The interesting bits for getting the data from a signature are the
messageis used to relate the signatures and its attributes to a DID. This is the actual text the user has signed using the IRMA app. The
Afields identifies which credential is used from the IRMA scheme. The
a_disclosedfield contains the actual attribute values. These values are base64 representations of big integers. Big integers are required for the cryptography to work. Underneath they contain strings, booleans, integers or enums. All the other fields are required to validate the authenticity of the signature.
The example signature from above will be base64 encoded when used in a Verifiable Credential proof:
Below is a complete example of how an Irma proof can be embedded in a Verifiable Credential:
"type": ["VerifiableCredential", "NutsKVKCredential"],
proofValuehas been abbreviated for readability.
Verification of an IRMA signature MUST be done by an IRMA server instance. It's also possible for an implementing party to embed the IRMA go libraries. Verification is done as follows:
- Verify IRMA signature using IRMA server (or embedded library), which returns the attributes contained in the IRMA signature.
- Verify each attribute in credentialSubject against its counterpart in the IRMA signature:
- Verify it's present in the IRMA signature
- Verify the attribute's value exactly matches its value in the IRMA signature
- Verify that
messagefrom the IRMA signature exactly matches the value of
The dot-delimited format of the attributes in the verification result can be extended as follows:
The last validation is to check if the
messagefrom the IRMA signature matches the value of
The IRMA ecosystem has two different schemes:
irma-demo. The latter one is not intended for production since all private keys are published with the scheme. Any implementing party MUST ignore all signatures made with that scheme in production.
Although IRMA supports revocation for credentials, the revocation check is only applied during issuance. An IRMA credential revoked today will not invalidate any signatures created in the past. This means that a Verifiable Credential with an IRMA proof MUST adhere to the generic revocation definition stated in §4.5 of RFC011 - Verifiable Credentials. It's the responsibility of the IRMA credential holder to revoke verifiable credentials that could have been compromised. The IRMA credential holder can do this with a renewed, not revoked IRMA credential. The next paragraph contains a default revocation for a Verifiable Credential with an IRMA proof
VCs that are issued with an IRMA proof can be revoked by publishing the following transaction on the network:
Such a revocation transaction has the following requirements:
- the issuer MUST match the DID of the
issuerfield of the VC.
- the subject MUST match the
idfield of the VC.
- a reason MAY be filled with a revocation reason.
- the date MUST provide the date in RFC3339 format. From this moment in time the VC is revoked.
- the proof MUST be a
- the IRMA signature in the
proofValueMUST use the same attributes as the IRMA signature in the original VC.
The transaction MUST be published on the Nuts network. The content-type is