Claim keys semantics and usage


The document, How Sovrin Works, describes “claim keys” at some level. Seems that claim keys are stored on the ledger and also in the storage of the issuing agent. However, I still lack a more in-depth understanding of how claim keys relate to everything else and how they are used more exactly.

Any supporting descriptions on this?


Claim keys are keys that the issuer uses to sign a claim. Suppose you have a driver’s license division of a regional government, and that organization issues two similar but not identical credentials:

  • a traditional driver’s license
  • a government ID that doesn’t confer driver privileges

These credentials (claims) may have different rules about expiration, and conceivably, the second claim type might begin to be issued by a different branch of the government over time.

In such a scenario, the org has one claim key that it uses to sign the first claim type, and another claim key that it uses to sign the second type.


The public half of a claim key is stored on the ledger as part of a CLAIM_DEF transaction that identifies the issuer that plans to generate claims, its key, the schema it intends to use, and the revocation mechanism that applies.


@danielh I’m understanding these keys are generated per claim schema, not per claim instance, is that correct?

In that case, do all claim definitions (schemas) require a key of this nature? Or can there also be “key-less” claim definitions?

Additionally, does this imply that only the issuer of a certain claim definition can issue claims of that type? Would it be possible to “share” the key for such claim type?


The schema defines the data type and information. The claim def used to be called an “issuer key” because what it does is show that an identifier intends to issue claims based on a certain schema. The means that any issuer can decide to issue claims against a schema published to the ledger (the hope is this encourages interoperability – it makes more sense to use an existing, common schema than to invent a new one).

We have done some thinking around what it would mean to have a delegated credential so that multiple parties could issue claims against the same claim definition (for example with national id card that could be issued by any of the states or provinces, it might make sense to issue them against the nation’s authority so that when presented you do not have to disclose which state or province issued it), but these are more advanced use cases that would require some careful consideration and probably some enhancements to the system. (You could just share the claimdef key, but then you also have to make sure that no one uses up the same parts of the shared tails list and manage who is allowed to revoke what parts of those tails lists, etc).


@nage and @danielh : So if one entity publishes a claim def, can other entities use it to issue claims? For example, could a national credit union association publish a “credit union member” claim def that all of the credit unions in that association could use to issue a credit union member claim to all of their members?

It seems almost a requirement to do that so that all of the credit unions can share the same claim semantics, but obviously not share the same issuer keys.

Assuming the answer is yes, and if we call the original claim def author the claim def publisher and the others who want to use it the claim def subscribers, how exactly does a claim def subscriber publish their own issuer keys?


I think the simplest way to address the scenario you give, @Drummond, is to have the NCUA publish a schema, and to have all the member credit unions publish claim defs advertising to the world that they are going to be issuing claims using that schema. There is no authorization-to-publish-against-that-schema in this approach; anybody could say they are issuing claims with such a schema. What makes the issuance authoritative is a claim given by the NCUA to a particular credit union, saying that the claims they issue are legit as far as NCUA is concerned.


Where are the claim details stored? Suppose I go to a bank, and the bank issues a claim that “John has an account with the bank”. Where is the fact “John has an account with XYZ bank” (basically this literal string) stored? Is it in the blockchain (ledger) or some database of the bank? If latter, how does the ledger refer to the factual data?


Hi @jmuir Claims are generally not supposes to be stored on the ledger. Bank would sign that claim with private part of their claim key and send the claim to John over a secure channel. It’s up to John to take care of this claim (using a phone application, for example). Then if another party requires John to prove them he got account in the Bank, John can send the claim he stores on his phone. The receiving party could then take a look at the claim, look up public claim key (part of schema definition issued by bank, stored on ledger) and verify that the claim is valid.
In addition to that, the receiving party might also check revocation registry, to make sure the claim is still valid and was not revoked (I guess in this kind of claim, it wouldn’t really make sense).

I recommend checking out this document: