diff --git a/index.html b/index.html index fa9053faf..6acc84447 100644 --- a/index.html +++ b/index.html @@ -2000,16 +2000,58 @@

Subject is the Holder

holder and all contained verifiable credentials are about a subject that can be identified to be the same as the holder.

+

+If only the credentialSubject is allowed to insert a verifiable credential +into a verifiable presentation the issuer MAY insert the "subjectOnly" property +into the verifiable credential, as defined below. + + +This feature is at risk and is likely to be removed due to lack of consensus. + +

+ +
+ +
'Subject Only' Property
+ +

+The Subject Only property states that a verifiable credential MUST only be +encapsulated into a verifiable presentation whose proof was issued by the +credentialSubject. A verifiable presentation that contains a verifiable credential +containing the subjectOnly property whose proof creator is not +the credentialSubject is invalid. +

+ + 
+{
+  "id": "http://dmv.example.gov/credentials/3732",
+  "type": ["VerifiableCredential", "ProofOfAgeCredential"],
+  "issuer": "https://dmv.example.gov/issuers/14",
+  "issued": "2010-01-01T19:73:24Z",
+  "claim": {
+    "credentialSubject": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+    "ageOver": 21
+    },
+  "SubjectOnly": "True",
+  "proof": { ..
+  "creator": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+  ... }
+}
+
+ +
+
+

Credential Uniquely Identifies a Subject

In this case, the credentialSubject property might contain multiple properties that each provide an aspect of the identity of the -subject, and which together, unambiguously identifies the subject. Some +subject, and which together, unambiguously identify the subject. Some use cases might not require the holder to be identified at all, such as checking to see if a doctor (the subject) is board certified. Other use cases might require the verifier to use out-of-band knowledge to @@ -2044,162 +2086,30 @@

Credential Uniquely Identifies a Subject

address, and birth date of the individual.

+
-

Subject Passes the Verifiable Credential to a Holder

- +

Subject Passes the Verifiable Credential to a Holder

-Verifiable credentials are usually presented to verifiers by the -subject. In some cases, the subject might need to pass the whole -or part of a verifiable credential to another holder. The data -model allows for both cases, as outlined below. -

- -

-If only the subject is allowed to present the -verifiable credential to a verifier, the issuer MUST -insert the SubjectOnly termsOfUse property into the -verifiable credential, as defined below. -This feature is at risk and is likely to be removed due to lack of consensus. - -

- -

-If the issuer permits the subject to pass the whole or part of a -verifiable credential to a holder (for example, a patient might -pass a prescription verifiable credential to a relative for -presentation to a pharmacist for dispensing), the subject MUST issue a -verifiable credential to the holder containing the -credentialSubject properties being passed on, as described below. -This feature is at risk and is likely to be removed and -replaced with another solution, possibly created by another Working Group -focusing on delegation of authority instead of delegation of attributes. - -

- -
- -
SubjectOnly Terms of Use
- -

-The group is currently debating the best security model for delegation. Readers -should treat this entire section as at-risk and currently under debate. -

- -

-The SubjectOnly termsOfUse property states that a -verifiable credential MUST be presented to a verifier by the -subject only. If a verifier is presented with a -verifiable credential containing the SubjectOnly -termsOfUse property by anyone other than the subject, the -verifier MUST refuse to accept it. -

- - 
-{
-  "id": "http://example.edu/credentials/3732",
-  "type": ["VerifiableCredential", "UniversityDegreeCredential"],
-  "issuer": "https://example.edu/issuers/14",
-  "issued": "2010-01-01T19:73:24Z",
-  "credentialSubject": {
-    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
-    "degree": {
-      "type": "BachelorDegree",
-      "name": "Bachelor of Science in Mechanical Engineering"
-    }
-  },
-  "termsOfUse": [{
-    "type": "SubjectOnly",
-    }]
-  },
-  "proof": { ... }
-}
-
- -
- -
-
Passing on a Verifiable Credential
- -

-The group is currently debating the best security model for delegation. Readers -should treat this entire section as at-risk and currently under debate. -

- -

-When a subject passes a verifiable credential to a -holder, the subject SHOULD issue a new -verifiable credential to the holder in which the: - -

+Normally verifiable credentials will be presented to verifiers by the +subject. However in some cases, the subject may need to pass the whole or +part of a verifiable credential to another holder. For example, a patient +(the subject) may be too ill to take a prescription (the verifiable credential) +to the pharmacist (the verifier), and so may ask a friend to take the +prescription for him/her in order to pick up the medication. +

-As well, the holder creates a verifiable presentation containing -these two verifiable credentials. +

+The data model allows for this, by the subject issuing a new verifiable +credential and giving it to the new holder, so that the holder can present +both verifiable credentials to the verifier. However, the content of this +second verifiable credential is likely to be application specific, and therefore +this specification does not standardise the contents of this second verifiable +credential. Nevertheless a non-normative example is given in Appendix A.2

- - 
-{
-  "id": "did:example:76e12ec21ebhyu1f712ebc6f1z2",
-  "type": ["VerifiablePresentation"],
-  "verifiableCredential": [{
-      "id": "http://example.gov/credentials/3732",
-      "type": ["VerifiableCredential", "PrescriptionCredential"],
-      "issuer": "https://example.edu",
-      "issued": "2010-01-01",
-      "credentialSubject": {
-        "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
-        "prescription": {....}
-      },
-      "revocation": {
-        "id": "http://example.gov/revocations/738",
-        "type": "SimpleRevocationList2017"
-      },
-      "proof": {....}
-    },
-    {
-      "id": "https://example.com/VC/123456789",
-      "type": ["VerifiableCredential", "PrescriptionCredential"],
-      "issuer": "did:example:ebfeb1f712ebc6f1c276e12ec21",
-      "issued": "2010-01-03",
-      "credentialSubject": {
-        "id": "did:example:76e12ec21ebhyu1f712ebc6f1z2",
-        "prescription": {....}
-      },
-      "proof": {
-        "type": "RsaSignature2018",
-        "created": "2017-06-17T10:03:48Z",
-        "creator": "did:example:ebfeb1f712ebc6f1c276e12ec21/keys/234",
-        "nonce": "d61c4599-0cc2-4479-9efc-c63add3a43b2",
-        "signatureValue": "pYw8XNi1..Cky6Ed = "
-      }
-    }
-  ],
-  "proof": [{
-    "type": "RsaSignature2018",
-    "created": "2017-06-18T21:19:10Z",
-    "creator": "did:example:76e12ec21ebhyu1f712ebc6f1z2/keys/2",
-    "nonce": "c0ae1c8e-c7e7-469f-b252-86e6a0e7387e",
-    "signatureValue": "BavEll0/I1..W3JT24 = "
-  }]
-}
-
- - +
-

Holder Acts on Behalf of the Subject

@@ -3944,7 +3854,75 @@

Device Theft and Impersonation

+
+

Appendix A.2 Subject passes a verifiable credential to someone else

+ + This section is non-normative. + +

+When the subject passes a verifiable credential to another +holder, the subject may issue a new verifiable credential to the holder in which: +the issuer is the subject, +the subject is the holder to whom the verifiable credential is being passed, +and the claim contains the properties that are being passed on. +The holder may now create a verifiable presentation that contains these two +verifiable credentials, so that the verifier can verify that the subject gave +the original verifiable credential to the holder. + + 

+{
+  "id": "did:example:76e12ec21ebhyu1f712ebc6f1z2",
+  "type": ["VerifiablePresentation"],
+  "credential": [{
+      "id": "http://example.gov/credentials/3732",
+      "type": ["VerifiableCredential", "PrescriptionCredential"],
+      "issuer": "https://dmv.example.gov",
+      "issued": "2010-01-01",
+      "claim": {
+        "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+        "prescription": {....}
+      },
+      "revocation": {
+        "id": "http://example.gov/revocations/738",
+        "type": "SimpleRevocationList2017"
+      },
+      "proof": {....}
+    },
+    {
+      "id": "https://example.com/VC/123456789",
+      "type": ["VerifiableCredential", "PrescriptionCredential"],
+      "issuer": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+      "issued": "2010-01-03",
+      "claim": {
+        "id": "did:example:76e12ec21ebhyu1f712ebc6f1z2",
+        "prescription": {....}
+      },
+      "proof": {
+        "type": "RsaSignature2018",
+        "created": "2017-06-17T10:03:48Z",
+        "creator": "did:example:ebfeb1f712ebc6f1c276e12ec21/keys/234",
+        "nonce": "d61c4599-0cc2-4479-9efc-c63add3a43b2",
+        "signatureValue": "pYw8XNi1..Cky6Ed = "
+      }
+    }
+  ],
+  "proof": [{
+    "type": "RsaSignature2018",
+    "created": "2017-06-18T21:19:10Z",
+    "creator": "did:example:76e12ec21ebhyu1f712ebc6f1z2/keys/2",
+    "nonce": "c0ae1c8e-c7e7-469f-b252-86e6a0e7387e",
+    "signatureValue": "BavEll0/I1..W3JT24 = "
+  }]
+}
+
+

+In the above example, a patient (the original subject) has passed a prescription +(the original verifiable credential) to a friend, and has issued a new verifiable +credential to the friend, in which the friend is the subject, the original subject is +the issuer, and the credential is a copy of the original prescription. +

diff --git a/index.text b/index.text new file mode 100644 index 000000000..333a3489c --- /dev/null +++ b/index.text @@ -0,0 +1,3403 @@ + + + + Verifiable Credentials Data Model 1.0 + + + + + + + + +
+

+Credentials are a part of our daily lives; +driver's licenses are used to assert that we are capable of operating a motor +vehicle, university degrees can be used to assert our level of education, and +government-issued passports enable holders to travel between countries. +This specification provides a mechanism to express these sorts of +credentials on the Web in a way that is cryptographically secure, +privacy respecting, and machine verifiable. +

+
+ +
+

+Comments regarding this document are welcome. Please file issues +directly on GitHub, +or send them to +public-vc-comments@w3.org +(subscribe, +archives). +

+ +

+There remain a list of terminology-related editorial issues that need to be +processed in this document. +

+ +

+There remain a list of editorial issues that need to be processed in this +document. +

+ +
+ +
+

Introduction

+ + This section is non-normative. + +

+Credentials are a part of our daily lives; driver's licenses are used to +assert that we are capable of operating a motor vehicle, university degrees +can be used to assert our level of education, and government-issued passports +enable us to travel between countries. These credentials provide benefits +to us when used in the physical world, but their use on the Web continues to +be elusive. +

+ +

+It is currently difficult to express banking account information, +education qualifications, healthcare data, and other sorts of machine-readable +personal information that has been verified by a 3rd party on the Web and this +makes it difficult to receive the same benefits from the Web that physical +credentials provide us in the physical world. +

+ +

+This specification provides a standard way to express credentials on the +Web in a way that is cryptographically secure, privacy-respecting, +and machine-verifiable. +

+

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

+
    +
  1. +the components that constitute a verifiable credential, +
    2. +
  2. +the components that constitutes a verifiable presentation, +
    3. +
  3. +an ecosystem where verifiable credentials and verifiable presentations are +expected to be useful, and +
    4. +
  4. +the use cases and requirements that informed this specification. +
    5. +
+

+ +
+

What is a Verifiable Credential?

+ +

+In the physical world, a credential may consist of: +

+ +
    +
  • +information related to the subject of the credential (e.g., photo, name, and +identification number), +
    • +
  • +information related to the issuing authority (e.g., city government, +national agency, or certification body), +
    • +
  • +evidence related to how the credential was derived, and +
    • +
  • +information related to expiration dates. +
    • +
+ +

+A verifiable credential can represent all of the same information that a +physical credential represents. The addition of technologies such as +digital signatures makes verifiable credentials more tamper-evident and +therefore more trustworthy than their physical counterparts. Holders can +generate presentations and share them with verifiers to prove they possess +verifiable credentials with certain characteristics. Both credentials and +presentations can be rapidly transmitted, making them more convenient than +their physical counterparts when establishing trust at a distance. +

+

+ The persistence of digital information, and the ease with which + disparate sources of digital data may be collected and correlated, + comprise a privacy concern that the use of verifiable and easily + machine-readable credentials threatens to exacerbate. A Privacy Considerations + section addresses these issues. Items of particular concern in + this specification may also be noted in the text. Examples of + how to use this data model using privacy-enhancing technologies + such as zero-knowledge proofs are also provided. +

+
+
+

Ecosystem Overview

+ + This section is non-normative. + +

+This section outlines a basic set of roles and an ecosystem where verifiable +credentials 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: +

+ +
+
holder
+
+A role an entity may perform by possessing one or more +verifiable credentials and generating presentations from them. +Examples of holders include students, employees, and customers. +
+
issuer
+
+A role an entity may perform by creating a verifiable credential, +associating it with a particular subject, and transmitting it to +a holder. Examples of issuers include corporations, non-profits, +trade associations, governments, and individuals. +
+
verifier
+
+A role an entity may perform by requesting and receiving a +verifiable presentation that proves the holder possesses the required verifiable credentials with certain characteristics. +Examples of verifiers include employers, security personnel, and websites. +
+
identifier registry
+
+A role a system may perform by mediating the creation and verification of issuer identifiers, +keys and other relevant data required to use verifiable credentials. Some configurations may require correlatable +identifiers for subjects. Examples of such data repositories include trusted databases, +decentralized 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 credentials also +provide benefit. +

+ +

+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. +

+ +

+The group is currently discussing how the ecosystem overview could be improved +with the intent to defer future improvements as the current section seems to +be working well so far. +

+ +

+The group is currently discussing how to bootstrap simple Web of Trust +credentials in this ecosystem. +

+ +
+ +
+

Use Cases and Requirements

+ + This section is non-normative. + +

+The Verifiable Credentials 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 +performed by the roles in the ecosystem, as well as their associated +requirements, 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 ecosystem characteristics have been identified for this +specification, namely: +

+ +

+There are +other requirements +listed in the Verifiable Credentials 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. +

+
+ +
+ +
+

Terminology

+ + This section is non-normative. + +
+
+
+ +
+

Core Data Model

+ + This section is non-normative. + +

+The following sections outline core data model concepts, such as +claims, credentials, and presentations, that form the +foundation of this specification. +

+ +
+

Claims

+ + This section is non-normative. + +

+A claim is statement about a subject. +A subject is an entity about which claims may be made. +Claims are expressed using +subject-property-value +relationships. +

+ +
+ +
+The basic structure of a claim. +
+
+ +

+The data model for claims described above is powerful and can be used to +express a large variety of statements. For example, whether or not someone is over +the age of 21 may be expressed as follows: +

+ +
+ +
+An example of a basic claim that expresses that Pat is over the age of 21. +
+
+ +

+If a presentation supports derived predicates, a claim about birthdate in a +credential can become the basis of proof that at an arbitrary point in time, the +age of a subject did or will fall within an arbitrary interval. Selective disclosure +schemes that use zero-knowledge proofs may use claims expressed in this model to prove +additional statements about those claims. For example, a claim specifying the date of +birth of a subject can be used as a predicate to prove that the subject's age is +within a given range, such as to prove drinking age or qualification for age-related +discounts, without actually revealing the birthdate. The holder has the flexibility +to use the claim in any way that is applicable to the desired presentation. +

+
+ +
+ An example of a basic claim that expresses that Pat's date of birth is 2010-01-01T19:73:24Z, + the encoding of date would be determined by the schema. +
+
+

+These claims may be merged together to express a graph of +information about a particular subject. The example below extends the +data model above by adding claims that state that Pat knows Sam and that +Sam is employed as a professor. +

+ +
+ +
+Multiple claims may be combined to express a more complex graph. +
+
+ +

+At this point, the concept of a claim has been introduced. To enable +one to trust the claims, more information must be added to the graph +of information. +

+ +
+
+

Credentials

+ + This section is non-normative. + +

+A credential is set of one or more claims made by the +same entity. It may include an identifier as well as metadata that +describes properties of the credential itself such as: the issuer, +the expiry time, a representative image, a public key to use for the purposes +of verification, the revocation mechanism to use etc. This metadata may be signed by the issuer. +A verifiable credential is a set of claims and meta data that are tamper-evident +and that cryptographically prove who issued it. +

+

+It is important to note that credential identifiers can be used for correlation. +A holder that wants to minimize correlation MUST use a selective disclosure scheme that +does not reveal the credential identifier. +

+ +
+ +
+The basic components of a verifiable credential. +
+
+ +

+Examples of verifiable credentials include digital employee identification +cards, digital birth certificates, digital educational certificates, etc. +

+ +

+It is possible to have a credential, such as a marriage certificate, +that contains multiple claims about different subjects that are +not required to be related. +

+ +

+The group is currently discussing whether or not they support all the types +of claims that can be made. +

+ +
+
+

Presentations

+ + This section is non-normative. + +

+As this specification takes a privacy-first approach, it is important that +the entities that use this technology are able to express only the portions of +their persona that are appropriate for the situation. The expression of a +subset of one's persona is called a verifiable presentation. +

+ +

+A verifiable presentation expresses data from one or more verifiable +credentials, and is packaged in such a way that the authorship of the data +is verifiable. If credentials are directly presented, they become a +presentation. Data formats derived from credentials that are cryptographically +verifiable but that do not, of themselves, contain credentials, may also be +presentations. +

+

+ The data in a presentation are often about the same subject that +have been issued by multiple issuers. The aggregation of this +information typically expresses an aspect of a person, organization, or entity. +

+ +
+ +
+The basic components of a verifiable presentation. +
+
+ +

+Examples of different presentations include a person's professional persona, online +gaming persona, or home-life persona. +

+ +

+It is possible to have a presentation, such as a business persona, +that draws upon multiple credentials about different subjects +that are often, but not required to be, related. +

+ +
+
+ +
+

Trust Model

+ + This section is non-normative. + +

+The Verifiable Credentials trust model is as follows: +

+ +
    +
  1. +The verifier trusts the issuer to issue the credential +that it receives. In order to establish this trust, a credential MUST +either 1) include a proof that establishes +that the issuer generated the credential (it is a verifiable credential), +or 2) have been transmitted in a way that clearly establishes that the +issuer generated the credential and that the credential has not been tampered +with in transit or storage. This trust could be weakened depending upon the +risk assessment of the verifier. +
    2. +
  2. +All entities trust the identifier registry to be incorruptible and +to be a correct record of which identifiers belong to which entities. +
    3. +
  3. +The subject trusts the issuer to issue true (i.e., not false) +credentials about the subject, and to revoke them quickly +when appropriate. +
    4. +
  4. +The holder trusts the repository to store the +credentials securely, to not release them to anyone other than the +holder, and to not corrupt or lose them whilst they are in its care. +
    5. +
+ +

+This trust model differentiates itself from other trust models by ensuring that: +

+ + + +

+By decoupling the trust between the identity provider and the +relying party, a more flexible and dynamic trust model is created +such that market competition and customer choice is increased. +

+
+ +
+

Basic Concepts

+ +

+This section outlines some of the basic concepts introduced in this +specification and lays the groundwork for the more advanced concepts +toward the end of the document. +

+ +
+

Contexts

+ +

+When two software systems need to exchange data, they must use terminology +that both systems understand. A useful analogy is to think about how two +people communicate; both people must use the same language and the words +that each of them use must mean the same thing to the other party. This +specification uses the @context property to express the context +of the conversation. +

+ +
+
@context
+
+The value of this property MUST be one or more URIs where first URI is the +value https://w3.org/2018/credentials/v1. +If more than one URI is provided, the URIs MUST be interpreted as an +ordered set. It is RECOMMENDED that dereferencing the URI results in a +document containing machine-readable information about the context. +
+
+ + 
+{
+  "@context": [
+    "https://w3.org/2018/credentials/v1",
+    "https://example.com/examples/v1"
+  ],
+  "id": "http://dmv.example.gov/credentials/3732",
+  "type": ["VerifiableCredential", "ProofOfAgeCredential"],
+  "claim": {
+    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+    "ageOver": 21
+  },
+  "proof": { ... }
+}
+
+ +

+The example above uses the base context +(https://w3.org/2018/credentials/v1) to establish that the +conversation is about a Verififiable Credential. It then adds an additional +context (https://example.com/examples/v1) to establish that the +conversation will also be about examples. +

+ +

+This document uses the Example Context +(https://example.com/examples/v1) for the purposes of +demonstrating examples. The Example Context MUST NOT be used for any other +purpose such as in pilot or production systems. +

+ +

+The data available at https://w3.org/2018/credentials/v1 +is a static document that is never updated and MAY be downloaded and +cached. The associated human-readable vocabulary document for the +Verifiable Credentials Data Model can be found at the following URL: +https://w3.org/2018/credentials. +This concept is expanded upon in Section . +

+
+ +
+

Identifiers

+ +

+When expressing statements about a particular thing, such as a person, product, +or organization, it is often useful to use an identifier so that others +may express statements about the same thing. Identifiers that others are +expected to use when expressing statements about a particular thing MUST be +expressed using the id property. +

+ +

+Developers should keep in mind that identifiers may be harmful in scenarios +where pseudonymity is required and are encourged to read +Section carefully when considering +such scenarios. +

+ +
+
id
+
+The value of this property MUST be a single URI. It is RECOMMENDED that +dereferencing the URI results in a document containing machine-readable +information about the identifier. +
+
+ + 
+{
+  "@context": "https://w3.org/2018/credentials/v1",
+  "id": "http://dmv.example.gov/credentials/3732",
+  "type": ["VerifiableCredential", "ProofOfAgeCredential"],
+  "claim": {
+    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+    "ageOver": 21
+  },
+  "proof": { ... }
+}
+
+ +

+The example above uses two types of identifiers. The first identifier is an +identifier for the credential and uses an HTTP-based URL. The second +identifier is an identifier for the subject of the credential, that is, the +thing that the claims are about, which uses a Decentralized Identifier, also +known as a DID. +

+ +

+Note that, as of this publication, DIDs are a new type +of identifier that are not necessary for Verifiable Credentials to be useful. +For the avoidance of doubt, Verifiable Credentials do not depend on +Decentralized Identifiers and Decentralized Identifiers do not depend on +Verifiable Credentials. +However, it is expected that many Verifiable Credentials will use +Decentralized Identifiers and software libraries that implement this +specification will most likely need to be able to resolve DIDs. DID-based +URLs are used for expressing identifiers associated with cryptographic keys +and other machine-readable information that is useful when used in +the Verifiable Credentials Ecosystem. +

+
+ +
+

Types

+ +

+Software systems that process the objects specified in this document +use type information to make determinations about whether or not the provided +credential or presentation is appropriate. +Type information MUST be expressed via the type property: +

+ +
+
type
+
+The value of this property MUST be or map to one or more URIs. +If more than one URI is provided, the URIs MUST be interpreted as an +unordered set. Note that syntactic conveniences, such as JSON-LD terms, +SHOULD be used to ease developer usage. It is RECOMMENDED that dereferencing +the URI results in a document containing machine-readable information about +the type. +
+
+ + 
+{
+  "@context": [
+    "https://w3.org/2018/credentials/v1",
+    "https://example.com/examples/v1"
+  ],
+  "id": "http://dmv.example.gov/credentials/3732",
+  "type": ["VerifiableCredential", "ProofOfAgeCredential"],
+  "claim": {
+    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+    "ageOver": 21
+  },
+  "proof": { ... }
+}
+
+ +

+With respect to this specification, the following types MUST be +specified on the following objects: +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ConceptType
+A credential object + +"type": ["VerifiableCredential"] and +a more specific credential type (e.g., ProofOfAgeCredential) +
+A presentation object + +"type": ["VerifiablePresentation"] and optionally a +more specific presentation type +(e.g., CredentialManagerPresentation). +
+A credentialStatus object + +A valid credential status type (e.g., CredentialStatusList2017) +
+A termsOfUse object + +A valid terms of use type (e.g., OdrlPolicy2017) +
+An evidence object + +A valid evidence type (e.g., DocumentVerification2018) +
+ +

+All credentials, presentations, and encapsulated objects MUST +specify or be associated with additional, more narrow types +(e.g., ProofOfAgeCredential) such that software systems can use +the additional information to more easily process the data. +

+ +

+When processing encapsulated objects in this specification, (e.g., objects +associated with the claim property or deeply nested therein), +a software system SHOULD use type information specified in encapsulating +objects higher in the hierarchy. For the avoidance of doubt, an +encapsulating object such as credential, SHOULD convey the types of +associated objects so that the verifier can quickly determine the +contents of the associated object based on the type of the encapsulating object. +To provide a concrete example, a credential with the additional +type of ProofOfAgeCredential would signal to the +verifier that the object associated with the claim property will +contain the identifier for the subject in the id property +and the age assertion in the ageOver property. This enables +implementers to rely on values associated with the type property +for verification purposes. The expectation of types and their associated +properties SHOULD be documented in at least a human-readable specification +and, preferably, in an additional machine-readable representation. +

+ +

+The type system for the Verifiable Credentials Data Model is the same as the +one for [[JSON-LD]] and is detailed in +Section 5.4: Specifying the Type +and +Section 8: JSON-LD Grammar. +When using a JSON-LD Context (see Section ), +this specification aliases the @type +keyword to type in order to make the JSON-LD documents more +idiomatic. While application developers and document authors do not need to +understand the specifics of JSON-LD's type system, implementers of this +specification that want to support extensibility in an interoperable fashion do. +

+ +
+ +
+

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. +
+
issuanceDate
+
+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. +
+
+ 
+{
+  "@context": [
+    "https://w3.org/2018/credentials/v1",
+    "https://example.com/examples/v1"
+  ],
+  "id": "http://dmv.example.gov/credentials/3732",
+  "type": ["VerifiableCredential", "ProofOfAgeCredential"],
+  "issuer": "https://dmv.example.gov/issuers/14",
+  "issuanceDate": "2010-01-01T19:73:24Z",
+  "claim": {
+    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+    "ageOver": 21
+  },
+  "proof": { ... }
+}
+
+
+ +
+

Proofs (e.g., Signatures)

+ +

+In order for a credential or presentation to be made +verifiable, the following property MUST be present: +

+
+
proof
+
+The method used for a mathematical proof will vary by representation language +and the technology used. For example, if digital signatures are used for +the proof mechanism, 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.
+
+ 
+{
+  "@context": [
+    "https://w3.org/2018/credentials/v1",
+    "https://example.com/examples/v1"
+  ],
+  "id": "http://example.gov/credentials/3732",
+  "type": ["VerifiableCredential", "ProofOfAgeCredential"],
+  "issuer": "https://dmv.example.gov",
+  "issuanceDate": "2010-01-01",
+  "claim": {
+    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+    "ageOver": 21
+  },
+  "proof": {
+    "type": "RsaSignature2018",
+    "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="
+  }
+}
+
+ +

+The group is currently discussing various alignments with the JOSE stack, +specifically JWS and JWK. +

+ +
+ +
+

Expiration

+ +

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

+ +
+
expirationDate
+
+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. +
+
+ + 
+{
+  "@context": [
+    "https://w3.org/2018/credentials/v1",
+    "https://example.com/examples/v1"
+  ],
+  "id": "http://dmv.example.gov/credentials/3732",
+  "type": ["VerifiableCredential", "ProofOfAgeCredential"],
+  "issuer": "https://dmv.example.gov/issuers/14",
+  "issuanceDate": "2010-01-01T19:73:24Z",
+  "expirationDate": "2020-01-01T19:73:24Z",
+  "claim": {
+    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+    "ageOver": 21
+  },
+  "proof": { ... }
+}
+
+ +

+The group is currently discussing expiration and caching. +

+ +

+The group is currently discussing how to automatically renew credentials. +

+ +

+The group is currently discussing how verifiable credentials may be +automatically updated. +

+ +
+ +
+

Status

+ +

Information about the current status of a verifiable credential, + such as suspension or revocation, + may be provided by adding the credentialStatus property. +This property + comprises the type of credential status information that is being provided + (sometimes referred to as the credential status scheme), plus the id of the status +type instance. The precise contents of the credential status information is + determined by the specific credentialStatus type definition, + and will vary + depending upon a variety of factors, such as whether it is + simple to implement or privacy-enhancing. +

+ +
+
credentialStatus
+
The value of this property MUST be a credential status scheme that + provides enough information to determine the current status of the + credential (e.g., suspended, revoked, etc.). +
+
+ + 
+{
+  "@context": [
+    "https://w3.org/2018/credentials/v1",
+    "https://example.com/examples/v1"
+  ],
+  "id": "http://dmv.example.gov/credentials/3732",
+  "type": ["VerifiableCredential", "ProofOfAgeCredential"],
+  "issuer": "https://dmv.example.gov/issuers/14",
+  "issuanceDate": "2010-01-01T19:73:24Z",
+  "claim": {
+    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+    "ageOver": 21
+  },
+  "credentialStatus": {
+    "id": "https://dmv.example.gov/status/24,
+    "type": "CredentialStatusList2017"
+  },
+  "proof": { ... }
+}
+
+ +

+Defining the data model, formats, and protocols for status schemes are out +of scope for this specification. A status scheme registry [[VC-STATUS-REGISTRY]] +exists for implementers that would like to implement credential status checking. +

+
+ +
+

Presentations

+ +

+Credentials MAY be used to construct a verifiable presentation. A +verifiable presentation may be of a verifiable credential itself, or +of data derived from verifiable credentials in a format that is +cryptographically verifiable. +

+ +

+In the example below, we show a verifiable presentation that embeds +verifiable credentials: +

+ + 
+{
+  "@context": [
+    "https://w3.org/2018/credentials/v1",
+    "https://example.com/examples/v1"
+  ],
+  "id": "urn:uuid:3978344f-8596-4c3a-a978-8fcaba3903c5",
+  "type": ["VerifiablePresentation"],
+  "verifiableCredential": [{ ... }],
+  "proof": [{ ... }]
+}
+
+

+The group is currently discussing whether the "id" field is appropriately +defined for Presentations. +

+ +

+The group is currently discussing how the data model expresses when the +subject is not the holder of the credential/presentation. +

+ +

+The group is currently discussing holders, subjects, and identifier +control. +

+ +

+The contents of the verifiableCredential property shown above are +verifiable credentials as described by this specification. The contents +of the proof property are proofs as described by the +Linked Data Proofs [[LD-PROOFS]] specification. The id property +is optional and MAY be used to provide a unique identifier for the presentation. +The value associated with the id property MUST be a URI. +

+ +

+Some zero-knowledge cryptography schemes may enable holders to indirectly +prove that they hold a credential without revealing the credential itself. In +these schemes, the original attribute, such as a date of birth, may be +translated into another value, such as "over the age of 15", that is +cryptographically asserted such that a verifier can trust the value if +they trust the issuer. +

+ +

+We are currently working on an example of a ZKP-style verifiable presentation +that contains derived data instead of directly embedded verifiable credentials. +

+
+
+ +
+

Advanced Concepts

+ +
+

Extensibility

+ +

+One of the goals of the Verifiable Credentials Data Model is to enable +permissionless innovation. This requires that the data model is extensible +in a number of different ways: +

+ +
    +
  • +The requirement to model complex multi-entity relationships is provided +through the use of a graph-based data model. +
    • +
  • +The requirement to be able to extend the machine-readable vocabularies +used to describe information in the data model without the use of a +centralized system for doing so is accomplished via the use +of [[LINKED-DATA]]. +
    • +
  • +The requirement to support multiple types of cryptographic proof formats is +accomplished via the use of Linked Data Proofs [[LD-PROOFS]], +Linked Data Signatures [[LD-SIGNATURES]], and a variety of signature suites. +
    • +
  • +The requirement to provide all of the extensibility mechanisms outlined above +in a data format that is popular among software developers and web page authors +is enabled via the use of [[!JSON-LD]]. +
    • +
+ +

+This approach to data modelling is often called an "open world assumption," +meaning that any entity can say anything about any other entity. This approach +often feels in conflict with building simple and predictable software systems. +Balancing extensibility with program correctness is always more challenging +with an open world assumption than it is with closed software systems. +

+ +

+The rest of this section describes how both extensibility and program +correctness are achieved through a series of examples. +

+ +

+The group is currently discussing how a travel use case could be covered as +an extension. +

+ +

+Let us assume that we start with the following verifiable credential: +

+ + 
+{
+  "@context": [
+    "https://w3.org/2018/credentials/v1",
+    "https://example.com/examples/v1"
+  ],
+  "id": "http://example.com/credentials/4643",
+  "type": ["VerifiableCredential"],
+  "issuer": "https://example.com/issuers/14",
+  "issuanceDate": "2018-02-24T05:28:04Z",
+  "claim": {
+    "id": "did:example:abcdef1234567",
+    "name": "Jane Doe"
+  },
+  "proof": { ... }
+}
+
+ +

+The credential above simply states that the entity associated with +did:example:abcdef1234567 has a name with a +value of Jane Doe. Let's assume that a developer wanted to +extend the verifiable credential to store two additional pieces of +information: an internal corporate reference number, and Jane's favorite +food. +

+ +

+The first thing that a developer would do is create a JSON-LD Context +containing two new terms: +

+ + 
+{
+  "@context": {
+    "referenceNumber": "https://example.com/vocab#referenceNumber",
+    "favoriteFood": "https://example.com/vocab#favoriteFood"
+  }
+}
+
+ +

+Now that the JSON-LD Context has been created, the developer must publish it +somewhere that is accessible to verifiers that will be processing the +verifiable credential. For this example, let us assume that the +JSON-LD Context above is published at the following URL: +https://example.com/contexts/mycontext.jsonld. At this point, +extending the first example in this section is a simple matter of including the +context above and adding the new properties to the verifiable credential. +

+ + 
+{
+  "@context": [
+    "https://w3.org/2018/credentials/v1",
+    "https://example.com/contexts/mycontext.jsonld"
+  ],
+  "id": "http://example.com/credentials/4643",
+  "type": ["VerifiableCredential"],
+  "issuer": "https://example.com/issuers/14",
+  "issuanceDate": "2018-02-24T05:28:04Z",
+  "referenceNumber": 83294847,
+  "claim": {
+    "id": "did:example:abcdef1234567",
+    "name": "Jane Doe",
+    "favoriteFood": "Papaya"
+  },
+  "proof": { ... }
+}
+
+ +

+The examples so far have shown that it is easy to extend the Verifiable +Credentials Data Model in a permissionless and decentralized way. The +mechanism shown also ensures that verifiable credentials that were created +in this way provide a mechanism to prevent namespace conflicts and +semantic ambiguity. +

+ +

+An extensibility model that is this dynamic does increase implementation burden. +Software written for such a system will have to determine if accepting +verifiable credentials with extensions is acceptable based on the +risk profile of the application. Some applications may choose to only accept +certain extensions while highly secure environments may require that no +extensions are allowed. These decisions are up to the developers of these +applications and are specifically not the domain of this specification. +Applications that do not understand the semantic meaning of all properties +while processing a verifiable credential or a verifiable presentation MUST +produce an error. +

+ +

+Developers are urged to ensure that extension JSON-LD Contexts are highly +available. Implementations that cannot fetch a context will produce an error. +Strategies for ensuring that extension JSON-LD Contexts are always available +include using content-addressed URLs for contexts, bundling context documents +with implementations, or enabling aggressive caching of contexts. +

+ +
+

Semantic Interoperability

+ +

+This specification endeavors to enable both the JSON and JSON-LD syntaxes +to be semantically compatible with one another without the JSON implementations +needing to process the documents as JSON-LD. In order to achieve this, the +specification creates the following additional restrictions on both syntaxes: +

+ +
    +
  • +JSON-based processors MUST process the @context property, ensuring +the expected values exist in the expected order for the type of +credential that they are processing. The expected order MUST be defined +by at least a human-readable extension specification and, preferably, a +machine-readable specification. +
    • +
  • +In addition to the rule above, JSON-LD-based processors MUST produce an error +when a JSON-LD Context redefines any term in the +active context. +
    • +
+ +

+To avoid the possibility of accidentally overriding terms, developers are urged +to scope their extensions. For example, the following extension scopes the +new favoriteFood term so that it may only be used within the +claim property: +

+ + 
+{
+  "@context": {
+    "referenceNumber": "https://example.com/vocab#referenceNumber",
+    "claim": {
+      "@id": "https://w3.org/2018/credentials#claim",
+      "@context": {
+        "favoriteFood": "https://example.com/vocab#favoriteFood"
+      }
+    }
+  }
+}
+
+ +
+ +
+ +
+

Refreshing

+ +

+It is often useful for systems to enable the manual or automatic refresh of a +verifiable credential that has expired. +This specification enables an issuer to include a link to a refresh +service. +

+

+The issuer may include the refresh service as an element inside the verifiable +credential if it is intended for either the verifier or the holder or both, or +inside the verifiable presentation if it is intended for the holder only. +

+

+Including the refresh reference in the presentation enables the holder to refresh the +credential details before creating a presentation to share with a verifier, while including +the refresh reference in the verifiable credential enables the both the holder and +the verifier to perform future updates of the credential. +

+

+The expression of a refresh service may be performed via the following +property: +

+ +
+
refreshService
+
The value of this property MUST be one or more refresh services + that provides enough information to the holder's software + such that it may refresh the credential. + Each refreshService comprises at least its + type (e.g. ManualRefreshService2018), + and the serviceEndpoint URL. The precise contents of each + refresh service is determined by the specific type definition. +
+
+ + 
+{
+  "@context": [
+    "https://w3.org/2018/credentials/v1",
+    "https://example.org/motorlicense/v1"
+  ],
+  "id": "http://dmv.example.gov/credentials/3732",
+  "type": ["VerifiableCredential", "ProofOfAgeCredential"],
+  "issuer": "https://dmv.example.gov/issuers/14",
+  "issuanceDate": "2010-01-01T19:73:24Z",
+  "claim": {
+    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+    "ageOver": 21
+  },
+  "refreshService": {
+    "type": "ManualRefreshService2018",
+    "serviceEndpoint": "https://dmv.example.gov/refresh/283947"
+  },
+  "proof": { ... }
+}
+
+ +

+In the example above, the issuer is specifying a +manual refreshService that can be used by directing the +holder to the following URL: +https://dmv.example.gov/refresh/283947. +

+ +
+ +
+

Terms of Use

+ +

Terms of use can be utilized by an issuer, a subject, or a + holder to constrain the use of information expressed by the Verifiable + Credentials Data Model. The issuer places their terms of use inside + the credential before it is converted into a verifiable credential. + The holder places holder terms of use inside a presentation. +

+ +

it is for further study how a subject who is not a + holder places terms of + use on his or her verifiable credentials. One way could be for the subject to + request the issuer to place them inside the issued verifiable credentials. Another + way could be by the subject delegating a verifiable credential to a holder and + placing terms of use restrictions on the delegated verifiable credential. +

+

The expression of + terms of use may be performed via the following property: +

+ +
+
termsOfUse
+
The value of this property MUST be one or more terms of use + that tell the verifier what actions it MUST perform if it is to + accept the verifiable credential or verifiable presentation. + If the verifier is not willing to accept these terms of use then it MUST reject + the verifiable credential or verifiable presentation. + Each termsOfUse comprises its type, + for example, IssuerPolicy, and + optionally its instance id. The precise contents of each term of use is + determined by the specific TermsOfUse type definition. +
+
+ +

+The group is currently exploring a variety of ways of expressing the terms of +use associated with a Verifiable Credential, namely, the +Open Digital Rights Language. +A related initiative is the one at Customer Commons. +

+ + 
+{
+  "@context": [
+    "https://w3.org/2018/credentials/v1",
+    "https://example.org/motorlicense/v1"
+  ],
+  "id": "http://dmv.example.gov/credentials/3732",
+  "type": ["VerifiableCredential", "ProofOfAgeCredential"],
+  "issuer": "https://dmv.example.gov/issuers/14",
+  "issuanceDate": "2010-01-01T19:73:24Z",
+  "claim": {
+    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+    "ageOver": 21
+  },
+  "termsOfUse": [{
+    "type": "IssuerPolicy",
+    "id": "http://example.com/policies/credential/4",
+    "profile": "http://example.com/profiles/credential",
+    "prohibition": [{
+      "assigner": "https://dmv.example.gov/issuers/14",
+      "assignee": "AllVerifiers",
+      "target": "http://dmv.example.gov/credentials/3732",
+      "action": ["Archival"]
+    }]
+  },
+  "proof": { ... }
+}
+
+ +

+In the example above, the issuer is prohibiting a verifier from +storing the data in an archive. +

+ + 
+{
+  "@context": [
+    "https://w3.org/2018/credentials/v1",
+    "https://example.org/motorlicense/v1"
+  ],
+  "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+  "type": "VerifiablePresentation",
+  "credential": [{
+    "id": "http://dmv.example.gov/credentials/3732",
+    "type": ["VerifiableCredential", "ProofOfAgeCredential"],
+    "issuer": "https://dmv.example.gov/issuers/14",
+    "issuanceDate": "2010-01-01T19:73:24Z",
+    "claim": {
+      "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+      "ageOver": 21
+    },
+    "proof": { ... }
+  }],
+  "termsOfUse": [{
+    "type": "HolderPolicy",
+    "id": "http://example.com/policies/credential/6",
+    "profile": "http://example.com/profiles/credential",
+    "prohibition": [{
+      "assigner": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+      "assignee": "https://wineonline.example.org/",
+      "target": "http://dmv.example.gov/credentials/3732",
+      "action": ["3rdPartyCorrelation"]
+    }]
+  },
+  "proof": [ ... ]
+}
+
+ +

+In the example above, the holder, who is also the subject, +is prohibiting the verifier (https://wineonline.example.org) +from using the information provided to correlate the +holder/subject by using a 3rd party service. +

+ +

+The group is currently discussing how one knows who specified the Terms of Use. +

+ +
+ +
+

Evidence

+ +

+The evidence property is used by an issuer to represent the +set of evidence that was used to determine whether or not to issue +a credential. For example, an issuer might check physical documentation +provided by the subject or might perform a set of background checks +before issuing the credential. In certain scenarios, this information is useful +to the verifier when determining the risk associated with accepting +the credential. +

+ +

+Evidence information for the credential in the Verifiable Credentials Data +Model is provided by adding the following property: +

+ +
+
evidence
+
The value of this property MUST be one or more evidence schemes + that provides enough information to a verifier + to determine whether or not the evidence gathered meets their + requirements. The contents of each evidence scheme is determined + by the particular scheme itself. +
+
+ +

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

+ +

+The group is currently discussing how attachments and references to +non-credential data are supported by the specification. +

+ +

+The group is currently discussing how attachments and references to +credentials are supported by the specification. +

+ + 
+{
+  "@context": [
+    "https://w3.org/2018/credentials/v1",
+    "https://example.org/motorlicense/v1"
+  ],
+  "id": "http://dmv.example.gov/credentials/3732",
+  "type": ["VerifiableCredential", "ProofOfAgeCredential"],
+  "issuer": "https://dmv.example.gov/issuers/14",
+  "issuanceDate": "2010-01-01T19:73:24Z",
+  "claim": {
+    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+    "ageOver": 21
+  },
+  "evidence": [{
+    "id": "https://dmv.example.gov/evidence/f2aeec97-fc0d-42bf-8ca7-0548192d4231",
+    "type": ["DocumentVerification"],
+    "verifier": "https://dmv.example.gov/issuers/14",
+    "evidenceDocument": "DriversLicense",
+    "subjectPresence": "Physical",
+    "documentPresence": "Physical"
+  }],
+  "proof": { ... }
+}
+
+ +

+For the avoidance of doubt, the evidence property provides +information that is different from and complementary to the +proof property. The evidence +property is used to express supporting information, such as documentary +evidence, related to the integrity of the credential. In contrast, the +proof property is used to express machine-verifiable mathematical +proofs related to the authenticity of the issuer and integrity of the +credential. +

+ +

+The group is currently discussing how to visualize verifiable credentials and +any media associated with them. +

+ +
+ +
+ +

Subject-Holder Relationships

+ +

+This section describes the possible relationships between the subject +and the holder and how the data model expresses the various relationships. The +following diagram depicts the various types of relationships that are covered in +the rest of this section: +

+ +
+ +
+Subject-Holder Relationships in Verifiable Credentials. +
+
+ +

+The following sections describe how each of these instances are handled in +the data model. +

+ +
+

Subject is the Holder

+ +

+The most common case is when the subject is the holder. For +example, the verifier can easily deduce that the subject is the +holder if the verifiable presentation is digitally signed by the +holder and all contained verifiable credentials are about a subject +that can be identified to be the same as the holder. +

+ +
+ +
+

Credential Uniquely Identifies Subject

+ +

. +In this case, the claim may contain multiple properties that each +provide an aspect of the identity of the subject, and which together +unambiguously identify the subject. Some use cases may not require the +holder to be identified at all, such as checking to see if a doctor (the +subject) is board certified. Other use cases may require the verifier to +use out-of-band knowledge to determine the relationship between the +subject and the holder. +

+ + 
+{
+  "@context": ["https://w3.org/2018/credentials/v1", "https://schema.org/"]
+  "id": "http://dmv.example.gov/credentials/332",
+  "type": ["VerifiableCredential", "IdentityCredential"],
+  "issuer": "https://dmv.example.gov/issuers/4",
+  "issued": "2017-02-24",
+  "claim": {
+    "name": "J. Doe",
+    "address": {
+      "streetAddress": "10 Rue de Chose",
+      "postalCode": "98052",
+      "addressLocality": "Paris",
+      "addressCountry": "FR"
+    },
+    "birthDate": "1989-03-15"
+    ...
+  },
+  "proof": { ... }
+}
+
+ +

+The example above uniquely identifies the subject through the use of the +name, address, and birth date of the individual. +

+ +
+ +
+

Subject Passes the Verifiable Credential to a Holder

+ +

+The group is currently debating the best security model for delegation. Readers +should treat this entire section as at-risk and currently under debate. +

+ +

+Normally verifiable credentials will be presented to verifiers by the +subject. However in some cases, the subject may need to pass the whole or +part of a verifiable credential to another holder. The data model allows for +both cases as follows. +

+ +

+If only the subject is allowed to present the verifiable credential to a +verifier, the issuer MUST insert the "subject only" Terms of Use into the +verifiable credential, as defined below. +This feature is at risk and is likely to be removed due to lack of consensus. + +

+ +

+If the subject is not forbidden by the issuer to pass the whole or part of a +verifiable credential to a holder, for example, a patient may pass a +prescription verifiable credential to a relative for the relative to present +it to a pharmacist for dispensing, then the subject MUST issue a verifiable +credential to the holder containing the claim properties that are being +passed on, as described below. +This feature is at risk and is likely to be removed and replaced with +another solution, possibly created by another Working Group, that focuses on +delegation of authority instead of delegation of attributes. + +

+ +
+ +

'Subject Only' Terms of Use

+ +

+The group is currently debating the best security model for delegation. Readers +should treat this entire section as at-risk and currently under debate. +

+ +

+The Subject Only Terms of Use states that a verifiable credential MUST only be +presented to a verifier by the subject. If a verifier is presented with a +verifiable credential containing the Subject Only Terms of Use, by anyone other + than the subject, it MUST refuse to accept it. +

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

Passing on a Verifiable Credential

+ +

+The group is currently debating the best security model for delegation. Readers +should treat this entire section as at-risk and currently under debate. +

+ +

+ +When the subject passes a verifiable credential to a +holder, the subject SHOULD issue a new verifiable credential to the holder in which: +the issuer is the subject, +the subject is the holder to whom the verifiable credential is being passed, +and the claim contains the properties that are being passed on. In addition, the +holder creates a verifiable presentation that contains these two +verifiable credentials. +

+ + 
+{
+  "id": "did:example:76e12ec21ebhyu1f712ebc6f1z2",
+  "type": ["VerifiablePresentation"],
+  "credential": [{
+      "id": "http://example.gov/credentials/3732",
+      "type": ["VerifiableCredential", "PrescriptionCredential"],
+      "issuer": "https://dmv.example.gov",
+      "issued": "2010-01-01",
+      "claim": {
+        "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+        "prescription": {....}
+      },
+      "revocation": {
+        "id": "http://example.gov/revocations/738",
+        "type": "SimpleRevocationList2017"
+      },
+      "proof": {....}
+    },
+    {
+      "id": "https://example.com/VC/123456789",
+      "type": ["VerifiableCredential", "PrescriptionCredential"],
+      "issuer": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+      "issued": "2010-01-03",
+      "claim": {
+        "id": "did:example:76e12ec21ebhyu1f712ebc6f1z2",
+        "prescription": {....}
+      },
+      "proof": {
+        "type": "RsaSignature2018",
+        "created": "2017-06-17T10:03:48Z",
+        "creator": "did:example:ebfeb1f712ebc6f1c276e12ec21/keys/234",
+        "nonce": "d61c4599-0cc2-4479-9efc-c63add3a43b2",
+        "signatureValue": "pYw8XNi1..Cky6Ed = "
+      }
+    }
+  ],
+  "proof": [{
+    "type": "RsaSignature2018",
+    "created": "2017-06-18T21:19:10Z",
+    "creator": "did:example:76e12ec21ebhyu1f712ebc6f1z2/keys/2",
+    "nonce": "c0ae1c8e-c7e7-469f-b252-86e6a0e7387e",
+    "signatureValue": "BavEll0/I1..W3JT24 = "
+  }]
+}
+
+ + +
+
+ +
+

Holder Acts on Behalf of the Subject

+ +

+The data model supports the holder acting on behalf of the +subject in at least the following ways: +

+ +
    +
  • +The issuer may include the relationship between the holder and the subject +in the claim data. +
    • +
  • +The issuer may express the relationship between the holder and the subject +by issuing a new verifiable credential which the holder utilizes. +
    • +
  • +The subject may express their relationship with the holder by issuing a +new verifiable credential which the holder utilizes. +
    • +
+ +

+The mechanisms above describe the relationship between the holder and the +subject and helps the verifier to decide whether the relationship is +sufficiently expressed for the given use case. +

+ +

+The additional mechanisms that the issuer or the verifier uses to verify the +relationship between the subject and the holder are outside of the scope of +this specification. +

+ +

+It is for further study which, if any, of these mechanisms is to be +standardised by the working group. +

+ + 
{
+  "id": "http://dmv.example.gov/credentials/3732",
+  "type": ["VerifiableCredential", "ProofOfAgeCredential"],
+  "issuer": "https://dmv.example.gov/issuers/14",
+  "issued": "2010-01-01T19:73:24Z",
+  "claim": {
+    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+    "ageUnder": 16,
+    "parent": {
+      "id": "did:example:ebfeb1c276e12ec211f712ebc6f",
+      "type": "Mother"
+    }
+  },
+  "proof": { ... } // the proof is generated by the DMV
+}
+
+ +

+In the example above, the issuer has expressed the relationship between the +child and the parent such that a verifier would most likely accept the +credential if it is provided by the child or the parent. +

+ + 
{
+  "id": "http://dmv.example.gov/credentials/3732",
+  "type": ["VerifiableCredential", "RelationshipCredential"],
+  "issuer": "https://dmv.example.gov/issuers/14",
+  "issued": "2010-01-01T19:73:24Z",
+  "claim": {
+    "id": "did:example:ebfeb1c276e12ec211f712ebc6f",
+    "child": {
+      "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+      "type": ["Person", "Child"]
+    }
+  },
+  "proof": { ... } // the proof is generated by the DMV
+}
+
+ +

+In the example above, the issuer has expressed the relationship between the +child and the parent in a separate credential such that a verifier would most +likely accept any of the child's credentials if it is provided by the child or +if the credential above is provided with any of the child's credentials. +

+ + 
{
+  "id": "http://example.org/credentials/23894",
+  "type": ["VerifiableCredential", "RelationshipCredential"],
+  "issuer": "http://example.org/credentials/23894",
+  "issued": "2010-01-01T19:73:24Z",
+  "claim": {
+    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+    "parent": {
+      "id": "did:example:ebfeb1c276e12ec211f712ebc6f",
+      "type": "Mother"
+    }
+  },
+  "proof": { ... } // the proof is generated by the child
+}
+
+ +

+In the example above, the child has expressed the relationship between the +child and the parent in a separate credential such that a verifier would most +likely accept any of the child's credentials if the credential above is +provided. +

+ +

+Similarly, these same strategies can be used for many other types of use cases +such as power of attorney, pet ownership, and patient prescription pick up. +

+ +
+ +
+

Issuer Authorises Holder

+ +

+When the issuer wishes to authorise a holder to possess a credential that +describes a subject who is not the holder, and the holder has no known relationship + with the subject, then the issuer inserts the +relationship of the holder to itself into the subject's credential. +

+ + + 
+
+{
+  "id": "http://dmv.example.gov/credentials/3732",
+  "type": ["VerifiableCredential", "NameAndAddress"],
+  "issuer": "https://dmv.example.gov/issuers/14",
+  "holder": {
+    "type": "LawEnforcement",
+    "id": "did:example:ebfeb1276e12ec21f712ebc6f1c"
+  },
+  "issued": "2010-01-01",
+  "claim": {
+    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+    "name": "Mr John Doe",
+    "address": "10 Some Street, Anytown, ThisLocal, Country X"
+  },
+  "proof": {
+    "type": "RsaSignature2018",
+    "created": "2017-06-17T10:03:48Z",
+    "creator": "https://dmv.example.gov/issuers/14/keys/234",
+    "nonce": "d61c4599-0cc2-4479-9efc-c63add3a43b2",
+    "signatureValue": "pY9...Cky6Ed = "
+  }
+}
+ + + + +
+ +
+

Holder Acts on Behalf of Verifier or has no Relationship with the +Subject, Issuer or Verifier

+ +

+ +The data model currently does not support either of these scenarios. It is +for further study how they might be supported. +

+
+ +
+ +
+

Disputes

+ +

+The time may come when an entity wants to dispute a credential +issued by the issuer. There are at least two different cases to consider: +a subject disputes a claim made by the issuer, e.g. the address property is out +of date, or an entity disputes a (false) claim made by the issuer about a +different subject, e.g. an imposter is claiming the entity's social security +number. Only the subject of a verifiable credential is entitled to issue a +"DisputeCredential". A "DisputeCredential" issued by anyone other than the +subject SHOULD be disregarded by the verifier, unless the verifier has some out +of band means of ascertaining the truth of the dispute. This is to prevent +denial of service attacks whereby an attacker falsely disputes a true claim. + +The mechanism for issuing a "DisputeCredential" +is the same as issuing a regular credential except that the subject +identifier for the claim in the "DisputeCredential" is the identifier of +the disputed credential. For example, if a credential with an identifier of +https://example.org/credentials/245 +is disputed, an entity may issue one of the following credentials. In the +former case, the subject might present this to the verifier along with the +disputed credential. In the latter case, the entity might publish the +"DisputeCredential" in a public venue to make it known that the credential +is disputed. +

+ + 
+{
+  "@context": [
+    "https://w3.org/2018/credentials/v1",
+    "https://example.com/examples/v1"
+  ],
+  "id": "http://example.com/credentials/123",
+  "type": ["VerifiableCredential", "DisputeCredential"],
+  "claim": {
+    "id": "http://example.com/credentials/245",
+    "currentStatus": "Disputed",
+    "statusReason": "Address is out of date"
+  },
+  "issuer": "https://example.com/people#me",
+  "issuanceDate": "2017-12-05T14:27:42Z",
+  "proof": { ... }
+}
+
+ + + 
+{
+  "@context": "https://w3id.org/credentials/v1",
+  "id": "http://example.com/credentials/321",
+  "type": ["VerifiableCredential", "DisputeCredential"],
+  "claim": {
+    "id": "http://example.com/credentials/245",
+    "currentStatus": "Disputed",
+    "statusReason": "Credential contains disputed statements",
+    "disputedClaim": {
+      "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+      "ageOver": 21
+    }
+  },
+  "issuer": "https://example.com/people#me",
+  "issuanceDate": "2017-12-05T14:27:42Z",
+  "proof": { ... }
+}
+
+ +

+A DisputeCredential issued by anyone other than the +subject, or its authorised agent, SHOULD be disregarded by a +verifier, unless the verifier has some out of band means of +ascertaining the truth of the dispute. +

+ +

+If a credential does not have an identifier, a content-addressed identifier +can be used to identify the disputed credential. Similarly, content-addressed +identifiers can be used to uniquely identify individual claims. +

+ +

+The group is currently exploring whether the specification of a vocabulary +term to express content-based identifiers for claims is within scope as well +as the specific vocabulary terms for disputed claims. +

+ +
+ +
+

Authorization

+ +

+Verifiable credentials are intended as a means of reliably identifying +subjects. Whilst it is recognized that Role Based Access Controls (RBAC) and +Attribute Based Access Controls (ABAC) rely on this identification as a means +of authorizing subjects to access resources, this specification +MUST NOT be used for authorization purposes without an accompanying +authorization framework. +

+ +

+The Working Group did consider authorization use cases during the creation of +this specification and is pursuing that work as an architectural layer that is +built on top of this specification. +

+ +
+ +
+

Conformance

+ +

+A concrete expression of the data model in this specification is a +conforming document if it complies with the normative statements in +this specification regarding syntax (e.g., the content in +Basic Concepts, +Advanced Concepts, and +Syntaxes). +For convenience, normative statements for conforming documents are +often phrased as statements on the syntax used in properties and their +associated values in the document (e.g., "MUST be a URI", +"MUST be a string value of an ISO8601 combined date and time string"). +

+ +

+A conforming processor is a software or hardware-based implementation +of the normative statements in this specification regarding the expected +contents of property-value pairs (e.g., the content in Verification). +For convenience, normative statements for conforming processors are +often phrased as behavioral statements regarding the contents of +property-value pairs (e.g., "MUST NOT be revoked", "MUST be in the expected range"). +

+ +
+ +
+ +
+

Syntaxes

+ + +

+Many of the data model concepts in this document thus far have been introduced +by example using the JSON syntax. This section formalizes how the data model +(described in Sections , +, and +) is realized in JSON and JSON-LD. Although syntactic mappings are only provided for these two syntaxes, +applications and services may also use any other data representation syntax, +such as XML, YAML, or CBOR, that is capable of expressing the data model. +

+ +
+

JSON

+ +

+The data model as described in Section can be +encoded in Javascript Object Notation (JSON) [[!RFC8259]] by mapping +property values to the following JSON types: +

+ +
    +
  • Numeric values representable as IEEE754 SHOULD be represented + as a Number type.
    • +
  • Any boolean value SHOULD be represented as a Boolean type.
    • +
  • Any sequence value SHOULD be represented as an Array type.
    • +
  • Any unordered set of values SHOULD be represented as + an Array type.
    • +
  • Any set of properties SHOULD be represented as + an Object type.
    • +
  • Any empty value SHOULD be represented as a null value.
    • +
  • Any other value MUST be represented as a String type.
    • +
+ +
+

JSON Web Token

+ +

+This section will be moved into its own specification before this document +enters the Candidate Recommendation stage. +

+ +

The following example demonstrates how one could + express this data model 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 Credentials. 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",
+    "verifiableCredential": {
+      "@context": "https://w3.org/2018/security/v1",
+      "id": "http://example.gov/credentials/3732",
+      "type": ["VerifiableCredential", "ProofOfAgeCredential"],
+      "issuer": "https://dmv.example.gov",
+      "issuanceDate": "2010-01-01",
+      "claim": {
+        "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+        "ageOver": 21
+      }
+    }
+  }
+
+ +
+ +
+ +
+

JSON-LD

+ +

+[[!JSON-LD]] is a JSON-based format that is used to serialize +Linked Data. +The syntax is designed to easily integrate into deployed systems that +already use JSON, and provides a smooth upgrade path from JSON to JSON-LD. +It is primarily intended to be a way to use Linked Data in +Web-based programming environments, to build interoperable Web services, +and to store Linked Data in JSON-based storage engines. +

+ +

+JSON-LD is useful when extending the data model described in this +specification. Instances of the data model are encoded in JSON-LD in +the same way that they are encoded in JSON (Section ), +with the addition of the @context property. The +JSON-LD Context +is described in detail in the [[!JSON-LD]] specification and its use +is elaborated upon in Section . +

+ +

+Multiple contexts MAY be used or combined to express any arbitrary +information about credentials in idiomatic JSON. If an application is +processing a verifiable credential or verifiable presentation, +and a @context property is not present at the top-level of the +JSON-LD document, then a @context property with a value of +https://w3.org/2018/credentials/v1 MUST be assumed. The +JSON-LD Context available at https://w3.org/2018/credentials/v1 +is a static document that is never updated and may thus be downloaded and +cached client side. The associated vocabulary document for the +Verifiable Credentials Data Model can be found at the following URL: +https://w3.org/2018/credentials. +

+ +
+ +
+ +
+

Verification

+ +

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

+ +

+The group is currently discussing whether a mechanism should be provided +that enables linkages to JSON Schema or other optional validation mechanisms. +

+ +
+

Syntax

+
    +
  • The document is syntactically valid (e.g., JSON, JSON-LD).
    • +
+
+
+

Credential

+
    +
  • Required properties MUST be present. For example, for a + verifiable credential, type + and proof properties are required.
    • +
  • Property values MUST match expectations described in this + specification. For example, the document type property + for a verifiable credential MUST contain the class + VerifiableCredential.
    • +
+
+
+

Issuer

+
    +
  • The value associated with the issuer + property MUST identify an issuer that is known to and trusted + by the verifier.
    • +
  • Pertinent metadata about the issuer MUST be + available to the verifier. For example, an issuer may publish + information that contains the public keys it uses to digitally + sign verifiable credentials that it has issued. This + metadata is pertinent when checking the proofs on the + verifiable credential.
    • +
+
+
+

Subject

+
    +
  • The value associated with the id property for each + claim MUST identify a subject to the + verifier. For example, if a subject is identified and the + verifier has public key metadata related to the subject that is + used for authentication purposes, then the verifier MAY be able to + authenticate the subject via a signature generated by the subject + that is contained in the verifiable presentation.
    • +
+ +

+The group is currently discussing how authentication and WebAuthn may work. +

+ +

+The id property is optional, and verifiers MAY use other +properties in a credential to uniquely identify the subject. +

+
+
+

Proofs (e.g., Signatures)

+ +

+The cryptographic mechanism used to prove that the information in a +verifiable credential or a verifiable presentation has not been +tampered with is called a proof. There are many types of cryptographic proofs +including but not limited to, digital signatures, zero-knowledge proofs, +proofs of work, and proofs of stake. In general, when verifying proofs, +implementations MUST ensure that: +

+ +
    +
  • The proof is available in the form of a known proof suite.
    • +
  • All required proof suite properties are present.
    • +
  • The proof suite verification agorithm, when applied to the + data, results in an acceptable proof.
    • +
+ +

+Some proofs are digital signatures. In general, when verifying digital +signatures, implementations MUST ensure that: +

+ +
    +
  • Acceptably recent metadata regarding the public key + associated with the signature is available. For example, the + metadata may include properties related to expiration, key owner, + or key purpose.
    • +
  • The key MUST NOT be revoked or expired.
    • +
  • The cryptographic signature MUST be valid.
    • +
  • + If the cryptographic suite expects a proofPurpose, + it MUST exist and be a valid value (such as + credentialIssuance) per the cryptographic suite. +
    • +
+ +

+The digital signature provides a number of protections, other than tamper +resistance, that are not immediately obvious. +For example, a Linked Data Signature's created property +establishes a date and time where the credential SHOULD NOT be considered +valid before that date and time. The creator property enables +the ability to dynamically discover information about the entity that created +the data to ensure that the public key has not been revoked or expired. +The proofPurpose property ensures that the reason the entity +created the signature, such as for the purposes of authentication or creating +a verifiable credential, is clear and protected in the signature. +

+
+
+

Issuance

+ +
    +
  • The issuanceDate MUST be in an expected range for + the verifier. For example, a verifier may ensure that the + issuance date of a verifiable credential is not in the + future.
    • +
+
+
+

Expiration

+ +
    +
  • The expirationDate MUST be in an expected range for + the verifier. For example, a verifier may ensure that the + expiration date is not in the past.
    • +
+
+
+

Revocation

+
    +
  • If revocation instructions are present, the credential must not + have been revoked.
    • +
+
+
+

Fitness for Purpose

+ +
    +
  • The custom properties in the credential are + appropriate for the verifier's purpose. For example if a + 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 verifier to make the + claims at hand. For example, a franchised Fast Food restaurant + location will trust discount coupon claims made by the + corporate headquarters of the franchise.
    • +
  • All policy information expressed by the issuer + in the verifiable credential MUST be enforced unless + verifiers accept the risk of not enforcing the policy information. + For example, the issuer may limit the use + of the credential to specific verifiers, certain holder + age ranges, or during certain dates.
    • +
  • All policy information expressed by the holder + in the verifiable presentation MUST be enforced unless + verifiers accept the risk of not enforcing the policy information. + For example, the holder may limit the use of the credential to + specific verifiers or for specific purposes + (such as authentication, but not data mining).
    • +
+
+
+ +
+

Accessibility Considerations

+ + This section is non-normative. + +

+There are a number of accessibility considerations of which implementors +should be aware when processing data described in this specification. +As with any implementation of web standards or protocols, ignoring +accessibility issues will make this information unusable to a large +subset of the population. It is important to follow accessiblity +guidelines and standards such as [[WCAG21]] to ensure that all people, +regardless of ability, can make use of this data. This is especially +important when establishing systems that utilize cryptography and encryption, +which, historically, have created problems for assistive technologies. +

+ +

+This section details the general accessibility considerations that should be +taken into account when utilizing this data model. +

+ +
+

Data First Approaches

+

+Many physical credentials in use today, such as government identification +cards, have poor accessibility characteristics. Some of these poor +characteristics include, but are not limited to, small print, +reliance on small, high resolution images, and no affordances for people with +vision impairments. +

+ +

+When utilizing this data model to create verifiable credentials, it is +suggested that data model designers use a "data first" approach. For example, +given the choice of using data or a graphical image to depict a credential, +a designer should choose to express every element of the image, +such as the name of an institution or the professional credential, in a +machine readable way rather than solely relying on the image to convey this +information. This approach is preferred because a "data first" approach +provides the foundational elements of building different interfaces for +people with varying abilities. +

+
+
+ +
+

Privacy Considerations

+ + This section is non-normative. + +

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

+ +
+

Spectrum of Privacy

+

+It is important to recognize that there is a spectrum of privacy that ranges +from pseudonymous 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 pseudonymous 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. +

+ +

+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 Credentials 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. +

+ +

+The group is currently discussing how the specification should be modified to +support ZKPs and other forms of anonymous credentials. +

+
+ +
+

Personally Identifiable Information

+ +

+The data associated with verifiable credentials stored in the +credential.claim field are largely susceptible to privacy +violations when shared with 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 verifier desires to determine if an +entity is over the age of 18. +

+
+ +
+

Identifier-Based Correlation

+ +

+Subjects of verifiable credentials are identified via the +credential.claim.id field. The identifiers that are used +to identify the subject 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 credentials, 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 credentials are secured via the +credential.proof field. The properties in this field +create a danger of correlation when the same values are used across more than +one session or domain and the value does not change. Examples include the +creator, created, +domain (for very specific domains), +nonce, and signatureValue fields. +

+ +

+If strong anti-correlation properties are desired, +it is advised that signature values and metadata are regenerated +each time using technologies like third-party pairwise signatures, +zero-knowledge proofs, or group signatures. It is also important to note +that even when using anti-correlation signatures that information may still +be contained in the credential that defeats the anti-correlation properties +of the cryptography. +

+
+ +
+

Long Lived Identifier-Based Correlation

+ +

+Verifiable credentials may contain long lived identifiers that could +be used to correlate individuals. These types of identifiers include: +subject identifiers, email addresses, government-issued identifiers, +organization-issued identifiers, addresses, healthcare vitals, +credential-specific JSON-LD Contexts, and many other sorts of long-lived +identifiers. +

+ +

+Organizations providing software to holders should strive to identify +fields in credentials containing information that could be used to correlate +them and warn the holder when this information is shared. +

+
+ +
+

Device Fingerprinting

+ +

+There are mechanisms external to Verifiable Credentials 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 Credentials, 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-respecting systems prevent the use of these other +tracking technologies when verifiable credentials are being utilized. In some cases, +these tracking technologies may need to be disabled entirely on devices that +transmit verifiable credentials on behalf of the Holder. +

+
+ +
+

Favor Abstract Claims

+ +

+In order to enable recipients of verifiable credentials 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 credential to a minimal set needed for +the expected purposes. One way to avoid placing personally identifiable +information in a credential is to use an "abstract" property that meets the +needs of 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 credentials containing 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 credentials, minimal disclosure for issuers means limiting the +content of a credential to the minimum required by potential verifiers for +expected use. For verifiers, it means limiting the scope of the information +requested 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 credential +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 set of credentials containing every +attribute that appears on a driver's license in addition to atomized +credentials (a credential containing only the person's birthday), and atomized +credentials that are more abstract (a credential containing only an +ageOver attribute). One possible simple adaptation is for the issuer to +provide secure HTTP endpoints for retrieving single-use bearer credentials to +promote the pseudonymous usage of credentials. Implementers that find this +impractical or unsafe should consider the use of selective disclosure schemes +that eliminate dependence on issuers at proving time and reduce temporal +correlation risk from the issuer. +

+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 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. +

+

+While it is possible to practice the Principle of Minimum Disclosure, it may +be impossible to avoid the strong identification of an individual for +specific use cases during a single session or over multiple sessions. The +authors of this document cannot stress how difficult it is to meet this +principle in real world scenarios. +

+
+ +
+

Bearer Credentials

+ +

+A bearer credential is a privacy-enhancing piece of information, +such as a concert ticket, that entitles the holder of the credential to a +particular resource without divulging sensitive information about the holder. +

+ +

+Verifiable Credentials that are bearer credentials are possible by not +specifying the subject identifier, expressed using the +id property that is nested in the claim property. +For example, the following Verifiable Credential is a bearer credential: +

+ + 
+{
+  "@context": [
+    "https://w3.org/2018/credentials/v1",
+    "https://example.com/examples/v1"
+  ],
+  "id": "http://dmv.example.gov/credentials/temporary/28934792387492384",
+  "type": ["VerifiableCredential", "ProofOfAgeCredential"],
+  "issuer": "https://dmv.example.gov/issuers/14",
+  "issuanceDate": "2017-10-22T12:23:48Z",
+  "claim": {
+    // note that the 'id' property is not specified for bearer credentials
+    "ageOver": 21
+  },
+  "proof": { ... }
+}
+
+ +

+While bearer credentials can be privacy enhancing, their use must be carefully +crafted to not accidentally divulge more information than the holder of the +credential expects. For example, repeated use of the same bearer credential +across sites enables each site to potentially collude to unduly track or +correlate the holder. Additionally, information that may seem non-identifying +such as a birthdate and zip code can be used to statistically identify an +individual when used together in the same credential or session. +

+ +

+Issuers of bearer credentials SHOULD ensure that bearer credentials that +are expected to provide privacy-enhancing benefits 1) are single use, when +possible, 2) do not contain personally identifying information, and 3) are not +unduly correlatable. +

