Loading vLEI.wiki
Fetching knowledge base...
Fetching knowledge base...
This comprehensive explanation has been generated from 19 GitHub source documents. All source documents are searchable here.
Last updated: October 7, 2025
This content is meant to be consumed by AI agents via MCP. Click here to get the MCP configuration.
Note: In rare cases it may contain LLM hallucinations.
For authoritative documentation, please consult the official GLEIF vLEI trainings and the ToIP Glossary.
Contingent disclosure is a privacy-preserving disclosure mechanism within the KERI/ACDC ecosystem that enables conditional, selective revelation of information based on predefined criteria or agreements. Unlike traditional all-or-nothing disclosure patterns, contingent disclosure allows disclosers to reveal only the minimum necessary information to disclosees under specific conditions, maintaining privacy while enabling verifiable data exchange.
The process accomplishes several critical objectives:
Contingent disclosure is used whenever sensitive information must be shared in a controlled manner, particularly in scenarios requiring:
Key participants in contingent disclosure include:
Implementations must support machine-readable condition encoding using Ricardian contracts or equivalent frameworks. Conditions should be:
Correct SAID computation is critical for contingent disclosure security:
Implementations must handle SAID verification for both compact and expanded variants, ensuring integrity across disclosure transitions.
For selective disclosure, implement proper blinding using:
Caching strategies: Cache KEL verification results and TEL revocation states with appropriate TTLs to reduce latency while maintaining security.
Batch verification: When verifying multiple disclosed ACDCs, batch signature verification operations to improve performance.
Lazy evaluation: Defer expensive cryptographic operations until necessary, evaluating conditions in order of computational cost.
Contingent disclosure operates through a multi-stage process that progressively reveals information as conditions are satisfied:
The discloser establishes the conditions under which information will be revealed. These conditions may include:
Conditions are typically encoded using Ricardian contracts or similar machine-readable legal frameworks that can be cryptographically verified.
The disclosee initiates a disclosure request through the IPEX (Issuance and Presentation Exchange) protocol. This request specifies:
The request does not yet trigger actual data disclosure but begins the conditional evaluation process.
The discloser evaluates whether the disclosee meets the established conditions. This evaluation may involve:
If conditions are not met, the disclosure process terminates without revealing sensitive information. If conditions are satisfied, the process advances to selective revelation.
Once conditions are satisfied, the discloser reveals only the specific information required by the disclosee. This selective revelation leverages ACDC graduated disclosure mechanisms:
Compact disclosure: Initially, only SAIDs (Self-Addressing Identifiers) of field maps are disclosed, providing cryptographic commitments without revealing actual content.
Partial disclosure: Selected sections of the ACDC are expanded while others remain as SAID references, enabling verification of specific attributes without full content exposure.
Selective disclosure: Individual attributes are unbundled and disclosed independently, preventing correlation between disclosed and undisclosed attributes through cryptographic blinding techniques.
Full disclosure: Complete field map details are revealed only when all conditions are satisfied and full transparency is required.
The disclosee verifies the disclosed information using CESR-Proof signatures and SAID integrity checks. This verification confirms:
Verification occurs without requiring the discloser to reveal additional information beyond what was conditionally disclosed.
The contingent disclosure process involves several critical state transitions:
Key decision points in the contingent disclosure flow include:
Condition satisfaction check: Does the disclosee meet all established conditions?
Disclosure level determination: What level of detail should be revealed?
Verification outcome: Does disclosed information pass validation?
Contingent disclosure relies on several cryptographic primitives and protocols:
SAID (Self-Addressing Identifier) computation: Each field map in an ACDC must have a correctly computed SAID that serves as a cryptographic commitment to its content. The SAID is computed using a cryptographic digest function (typically Blake3-256) over the canonical serialization of the field map, with the SAID field itself included in the computation.
Digital signatures: All disclosed information must be signed by the issuer's authoritative key pair. Signatures are attached using CESR-Proof format, enabling verification without expanding the entire ACDC structure.
Blinding techniques: For selective disclosure, cryptographic blinding using high-entropy UUIDs (≥128 bits) prevents rainbow table attacks and correlation across different disclosure contexts.
KEL verification: The disclosee must verify the issuer's key state through the Key Event Log, ensuring the signing keys were authoritative at the time of issuance.
TEL checking: For revocable credentials, the Transaction Event Log must be consulted to verify the credential has not been revoked before accepting the disclosure.
Contingent disclosure involves several timing-sensitive operations:
Condition evaluation latency: The time required to evaluate whether conditions are satisfied must be bounded to prevent denial-of-service attacks. Typical implementations should complete condition evaluation within seconds.
Disclosure validity windows: Disclosed information may have temporal validity constraints, requiring the disclosee to verify timestamps and ensure disclosure occurs within acceptable time bounds.
Revocation checking: TEL verification introduces latency as the disclosee must query the registry. Implementations should cache recent revocation states while respecting freshness requirements.
Signature verification performance: Cryptographic signature verification must be efficient enough to support real-time disclosure scenarios. CESR encoding optimizes this through compact representation and efficient parsing.
Robust contingent disclosure implementations must handle various error conditions:
Condition evaluation failures: If conditions cannot be evaluated (e.g., due to network issues accessing required credentials), the disclosure should fail safely without revealing information.
Cryptographic verification failures: Invalid signatures, mismatched SAIDs, or other cryptographic errors must result in disclosure rejection with appropriate error reporting.
Revocation detection: If a credential is discovered to be revoked during disclosure, the process must terminate immediately and the disclosee must be notified.
Malformed disclosure requests: Requests that do not conform to IPEX protocol specifications should be rejected with clear error messages indicating the specific protocol violation.
Timeout handling: Long-running condition evaluations or verification processes should timeout gracefully, allowing retry with exponential backoff.
Age verification without revealing birthdate: A discloser can prove they are over a certain age threshold without revealing their exact birthdate. The ACDC contains the birthdate attribute, but contingent disclosure reveals only a boolean "over_18" derived attribute, with the actual birthdate remaining as a SAID reference.
Professional credential presentation: When applying for a job, a candidate can disclose their degree and institution through selective disclosure while keeping GPA, graduation date, and other details private unless specifically requested and agreed upon through contractually protected disclosure.
Financial qualification: A loan applicant can prove their income exceeds a threshold without revealing exact salary figures. The ACDC contains detailed financial information, but contingent disclosure reveals only the qualification status based on predefined criteria.
Healthcare information sharing: Medical credentials can be disclosed to healthcare providers with different levels of detail based on treatment context. Emergency information might be fully disclosed, while routine appointments receive only relevant medical history through partial disclosure.
Minimize disclosed information: Always disclose the minimum information necessary to satisfy the disclosee's legitimate requirements. Use compact disclosure as the default, expanding to partial or selective disclosure only when necessary.
Establish clear conditions: Define disclosure conditions precisely using Ricardian contracts that are both human-readable and machine-verifiable. Ambiguous conditions lead to security vulnerabilities and user confusion.
Implement chain-link confidentiality: When disclosed information may be further shared, use chain-link confidentiality to bind downstream recipients to the same privacy obligations, creating a contractual chain of protection.
Verify before accepting: Disclosees must always verify disclosed information through CESR-Proof signature validation, SAID integrity checking, KEL verification, and TEL revocation checking before accepting the disclosure.
Log disclosure events: Maintain audit logs of disclosure events for accountability and compliance purposes. These logs should record what was disclosed, to whom, when, and under what conditions, without storing the actual disclosed content.
Handle errors gracefully: Implement comprehensive error handling that fails safely, provides clear error messages, and does not leak information through error conditions.
IPEX protocol integration: Contingent disclosure is implemented through the IPEX protocol, which provides the message structure and exchange patterns for disclosure operations. Implementations must conform to IPEX specifications for interoperability.
ACDC structure design: ACDCs must be designed with contingent disclosure in mind, structuring attributes and field maps to support the desired disclosure patterns. Use selective disclosure arrays for attributes that may be independently disclosed.
CESR encoding: All disclosed information must be encoded using CESR (Composable Event Streaming Representation) to ensure efficient parsing, compact representation, and interoperability across text and binary domains.
Witness and Watcher infrastructure: Contingent disclosure relies on KERI infrastructure including witnesses for KEL validation and watchers for duplicity detection. Ensure appropriate infrastructure is available.
Registry integration: For revocable credentials, integrate with TEL registries to enable real-time revocation checking during disclosure operations.
User interface design: Design user interfaces that clearly communicate what information will be disclosed under what conditions, enabling informed consent from disclosers and appropriate verification by disclosees.
Contingent disclosure is closely related to chain-link confidentiality, which is explicitly identified as a form of contingent disclosure in the KERI glossary. Chain-link confidentiality extends contingent disclosure by creating contractual obligations that bind all downstream recipients of disclosed information to the same privacy protections.
When information is disclosed under chain-link confidentiality, the disclosee becomes contractually obligated to:
This creates a "chain" of confidentiality obligations that extends through multiple disclosure events, ensuring that privacy protections persist as information moves through an ecosystem. Chain-link confidentiality is particularly important in scenarios where:
Contingent disclosure serves as a foundational mechanism for contractually protected disclosure, which represents the most elaborate disclosure pattern in the KERI/ACDC ecosystem. Contractually protected disclosure combines contingent disclosure with:
Schema-based mechanical protection: Before any content is disclosed, the schema of the data is shared, allowing the disclosee to understand the structure and nature of information without accessing actual content.
Contract-based legal protection: Ricardian contracts are disclosed and must be cryptographically accepted before content disclosure proceeds, creating legally binding obligations.
Progressive revelation: Information is revealed incrementally as the disclosee satisfies successive conditions, implementing a graduated approach to disclosure.
The relationship can be understood as:
This layered approach enables sophisticated disclosure scenarios where mechanical, cryptographic, and legal protections work together to control information flow while maintaining verifiability and accountability.
Contingent disclosure is implemented across the KERI suite of protocols:
ACDC structure: ACDCs are designed with graduated disclosure capabilities built into their structure, using SAIDs to enable compact representation and progressive revelation.
IPEX protocol: The IPEX protocol provides the message exchange patterns and state machines for implementing contingent disclosure operations between disclosers and disclosees.
CESR encoding: CESR provides the encoding framework that enables efficient representation of both compact and expanded disclosure variants.
KERI infrastructure: The underlying KERI protocol provides the KELs, witness pools, and watcher networks that enable verification of disclosed information.
TEL registries: Transaction Event Logs provide the revocation infrastructure necessary for contingent disclosure of revocable credentials.
This integrated architecture ensures that contingent disclosure operates as a cohesive mechanism across the entire KERI ecosystem, providing consistent privacy-preserving disclosure capabilities for all ACDC-based credentials and attestations.
Fail safely: Any error in condition evaluation, cryptographic verification, or protocol processing should result in disclosure rejection without information leakage.
Timing attack prevention: Ensure condition evaluation and verification operations have constant time characteristics to prevent timing-based information leakage.
Audit logging: Maintain comprehensive logs of disclosure events for security monitoring and compliance, ensuring logs do not contain disclosed content.
Implementations must conform to:
Comprehensive testing should cover: