Driver's licenses are used to claim that we are capable of operating a motor vehicle, university degrees can be used to claim our education status, and government-issued passports enable holders to travel between countries. This specification provides a standard way to express these sorts of claims on the Web in a way that is cryptographically secure, privacy respecting, and automatically verifiable.

Introduction

Granting a benefit requires proof and verification. Some benefits demand a formal process that includes three parties. In this process, the holder asks for the benefit and the inspector-verifier grants or denies the benefit based on verification of the holder’s qualification from a trusted issuer.

For example, we use a driver's licenses to prove that we are capable of operating a motor vehicle, a university degree to prove our education status, and government-issued passports to grant travel between countries. This specification provides a standard way to express these claims on the Web in a way that is cryptographically secure, privacy respecting, and automatically verifiable.

For those that are unfamiliar with the concepts related to verifiable claims, the following sections provide an overview of:

what a verifiable claim contains,
an ecosystem where verifiable claims are expected to be useful, and
the use cases and requirements that informed this specification

What is a Verifiable Claim?

Expand on introductory verifiable claims section that doesn't dive too deeply into the details but rather provides an overview of what we're trying to achieve.

Ecosystem Overview

This section outlines a basic set of roles and an ecosystem where verifiable claims are expected to be useful. In this section, we distinguish the essential roles of core actors and the relationships between them; how do they interact? A role is an abstraction that might be implemented in many different ways. The separation of roles suggests likely interfaces and/or protocols for standardization. The following roles are introduced in this specification:

The VCWG is actively discussing the number of roles and terminology used in this specification. The group expects terminology and role identification to be an ongoing discussion and will be influenced by public feedback on the specification. At present, the following incomplete list of roles and terminology have been considered: Subject, Issuer, Authority, Author, Signatory, Holder, Presenter, Asserter, Claimant, Sharer, Subject's Agent, Prover, Mediator, Inspector, Evaluator, Verifier, Consumer, and Relying Party. Some of these are aliases for the same concept, others are possibly new roles in the ecosystem. Reviewers should be aware that the terminology used in this document is not necessarily final and the group is actively soliciting feedback on the roles and terminology used in this specification.

holder: An entity that is in control of one or more verifiable claims. Examples of holders include students, employees, and customers.
issuer: An entity that creates a verifiable claim, associates it with a particular subject, and transmits it to a holder. Examples of issuers include corporations, governments, and individuals.
inspector-verifier: An entity that receives one or more verifiable claims for processing. Examples of inspector-verifiers include employers, security personnel, and websites.
identifier registry: Mediates the creation and verification of subject identifiers. Examples of identifier registries include corporate employee databases, government ID databases, and distributed ledgers.

The roles and information flows that form the basis for this specification.

The ecosystem above is provided as an example to the reader in order to ground the rest of the concepts in this specification. Other ecosystems exist, such as protected environments or proprietary systems, where verifiable claims also provide benefit.

Use Cases and Requirements

The Verifiable Claims Use Cases[[VC-USECASES]] document outlines a number of key topics that readers may find useful, including:

a more thorough explanation of the roles introduced above,
the needs identified in market verticals like education, finance, healthcare, retail, professional licensing, and government,
common tasks and requirement performed by the roles in the ecosystem, and
common sequences and flows identified by the Working Group.

As a result of documenting and analyzing the use cases document, a number of desirable capabilities have been identified as requirements for this specification, specifically:

Holders MUST receive and store verifiable claims from issuers through an agent that the issuer does not need to trust.
Holders SHOULD be positioned between issuers and inspector-verifiers and mediate the transmission of verifiable claims.
Holders MUST provide verifiable claims to inspector-verifiers through an agent that inspector-verifiers needn't trust; they only need to trust issuers.
Verifiable claims MUST be associated with subjects, not particular services; holders SHOULD decide how to aggregate and manage verifiable claims.
Holders SHOULD be able to easily control and own their own identifiers.
Holders MUST control which verifiable claims to use and when.
Holders MUST be able to freely choose and change the agents they employ to help them manage and share their verifiable claims.
Holders that share verifiable claims MUST NOT be required to reveal the identity of the inspector-verifier to issuers.
A verifiable claim MUST be expressed in one or more standard, machine-readable data formats for expressing verifiable claims which can also be extended with minimal coordination.
Verifiable claims MUST be able to be indepenently issued, stored, and verified.
Verifiable Claims MUST be able to be revoked by the issuer.

There are other requirements listed in the Verifiable Claims Use Cases document that may or may not be aligned with the requirements listed above. The VCWG will be ensuring alignment of the list of requirements from both documents over time and will most likely move the list of requirements to a single document.