+ +

+Holders SHOULD be warned by their software if bearer credentials +containing sensitive information are issued or requested, or if there is a +correlation risk when combining two or more bearer credentials across one +or more sessions. While it may be impossible to detect all correlation risks, +some may be detectable. +

+ +

+Verifiers SHOULD NOT request bearer credentials that can be used to +unduly correlate the user. +

+
+ +
+

Validity Checks

+ +

+When processing verifiable credentials, verifiers typically perform +many of the checks listed in Section as well as +a variety of business-process-specific checks. For example, validity checks +may include any of the following: +

+ +
    +
  • +Checking the professional licensure status of the holder. +
    • +
  • +Checking a date of license renewal or revocation. +
    • +
  • +Checking sub-qualifications of an individual. +
    • +
  • +Ensuring that a relationship exists between the holder and the entity +with whom the holder is attempting to interact. +
    • +
  • +Checking the geolocation information associated with the holder. +
    • +
+ +

+The process of performing these checks may result in information leakage that +leads to a privacy violation of the holder. For example, an operation as +simple as checking a revocation list can notify the issuer that a very specific +business is most likely interacting with the holder. This would enable +issuers to collude and correlate individuals without their knowledge. +

+ +

+Issuers are urged to not use mechanisms, such as credential revocation +lists that are unique per credential, during the verification process that +would lead to privacy violations. Organizations providing software to +holders should warn when credentials include information that could +lead to privacy violations during the verification process. Verifiers +should consider rejecting credentials that produce privacy violations or that +enable bad privacy practices. +

+
+ +
+

Storage Providers and Data Mining

+ +

+When a holder receives a credential from an issuer, the +credential will need to be stored somewhere (e.g., in a credential repository). +Holders are warned that the information in a verifiable credential 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 credentials 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 credentials +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 credentials such that a service provider +cannot view the contents of the credential. +
    • +
  • +Use software that stores verifiable credentials locally on a device that you +control and that does not upload or analyze your information beyond +your expectations. +
    • +
+
+ +
+

Aggregation of Credentials

+ +

+Two pieces of information about the same subject almost always reveal +more information than just a single piece of information, even when delivered +through different channels. The aggregation of credentials is a privacy risk and +all participants in the ecosystem need to be aware of the risks of data +aggregation. +

+ +

+For example, if a bearer credential for an email address and then a bearer +credential +stating that the holder is over the age of 21 are provided across multiple +sessions, the verifier of the information has 1) a unique identifier to +associate with the individual, and 2) age-related information for that +individual. It then becomes trivial to +create a profile for the holder such that more and more information is leaked +over time. Aggregation of credentials can be performed across multiple sites that +are colluding as well, leading to privacy violations. +

+ +

+Preventing the aggregation of information is a very difficult privacy problem +to address from a technological perspective. While new cryptographic techniques, +such as zero-knowledge proofs, have been proposed as solutions to the problem +of aggregation and correlation, the existence of long-lived identifiers +and browser tracking techniques easily defeat even the most modern +cryptographic techniques. +

