• Message forwarding: Routing KERI messages through intermediary agents or controllers while preserving verifiable signatures on specific message components
• Embedded message handling: Processing messages contained within other messages (e.g., exn exchange messages, rpy reply messages, exp exposition events)
• Selective component verification: Verifying signatures on message substructures without requiring access to or verification of the entire message envelope

Key Participants

The pathing process involves:

• Signer: Entity creating cryptographic signatures on specific SAD portions identified by paths
• Path Specifier: Component generating SAD path expressions that identify signature scope
• Verifier: Entity validating signatures by resolving paths to extract the signed content
• Message Forwarder: Intermediary that may transpose signature attachments by updating path references when embedding SADs in new envelopes

Design Philosophy Note

A critical architectural principle in KERI: credentials themselves are not directly signed. The KERI approach verifies ACDC credentials through their cryptographic binding to the issuer's Key Event Log (KEL) rather than through traditional direct signatures on credential documents. Authenticity derives from the verifiable chain of key events in the KEL, not from signing credential content directly. This explains why pathing, despite being designed for credential signing, is not used for that purpose in practice.

Process Flow

Step 1: Path Expression Construction

The process begins with constructing a SAD Path Language expression that identifies the target content within a SAD structure. The path language uses these rules:

Syntax Components:

• Root indicator: Single - character represents the entire SAD
• Path separator: - character delimits path components
• Field labels: Base64-safe strings identifying map fields
• Integer indices: Numeric values indexing into arrays or map field positions
• Context-dependent interpretation: Integers reference array elements or map fields based on context

Path Construction Rules:

1. All paths begin with root - indicator
2. First component after root is always a map field (in ACDC/KERI contexts)
3. Subsequent components navigate nested structures
4. Integer indices can reference array positions or map field ordinal positions
5. No wildcards or pattern matching - paths must be fully specified

Example Path Expressions:

-                    # Root (entire SAD)
-a-personal          # Nested personal information map
-4-5                 # Same location using field indices
-a-personal-legalName # Specific field value
-p-1                 # Second element in credential chain array
-a-LEI               # Legal Entity Identifier field

Step 2: Content Extraction

Once the path is specified, the signing process extracts the referenced content:

1. Parse the SAD structure: Deserialize the SAD from its serialization format (JSON, CBOR, or MessagePack)
2. Traverse the path: Navigate through the data structure following each path component
3. Extract target content: Retrieve the value at the path terminus
4. Serialize for signing: Convert the extracted content to canonical serialization form

Critical Constraint: KERI and ACDC require deterministic field ordering in map structures. This enables integer-based indexing where field positions are predictable and stable across serializations.

Step 3: Signature Generation

The extracted content undergoes cryptographic signing:

1. Digest computation: Generate cryptographic digest of the serialized content using the specified hash algorithm (typically Blake3-256 in KERI)
2. Signature creation: Apply the signing key to produce a digital signature over the digest
3. CESR encoding: Encode the signature as a CESR primitive with appropriate derivation code indicating signature algorithm
4. Path attachment: Associate the path expression with the signature in the CESR proof structure

Step 4: Signature Attachment

The signature and path are attached to the SAD using CESR Proof Signatures format:

Attachment Structure:

-SAD-<path>-<signature_primitive>

Where:

• -SAD- is the CESR proof signature framing code
• <path> is the SAD path expression
• <signature_primitive> is the CESR-encoded signature

Multiple Signatures: A single SAD can have multiple signature attachments, each with its own path specifying different signed portions.

Step 5: Verification Process

Verification reverses the signing process:

1. Parse attachment: Extract path and signature from CESR proof structure
2. Resolve path: Navigate the SAD structure using the path expression
3. Extract content: Retrieve the content at the specified path
4. Recompute digest: Generate digest of the extracted content
5. Verify signature: Validate the signature against the digest using the signer's public key
6. Check binding: Verify the signer's AID (Autonomic Identifier) is authorized for this signing operation

Step 6: Transposition (Optional)

When a signed SAD is embedded in a new envelope, signature transposition updates path references:

1. Identify embedding context: Determine the new path to the embedded SAD within the envelope
2. Update path prefix: Prepend the embedding path to existing signature paths
3. Preserve signature: Keep the signature primitive unchanged
4. Reattach: Associate the updated path with the signature in the new envelope's CESR proof structure

Example Transposition:

• Original path in standalone SAD: -a-personal-legalName
• SAD embedded at path -e-acdc in envelope
• Transposed path: -e-acdc-a-personal-legalName
• Signature remains cryptographically valid because it was computed over the content, not the path

Technical Requirements

Cryptographic Requirements

Hash Algorithm Constraints:

• Must use cryptographically strong hash functions (KERI typically uses Blake3-256)
• Hash algorithm must be specified in CESR derivation code
• Digest length must align with CESR 24-bit boundary requirements