Basic Concepts

Issuer

Issuer information may be expressed via the following properties:

issuer: The value of this property MUST be a URI. It is RECOMMENDED that dereferencing the URI results in a document containing machine-readable information about the issuer that may be used to verify the information expressed in the credential.
issued: The value of this property MUST be a string value of an [[!ISO8601]] combined date and time string and represents the date and time the credential was issued. Note that this date represents the earliest date when the information associated with the claim property became valid.

{
  "id": "http://dmv.example.gov/credentials/3732",
  "type": ["Credential", "ProofOfAgeCredential"],
  "issuer": "https://dmv.example.gov/issuers/14",
  "issued": "2010-01-01T19:73:24Z",
  "claim": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "ageOver": 21
  },
  "signature": { ... }
}

Signature

A credential MAY be made verifiable by adding the following property:

signature: The method used for a signature will vary byrepresentation language. However, this property is expected to have a value that is a set of name-value pairs including at least a signature, a reference to the signing entity, and a representation of the signing date.

{
  "id": "http://example.gov/credentials/3732",
  "type": ["Credential", "ProofOfAgeCredential"],
  "issuer": "https://dmv.example.gov",
  "issued": "2010-01-01",
  "claim": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "ageOver": 21
  },
  "signature": {
    "type": "LinkedDataSignature2017",
    "created": "2017-06-18T21:19:10Z",
    "creator": "https://example.com/jdoe/keys/1",
    "nonce": "c0ae1c8e-c7e7-469f-b252-86e6a0e7387e",
    "signatureValue": "BavEll0/I1zpYw8XNi1bgVg/sCneO4Jugez8RwDg/+
    MCRVpjOboDoe4SxxKjkCOvKiCHGDvc4krqi6Z1n0UfqzxGfmatCuFibcC1wps
    PRdW+gGsutPTLzvueMWmFhwYmfIFpbBu95t501+rSLHIEuujM/+PXr9Cky6Ed
    +W3JT24="
  }
}

Expiration

Expiration information for the credential MAY be provided by adding the following property:

expires: The value of this property MUST be a string value of an [[!ISO8601]] combined date and time string and represents the date and time the credential will cease to be valid.

{
  "id": "http://dmv.example.gov/credentials/3732",
  "type": ["Credential", "ProofOfAgeCredential"],
  "issuer": "https://dmv.example.gov/issuers/14",
  "issued": "2010-01-01T19:73:24Z",
  "expires": "2020-01-01T19:73:24Z",
  "claim": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "ageOver": 21
  },
  "signature": { ... }
}

Revocation

Revocation information for the claims in the Verifiable Claims Model may be provided by adding the following property:

revocation: The value of this property MUST be a revocation scheme that provides enough information to determine whether or not the credential has been revoked. The revocation scheme will vary depending on a variety of factors, such as whether it is simple to implement or privacy-enhancing.

The group is currently determining whether or not they should publish a very simple scheme for revocation as a part of this specification.

{
  "id": "http://dmv.example.gov/credentials/3732",
  "type": ["Credential", "ProofOfAgeCredential"],
  "issuer": "https://dmv.example.gov/issuers/14",
  "issued": "2010-01-01T19:73:24Z",
  "claim": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "ageOver": 21
  },
  "revocation": {
    "id": "https://dmv.example.gov/revocation/24,
    "type": "RevocationList2017"
  },
  "signature": { ... }
}

Verification

This section describes a number of checks required to verify a claim. Some checks are essential for all verifiable claims, while some are applicable to only some claims.

Syntax

Document is syntactically valid (e.g. JSON, JSON-LD).

Credential

Required properties are present. For example, for a Credential, type and claim are required.
Property values match expectations described in the specification. For example, the document type for a verifiable claim must contain the class "Credential".

Issuer

The issuer id must match expectations. Likely, that means it is the id of a known and trusted verifiable profile.
Recent metadata about the issuer which was published by the issuer MUST be available.

Subject

The claim subject identifier must match expectations. Likely, that means it is the id of a known and trusted verifiable profile for the subject of the claim. If the entity that is subject of a claim has transmitted it to the inspector-verifier, the subject may be able to prove ownership of key identifying properties such as email address(es) and public key(s).

Signature

The document signature is available in the form of a known signature suite.
Required signature properties are present. For example, for a Linked Data Signature, type, created, creator>, and signatureValue are present.
The public key associated with the signature is available and a trustworthy link between this signing key and the issuer's verifiable profile may be established. The key must not be revoked or expired.
The cryptographic signature is valid.

