This document describes the Security Vocabulary, i.e., the vocabulary used to ensure the authenticity and integrity of Verifiable Credentials and similar types of constrained digital documents using cryptography, especially through the use of digital signatures and related mathematical proofs .

Alternate versions of the vocabulary definition exist in Turtle and JSON-LD.

Published:
Version Info:
2.0
See Also: https://www.w3.org/TR/vc-data-integrity/

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

Specification of terms

In general, the terms — i.e., the properties and classes — used in the VCDM are formally specified in Recommendation Track documents published by the W3C Verifiable Credentials Working Group or, for some deprecated or reserved terms, in Reports published by the W3C Credentials Community Group. In each case of such external definition, the term's description in this document contains a link to the relevant specification. Additionally, the `rdfs:definedBy` property in the RDFS representation(s) refers to the formal specification.

In some cases, a local explanation is necessary to complement, or to replace, the definition found in an external specification. For instance, this is so when the term is needed to provide a consistent structure to the RDFS vocabulary, such as when the term defines a common supertype for class instances that are used as objects of specific properties, or when RDF Graphs are involved. For such cases, the extra definition is included in the current document (and the `rdfs:comment` property is used to include them in the RDFS representations).

Overview diagram of the vocabulary (without the reserved and deprecated items, error codes, and `xsd` datatypes).
A separate, stand-alone SVG version of the diagram, as well as a textual description, are also available.

Namespaces

This specification makes use of the following namespaces:

sec
https://w3id.org/security#
cred
https://www.w3.org/2018/credentials#
dc
http://purl.org/dc/terms/
owl
http://www.w3.org/2002/07/owl#
rdf
http://www.w3.org/1999/02/22-rdf-syntax-ns#
rdfs
http://www.w3.org/2000/01/rdf-schema#
xsd
http://www.w3.org/2001/XMLSchema#
vs
http://www.w3.org/2003/06/sw-vocab-status/ns#

Regular terms

Class definitions

The following are class definitions in the sec namespace.

Proof

Digital proof

See the formal definition of the term.

This class represents a digital proof on serialized data.
stable
Range of:
previousProof
Domain of:
domain, challenge, previousProof, proofPurpose, proofValue, created, nonce
In the domain of:
expiration

ProofGraph

An RDF Graph for a digital proof

Instances of this class are RDF Graphs [[RDF12-CONCEPTS]], where each of these graphs must include exactly one Proof instance.
stable
Range of:
proof

VerificationMethod

Verification method

See the formal definition of the term.

stable
Range of:
verificationMethod, authentication, assertionMethod, capabilityDelegation, capabilityInvocation, keyAgreement
Domain of:
controller, revoked
In the domain of:
expiration

DataIntegrityProof

A Data Integrity Proof

See the formal definition of the term.

stable
Subclass of:
Proof
Domain of:
cryptosuite

Multikey

Multikey Verification Method

See the formal definition of the term.

See also:
EdDSA Cryptosuite v2022
stable
Subclass of:
VerificationMethod
Domain of:
publicKeyMultibase, secretKeyMultibase

JsonWebKey

JSON Web Key Verification Method

See the formal definition of the term.

stable
Subclass of:
VerificationMethod
Domain of:
publicKeyJwk, secretKeyJwk

Ed25519VerificationKey2020

ED2559 Verification Key, 2020 version

See the formal definition of the term.

stable
Subclass of:
VerificationMethod

Ed25519Signature2020

Ed25519 Signature Suite, 2020 version

See the formal definition of the term.

stable
Subclass of:
Proof

ProcessingError

Processing error

See the formal definition of the term.

stable

Property definitions

The following are property definitions in the sec namespace.

verificationMethod

Verification method

See the formal definition of the term.

See also:
Decentralized Identifiers (DIDs) v1.0
stable
Range:
VerificationMethod

controller

Controller

See the formal definition of the term.

The property's value should be a URL, i.e., not a literal.

stable
Domain:
VerificationMethod

proof

Proof sets

See the formal definition of the term.

stable
Range:
ProofGraph

domain

Domain of a proof

See the formal definition of the term.

stable
Range:
xsd:string
Domain:
Proof

challenge

Challenge of a proof

See the formal definition of the term.

stable
Range:
xsd:string
Domain:
Proof

previousProof

Previous proof

See the formal definition of the term.

stable
Range:
Proof
Domain:
Proof

proofPurpose

Proof purpose

See the formal definition of the term.

stable
Range:
xsd:string
Domain:
Proof

proofValue

Proof value

See the formal definition of the term.

stable
Range:
multibase
Domain:
Proof

created

Proof creation time

See the formal definition of the term.

stable
Range:
xsd:dateTime
Domain:
Proof

expiration

Expiration time for a proof or verification method

See the formal definition of the term.

Historically, this property has often been expressed using `expires` as a shortened term in JSON-LD. Since this shortened term and its mapping to this property are in significant use in the ecosystem, the inconsistency between the short term name (`expires`) and the property identifier (`...#expiration`) is expected and should not trigger an error.
stable
Range:
xsd:dateTime
Domain:
Union of:
Proof
VerificationMethod

nonce

Nonce supplied by proof creator

See the formal definition of the term.

stable
Range:
xsd:string
Domain:
Proof

authentication

Authentication method

See the formal definition of the term.

stable
Range:
VerificationMethod

assertionMethod

Assertion method

See the formal definition of the term.

stable
Range:
VerificationMethod

capabilityDelegation

Capability delegation method

See the formal definition of the term.

stable
Range:
VerificationMethod

capabilityInvocation

Capability invocation method

See the formal definition of the term.

stable
Range:
VerificationMethod

keyAgreement

Key agreement protocols

See the formal definition of the term.

stable
Range:
VerificationMethod

cryptosuite

Cryptographic suite

See the formal definition of the term.

stable
Range:
cryptosuiteString
Domain:
DataIntegrityProof

publicKeyMultibase

Public key multibase

See the formal definition of the term.

See also:
multibase
multicodec
ed25519-2020
stable
Range:
multibase
Domain:
Multikey

secretKeyMultibase

Secret key multibase

See the formal definition of the term.

See also:
multibase format
multicodec format
ed25519-2020
stable
Range:
multibase
Domain:
Multikey

publicKeyJwk

Public key JWK

See the formal definition of the term.

See also:
IANA JOSE
RFC 7517
stable
Range:
rdf:JSON
Domain:
JsonWebKey

secretKeyJwk

Secret key JWK

See the formal definition of the term.

See also:
IANA JOSE
RFC 7517
stable
Range:
rdf:JSON
Domain:
JsonWebKey

revoked

Revocation time

See the formal definition of the term.

stable
Range:
xsd:dateTime
Domain:
VerificationMethod

digestMultibase

Digest multibase

See the formal definition of the term.

(Feature at Risk) The Working Group is currently attempting to determine whether cryptographic hash expression formats can be unified across all of the VCWG core specifications. Candidates for this mechanism include `digestSRI` and `digestMultibase`.
stable
Range:
multibase

Datatype definitions

The following are datatype definitions in the sec namespace.

cryptosuiteString

Datatype for cryptosuite Identifiers

See the formal definition of the term.

stable
Derived from:
xsd:string
Range of:
cryptosuite

multibase

Datatype for multibase values

See the formal definition of the term.

stable
Derived from:
xsd:string
Range of:
proofValue, publicKeyMultibase, secretKeyMultibase, digestMultibase

Definitions for individuals

The following are definitions for individuals in the sec namespace.

PROOF_GENERATION_ERROR

Proof generation error

See the formal definition of the term.

stable
Type
ProcessingError

MALFORMED_PROOF_ERROR

Malformed proof

See the formal definition of the term.

stable
Type
ProcessingError

MISMATCHED_PROOF_PURPOSE_ERROR

Mismatched proof purpose

See the formal definition of the term.

stable
Type
ProcessingError

INVALID_DOMAIN_ERROR

Invalid proof domain

See the formal definition of the term.

stable
Type
ProcessingError

INVALID_CHALLENGE_ERROR

Invalid challenge

See the formal definition of the term.

stable
Type
ProcessingError

INVALID_VERIFICATION_METHOD_URL

Invalid verification method URL

See the formal definition of the term.

stable
Type
ProcessingError

INVALID_CONTROLLER_DOCUMENT_ID

Invalid controller document id

See the formal definition of the term.

stable
Type
ProcessingError

