Difference between revisions of "Verifiable Cred V1.1 Normative"

Latest revision as of 21:08, 20 November 2023

Full Title or Meme

W3C Verifiable Credential Abstract.

Context

The Variable Cred Data Model Spec is hard to read. This is a collection of only the mandatory bits separated from the optional bits with assistance from David Chadwick, one of the Authors of the spec. It is designed to be helpful for people who are familiar with identity standards come up-to-speed quickly.

Problems

These are not necessarily defects in the VC data model as much as they are limitations in the model itself, which may have been intentional.

1. The VC data model is a definition of the structure (and use) of the credential and so term like Expiration Date applies not to the license or grant, but to the bucket of bits that is defined in the model.
2. In general, the use of term license in the real world conflates the concept of a grant with the documentation of that grant. So, a Driver's License sometimes refers to the grant of a privilege to use the public road with the documentation of that grant in an ISO 18013 paper or digital document.
3. All of today's Mobile Credentials have a problem distinguishing between the Subject and the Holder. The easiest way to think about the problem is a parent traveling with an under-age child that does not yet have a Smartphone. More work is needed in the UX of any proposed solution. Think about the challenge of being in front of a boarder agent with a long line of applicants trying to get the right credential to display on the agent's demand while still controlling the child.
4. The standard includes several long URLs that make it hard for a VC to be encoded in a single QR Code, which is suggested as a back-up for when the networks are down. The Smart Health Card took the approach of putting the context (i.e. shc://) outside the certificate, which allowed the SHC to be encoded in a single QR code image.
5. For many use cases, the most important element for verifiers would be Proof of Presence of the holder, for example, when an attribute like age of the holder is required by law. This is not defined in the standard, although there is an "Evidence" section where it could be included if defined elsewhere.

Mandatory Elements

The key words MAY, MUST, MUST NOT, RECOMMENDED, and SHOULD in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

1.4 Conformance

A conforming document is any concrete expression of the data model that complies with the normative statements in this specification. Specifically, all relevant normative statements in Sections 4. Basic Concepts, 5. Advanced Concepts, and 6. Syntaxes of this document MUST be enforced. A serialization format for the conforming document MUST be deterministic, bi-directional, and lossless as described in Section 6. Syntaxes. The conforming document MAY be transmitted or stored in any such serialization format.

A conforming processor is any algorithm realized as software and/or hardware that generates or consumes a conforming document. Conforming processors MUST produce errors when non-conforming documents are consumed.

This specification makes no normative statements with regard to the conformance of roles in the ecosystem, such as issuers, holders, or verifiers, because the conformance of ecosystem roles are highly application, use case, and market vertical specific.

Digital proof mechanisms, a subset of which are digital signatures, are required to ensure the protection of a verifiable credential. Having and validating proofs, which may be dependent on the syntax of the proof (for example, using the JSON Web Signature of a JSON Web Token for proofing a key holder), are an essential part of processing a verifiable credential. At the time of publication, Working Group members had implemented verifiable credentials using at least three proof mechanisms:

1. JSON Web Tokens [RFC7519] secured using JSON Web Signatures [RFC7515]
2. Data Integrity Proofs [DATA-INTEGRITY]
3. Camenisch-Lysyanskaya Zero-Knowledge Proofs [CL-SIGNATURES].

Implementers are advised to note that not all proof mechanisms are standardized as of the publication date of this specification. The group expects some of these mechanisms, as well as new ones, to mature independently and become standardized in time. Given there are multiple valid proof mechanisms, this specification does not standardize on any single digital signature mechanism. One of the goals of this specification is to provide a data model that can be protected by a variety of current and future digital proof mechanisms. Conformance to this specification does not depend on the details of a particular proof mechanism; it requires clearly identifying the mechanism a verifiable credential uses.

4.1 Contexts

When two software systems need to exchange data, they need to use terminology that both systems understand. As an analogy, consider how two people communicate. Both people must use the same language and the words they use must mean the same thing to each other. This might be referred to as the context of a conversation.

Verifiable credentials and verifiable presentations have many attributes and values that are identified by URIs [RFC3986]. However, those URIs can be long and not very human-friendly. In such cases, short-form human-friendly aliases can be more helpful. This specification uses the @context property to map such short-form aliases to the URIs required by specific verifiable credentials and verifiable presentations.

NOTE: In JSON-LD, the @context property can also be used to communicate other details, such as datatype information, language information, transformation rules, and so on, which are beyond the needs of this specification, but might be useful in the future or to related work. For more information, see Section 3.1: The Context of the [JSON-LD] specification.

Verifiable credentials and verifiable presentations MUST include a @context property.

@context

The value of the @context property MUST be an ordered set where the first item is a URI with the value https://www.w3.org/2018/credentials/v1. For reference, a copy of the base context is provided in Appendix B.1 Base Context. Subsequent items in the array MUST express context information and be composed of any combination of URIs or objects. It is RECOMMENDED that each URI in the @context be one which, if dereferenced, results in a document containing machine-readable information about the @context.

NOTE: Though this specification requires that a @context property be present, it is not required that the value of the @context property be processed using JSON-LD. This is to support processing using plain JSON libraries, such as those that might be used when the verifiable credential is encoded as a JWT. All libraries or processors MUST ensure that the order of the values in the @context property is what is expected for the specific application. Libraries or processors that support JSON-LD can process the @context property using full JSON-LD processing as expected.

The following paragraph appears to be in a normative section, but it is empirically false as it points to v1.1 and not v1.0
The data available at https://www.w3.org/2018/credentials/v1 is a static document that is never updated and SHOULD be downloaded and cached. The associated human-readable vocabulary document for the Verifiable Credentials Data Model is available at https://www.w3.org/2018/credentials/.

4.3 Types

Software systems that process the kinds of objects specified in this document use type information to determine whether or not a provided verifiable credential or verifiable presentation is appropriate. This specification defines a type property for the expression of type information. Verifiable credentials and verifiable presentations MUST have a type property. That is, any credential or presentation that does not have type property is not verifiable, so is neither a verifiable credential nor a verifiable presentation.

type
The value of the type property MUST be, or map to (through interpretation of the @context property), one or more URIs. If more than one URI is provided, the URIs MUST be interpreted as an unordered set. Syntactic conveniences SHOULD be used to ease developer usage. Such conveniences might include JSON-LD terms. It is RECOMMENDED that each URI in the type be one which, if dereferenced, results in a document containing machine-readable information about the type.

All credentials, presentations, and encapsulated objects MUST specify, or be associated with, additional more narrow types (like UniversityDegreeCredential, for example) so software systems can process this additional information.

4.4 Credential Subject

A verifiable credential contains claims about one or more subjects. This specification defines a credentialSubject property for the expression of claims about one or more subjects. A verifiable credential MUST have a credentialSubject property.

credentialSubject
The value of the credentialSubject property is defined as a set of objects that contain one or more properties that are each related to a subject of the verifiable credential. Each object MAY contain an id, as described in Section 4.2 Identifiers.

4.5 Issuer

This specification defines a property for expressing the issuer of a verifiable credential. A verifiable credential MUST have an issuer property.

issuer
The value of the issuer property MUST be either a URI or an object containing an id property. It is RECOMMENDED that the URI in the issuer or its id be one which, if dereferenced, results in a document containing machine-readable information about the issuer that can be used to verify the information expressed in the credential.

4.6 Issuance Date

This specification defines the issuanceDate property for expressing the date and time when a credential becomes valid.

issuanceDate
A credential MUST have an issuanceDate property. The value of the issuanceDate property MUST be a string value of an [XMLSCHEMA11-2] combined date-time string representing the date and time the credential becomes valid, which could be a date and time in the future.

4.7 Proofs (Signatures)

At least one proof mechanism, and the details necessary to evaluate that proof, MUST be expressed for a credential or presentation to be a verifiable credential or verifiable presentation; that is, to be verifiable. This specification identifies two classes of proof mechanisms:

1. An external proof is one that wraps an expression of this data model, such as a JSON Web Token. Three signature methods are included in the base schema:
   1. EcdsaSecp256k1Signature2019
   2. EcdsaSecp256r1Signature2019 - this is the only one approved for use in Signing by Western governments in early 2022.
   3. Ed25519Signature2018
2. An embedded proof is a mechanism where the proof is included in the data, such as a Linked Data Signature, which is elaborated upon in Section 6.3.2 Data Integrity Proofs. When embedding a proof, the proof property MUST be used.

proof
One or more cryptographic proofs that can be used to detect tampering and verify the authorship of a credential or presentation. The specific method used for an embedded proof MUST be included using the type property.

Optional Elements

4.2 Identifiers

Defines the normative use of ID, which is, itself, optional.

The value of the id property MUST be a single URI.

4.8 Expiration

This specification defines the expirationDate property for the expression of credential expiration information. (I would expect this element to be mandatory in most use cases.)

expirationDate
If present, the value of the expirationDate property MUST be a string value of an [XMLSCHEMA11-2] date-time representing the date and time the credential ceases to be valid.

4.9 Status

This specification defines the following credentialStatus property for the discovery of information about the current status of a verifiable credential, such as whether it is suspended or revoked.

credentialStatus
If present, the value of the credentialStatus property MUST include the following:
id property, which MUST be a URI.
type property, which expresses the credential status type (also referred to as the credential status method). It is expected that the value will provide enough information to determine the current status of the credential and that machine readable information needs to be retrievable from the URI. For example, the object could contain a link to an external document noting whether or not the credential is suspended or revoked.

4.10 Presentations

Presentations MAY be used to combine and present credentials. They can be packaged in such a way that the authorship of the data is verifiable. The data in a presentation is often all about the same subject, but there is no limit to the number of subjects or issuers in the data. The aggregation of information from multiple verifiable credentials is a typical use of verifiable presentations.

A verifiable presentation is typically composed of the following properties:

id
The id property is optional and MAY be used to provide a unique identifier for the presentation. For details related to the use of this property, see 
Section 4.2 Identifiers.
type
The type property is required and expresses the type of presentation, such as VerifiablePresentation. For details related to the use of this property, see 
Section 4.3 Types.
verifiableCredential
If present, the value of the verifiableCredential property MUST be constructed from one or more verifiable credentials, or of data derived from verifiable credentials in a cryptographically verifiable format.

holder
If present, the value of the holder property is expected to be a URI for the entity that is generating the presentation.

proof
If present, the value of the proof property ensures that the presentation is verifiable. For details related to the use of this property, see Section 4.7 
Proofs (Signatures).

5.4 Data Schemas

Data schemas are useful when enforcing a specific structure on a given collection of data. There are at least two types of data schemas that this specification considers:

Data verification schemas, which are used to verify that the structure and contents of a credential or verifiable credential conform to a published schema.
Data encoding schemas, which are used to map the contents of a verifiable credential to an alternative representation format, such as a binary format used in a zero-knowledge proof.
It is important to understand that data schemas serve a different purpose from the @context property, which neither enforces data structure or data syntax, nor enables the definition of arbitrary encodings to alternate representation formats.

This specification defines the following property for the expression of a data schema, which can be included by an issuer in the verifiable credentials that it issues:

credentialSchema
The value of the credentialSchema property MUST be one or more data schemas that provide verifiers with enough information to determine if the provided data conforms to the provided schema. Each credentialSchema MUST specify its type (for example, JsonSchemaValidator2018), and an id property that MUST be a URI identifying the schema file. The precise contents of each data schema is determined by the specific type definition.

5.5 Refreshing

It is useful for systems to enable the manual or automatic refresh of an expired verifiable credential. For more information about expired verifiable credentials, see Section 4.8 Expiration. This specification defines a refreshService property, which enables an issuer to include a link to a refresh service.

The issuer can 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. In the latter case, this enables the holder to refresh the verifiable credential before creating a verifiable presentation to share with a verifier. In the former case, including the refresh service inside the verifiable credential enables either the holder or the verifier to perform future updates of the credential.

The refresh service is only expected to be used when either the credential has expired or the issuer does not publish credential status information. Issuers are advised not to put the refreshService property in a verifiable credential that does not contain public information or whose refresh service is not protected in some way.

NOTE Placing a refreshService property in a verifiable credential so that it is available to verifiers can remove control and consent from the holder and allow the verifiable credential to be issued directly to the verifier, thereby bypassing the holder.

refreshService
The value of the refreshService property MUST be one or more refresh services that provides enough information to the recipient's software such that the recipient can refresh the verifiable credential. Each refreshService value MUST specify its type (for example, ManualRefreshService2018) and its id, which is the URI of the service. There is an expectation that machine readable information needs to be retrievable from the URI. The precise content of each refresh service is determined by the specific refreshService type definition.

5.6 Terms of Use

Terms of use can be utilized by an issuer or a holder to communicate the terms under which a verifiable credential or verifiable presentation was issued. (This whole section is clearly anachronistic when written and will have little use in enabling a common user to understand anything.)

termsOfUse
The value of the terms-Of-Use property MUST specify one or more terms of use policies under which the creator issued the credential or presentation. If the recipient (a holder or verifier) is not willing to adhere to the specified terms of use, then they do so on their own responsibility and might incur legal Liability if they violate the stated terms of use. Each terms-Of-Use value MUST specify its type, for example, IssuerPolicy, and MAY specify its instance id. The precise contents of each term of use is determined by the specific terms-Of-Use type definition.

5.7 Evidence

Evidence can be included by an issuer to provide the verifier with additional supporting information in a verifiable credential. This could be used by the verifier to establish the confidence with which it relies on the claims in the verifiable credential. (It is unclear what use will be made of this. It has the potential for being of use once an ontology of evidence is created.)

evidence
The value of the evidence property MUST be one or more evidence schemes providing enough information for a verifier to determine whether the evidence gathered by the issuer meets its confidence requirements for relying on the credential. Each evidence scheme is identified by its type. The id property is optional, but if present, SHOULD contain a URL that points to where more information about this instance of evidence can be found. The precise content of each evidence scheme is determined by the specific evidence type definition.

5.8 Zero-Knowledge Proofs

(An interesting concept that may become useful one day. It can be ignored for the present.)

References