Contractually-protected-disclosure is a disclosure mechanism for ACDCs that combines schema-based mechanical controls with contract-based legal controls to minimize information leakage through graduated revelation, where the discloser progressively reveals credential information only after the disclosee agrees to contractual terms at each stage.
Related Concepts
No related concepts available
Comprehensive Explanation
contractually-protected-disclosure
Process Definition
Contractually-protected-disclosure represents the most elaborate and comprehensive disclosure mechanism available in the IPEX (Issuance and Presentation EXchange) protocol. This process accomplishes the secure, legally-bound exchange of ACDC (Authentic Chained Data Container) credential information through a dual-layer protection framework that combines both mechanical (cryptographic/schema-based) and legal (contract-based) safeguards.
The process is used when credential disclosure requires not only cryptographic verification but also legal accountability and protection against unauthorized correlation or exploitation of disclosed information. This is particularly critical in high-stakes scenarios involving:
Sensitive personal information requiring chain-of-custody protections
Business-to-business data exchanges with contractual obligations
Regulated industries requiring documented consent and terms of use
Cross-jurisdictional credential presentations with varying legal frameworks
Discloser: The entity controlling and executing the contractually-protected disclosure process, who sets the terms and conditions for progressive information revelation
Disclosee: The entity receiving the progressively disclosed information, who must agree to contractual terms before receiving sensitive data contents
Implementation Notes
Critical Implementation Considerations
Schema Management
Schema Versioning: Implement robust schema versioning to handle evolution of credential structures over time. Use SAID-based schema references to ensure immutability.
Schema Validation: Validate all disclosed data against schemas at each stage. JSON Schema validation libraries should be integrated into the disclosure pipeline.
Schema Caching: Cache frequently-used schemas to reduce latency in repeated disclosure operations. Implement cache invalidation based on schema SAID changes.
Contract Handling
Ricardian Contract Parsing: Implement parsers that can extract both human-readable and machine-readable components of Ricardian contracts. The contract structure should support multiple languages for international deployments.
Contract Signature Verification: Always verify contract signatures against the signer's KEL before proceeding with data disclosure. Implement timeout mechanisms for signature verification operations.
Contract Storage: Maintain audit logs of all contract agreements with cryptographic proofs. This is critical for dispute resolution and compliance auditing.
State Management
Disclosure State Tracking: Implement state machines to track disclosure progression through stages (schema disclosed, contract sent, contract agreed, data disclosed). Use persistent storage to handle process interruptions.
Timeout Handling: Implement configurable timeouts for each disclosure stage. Default timeouts should be: schema disclosure (30s), contract review (5 minutes), data disclosure (60s).
Error Recovery: Implement retry mechanisms with exponential backoff for transient failures. Permanent failures should trigger cleanup of partial disclosure state.
Cryptographic Operations
SAID Computation: Use standardized SAID computation libraries (keripy, signify, etc.) to ensure consistency. Never implement custom SAID algorithms.
Signature Verification: Verify all signatures against current KEL state. Implement KEL synchronization mechanisms to ensure up-to-date key state information.
contractually-protected-disclosure - vLEI.wiki | KERI Knowledge Base - vLEI.wiki
Issuer: The original credential issuer whose cryptographic commitments enable verification across all disclosure variants
The process begins with schema-based mechanical protection, where the discloser shares the schema of the data to be disclosed prior to sharing actual data contents. This initial stage:
Schema Transmission: The discloser sends the JSON Schema or schema SAID that defines the structure and format of the credential data
Structure Understanding: The disclosee examines the schema to understand what types of information will be shared, field structures, data types, and validation rules
Capability Assessment: The disclosee determines whether their systems can process the disclosed data format and whether the information meets their verification requirements
No Content Exposure: At this stage, no actual sensitive data contents are revealed—only the structural blueprint
This mechanical protection layer leverages CESR encoding and SAID-based content addressing to ensure schema integrity while maintaining content confidentiality.
Stage 2: Contract Disclosure (Legal Protection)
The second stage introduces contract-based legal protection through Ricardian contracts:
Contract Presentation: The discloser presents legal contracts that must be agreed to before data contents are shared
Terms Review: The disclosee reviews contractual obligations, which may include:
Cryptographic Agreement: The disclosee cryptographically signs the contract using their AID (Autonomic Identifier), creating a non-repudiable commitment
Agreement Verification: The discloser verifies the disclosee's signature against their KEL (Key Event Log) to ensure authentic agreement
Stage 3: Graduated Content Disclosure
Once contractual agreements are cryptographically verified, the process enters graduated-disclosure of actual data contents:
Initial Compact Disclosure: The discloser may begin with compact-disclosure, revealing only SAIDs of field maps rather than full contents
Condition Verification: Before each progressive disclosure step, the discloser verifies that the disclosee has satisfied conditions (contractual agreements, technical capabilities, etc.)
Progressive Revelation: As conditions are met, the discloser progressively reveals more information through:
Cryptographic Binding: Each disclosure stage maintains cryptographic proof chains through CESR-Proofs that verify back to the original issuer's commitment
Stage 4: Downstream Protection
The process includes mechanisms for protecting disclosed information as it moves downstream:
Chain-link-confidentiality: Contractual restrictions bind each recipient in the disclosure chain, creating obligations that extend to all subsequent recipients
Contingent-disclosure: Additional information release remains contingent upon ongoing satisfaction of conditions
Liability Propagation: Legal obligations propagate through the disclosure chain, ensuring downstream recipients inherit protection responsibilities
Technical Requirements
Cryptographic Requirements
Contractually-protected-disclosure depends on several cryptographic primitives and protocols:
SAID Protocol: Self-addressing identifiers provide content-addressable references that enable:
Compact disclosure without revealing content
Cryptographic binding between schemas, contracts, and data
Verification of content integrity across disclosure stages
Verifiable control authority for signing operations
Protocol Requirements
The process operates within the IPEX protocol framework, which requires:
Message Exchange: Structured message flows for schema, contract, and data disclosure
State Management: Tracking of disclosure stages and condition satisfaction
Verification Workflows: Cryptographic verification of signatures, SAIDs, and KEL states
Error Handling: Graceful handling of verification failures, timeout conditions, and protocol violations
Timing Considerations
The process involves several timing-sensitive aspects:
Contract Expiration: Ricardian contracts may include time-bound validity periods
Credential Freshness: Verification of credential issuance dates and expiration
KEL Synchronization: Ensuring all parties have current key state information
Grace Periods: Handling of credential revocation grace periods (typically 90 days in vLEI ecosystem)
Error Handling
Robust error handling addresses:
Schema Validation Failures: When disclosee systems cannot process disclosed schema formats
Contract Rejection: When disclosee declines contractual terms
Signature Verification Failures: When cryptographic proofs fail validation
KEL Inconsistencies: When key state cannot be verified or shows duplicity
Timeout Conditions: When disclosure stages exceed time limits
Revocation Detection: When credentials are discovered to be revoked during disclosure
Usage Patterns
Pattern 1: High-Stakes Credential Presentation
In scenarios requiring maximum privacy protection and legal accountability:
Initial Contact: Discloser and disclosee establish communication channel
Schema Exchange: Discloser shares credential schema to establish data structure expectations
Contract Negotiation: Parties negotiate and agree to contractual terms
Minimal Disclosure: Discloser reveals only compact SAIDs initially
Progressive Trust: As trust develops, more detailed information is revealed
Full Disclosure: Complete data shared only when absolutely necessary
Pattern 2: Regulated Industry Compliance
For industries with strict data protection regulations:
Regulatory Framework: Contracts incorporate specific regulatory requirements (GDPR, HIPAA, etc.)
Audit Trail: All disclosure stages are logged for compliance auditing
Consent Management: Explicit consent captured at each disclosure stage
Data Minimization: Only information required for specific regulatory purposes is disclosed
Retention Policies: Contracts specify data retention and deletion requirements
Pattern 3: Cross-Organizational Data Sharing
For business-to-business credential exchanges:
Organizational Verification: Both parties verify organizational credentials (e.g., vLEI credentials)
Role-Based Disclosure: Contracts specify which organizational roles can access which data
Downstream Controls: Chain-link-confidentiality ensures data protection as it moves through organizational hierarchies
Liability Framework: Clear liability allocation for data breaches or misuse
Best Practices
Schema-First Design: Always disclose schemas before contracts to enable informed consent
Minimal Initial Disclosure: Start with compact disclosure and reveal more only as needed
Clear Contractual Language: Use unambiguous legal language in Ricardian contracts
Cryptographic Verification: Verify all signatures and SAIDs at each stage
State Tracking: Maintain clear records of disclosure stages and condition satisfaction
Timeout Management: Implement reasonable timeouts for each disclosure stage
Revocation Checking: Verify credential status before each disclosure stage
Audit Logging: Log all disclosure events for compliance and dispute resolution
Integration Considerations
KERI Infrastructure: Requires operational witness pools and watcher networks for KEL verification
Registry Integration: Connection to TEL (Transaction Event Log) registries for credential status checking
Schema Repositories: Access to schema registries for schema SAID resolution
Legal Framework: Integration with legal systems for contract enforcement
User Interface: Clear presentation of contractual terms and disclosure stages to end users
Implementation Challenges
Challenge 1: Contextual Linkability Mitigation
Even with contractually-protected-disclosure, contextual-linkability attacks remain a significant threat. The disclosee controls the presentation context and can capture auxiliary data that enables statistical correlation. Mitigation strategies include:
Context Blinding: Minimize contextual metadata captured during disclosure
Temporal Separation: Separate disclosure stages temporally to reduce correlation opportunities
Decoy Interactions: Generate decoy disclosure requests to obscure actual patterns
Legal Recourse: Strong contractual language prohibiting contextual data capture and correlation
Challenge 2: Contract Enforceability
Ricardian contracts provide legal frameworks, but enforcement depends on:
Jurisdictional Clarity: Clear specification of governing law and jurisdiction
Dispute Resolution: Defined mechanisms for resolving contract disputes
Liability Limits: Reasonable liability caps to ensure enforceability
Practical Remedies: Actionable remedies for contract violations
Challenge 3: Performance Optimization
Multi-stage disclosure processes can introduce latency. Optimization strategies include:
Parallel Verification: Verify signatures and SAIDs in parallel where possible
Caching: Cache verified schemas and contracts for repeated interactions
Batch Processing: Batch multiple disclosure requests when appropriate
Asynchronous Operations: Use asynchronous message patterns to avoid blocking
Relationship to Other Disclosure Mechanisms
Contractually-protected-disclosure represents the most elaborate form of disclosure in IPEX, explicitly including both:
Legal Accountability: Contractual frameworks provide recourse for violations
Correlation Resistance: Graduated disclosure and contractual protections minimize exploitable correlation
Governance and Ecosystem Context
Within the vLEI ecosystem governed by GLEIF, contractually-protected-disclosure is particularly relevant for:
ECR Credentials: Engagement Context Role credentials requiring privacy protection
OOR Credentials: Official Organizational Role credentials with sensitive organizational data
Cross-border Presentations: International credential presentations requiring jurisdictional clarity
High-value Transactions: Financial or legal transactions requiring maximum assurance
The vLEI Ecosystem Governance Framework provides additional policies and procedures that complement the technical mechanisms of contractually-protected-disclosure, creating a comprehensive framework for secure, privacy-preserving credential exchange in enterprise and regulatory contexts.
Key Rotation Handling: Account for key rotation events during multi-stage disclosure processes. Verify signatures against the key state at the time of signing, not current state.
Performance Optimization
Parallel Verification: Verify multiple signatures and SAIDs in parallel where possible. Use worker pools or async operations to maximize throughput.
Batch Processing: When disclosing to multiple recipients, batch common operations (schema transmission, contract distribution) to reduce overhead.
Caching Strategy: Implement multi-level caching: schema cache, contract cache, KEL state cache. Use LRU eviction policies with configurable size limits.
Security Hardening
Input Validation: Validate all received data against expected formats before processing. Reject malformed schemas, contracts, or ACDCs immediately.
Rate Limiting: Implement rate limiting on disclosure requests to prevent denial-of-service attacks. Typical limits: 10 requests/minute per AID.
Audit Logging: Log all disclosure events with timestamps, participant AIDs, and disclosure stages. Use append-only logs with cryptographic integrity protection.
Integration Patterns
KERI Infrastructure: Ensure connectivity to witness pools and watcher networks. Implement fallback mechanisms for witness unavailability.
TEL Integration: Connect to transaction event log registries for credential status checking. Implement caching of credential status with configurable TTL (typically 5 minutes).
User Interface: Provide clear visual indicators of disclosure stages to end users. Display contract terms in human-readable format with clear accept/reject options.
Testing Strategies
Unit Tests: Test each disclosure stage independently with mocked dependencies. Verify correct handling of success and failure cases.
Integration Tests: Test complete disclosure workflows across multiple implementations (keripy, signify, etc.) to ensure interoperability.
Security Tests: Test resistance to common attacks: replay attacks, man-in-the-middle, signature forgery, SAID manipulation.
Deployment Considerations
Configuration Management: Externalize configuration for timeouts, retry policies, cache sizes, and rate limits. Use environment-specific configurations.
Monitoring: Implement metrics collection for disclosure success rates, stage durations, and error frequencies. Set up alerts for anomalous patterns.
Scalability: Design for horizontal scalability. Disclosure state should be stored in distributed storage systems (Redis, etc.) rather than in-memory.
Common Pitfalls
Premature Data Disclosure: Never disclose data contents before verifying contract agreement signatures. This is the most critical security requirement.
Insufficient Verification: Always verify KEL state, not just signature validity. A valid signature from a compromised key is still invalid.
State Leakage: Ensure disclosure state is properly cleaned up after completion or failure. Lingering state can lead to information leakage.
Contextual Data Capture: Be aware that even with contractual protections, contextual linkability remains a threat. Minimize metadata capture during disclosure operations.