INVALID_CONTROLLER_DOCUMENT

Invalid controller document

See the formal definition of the term.

stable
Type
ProcessingError

INVALID_VERIFICATION_METHOD

Invalid verification method

See the formal definition of the term.

stable
Type
ProcessingError

INVALID_PROOF_PURPOSE_FOR_VERIFICATION_METHOD

Invalid proof purpose for verification method

See the formal definition of the term.

stable
Type
ProcessingError

Reserved terms

All terms in this section are reserved. Implementers may use these properties, but should expect them and/or their meanings to change during the process to normatively specify them.

Reserved properties

The following are reserved property definitions in the sec namespace.

allowedAction

Allowed action (reserved)

See the formal definition of the term.

reserved

capabilityChain

Capability chain (reserved)

See the formal definition of the term.

reserved

capabilityAction

Capability action (reserved)

See the formal definition of the term.

reserved

caveat

Caveat (reserved)

See the formal definition of the term.

reserved

delegator

Delegator (reserved)

See the formal definition of the term.

reserved

invocationTarget

Invocation target (reserved)

See the formal definition of the term.

reserved

invoker

Invoker (reserved)

See the formal definition of the term.

reserved

Deprecated terms

All terms in this section are deprecated, and are only kept in this vocabulary for backward compatibility.

New applications should not use them.

Deprecated classes

The following are deprecated class definitions in the sec namespace.

Key

Cryptographic key (deprecated)

This class represents a cryptographic key that may be used for encryption, decryption, or digitally signing data. This class serves as a supertype for specific key types.
deprecatedtrue

EcdsaSecp256k1Signature2019

ecdsa-sep256k1, 2019 version (deprecated)

See the formal definition of the term.

deprecatedtrue

EcdsaSecp256k1Signature2020

ecdsa-sep256k1, 2020 version (deprecated)

See the formal definition of the term.

deprecatedtrue

EcdsaSecp256k1VerificationKey2019

ecdsa-secp256k1 verification key, 2019 version (deprecated)

See the formal definition of the term.

deprecatedtrue
Subclass of:
Key

EcdsaSecp256k1RecoverySignature2020

ecdsa-secp256k1 recovery signature, 2020 version (deprecated)

See the formal definition of the term.

deprecatedtrue

EcdsaSecp256k1RecoveryMethod2020

ecdsa-secp256k1 recovery method, 2020 version (deprecated)

See the formal definition of the term.

deprecatedtrue

MerkleProof2019

Merkle Proof (deprecated)

See the formal definition of the term.

deprecatedtrue

X25519KeyAgreementKey2019

X25519 Key Agreement Key, 2019 version (deprecated)

See the formal definition of the term.

deprecatedtrue

Ed25519VerificationKey2018

ED2559 Verification Key, 2018 version (deprecated)

See the formal definition of the term.

deprecatedtrue

JsonWebKey2020

JSON Web Key, 2020 version (deprecated)

See the formal definition of the term.

A linked data proof suite verification method type used with `JsonWebSignature2020`
deprecatedtrue

JsonWebSignature2020

JSON Web Signature, 2020 version (deprecated)

See the formal definition of the term.

deprecatedtrue

BbsBlsSignature2020

BBS Signature, 2020 version (deprecated)

See the formal definition of the term.

deprecatedtrue

BbsBlsSignatureProof2020

BBS Signature Proof, 2020 version (deprecated)

See the formal definition of the term.

deprecatedtrue

Bls12381G1Key2020

BLS 12381 G1 Signature Key, 2020 version (deprecated)

See the formal definition of the term.

deprecatedtrue

Bls12381G2Key2020

BLS 12381 G2 Signature Key, 2020 version (deprecated)

See the formal definition of the term.

deprecatedtrue

Deprecated properties

The following are deprecated property definitions in the sec namespace.

blockchainAccountId

Blockchain account ID (deprecated)

See the formal definition of the term.

deprecatedtrue
Range:
xsd:string

ethereumAddress

Ethereum address (deprecated)

See the formal definition of the term.

See also:
EIP-55
Ethereum Yellow Paper: Ethereum: a secure decentralised generalised transaction ledger
deprecatedtrue
Range:
xsd:string

publicKeyBase58

Base58-encoded Public Key (deprecated)