+ +

+The solution to the privacy implications of correlation or aggregation tend +to not be technological in nature, but policy driven instead. Therefore, if +a holder does not wish information to be aggregated about them, then they +must express this in the verifiable presentations that they transmit. +

+ +
+ +
+

Usage Patterns

+ +

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

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

+It’s possible to mitigate this in part: +

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

+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 credentials 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 credential usage occur when unintended or unexpected +correlation arises from the presentation of verifiable credentials. +

+
+ +
+

Sharing Information with the Wrong Party

+ +

+When a holder chooses to share information with a verifier, it +may be the case that the verifier is acting in bad faith and requests +information that could be used to harm the holder. For example, a +verifier may ask for a bank account number, which could then be used in +concert with other information to defraud the holder or the bank. +

+ +

+Issuers should strive to tokenize as much information as possible such +that if a holder accidentally transmits credentials to the wrong +verifier that the information loss isn't catastrophic. +

+ +

+For example, instead of including a bank account number +for the purposes of checking a bank balance for an individual, provide a +token that enables the verifier to use the token to check to see if the +balance is above a certain amount. In this case, the bank could +issue a verifiable credential containing a token for checking balance +to a holder. A holder would then include the verifiable credential in a +verifiable presentation and bind the token to a credit checking agency via a digital +signature. The verifier would then wrap the verifiable presentation in their digital +signature, and hand it back to the issuer to dynamically check the account +balance. +