Expiration

The issued date must be in the expected range. For example, an inspector-verifier may wish to ensure that the recorded issued date of valid claims is not in the future.

Revocation

If revocation instructions are present, the claim must not have been revoked.

Fitness for Purpose

The custom properties in the claim should be appropriate for the inspector-verifier's purpose. For example if an inspector-verifier needs to determine that a subject is older than 21 years of age, they may accept claims of specific birthdate or abstract properties such as ageOver.
The issuer is trusted by the inspector-verifier to make the claims at hand. For example, Fast Food Resturant A will not be trusted to make a claim that an individual may enjoy a lifetime 10% discount to its competitor Fast Food Restaurant B.
If the issuer has placed any policy information about the use of the credential, e.g. intended inspector-verifiers, expiration date, etc., that this policy is adhered to.
If the holder has placed any policy information about the use of the credential, e.g. intended inspector-verifiers, restricted usage rights, etc., that this policy is adhered to.

Syntaxes

This section defines how the data model described in Section is realized in each of 3 different languages: JSON, JSON-LD, and WebIDL. Although syntactic mappings are only provided for these three different languages, applications and services may also use any other data representation language (XML, for example) that can support the data model.

JSON

Verifiable Credential

In JSON, an instance of the Verifiable Credential is expressed as a single JSON object whose properties are the verifiable credential's properties, with the following value type assignments:

Any number value MUST be represented as a Number type.
Any boolean value MUST be represented as a Boolean type.
Any sequence value MUST be represented as an Array type.
Any unordered set of values MUST be represented as an Array type.
Any set of properties MUST be represented as an Object type.
Any empty value MUST be represented as a null value.
Any other value MUST be represented as a String type.

The following example demonstrates how to express an verifiable credential containing a simple (unverifiable) claim about a particular subject. In this case, the claim is that the subject with the Verifiable Profile id of did:ebfeb1f712ebc6f1c276e12ec21 is 21 years of age or older. While a human reading the property ageOver may be able to guess its meaning by its name, no machine-readable semantics for the name are provided. There is information about the claim itself, such as an identifier for the entity that issued it and a date for when it was issued.

{
  "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", // subject identifier
  "ageOver": 21 // property-value pair
}

The following example demonstrates how to express the same claim about the same subject, but in a verifiable form. As such, it contains a signature that can be used to verify its entire contents, including the claim.

{
  "id": "http://example.gov/credentials/3732",
  "type": ["Credential", "ProofOfAgeCredential"],
  "issuer": "https://dmv.example.gov",
  "issued": "2010-01-01",
  "claim": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "ageOver": 21
  },
  "revocation": {
    "id": "http://example.gov/revocations/738",
    "type": "SimpleRevocationList2017"
  },
  "signature": {
    "type": "LinkedDataSignature2015",
    "created": "2016-06-18T21:19:10Z",
    "creator": "https://example.com/jdoe/keys/1",
    "domain": "json-ld.org",
    "nonce": "598c63d6",
    "signatureValue": "BavEll0/I1zpYw8XNi1bgVg/sCneO4Jugez8RwDg/+
    MCRVpjOboDoe4SxxKjkCOvKiCHGDvc4krqi6Z1n0UfqzxGfmatCuFibcC1wps
    PRdW+gGsutPTLzvueMWmFhwYmfIFpbBu95t501+rSLHIEuujM/+PXr9Cky6Ed
    +W3JT24="
  }
}

The following example demonstrates how one could express the same claim about the same subject using a JSON Web Token.

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2Rtdi
5leGFtcGxlLmdvdiIsImlhdCI6MTI2MjMwNDAwMCwiZXhwIjoxNDgzMjI4ODAwL
CJhdWQiOiJ3d3cuZXhhbXBsZS5jb20iLCJzdWIiOiJkaWQ6ZWJmZWIxZjcxMmVi
YzZmMWMyNzZlMTJlYzIxIiwiZW50aXR5Q3JlZGVudGlhbCI6eyJAY29udGV4dCI
6Imh0dHBzOi8vdzNpZC5vcmcvc2VjdXJpdHkvdjEiLCJpZCI6Imh0dHA6Ly9leG
FtcGxlLmdvdi9jcmVkZW50aWFscy8zNzMyIiwidHlwZSI6WyJDcmVkZW50aWFsI
iwiUHJvb2ZPZkFnZUNyZWRlbnRpYWwiXSwiaXNzdWVyIjoiaHR0cHM6Ly9kbXYu
ZXhhbXBsZS5nb3YiLCJpc3N1ZWQiOiIyMDEwLTAxLTAxIiwiY2xhaW0iOnsiaWQ
iOiJkaWQ6ZWJmZWIxZjcxMmViYzZmMWMyNzZlMTJlYzIxIiwiYWdlT3ZlciI6Mj
F9fX0.LwqH58NasGPeqtTxT632YznKDuxEeC59gMAe9uueb4pX_lDQd2_UyUcc6
NW1E3qxvYlps4hH_YzzTuXB_R1A9UHXq4zyiz2sMtZWyJkUL1FERclT2CypX5e1
fO4zVES_8uaNoinim6VtS76x_2VmOMQ_GcqXG3iaLGVJHCNlCu4

The JWT above was produced using the inputs below:

A number of the concerns have been raised around security, composability, reusability, and extensibility with respect to the use of JWTs for Verifiable Claims. These concerns will be documented in time in at least the Verfiable Claims Model and Security Considerations section of this document.

// JWT Header
{
  "alg": "RS256",
  "typ": "JWT"
}
// JWT Payload
{
  "iss": "https://dmv.example.gov",
  "iat": 1262304000,
  "exp": 1483228800,
  "aud": "www.example.com",
  "sub": "did:example:ebfeb1f712ebc6f1c276e12ec21",
  "entityCredential": {
    "@context": "https://w3id.org/security/v1",
    "id": "http://example.gov/credentials/3732",
    "type": ["Credential", "ProofOfAgeCredential"],
    "issuer": "https://dmv.example.gov",
    "issued": "2010-01-01",
    "claim": {
      "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
      "ageOver": 21
    }
  }
}

The following example demonstrates how to express a more complex set of verfiable claims about a particular subject.

{
  "id": "http://example.gov/credentials/3732",
  "type": ["Credential", "PassportCredential"],
  "name": "Passport",
  "issuer": "https://example.gov",
  "issued": "2010-01-01",
  "claim": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "name": "Alice Bobman",
    "birthDate": "1985-12-14",
    "gender": "female",
    "nationality": {
      "name": "United States"
    },
    "address": {
      "type": "PostalAddress",
      "addressStreet": "372 Sumter Lane",
      "addressLocality": "Blackrock",
      "addressRegion": "Nevada",
      "postalCode": "23784",
      "addressCountry": "US"
    },
    "passport": {
      "type": "Passport",
      "name": "United States Passport",
      "documentId": "123-45-6789",
      "issuer": "https://example.gov",
      "issued": "2010-01-07T01:02:03Z",
      "expires": "2020-01-07T01:02:03Z"
    }
  },
  "signature": {
    "type": "LinkedDataSignature2015",
    "created": "2016-06-21T03:40:19Z",
    "creator": "https://example.com/jdoe/keys/1",
    "domain": "json-ld.org",
    "nonce": "783b4dfa",
    "signatureValue": "Rxj7Kb/tDbGHFAs6ddHjVLsHDiNyYzxs2MPmNG8G47oS06N8i0Dis5mUePIzII4+p/ewcOTjvH7aJxnKEePCO9IrlqaHnO1TfmTut2rvXxE5JNzur0qoNq2yXl+TqUWmDXoHZF+jQ7gCsmYqTWhhsG5ufo9oyqDMzPoCb9ibsNk="
  }
}

Verifiable Profile

In JSON [[!JSON]], an instance of the Verifiable Profile is expressed as a single JSON object whose properties are the verifiable profile's properties, with the following value type assignments:

Any number value MUST be represented as a Number type.
Any boolean value MUST be represented as a Boolean type.
Any sequence value MUST be represented as an Array type.
Any unordered set of values MUST be represented as an Array type.
Any set of properties MUST be represented as an Object type.
Any empty value MUST be represented as a null value.
Any other value MUST be represented as a String type.

The following example demonstrates how to express a simple verifiable profile.

{
  "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
  "credential": [{
    "id": "http://dmv.example.gov/credentials/3732",
    "type": ["Credential", "ProofOfAgeCredential"],
    "issuer": "https://dmv.example.gov/issuers/14",
    "issued": "2010-01-01T19:73:24Z",
    "claim": {
      "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
      "ageOver": 21
    },
    "signature": {
    "type": "LinkedDataSignature2017",
    "created": "2017-06-17T10:03:48Z",
    "creator": "https://dmv.example.gov/issuers/14/keys/234",
    "nonce": "d61c4599-0cc2-4479-9efc-c63add3a43b2",
    "signatureValue": "pYw8XNi1bgVg/sCneO4BavEll0/I1zJugez8RwDg/+
    ibcC1wpsMCRVpjOboDoe4SxxKjkCOvKiCHGDvc4krqi6Z1n0UfqzxGfmatCuF
    zvueMWmFPRdW+gGsutPTLhwYmfIFpbBu95t501+rSLHIEuujM/+PXr+W3JT24
    9Cky6Ed="
  }],
  "signature": [{
    "type": "LinkedDataSignature2017",
    "created": "2017-06-18T21:19:10Z",
    "creator": "did:example:ebfeb1f712ebc6f1c276e12ec21/keys/2",
    "nonce": "c0ae1c8e-c7e7-469f-b252-86e6a0e7387e",
    "signatureValue": "BavEll0/I1zpYw8XNi1bgVg/sCneO4Jugez8RwDg/+
    MCRVpjOboDoe4SxxKjkCOvKiCHGDvc4krqi6Z1n0UfqzxGfmatCuFibcC1wps
    PRdW+gGsutPTLzvueMWmFhwYmfIFpbBu95t501+rSLHIEuujM/+PXr9Cky6Ed
    +W3JT24="
  }]
}

JSON-LD

JSON-LD [[!JSON-LD]] is a data storage and expression approach called Linked Data. It is a way of expressing information on the Web that is both simple and extensible.

Verifiable Credential

Instances of the Verifiable Credential are expressed in JSON-LD in the same way they are expressed in JSON (Section ), except that there is an additional property @context. Each property of the verifiable credential expression, along with each sub-property within the claim property (such as the generic issuer property or the app-specific ageOver), is given context via the @context value. Other contexts can be used or combined to express any arbitrary information about claims in idiomatic JSON.

The following example demonstrates how to express a simple (unverifiable) claim about a particular subject. In this case, the claim is that the subject with the Entity Profile id of did:ebfeb1f712ebc6f1c276e12ec21 is 21 years of age or older. While a human reading the property ageOver may be able to guess its meaning by its name, the context maps it to a global identifier (URL) where a document could be retrieved that provides its semantics in a machine-readable data format. There is also information about the claim itself, such as an identifier for the entity that issued it and a date for when it was issued.

{
  "@context": "https://w3id.org/identity/v1",
  "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
  "ageOver": 21
}

{
  "@context": [
    "https://w3id.org/identity/v1",
    "https://w3id.org/security/v1"
  ],
  "id": "http://example.gov/credentials/3732",
  "type": ["Credential", "ProofOfAgeCredential"],
  "issuer": "https://dmv.example.gov",
  "issued": "2010-01-01",
  "claim": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "ageOver": 21
  },
  "signature": {
    "type": "LinkedDataSignature2015",
    "created": "2016-06-18T21:10:38Z",
    "creator": "https://example.com/jdoe/keys/1",
    "domain": "json-ld.org",
    "nonce": "6165d7e8",
    "signatureValue": "g4j9UrpHM4/uu32NlTw0HDaSaYF2sykskfuByD7UbuqEcJIKa+IoLJLrLjqDnMz0adwpBCHWaqqpnd47r0NKZbnJarGYrBFcRTwPQSeqGwac8E2SqjylTBbSGwKZkprEXTywyV7gILlC8a+naA7lBRi4y29FtcUJBTFQq4R5XzI="
  }
}

The following example demonstrates how to express a more complex set of verifiable claims about a particular subject.

{
  "@context": [
    "https://w3id.org/identity/v1",
    "https://w3id.org/security/v1"
  ],
  "id": "http://example.gov/credentials/3732",
  "type": ["Credential", "PassportCredential"],
  "name": "Passport",
  "issuer": "https://example.gov",
  "issued": "2010-01-01",
  "claim": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "name": "Alice Bobman",
    "birthDate": "1985-12-14",
    "gender": "female",
    "nationality": {
      "name": "United States"
    },
    "address": {
      "type": "PostalAddress",
      "addressStreet": "372 Sumter Lane",
      "addressLocality": "Blackrock",
      "addressRegion": "Nevada",
      "postalCode": "23784",
      "addressCountry": "US"
    },
    "passport": {
      "type": "Passport",
      "name": "United States Passport",
      "documentId": "123-45-6789",
      "issuer": "https://example.gov",
      "issued": "2010-01-07T01:02:03Z",
      "expires": "2020-01-07T01:02:03Z"
    }
  },
  "signature": {
    "type": "LinkedDataSignature2015",
    "created": "2016-06-21T03:43:29Z",
    "creator": "https://example.com/jdoe/keys/1",
    "domain": "json-ld.org",
    "nonce": "c168dfab",
    "signatureValue": "jz4bEW2FBMDkANyEjiPnrIctucHQCIwxrtzBXt+rVGmYMEflHrOwf7FYLH60E3Oz54VwSSQCi9J4tXQIhv4SofT5opbcIUj7ji6QrC6c+a3YLjg8l/+/uFjhzsLelAO4gh2k0FJxM04ljH0GZGuXTzhRnqTzJTnYSVo72PC92NA="
  }
}