See the formal definition of the term.

deprecatedtrue
Range:
xsd:string

publicKeyPem

Public key PEM (deprecated)

See the formal definition of the term.

deprecatedtrue
Range:
xsd:string

publicKeyHex

Hex-encoded version of public Key (deprecated)

See the formal definition of the term.

See also:
rfc4648
deprecatedtrue
Range:
xsd:string

jws

Json Web Signature (deprecated)

See the formal definition of the term.

See also:
Detached JSON Web Signature
deprecatedtrue

Diagram description

Overview diagram of the vocabulary (without the reserved and deprecated items, error codes, and `xsd` datatypes).

The diagram uses boxes, ellipses, and connecting lines with different "styles" (border color, end marker, line type) to differentiate their semantic meaning; these styles identify Property, Class, or Datatype, via the shapes used for the graph nodes, and Superclass, Domain Of, Range, or Contains, via the styles of the connecting lines. These style names are used in the explanation text that follows, below.

The diagram is roughly divided into left and right sections (although there are some common nodes; see later). To make this description easier to understand, these will be referred to as the "Proof Section" and the "Verification Section". Each of these sections has an ellipse at the top, styled as Class, and respectively labeled as "Proof" and "VerificationMethod".

Proof Section

The left side of the Proof Section contains another ellipse, styled as Class and labeled as "ProofGraph", and connected to the ellipse labeled as "Proof" with a connecting line styled as Contains. There is also a box, styled as Property and labeled as "proof", connected to the ellipse labeled as "ProofGraph" with a connecting line styled as Range.

There are two more ellipses in this section, styled as Class and labeled as "Ed25519Signature2020" and "DataIntegrityProof", each connected to the ellipse labeled as "Proof" with connecting lines styled as Superclass. The ellipse labeled as "DataIntegrityProof" is also connected to a box styled as Property, and labeled as "cryptosuite", with a connecting line styled as Domain Of. The "cryptosuite" Property box is connected to a shape styled as Datatype and labeled as "cryptosuiteString", with a connecting line styled as Range.

The right side of the Section contains a column of labeled boxes, all styled as Property. The labels, from top to bottom, are "previousProof", "domain", "challenge", "proofPurpose", "nonce", "created", "proofValue". The ellipse labeled as "Proof" is connected to all of these with connecting lines styled as Domain Of. The box labeled as "previousProof" is also connected to the ellipse labeled as "Proof" with a connecting line styled as Range. The box labeled as "proofValue" is connected to a shape styled as Datatype and labeled as "multibase", with a connecting line styled as Range. Finally, another box, styled as Property and labeled as "digestMultibase", is connected to the same "multibase" Datatype shape with a connecting line styled as Range.

VerificationMethod Section

The right side of this Section contains a column of labeled boxes, all styled as Property. The labels, from top to bottom, are "verificationMethod", "authentication", "assertionMethod", "capabilityDelegation", "capabilityInvocation", and "keyAgreement". Each of these boxes is connected to the ellipse labeled "VerificationMethod", with a connecting line styled as Range.

The left side of this Section contains a column of three labeled boxes, all styled as Property. The labels, from top to bottom, are "expires", "controller", and "revoked". Each of these is connected to the ellipse labeled "VerificationMethod", with connecting lines styled as Domain Of. The "expires" Property box is also connected to the ellipse labeled "Proof" in the Proof Section, with a connecting line styled as Domain Of.

The middle of this section contains three ellipses, styled as Class, and labeled as "Multikey, "Ed25519VerificationKey2020", and "JsonWebKey". Each of these is connected to the ellipse labeled as "VerificationMethod" with a connecting line styled as Superclass.

Two boxes, styled as Property and labeled as "secretKeyMultibase" and "publicKeyMultibase", are connected to the ellipse labeled as "Multikey" with a connecting line styled as Domain Of. Each of these boxes is also connected to the shape in the Proof section styled as Datatype and labeled as "multibase", with connecting lines styled as Range.

Finally, two boxes, styled as Property and labeled "secretKeyJwk" and "publicKeyJwk", are connected to the ellipse labeled "JsonWebKey" with a connecting line styled as Domain Of. Each of these boxes is also connected to a shape styled as Datatype and labeled as "rdf:JSON", with connecting lines styled as Range.