HomeW3C VCDMSecuring Mechanisms

Securing Mechanisms

How credentials are cryptographically secured using embedded proofs (Data Integrity) or enveloping proofs (JWT, SD-JWT, COSE).

Two Approaches to Securing

VCDM 2.0 supports two fundamentally different approaches to cryptographically securing credentials: embedded proofs and enveloping proofs.

Loading diagram...

Embedded Proof

The proof is included as a proof property inside the credential JSON-LD. Uses Data Integrity specification.

Enveloping Proof

The credential is wrapped in a signed envelope (JWT, SD-JWT, or COSE). The signature covers the entire payload.

JWT Format (vc+jwt)

The most widely adopted format. A JWT consists of three Base64URL-encoded parts separated by dots: Header, Payload, and Signature.

Loading diagram...

JWT Header

Contains algorithm, type, and key identifier.

Header (decoded)

{
  "alg": "ES256",
  "typ": "vc+jwt",
  "kid": "did:example:issuer#key-1"
}

alg

Signing algorithm (ES256, EdDSA, RS256)

typ

Token type, must be "vc+jwt"

kid

Key ID for verification

JWT Payload

Contains standard JWT claims plus the credential in the vc claim.

Payload (decoded)

{
  "iss": "did:example:issuer",
  "sub": "did:example:holder",
  "iat": 1704067200,
  "exp": 1735689600,
  "nbf": 1704067200,
  "jti": "urn:uuid:3978344f-8596-4c3a-a978-8fcaba3903c5",
  "vc": {
    "@context": [
      "https://www.w3.org/ns/credentials/v2"
    ],
    "type": ["VerifiableCredential", "UniversityDegreeCredential"],
    "credentialSubject": {
      "degree": {
        "type": "BachelorDegree",
        "name": "Bachelor of Computer Science"
      }
    }
  }
}

JWT Claims in Detail

When using JWT format, certain claims have specific meanings and map to VCDM properties.

Claim	Name	Required	Purpose
iss	Issuer	Required	DID or URL of the credential issuer. Maps to VC issuer property.
sub	Subject	Optional	DID of the credential subject. Maps to credentialSubject.id.
iat	Issued At	Required	Unix timestamp when the JWT was issued.
exp	Expiration	Optional	Unix timestamp after which the credential is invalid. Maps to validUntil.
nbf	Not Before	Optional	Unix timestamp before which the credential is invalid. Maps to validFrom.
jti	JWT ID	Optional	Unique identifier for the JWT. Maps to credential id.
vc	Credential	Required	The verifiable credential object (without issuer, validFrom/Until, id).

Claim Duplication

Properties like issuer and validFrom appear both in the outer JWT claims (iss, nbf) and may appear in the vc object. The JWT claims take precedence for processing.

SD-JWT (Selective Disclosure)

SD-JWT extends JWT to enable selective disclosure. The issuer creates a JWT with hashed claims, and provides separate disclosures that the holder can choose to reveal.

Loading diagram...

How SD-JWT Works

1Issuer replaces disclosable claims with hash digests in the JWT
2Each original claim value is encoded as a Disclosure (Base64URL of [salt, name, value])
3Holder receives JWT + all Disclosures
4When presenting, holder includes only the Disclosures they want to reveal
5Verifier hashes received Disclosures and matches against JWT digests

Disclosure Format

Base64URL([salt, "claimName", claimValue])

The salt ensures each disclosure is unique even for identical values.

Key Binding JWT

Optional KB-JWT proves the holder possesses the key bound to the credential. Prevents credential theft.

Data Integrity Proofs

Data Integrity adds a proof property directly to the credential JSON-LD. This approach preserves the native JSON-LD structure.

Embedded Proof Example

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://w3id.org/security/data-integrity/v2"
  ],
  "type": ["VerifiableCredential"],
  "issuer": "did:example:issuer",
  "credentialSubject": {
    "id": "did:example:holder",
    "name": "Alice"
  },
  "proof": {
    "type": "DataIntegrityProof",
    "cryptosuite": "ecdsa-rdfc-2019",
    "created": "2024-01-15T10:30:00Z",
    "verificationMethod": "did:example:issuer#key-1",
    "proofPurpose": "assertionMethod",
    "proofValue": "z58DAdFfa9SkqZMVPxAQpic7n..."
  }
}

Proof Properties

type: DataIntegrityProof
cryptosuite: Algorithm suite (ecdsa-rdfc-2019, eddsa-rdfc-2022)
verificationMethod: DID URL of the public key
proofPurpose: assertionMethod, authentication, etc.

Common Cryptosuites

ecdsa-rdfc-2019 - ECDSA with P-256/P-384
eddsa-rdfc-2022 - EdDSA with Ed25519
ecdsa-sd-2023 - ECDSA with selective disclosure
bbs-2023 - BBS+ signatures for ZKP

Security Considerations

Proper algorithm selection and key management are critical for credential security.

Algorithm Selection

Key Management

Signature Verification

Always verify the full certificate chain and check for revocation. A valid signature alone does not guarantee the issuer is trusted for the credential type.

Choosing a Proof Format

Each format has trade-offs. Your choice depends on privacy requirements, ecosystem compatibility, and implementation constraints.

JWT (vc+jwt)

JSON Web Token format. Compact, widely supported.

Advantages

Compact representation
Wide library support
Familiar to developers

Disadvantages

All-or-nothing disclosure
No selective disclosure natively

SD-JWT

Selective Disclosure JWT. Extends JWT with selective disclosure.

Advantages

Selective disclosure
Based on JWT
Privacy-preserving

Disadvantages

More complex
Larger payload
Newer standard

Data Integrity

Embedded proof using Linked Data Signatures.

Advantages

Native JSON-LD
Multiple proofs possible
Rich metadata

Disadvantages

Larger payload
JSON-LD processing required
Less compact

Claims & Subjects Presentations