Verifiable Profile

Instances of the Verifiable Profile are expressed in JSON-LD in the same way they are expressed in JSON (Section ), except that there is an additional property @context. Each property of the verifiable profile, such as name or email, is given context via the @context value. Other contexts can be used or combined to express any arbitrary information about an verifiable profile in idiomatic JSON.

The following example demonstrates how to express a simple verifiable profile.

{
  "@context": [
    "https://w3id.org/identity/v1",
    "https://w3id.org/security/v1"
  ],
  "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
  "credential": [{
    "id": "http://dmv.example.gov/credentials/3732",
    "type": ["Credential", "ProofOfAgeCredential"],
    "issuer": "https://dmv.example.gov/issuers/14",
    "issued": "2010-01-01T19:73:24Z",
    "claim": {
      "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
      "ageOver": 21
    },
    "signature": {
    "type": "LinkedDataSignature2017",
    "created": "2017-06-17T10:03:48Z",
    "creator": "https://dmv.example.gov/issuers/14/keys/234",
    "nonce": "d61c4599-0cc2-4479-9efc-c63add3a43b2",
    "signatureValue": "pYw8XNi1bgVg/sCneO4BavEll0/I1zJugez8RwDg/+
    ibcC1wpsMCRVpjOboDoe4SxxKjkCOvKiCHGDvc4krqi6Z1n0UfqzxGfmatCuF
    zvueMWmFPRdW+gGsutPTLhwYmfIFpbBu95t501+rSLHIEuujM/+PXr+W3JT24
    9Cky6Ed="
  }],
  "signature": [{
    "type": "LinkedDataSignature2017",
    "created": "2017-06-18T21:19:10Z",
    "creator": "did:example:ebfeb1f712ebc6f1c276e12ec21/keys/2",
    "nonce": "c0ae1c8e-c7e7-469f-b252-86e6a0e7387e",
    "signatureValue": "BavEll0/I1zpYw8XNi1bgVg/sCneO4Jugez8RwDg/+
    MCRVpjOboDoe4SxxKjkCOvKiCHGDvc4krqi6Z1n0UfqzxGfmatCuFibcC1wps
    PRdW+gGsutPTLzvueMWmFhwYmfIFpbBu95t501+rSLHIEuujM/+PXr9Cky6Ed
    +W3JT24="
  }]
}

The group is currently considering which expressions of the data model should be listed in the spec. WebIDL and XML are two of the expressions that are being considered.

Privacy Considerations

This section details the general privacy considerations and specific privacy implications of deploying the verifiable claims data model into production environments.

Spectrum of Privacy

It is important to recognize that there is a spectrum of privacy that ranges from pseudo-anonymous to strongly identified. Depending on the use case, people have different appetites when it comes to what information they are willing to provide and what information may be derived from what is provided.

- Privacy is a spectrum that ranges from pseudo-anonymous to fully identified.

For example, one would most likely desire to remain anonymous when purchasing alcohol because the regulatory check that’s required is solely whether or not the person is above a particular age. However, when a doctor is writing a prescription for a patient, the pharmacy fulfilling the prescription is required to more strongly identify the medical professional. Therefore it is important to recognize that there is not one approach to privacy that works for all use cases; privacy solutions tend to be use case specific.

Note that even if one may desire to remain anonymous when purchasing alcohol, a photo ID may still be required to provide appropriate assurance to the merchant. The merchant may not need to know your name or other details (other than that you are over a certain age), but in many cases a mere proof of age may still be insufficient to meet regulations.

The Verifiable Claims data model strives to support the full spectrum of privacy and does not take philosophical positions on the right level of anonymity for any particular transaction. The following sections provide guidance for implementers that want to avoid specific scenarios that are hostile to privacy.

Personally Identifiable Information

The data associated with verifiable claims stored in the credential.claim field are largely susceptible to privacy violations when shared with Inspector-verifiers. Personally identifying data such as a government-issued identifier, shipping address, and full name can be easily used to determine, track, and correlate an entity. Even information that does not seem personally identifiable like the combination of a birth date and zip code have very powerful correlation and de-anonymizing capabilities.

Implementers are strongly advised to warn Holders when they share data with these sorts of characteristics. Issuers are strongly advised to provide privacy-protecting credentials when possible. For example, issuing ageOver credentials instead of birthdate credentials when the Inspector-verifier desires to determine if an entity is over the age of 18.

Identifier-based Correlation

Subjects of verifiable claims are identified via the credential.claim.id field. The identifiers that are used to identify the subject of a claim create a danger of correlation when the identifiers are long-lived or used across more than one web domain.

If strong anti-correlation properties are a requirement in a system using verifiable claims, it is strongly advised that identifiers are bound to a single origin or that identifiers are single-use or not used at all and are replaced by short-lived, single use bearer tokens.

Signature-based Correlation

The contents of verifiable claims are secured via the credential.signature field. The credential.signature.signatureValue field creates a danger of correlation when it is used across more than one web domain and the value does not change.

If strong anti-correlation properties are desired, it is strongly advised that signature values and metadata are regenerated each time using technologies like group signatures.

Device Fingerprinting

There are mechanisms external to Verifiable Claims that are used to track and correlate individuals on the Internet and the Web. Some of these mechanisms include Internet Protocol address tracking, Web Browser fingerprinting, Evercookies, Advertising Network trackers, mobile network position information, and in-application Global Positioning System APIs. The use of Verifiable Claims cannot prevent the use of these other tracking technologies. In addition, when these technologies are used in concert with Verifiable Claims, new correlatable information may be discovered. For example, a birthday coupled with a GPS position can be used to strongly correlate an individual across multiple websites.

It is advised that privacy preserving systems prevent the use of these other tracking technologies when verifiable claims are being utilized. In some cases, these tracking technologies may need to be disabled entirely on devices that transmit verifiable claims on behalf of the Holder.

Favor Abstract Claims

In order to enable recipients of verifiable claims to use them in a variety of circumstances without revealing more personally identifiable information than necessary for the transaction, issuers should consider limiting the information published in a claim to a minimal set needed for the expected purposes. One way to avoid placing personally identifiable information in a claim is to use an "abstract" property that meets the needs of inspector-verifiers without providing specific information about the subject.

An example in this document is the use of the ageOver property as opposed to a specific birthdate that would constitute much stronger personally identifiable information. If retailers in a market commonly require purchasers to be older than a specific age, an issuer trusted in that market may choose to offer a credential claiming that subjects have met that requirement as opposed to offering claims of their specific birthdates. This enables individual customers to purchase items without revealing specific personally identifiable information.

The Principle of Minimum Disclosure

Privacy violations occur when information divulged in one context leaks into another. Accepted best practice for preventing such violations is to limit the information requested, and received, to the absolute minimum necessary. This minimal disclosure approach is required by regulation in multiple jurisdictions, including HIPAA in the US and GDPR in the EU.

With verifiable claims, minimal disclosure for issuers means limiting the content of a claim to the minimum required by potential inspector-verifiers for expected use. For inspector-verifiers, it means limiting the scope of claims request or required for accessing services.

For example, a driver's license containing a driver's ID number, height, weight, birthday, and home address is an example of a claim set containing more information than is necessary to establish that the person is above a certain age.

It is considered a best practice for issuers to atomize information or use a signature scheme that allows for selective disclosure. For example, an issuer that issues driver's licenses could issue a claim set containing every attribute that appears on a driver's license in addition to individual claims (a singular claim containing the person's birthday), and individual claims that are more abstract (a singular claim containing an ageOver attribute). In addition, the issuer is encouraged to provide secure HTTP endpoints for retrieving single-use bearer claims to promote the pseudonymous usage of claims when it is safe for the issuer to issue such claims.

Similarly, inspector-verifiers are urged to only request information that is absolutely necessary for a particular transaction to occur. This is important for at least two reasons: 1) it reduces the liability on the inspector-verifier for handling highly sensitive information that it does not need, and 2) it enhances the privacy of the individual by only asking for information that is required for the particular transaction.