Signature Algorithm Support:

• Ed25519 (most common in KERI)
• ECDSA with secp256k1 or secp256r1
• Post-quantum algorithms (Dilithium, Falcon) for future-proofing
• Algorithm indicated by CESR signature primitive derivation code

Key Management:

• Signing keys must be part of an AID key state
• Key state must be verifiable through KEL or KERL
• Pre-rotation commitments must be honored
• Threshold signatures supported for multi-sig AIDs

Serialization Requirements

Deterministic Ordering:

• Map fields must maintain consistent ordering across serializations
• KERI/ACDC mandate alphabetical field ordering by field label
• This enables integer-based path indexing to be stable

Supported Formats:

• JSON (JavaScript Object Notation) - text domain
• CBOR (Concise Binary Object Representation) - binary domain
• MessagePack (MGPK) - binary domain
• All formats must produce identical semantic content

CESR Compatibility:

• Paths must use only Base64 URL-safe characters: [A-Z, a-z, 0-9, -, _]
• Path expressions must align on 24-bit boundaries for CESR composability
• Signature primitives must be valid CESR-encoded values

Timing Considerations

Signature Freshness:

• Signatures are bound to specific key states in the signer's KEL
• Verification must check that the signing key was authoritative at signature creation time
• Rotation events may invalidate signatures if keys are revoked

Path Resolution Timing:

• Path resolution must occur before signature verification
• Content extraction must use the same serialization format as signing
• Transposition must preserve temporal relationships between signatures

Verification Order:

1. Verify signer's KEL is valid and non-duplicitous
2. Verify signing key was authoritative at signature timestamp
3. Resolve path and extract content
4. Verify signature cryptographically
5. Check authorization policies for the signing operation

Error Handling

Path Resolution Failures:

• Invalid path syntax: Reject malformed path expressions
• Path not found: Handle missing fields or out-of-bounds array indices
• Type mismatches: Detect attempts to index non-indexable structures
• Ambiguous paths: Reject paths that could resolve to multiple locations

Signature Verification Failures:

• Invalid signature: Cryptographic verification fails
• Key not found: Signing key not in signer's key state
• Key revoked: Signing key rotated out before signature timestamp
• Unauthorized signer: Signer lacks authority for this operation

Transposition Errors:

• Path collision: Transposed path conflicts with existing paths
• Invalid embedding: Embedded SAD structure violates envelope constraints
• Signature invalidation: Transposition breaks cryptographic binding

Recovery Strategies:

• Graceful degradation: Verify what can be verified, report what cannot
• Partial verification: Accept signatures on verifiable portions, reject unverifiable
• Audit logging: Record all verification failures for security analysis

Usage Patterns

Message Forwarding (Primary Use Case)

The dominant production use of pathing is forwarding KERI embedded messages through intermediary agents:

Scenario: An agent receives a message intended for another controller and must forward it while preserving signature integrity.

Pattern:

1. Original message signed with path - (root)
2. Agent embeds message in forwarding envelope at path -e-msg
3. Agent transposes signature path to -e-msg-
4. Recipient extracts embedded message and verifies original signature

Benefits:

• Intermediaries cannot forge or modify signed content
• Recipients verify end-to-end authenticity
• Forwarding is transparent to cryptographic verification

Nested Credential References (Design Intent)

Although not used in production, pathing was designed for signing portions of nested ACDC credentials:

Scenario: A credential contains embedded credentials, and different issuers sign different portions.

Pattern:

1. Root credential issuer signs path - (entire structure)
2. Embedded credential issuer signs path -e-0 (first embedded credential)
3. Attribute issuer signs path -a-personal (personal information section)
4. Each signature independently verifiable

Note: This pattern is not recommended in KERI architecture. Credentials should be verified through KEL binding, not direct signatures.

Selective Disclosure Support

Pathing enables selective disclosure by signing individual attributes:

Scenario: Issuer wants to enable holder to disclose attributes independently.

Pattern:

1. Issuer signs each disclosable attribute with its own path
2. Holder discloses only required attributes with their signatures
3. Verifier validates disclosed attributes without seeing undisclosed ones

Example Paths:

• -a-legalName (legal name attribute)
• -a-LEI (Legal Entity Identifier)
• -a-personal-birthDate (birth date in personal section)

Best Practices

Path Design:

• Use field labels for human readability when possible
• Use integer indices only when necessary for non-Base64-safe labels
• Keep paths as short as possible while remaining unambiguous
• Document path conventions in schema definitions

Signature Scope:

• Sign the smallest necessary scope to minimize disclosure
• Avoid signing entire structures when partial signing suffices
• Consider future transposition needs when choosing paths
• Balance granularity against signature overhead

Verification Strategy:

• Verify KEL integrity before signature verification
• Cache verified key states to optimize repeated verifications
• Implement path resolution caching for performance
• Log all verification failures for security monitoring

Transposition Handling:

• Validate transposed paths before accepting
• Verify embedding context matches expected structure
• Preserve original paths in audit logs
• Test transposition logic thoroughly

Integration Considerations

KERI Protocol Integration:

• Pathing is part of CESR Proof Signatures specification
• Integrates with KERI event messages for forwarding
• Compatible with OOBI (Out-Of-Band Introduction) discovery
• Works with IPEX (Issuance and Presentation Exchange) protocol

ACDC Integration:

• Designed for ACDC credential structures
• Supports ACDC edge references
• Compatible with ACDC schema definitions
• Enables ACDC selective disclosure

Implementation Libraries:

• KERIpy: Python reference implementation includes pathing support
• keride: Rust library with pathing capabilities
• KERIox: Rust implementation with CESR support
• cesrox: Extracted CESR logic including path handling

Performance Optimization:

• Path resolution is O(n) in path depth
• Cache parsed SAD structures for repeated operations
• Use integer indices for performance-critical paths
• Batch signature verifications when possible

Current Status and Future Direction

As of 2023, pathing remains a specified but underutilized feature in the KERI ecosystem. Its primary value is in message forwarding infrastructure rather than its original credential signing design intent. The KERI community's architectural decision to verify credentials through KEL binding rather than direct signatures has made the credential use cases less relevant.

Future developments may expand pathing usage if:

• New use cases emerge requiring granular content signing
• Cross-protocol integrations need selective signature verification
• Privacy-preserving disclosure patterns require attribute-level signatures
• Regulatory requirements mandate specific signing granularity

However, the fundamental KERI principle remains: authenticity derives from verifiable key event logs, not from signing data directly. Pathing serves as a supporting mechanism for message handling, not as a primary authentication method.

Performance Optimization:

• Cache verified KEL states (with expiration)
• Cache parsed SAD structures
• Batch signature verifications when possible
• Use parallel verification for multiple signatures
• Implement path resolution caching

Error Handling:

• Distinguish between cryptographic failures and path resolution failures
• Log all verification failures with context
• Implement graceful degradation (verify what can be verified)
• Provide detailed error messages for debugging

Transposition Implementation

Path Update Algorithm:

function transpose_path(original_path, embedding_path):
    # Remove root '-' from original path
    original_components = original_path[1:].split('-')
    # Remove root '-' from embedding path
    embedding_components = embedding_path[1:].split('-')
    # Concatenate: root + embedding + original
    transposed = '-' + '-'.join(embedding_components + original_components)
    return transposed

Validation Requirements:

• Verify embedding path exists in envelope structure
• Check transposed path resolves to same content
• Validate no path collisions with existing signatures
• Preserve original paths in audit logs

Library Integration

KERIpy Integration:

• Use keri.core.coring for CESR primitives
• Use keri.core.eventing for KEL verification
• Use keri.core.signing for signature operations
• Use keri.db.dbing for key state caching

keride/KERIox Integration:

• Leverage Rust's type safety for path validation
• Use serde for SAD serialization
• Implement zero-copy path resolution where possible
• Use rayon for parallel signature verification

Testing Requirements

Path Resolution Tests:

• Valid paths (field labels, integers, nested, arrays)
• Invalid paths (malformed syntax, non-existent fields, out-of-bounds)
• Edge cases (empty paths, very deep nesting, large arrays)
• Performance tests (large SADs, many signatures)

Signature Tests:

• Valid signatures on various path scopes
• Invalid signatures (wrong key, tampered content, expired keys)
• Multiple signatures on same SAD
• Signature transposition scenarios

Integration Tests:

• End-to-end message forwarding
• KEL verification integration
• Multi-format serialization (JSON, CBOR, MessagePack)
• CESR encoding/decoding round-trips

Security Considerations

Path Injection Prevention:

• Validate all path components before resolution
• Reject paths with suspicious patterns
• Implement path length limits
• Sanitize error messages (don't leak structure)

Timing Attack Mitigation:

• Use constant-time comparison for signature verification
• Avoid early returns that leak information
• Implement rate limiting for verification requests

Key State Validation:

• Always verify KEL before trusting signatures
• Check for key rotation events
• Validate witness receipts
• Detect duplicitous KELs

Production Deployment

Current Usage Pattern: Focus implementation effort on message forwarding use case, as this is the primary production usage. Credential signing features should be implemented for completeness but are not currently used in production systems.

Monitoring:

• Log all signature verifications (success and failure)
• Track path resolution performance
• Monitor KEL verification latency
• Alert on verification failure rate increases

Scalability:

• Implement caching at multiple levels (KEL, key state, parsed SADs)
• Use connection pooling for witness queries
• Consider distributed caching for high-volume systems
• Implement backpressure for verification queues