+ +

+This approach ensures that even if the holder shares the account balance token +with the wrong party that the attacker doesn't discover the bank account +number, nor the exact value in the account, and given the validity period for +the counter-signature, doesn't gain access to the token for more than a few +minutes. +

+
+ +
+

Frequency of Claim Issuance

+ +

+As Section details, usage patterns can be +correlated into certain types of behavior. Part of this correlation is +mitigated when a holder uses a verifiable credential without the +knowledge of the issuer. Issuers may defeat this protection by making +their credentials short lived and renewal automatic. +

+ +

+For example, an "over the age of 21" credential may be useful when gaining +access to a bar. If an issuer makes the credential have a very short expiration +date and an automatic renewal mechanism, then they could possibly correlate +the holder's behavior in a way that negatively impacts the holder. +

+ +

+Organizations providing software to holders should warn holders if they +repeatedly use credentials with short lifespans that could result in +behavior correlation. Issuers should avoid issuing credentials in a way that +enables them to correlate usage patterns. +

+ +
+ +
+

Prefer Single-Use Credentials

+ +

+An ideal privacy-respecting system would only require information to be +disclosed by the holder that is necessary for the interaction with the verifier. +The verifier would then record that the disclosure requirement was met and +forget any sensitive information that was disclosed. In many cases, +competing priorities, such as regulatory burden, prevent this ideal system +from being employed. +In other cases, long-lived identifiers prevent single use. +The design of any verifiable credentials ecosystem, however, should strive to +be as privacy-respecting as possible by preferring single-use credentials +when possible. +