Bearer Claims

Bearer claims containing PII or unique identifiers can be correlated. Bearer claims can be tracked based on usage patterns.

Validity Checks

Inspector-verifier (corporation) is required to check revocation via Issuer (government).

Storage Providers and Data Mining

When a holder receives a claim from an issuer, the claim will need to be stored somewhere (e.g. in a credential repository). Holders are warned that the information in a verifiable claim may be sensitive in nature and highly individualized, making it a high value target for data mining. Therefore, there may be services that store verifiable claims for free and mine personal data and sell it to organizations that desire individualized profiles on people and organizations (i.e. if the service is free, you are the product).

It is suggested that holders be aware of the terms of service for their credential repository, specifically the correlation and data mining protections that are in place for those who store their verifiable claims at the service provider.

There are a number of effective mitigations for data mining and profiling:

Use service providers that do not sell your information to third parties.
Use software that encrypts verifiable claims such that a service provider cannot view the contents of the claims.
Use software that stores verifiable claims locally on a device that you control and that does not upload or analyze your information beyond your expectations.

Aggregation of Claims

Aggregation of claims can reveal more information than just the attributes being aggregated.

Usage Patterns

Despite the best efforts to assure privacy, the actual use of verifiable claims can potentially lead to de-anonymization and a loss of privacy. This correlation can occur:

When the same claim is presented to the same inspector-verifier more than once – that inspector-verifier could infer that the holder is the same individual.
When the same claim is presented to different inspector-verifiers, and either those inspector-verifiers collude or a third party has access to transaction records from both inspector-verifiers – the observant party could infer that the individual presenting the claims is the same person at both services, i.e., the accounts are controlled by the same person.
When the same subject identifier of a claim refers to the same subject across presentations or inspector-verifiers. Even when different claims are presented, if the subject identifier is the same, inspector-verifiers (and those with access to inspector-verifier logs) could infer that the holder of the claims is the same person.
When the underlying information in a claim can be used to identify an individual across services – using information from other sources (including information provided directly by the user), inspector-verifiers can use the information inside the claim to correlate the individual with an existing profile. For example, if a holder presents claims that include zip code, age, and sex, the inspector-verifier can potentially correlate the subject of that claim with an established profile [see Sweeney 2000 Simple Demographics Often Identify People Uniquely].
When passing the identifier of a claim to a centralized revocation server – the centralized server can correlate the claim usage across interactions. For example, if a verifiable claim is used for proof of age in this manner, the centralized service could know everywhere that claim was presented: all liquor stores, bars, adult stores, lottery purchases, etc.

It’s possible to mitigate this in part:

Use a globally unique identifier as the subject for any given claim and never re-use that claim.
If the claim supports revocation, use a globally distributed service for revocation.
Design revocation APIs that do not depend on submitting the ID of the claim, e.g., use a revocation list rather than a query.
Avoid associating personally identifiable information with any particular long-lived subject identifier.

It is understood that these mitigation techniques are not always practical or even compatible with necessary usage. Sometimes correlation is the point.

In state prescription monitoring programs, usage monitoring is a requirement: enforcement entities need to be able to confirm that individuals are not cheating the system to get multiple prescriptions for controlled substances. This statutory or regulatory need to correlate usage overrides individual privacy concerns.

Verifiable claims will so be used to intentionally correlate individuals across services, for example, when using a common persona to log in to multiple services, so all activity on each of those services is intentionally linked to the same individual. This is not a privacy issue as long as each of those services uses the correlation in the expected manner.

Privacy risks of claim usage occur when unintended or unexpected correlation arises from the presentation of verifiable claims.

Sharing Information with the Wrong Party

Tokenize identifiers (like bank account numbers) when possible. Granting of rights to a service via cryptographic mechanisms.

Frequency of Claim Issuance

The rate at which an issuer issues claims may be a privacy violation.

Prefer Single Use Claims

Single-use, origin bound claims are generally safer than long-lived claims.

Introduction

What is a Verifiable Claim?

Ecosystem Overview

Use Cases and Requirements

Terminology

Core Data Model

Claims

Credentials

Profiles

Basic Concepts

Issuer

Signature

Expiration

Revocation

Advanced Concepts

Evidence

Verification

Syntax

Credential

Issuer

Subject

Signature

Expiration

Revocation

Fitness for Purpose

Syntaxes

JSON

Verifiable Credential

Verifiable Profile

JSON-LD

Verifiable Credential

Verifiable Profile

Privacy Considerations

Spectrum of Privacy

Personally Identifiable Information

Identifier-based Correlation

Signature-based Correlation

Device Fingerprinting

Favor Abstract Claims

The Principle of Minimum Disclosure

Bearer Claims

Validity Checks

Storage Providers and Data Mining

Aggregation of Claims

Usage Patterns

Sharing Information with the Wrong Party

Frequency of Claim Issuance

Prefer Single Use Claims

Security Considerations

Unsigned Claims

Bundling Dependent Claims

Highly Dynamic Information