Indy HIPE 0156: Rich Schema Credential Definition¶
Authors: Alexander Shcherbakov alexander.shcherbakov@evernym.com, Brent Zundel brent.zundel@evernym.com, Ken Ebert ken@sovrin.org
Start Date: 2020-13-03
Status¶
Status: PROPOSED
Status Date: 2019-13-03
Status Note: part of Rich Schema work
Summary¶
Credential Definition can be used by the Issuer to set public keys for a particular Rich Schema and Mapping. The public keys can be used for signing the credentials by the Issuer according to the order and encoding of attributes defined by the referenced Mapping.
Credential Definition objects are processed in a generic way defined in Rich Schema Objects Common.
Motivation¶
The current format for Indy credential definitions provides a method for issuers to specify a schema and provide public key data for credentials they issue. This ties the schema and public key data values to the issuer’s DID. The verifier uses the credential definition to check the validity of each signed credential attribute presented to the verifier.
The new credential definition object that uses rich schemas is a minor modification of the current Indy credential definition. The new format has the same public key data. In addition to referencing a schema, the new credential definition can also reference a mapping object.
Tutorial¶
Intro to Credential Definition¶
Credential definitions are written to the ledger so they can be used by holders and verifiers in presentation protocol.
A Credential Definition can reference a single Mapping and a single Rich Schema only.
Credential Definition is a JSON object.
Credential Definition should be immutable in most of the cases. Some application may consider it as a mutable object since the Issuer may rotate keys present there. However, rotation of Issuer’s keys should be done carefully as it will invalidate all credentials issued for this key.
Properties¶
Credential definition’s properties follow the generic template defined in Rich Schema Common.
Credential Definition’s content
field is a JSON-serialized string with the following fields:
signatureType¶
Type of the ZKP signature. CL
(Camenisch-Lysyanskaya) is the only supported type now.
mapping¶
An id
of the corresponding Mapping
schema¶
An id
of the corresponding Rich Schema. The mapping
must reference the same Schema.
publicKey¶
Issuer’s public keys. Consists of primary
and revocation
keys.
Example Credential Definition¶
An example of the content
field of a Credential Definition object:
"signatureType": "CL",
"mapping": "did:sov:UVj5w8DRzcmPVDpUMr4AZhJ",
"schema": "did:sov:U5x5w8DRzcmPVDpUMr4AZhJ",
"publicKey": {
"primary": "...",
"revocation": "..."
}
Use in Verifiable Credentials¶
A ZKP credential created according to the CL
signature scheme must reference a Credential Definition used
for signing. A Credential Definition is referenced in the credentialSchema
property. A Credential Definition is referenced by its id
.
Stored on Ledger¶
Credential Definition will be written to the ledger in a generic way defined in Rich Schema Objects Common.
Indy Node Rich Schema API¶
Indy Node processes ledger transaction requests via request handlers.
There is a write request handler for RICH_SCHEMA_CRED_DEF
transaction.
The numerical code for a RICH_SCHEMA_CRED_DEF
transaction is 204
.
A Rich Schema can be obtained from the Ledger by the generic GET_RICH_SCHEMA_OBJECT_BY_ID
and GET_RICH_SCHEMA_OBJECT_BY_METADATA
requests (see Rich Schema Objects Common).
The numerical code for a GET_RICH_SCHEMA_OBJECT_BY_ID
transaction is 300
.
The numerical code for a GET_RICH_SCHEMA_OBJECT_BY_METADATA
transaction is 301
.
RICH_SCHEMA_CRED_DEF Transaction¶
Adds a Credential Definition object as part of Rich Schema feature.
id
(string):A unique ID (for example a DID with an id-string being base58 representation of the SHA2-256 hash of the
content
field)content
(json-serialized string):Credential Definition object as JSON serialized in canonical form.
signatureType
(string): Type of the ZKP signature.CL
(Camenisch-Lysyanskaya) is the only supported type now.mapping
(string): Anid
of the corresponding Mappingschema
(string): Anid
of the corresponding Rich Schema. Themapping
must reference the same Schema.publicKey
(dict): Issuer’s public keys. Consists ot primary and revocation keys.primary
(dict): primary keyrevocation
(dict, optional): revocation key
rsType
(string enum):Rich Schema’s type. Currently expected to be
cdf
.rsName
(string):Rich Schema’s name
rsVersion
(string):Rich Schema’s version
The combination of rsType
, rsName
, and rsVersion
must be unique among all rich schema objects on the ledger.
The generic patterns for RICH_SCHEMA_CRED_DEF
transaction, request, and reply can be found in Rich Schema Objects Common.
Indy VDR API¶
Indy VDR methods for adding and retrieving a Credential Definition from the ledger comply with the generic approach described in Rich Schema Objects Common.
This means the following methods can be used:
indy_vdr_build_rich_schema_object_request
indy_vdr_build_get_schema_object_by_id_request
indy_vdr_build_get_schema_object_by_metadata_request
Reference¶
More information on the Verifiable Credential data model use of schemas
may be found here
Drawbacks¶
Rich schema objects introduce more complexity.
Unresolved Questions and Future Work¶
Of all the Rich Schema objects, the CredDef most closely fits the format of a DID DOC.
However, we are not defining Rich Schema objects as DID DOCs for now. We may re-consider this in future once DID DOC format is finalized.
It may make sense to extend DID specification to include using DID for referencing Rich Schema objects.
The proposed canonicalization form of a content to be used for DID’s id-string generation is in a Draft version, so we may find a better way to do it.