Core Concepts

DIDKit makes as accessible, simple, and portable as possible the core engine of any credentialing system built around W3C Verifiable Credentials: the issuance and verification mechanisms.

For information on some of the terms mentioned, check out our Glossary.

High-level explanation of core logic

The generation of Verifiable Credentials (VCs) and Verifiable Presentations (VPs) requires three separate inputs:

1. Key Material: of the issuer in the case of a VC, or of the holder in the case of a VP

2. Data Payload: typically JSON in the case of VCs, and an array of 1 or more VCs in the case of VPs

3. Data Structure: in the form of JSON-LD Schema

From these, a 4th element, the "proof" is generated by signing over 2 and 3 with 1. Once these four elements have been combined, a verifiable credential is a portable, tamper-evident unit of data. Optionally, the data often contains the identifier of a "data subject" of the credential; this identifier is often the vital link between a VP and its contents, rendering the whole package meaningful and verifiable.

Running the process in reverse from the side of a verifier, we start from the whole tamperproofed package. Verifying the proofs on a VC or VP requires fetching key material and verification method (i.e., the type of key material) from the listed issuer or holder (respectively). It is important to note that the data "payload" of a VP is usually one or more VCs and nothing else, so verifying the outer layer (the VP) reveals a new proof and identity to be queried for key and key type (the VC).

Semantics

The third element in the above explanation can be the hardest for developers new to the world of decentralized identity and credentialing to grapple with. This is because the data structure mechanisms assumed and expressed in the examples of the core W3C specifications are so-called "open-world," semantic-web semantics expressed in JSON-LD, rather than the closed-world, static JSON schema that most developers use day in and day out.

While static JSON schema are easier to use and easier to secure in conventional ways, the more dynamic and open-data-friendly mechanics of JSON-LD are given pride of place in the decentralized identity community.

NOTE

DIDKit was built for LD data structures, and currently requires VC semantics to be expressed in JSON-LD, but support for static structures in "vanilla" JSON VC/VP representations (aka "JWT"s) is also available.

For a good introduction to the Semantic Web and JSON-LD as a data format and as a novel approach to web engineering, see these articles by Nader Helmy and Orie Steele.

Verification Methods

DID Documents are signed and verifiable data objects containing key material, metadata, and routing/addressing information to support cross-context identification and verification. As such, they can be queried or qualified by "verificationMethod", i.e. by purpose, in case they contain multiple keys (or multiple representations of the same key) for different purposes. In a typical did:key document like this:

{
  "@context": "https://www.w3.org/ns/did/v1",
  "id": "did:key:z6MkwJBFYK8vTVGeiMsLzcqbSRXW4aTg4PozGbekWtQNUnnW",
  "verificationMethod": [
    {
      "id": "did:key:z6MkwJBFYK8vTVGeiMsLzcqbSRXW4aTg4PozGbekWtQNUnnW#z6MkwJBFYK8vTVGeiMsLzcqbSRXW4aTg4PozGbekWtQNUnnW", 
      "type": "Ed25519VerificationKey2018",
      "controller": "did:key:z6MkwJBFYK8vTVGeiMsLzcqbSRXW4aTg4PozGbekWtQNUnnW",
      "publicKeyJwk": {
        "kty": "OKP",
        "crv": "Ed25519",
        "x": "-kMHp5nohaFOK5E9Jch4ErdgwMFYFUc4Lt_wYlAGy8s"
      }
    }
  ],
  "authentication": [
    "did:key:z6MkwJBFYK8vTVGeiMsLzcqbSRXW4aTg4PozGbekWtQNUnnW#z6MkwJBFYK8vTVGeiMsLzcqbSRXW4aTg4PozGbekWtQNUnnW"
  ],
  "assertionMethod": [
    "did:key:z6MkwJBFYK8vTVGeiMsLzcqbSRXW4aTg4PozGbekWtQNUnnW#z6MkwJBFYK8vTVGeiMsLzcqbSRXW4aTg4PozGbekWtQNUnnW"
  ]
}

The verification methods #authentication and #assertionMethod, two of the most commonly used methods (for authentication and for signing verifiable credentials or other assertion formats) are simply aliases for the main key, which is simply the entire DID itself (without the prefix did:key) after the # symbol.