Proof Purpose Validation

Overview

Proof Purpose Validation ensures that proofs in verifiable credentials are used only for their intended purposes as defined in the DID Document’s verification relationships. This is a critical security feature that prevents misuse of verification methods.

Key Concepts

Proof Purpose

A proof purpose indicates why a proof was created. Common proof purposes include:

  • assertionMethod: For signing verifiable credentials
  • authentication: For authenticating the DID controller
  • keyAgreement: For establishing secure channels
  • capabilityInvocation: For invoking capabilities
  • capabilityDelegation: For delegating capabilities

Verification Relationships

Each proof purpose corresponds to a verification relationship in the DID Document:

  • assertionMethod → assertionMethod relationship
  • authentication → authentication relationship
  • keyAgreement → keyAgreement relationship
  • capabilityInvocation → capabilityInvocation relationship
  • capabilityDelegation → capabilityDelegation relationship

Verification Method Matching

The proof’s verificationMethod must be listed in the corresponding verification relationship of the issuer’s DID Document.

Usage

Basic Validation 

1
2
3
4
5
6
7
8
9
10

import org.trustweave.credential.results.VerificationResult

when (val result = trustWeave.verify {
    credential(credential)
    validateProofPurpose()
}) {
    is VerificationResult.Valid -> println("Proof purpose and other checks passed")
    is VerificationResult.Invalid.InvalidProof -> println("Proof issue: ${result.reason}")
    else -> println(result.allErrors.joinToString())
}

Complete Verification Example 

1
2
3
4
5
6
7
8
9
10
11
12

import org.trustweave.credential.results.VerificationResult

val registry = trustWeave.configuration.trustRegistry
when (val result = trustWeave.verify {
    credential(credential)
    validateProofPurpose()
    checkExpiration()
    registry?.let { requireTrust(it) }
}) {
    is VerificationResult.Valid -> println("Verification succeeded")
    is VerificationResult.Invalid -> println(result.allErrors.joinToString())
}

Proof Purposes

assertionMethod

Used for signing verifiable credentials. The verification method must be in the issuer’s assertionMethod list.

1
2
3
4
5
6
7
8
9
10

// DID Document must have:
{
  "assertionMethod": ["did:key:issuer#key-1"]
}

// Proof must have:
{
  "proofPurpose": "assertionMethod",
  "verificationMethod": "did:key:issuer#key-1"
}

authentication

Used for authenticating the DID controller. The verification method must be in the DID’s authentication list.

1
2
3
4
5
6
7
8
9
10

// DID Document must have:
{
  "authentication": ["did:key:user#key-1"]
}

// Proof must have:
{
  "proofPurpose": "authentication",
  "verificationMethod": "did:key:user#key-1"
}

keyAgreement

Used for establishing secure channels. The verification method must be in the DID’s keyAgreement list.

1
2
3
4
5
6
7
8
9
10

// DID Document must have:
{
  "keyAgreement": ["did:key:user#key-1"]
}

// Proof must have:
{
  "proofPurpose": "keyAgreement",
  "verificationMethod": "did:key:user#key-1"
}

capabilityInvocation

Used for invoking capabilities on behalf of the DID. The verification method must be in the DID’s capabilityInvocation list.

1
2
3
4
5
6
7
8
9
10

// DID Document must have:
{
  "capabilityInvocation": ["did:key:user#key-1"]
}

// Proof must have:
{
  "proofPurpose": "capabilityInvocation",
  "verificationMethod": "did:key:user#key-1"
}

capabilityDelegation

Used for delegating capabilities to other DIDs. The verification method must be in the DID’s capabilityDelegation list.

1
2
3
4
5
6
7
8
9
10

// DID Document must have:
{
  "capabilityDelegation": ["did:key:delegator#key-1"]
}

// Proof must have:
{
  "proofPurpose": "capabilityDelegation",
  "verificationMethod": "did:key:delegator#key-1"
}

Verification Method References

Full DID URLs 

1
2

// Full DID URL
"did:key:issuer#key-1"

Relative References 

1
2

// Relative reference (resolved relative to issuer DID)
"#key-1" // Resolves to "did:key:issuer#key-1"

Matching Logic

The validator matches verification methods using:

  1. Exact match (full DID URL)
  2. Relative reference match (resolved relative to issuer DID)
  3. Fragment-only match (e.g., #key-1 matches did:key:issuer#key-1)

Examples

Proof-purpose validation is invoked via validateProofPurpose() on the VerificationBuilder DSL (see “Basic Validation” above). There is no public standalone validator.validateProofPurpose(...) entry point. The cases below show which DID-document / proof combinations pass or fail that check.

Valid Proof Purpose

DID document and proof that satisfy validateProofPurpose():

1
2
3
4
5

// did:key:issuer DID document
{
  "id": "did:key:issuer",
  "assertionMethod": ["did:key:issuer#key-1"]
}

1
2
3
4
5

// proof on the issued credential
{
  "proofPurpose": "assertionMethod",
  "verificationMethod": "did:key:issuer#key-1"
}

validateProofPurpose() succeeds: the proof’s verificationMethod appears in the issuer DID document’s assertionMethod relationship.

Invalid Proof Purpose

Same key, but the proof claims capabilityInvocation — a relationship the key is not listed under:

1
2
3
4
5

{
  "id": "did:key:issuer",
  "assertionMethod":      ["did:key:issuer#key-1"],
  "capabilityInvocation": []
}

1
2
3
4

{
  "proofPurpose": "capabilityInvocation",
  "verificationMethod": "did:key:issuer#key-1"
}

validateProofPurpose() fails. In code, the surrounding trustWeave.verify { ... } call returns a VerificationResult.Invalid.InvalidProof whose reason references the missing verification relationship.

Best Practices

  1. Always Enable Validation: Enable proof purpose validation in production
  2. Update DID Documents: Keep DID documents up-to-date with correct verification relationships
  3. Use Correct Purposes: Use the appropriate proof purpose for each operation
  4. Verify Before Issuing: Ensure issuer DID document has correct relationships before issuing credentials
  5. Monitor Validation Failures: Track proof purpose validation failures to identify issues

Error Messages

Common validation errors:

  • Unknown proof purpose: Proof purpose is not recognized
  • Verification method not found: Verification method doesn’t exist in DID Document
  • Proof purpose mismatch: Proof purpose doesn’t match verification relationship
  • DID resolution failed: Cannot resolve issuer DID

Integration with Credential Verification

Proof purpose validation is automatically performed when enabled in credential verification:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

import org.trustweave.credential.results.VerificationResult

when (val result = trustWeave.verify {
    credential(credential)
    validateProofPurpose()
    checkExpiration()
    trustWeave.configuration.trustRegistry?.let { requireTrust(it) }
}) {
    is VerificationResult.Valid -> { }
    is VerificationResult.Invalid.InvalidProof -> {
        println("Proof purpose or signature issue: ${result.reason}")
    }
    else -> result.allErrors.forEach { println("  - $it") }
}

See Also

This site uses Just the Docs, a documentation theme for Jekyll.