+ +

+The usage of these type of credentials provides several benefits. The first +benefit is to verifiers who can be sure that the data in the credential is +fresh. The second benefit is to holders, who know that if there are no long-lived +identifiers in the credential that the credential itself cannot be used +to track or correlate them online. Finally, the third benefit ensures that +there is nothing for attackers to steal, making the entire ecosystem safer +to operate within. +

+
+
+

Avoid Disclosing Credential Identifier

+

+Disclosing the credential identifier leads to situations where multiple +verifiers or an issuer and a verifier can collude to correlate the holder. +If the holder desires to reduce correlation, they should use credential +schemes which allow hiding the identifier during presentation. Such schemes +expect the holder to generate the identifier and may even allow hiding the +identifier from the issuer, whilst still keeping the identifier embedded +and signed in the credential. +

+
+
+ +
+

Security Considerations

+ + This section is non-normative. + +

+There are a number of security considerations that issuers, +holders, and verifiers should be aware of when processing +data described by this specification. Ignoring or not understanding the +implications of this section can result in security vulnerabilities. +

+ +

+While this section attempts to highlight a broad set of security +considerations, it should not be interpreted as a complete list of all +security considerations. Implementers are urged to seek the advice of security +and cryptography professionals when implementing mission critical systems +using the technology outlined in this specification. +

+ +
+

Cryptography Suites and Libraries

+ +

+Some aspects of the data model described in this specification can be +protected through the use of cryptography. +Implementers should be aware of the underlying +cryptography suites and libraries that are used to implement the +creation and verification of digital signatures and mathematical proofs +utilized by their systems when processing credentials and +presentations. Software developers with extensive experience implementing +or auditing systems that use cryptography must be used to ensure that +systems are properly designed. Proper +red teaming +is also suggested to remove bias from security reviews. +

+ +

+Cryptography suites and libraries have a shelf life and eventually fall to +new attacks and technology advances. Any production quality system must take +this reality into account and ensure that mechanisms exist to easily upgrade +old or broken cryptographic suites and libraries in a proactive manner. +Mechanisms should also exist to invalidate and replace existing credentials +in the event of a cryptography suite or library failure. +Regular monitoring of systems to ensure proper upgrades are made in a timely +manner are also important to ensure the long term viability of systems +processing verifiable credentials. +

+ +
+ +
+

Unsigned Claims

+ +

+This specification allows credentials to be produced that do not +contain signatures or proofs of any kind. These types of credentials are often +useful for intermediate storage, or self-asserted information, which is +analogous to filling out a form on a web page. Implementers should note that +these types of credentials are not verifiable because the authorship +is either not known or cannot be trusted. +

+
+ +
+

Token Binding

+

+A verifier may need to ensure that it is the intended recipient +of a verifiable presentation and is not the target of a + +man-in-the-middle attack. Any protocol that utilizes the +Verifiable Credentials Data Model and requires protection against these +sorts of attacks needs to perform some sort of token binding, such +as using +The Token Binding Protocol v1.0, that ties +the request for a verifiable presentation with the response. Any +protocol that does not perform token binding is susceptible to +man-in-the-middle attacks. +

+ +
+ +
+

Bundling Dependent Claims

+

+It is considered a best practice for issuers to atomize information in a +credential, or use a signature scheme that allows for selective disclosure. +In the former case, if the atomization is not done securely by the issuer, +the holder might bundle together different credentials in a way that was not +intended by the issuer. +

+

+For example a university might issue two credentials to a person, each +containing two properties, i.e., "Staff Member" in the +"Department of Computing" and "Post Graduate Student" in the +"Department of Economics". If these credentials are atomized into separate +properties, then the university would issue four credentials to the person, +each containing one of the following properties: +"Staff Member", "Post Graduate Student", "Department of Computing", and +"Department of Economics". The holder could then transfer +the "Staff Member" and "Department of Economics" to a verifier, +which together would comprise a false claim. +

+ +
+ +
+

Highly Dynamic Information

+ +

+When verifiable credentials are issued for highly dynamic information, +implementers should ensure that the expiration times for the credential are +set appropriately. Expiration periods that are longer than the timeframe +where the credential is valid may create exploitable security vulnerabilities. +Expiration periods that are shorter than the timeframe where the information +expressed by the credential is valid create a burden on holders and +verifiers. It is therefore important to set validity periods for +credentials that are appropriate to the use case and the expected lifetime +for the information contained in the credential. +

+ +
+ +
+

Device Theft and Impersonation

+ +

+When verifiable credentials are stored on a device and that +device is stolen by an attacker, it may be possible for the attacker to then +gain access to systems using the victim's verifiable credentials. Mitigations +for this attack include: +

+ +
    +
  • +Enabling password, pin, pattern, or biometric screen unlock protection. +
    • +
  • +Enabling password, biometric, or multi-factor authentication for the +credential repository. +
    • +
  • +Enabling password, biometric, or multi-factor authentication when +accessing cryptographic keys. +
    • +
  • +Utilizing a separate hardware-based signature device. +
    • +
  • +All or any combination of the above. +
    • +
+ +
+ + + +