Comprehensive Explanation

presentation-exchange

Process Definition

A presentation exchange represents the formal mechanism within the KERI/ACDC ecosystem through which verifiable credentials are disclosed from one party to another. Unlike simple data transmission, presentation exchanges establish cryptographically verifiable relationships between credentials through a directed acyclic graph (DAG) structure, ensuring that disclosed information maintains its authenticity chain back to authoritative issuers.

The process accomplishes several critical objectives:

1. Verifiable Disclosure: Enables a Discloser to present credentials in a way that allows the Disclosee to cryptographically verify their authenticity
2. Selective Revelation: Supports graduated disclosure mechanisms where only necessary information is revealed at each stage
3. Provenance Preservation: Maintains the chain of authority from Issuer through any intermediate credentials to the presented credential
4. Privacy Protection: Allows for compact disclosure, partial disclosure, and selective disclosure to minimize information leakage

Presentation exchanges are used whenever a credential holder needs to prove claims to a verifier, whether for authentication, authorization, or attestation purposes. This includes scenarios such as:

• Proving organizational roles (OOR credentials in vLEI)
• Demonstrating engagement context roles (ECR credentials)
• Establishing legal entity identity
• Chaining multiple credentials to show delegated authority
• Presenting authorization credentials that reference other credentials

Key Participants

Every presentation exchange involves two primary roles:

Discloser: The party that controls and presents the ACDC credentials. The Discloser may or may not be the original Issuer of the credentials being presented. In many scenarios, the Discloser is the Issuee (subject) of the credential, presenting it to prove claims about themselves.

Disclosee: The party that receives the presented credentials and performs verification. The Disclosee acts as a verifier, validating cryptographic signatures, checking credential status, and evaluating the credential chain against their trust policies.

Process Flow

The presentation exchange process follows a structured sequence that ensures cryptographic integrity while supporting flexible disclosure patterns:

1. Presentation Request Initiation

The Disclosee initiates the exchange by requesting specific credentials or claims. This request may specify:

• Required credential types (identified by schema SAIDs)
• Acceptable issuers (identified by AIDs)
• Required attributes or claims
• Acceptable credential chains (e.g., requiring specific edge relationships)

The request is typically transmitted using the IPEX (Issuance and Presentation EXchange) protocol, which provides a uniform mechanism for both credential issuance and presentation.

2. Credential Selection and Preparation

The Discloser selects appropriate credentials from their credential store that satisfy the Disclosee's requirements. This involves:

• Identifying credentials that match the requested schema
• Verifying that credentials are not revoked by checking TEL (Transaction Event Log) status
• Determining the appropriate disclosure level (compact, partial, selective, or full)
• Assembling any chained credentials required to establish the complete provenance chain

3. DAG Construction

A critical aspect of presentation exchanges is that the set of disclosed ACDCs MUST be chained together, forming a directed acyclic graph. This DAG structure:

• MUST have at least one vertex (minimum one ACDC)
• MAY have zero or more edges pointing to other vertices
• Represents relationships between credentials through edge properties
• Enables verification of the complete trust chain from root authority to presented credential

For example, in the vLEI ecosystem, an ECR credential presentation might include:

1. The ECR credential itself (vertex 1)
2. The Legal Entity credential referenced by the ECR credential (vertex 2)
3. The QVI credential that authorized the Legal Entity credential (vertex 3)
4. Edges connecting these credentials through their e (edges) sections

This DAG structure allows the Disclosee to verify not just the presented credential, but the entire chain of authority back to the root trust anchor (GLEIF in the vLEI case).

4. Disclosure Level Determination

The Discloser determines the appropriate disclosure level based on:

• The Disclosee's requirements
• Privacy considerations
• Contractual obligations (chain-link confidentiality)
• Regulatory requirements

Disclosure levels include:

Compact Disclosure: Only SAIDs are revealed, providing minimal information leakage while allowing the Disclosee to verify credential structure and relationships.

Partial Disclosure: Some field maps are fully disclosed while others remain as SAIDs, enabling progressive revelation as trust develops.

Selective Disclosure: Specific attributes from selectively disclosable sets are revealed while others remain blinded, supporting privacy-preserving presentations.

Full Disclosure: Complete credential details are revealed, typically after contractual protections are established.

5. Cryptographic Signing

The Discloser signs the presentation using their AID's current authoritative keys. This signature:

• Proves the Discloser's control over the presented credentials
• Provides non-repudiation of the presentation act
• Enables the Disclosee to verify the presentation's authenticity
• May be required even when the Discloser is not the original Issuer

In multi-signature scenarios, the presentation may require signatures from multiple parties to satisfy threshold requirements.

6. Transmission via IPEX

The presentation is transmitted using the IPEX protocol, which provides:

• Standardized message formats for credential exchange
• Support for both issuance and presentation exchanges
• CESR (Composable Event Streaming Representation) encoding for efficient transmission
• Attachment mechanisms for signatures and supporting data

IPEX messages include:

• The credential data (in the chosen disclosure level)
• Cryptographic signatures
• Any supporting credentials in the DAG
• Metadata about the presentation context

7. Verification by Disclosee

The Disclosee performs comprehensive verification:

Cryptographic Verification:

• Validates all signatures using the Discloser's public keys from their KEL (Key Event Log)
• Verifies SAID integrity for all disclosed field maps
• Checks that edge references resolve to valid credentials

Credential Status Verification:

• Queries TEL registries to confirm credentials are not revoked
• Verifies issuance timestamps are within acceptable ranges
• Checks that all credentials in the chain are currently valid

Trust Chain Verification:

• Validates the complete DAG structure
• Verifies that edge operators (I2I, DI2I, NI2I) are satisfied
• Confirms that issuers are authorized according to the Disclosee's trust policies
• Validates that the chain terminates at an acceptable root of trust

Schema Validation:

• Verifies that credentials conform to their declared schemas
• Validates that required attributes are present
• Checks that attribute values meet schema constraints

8. Decision and Response

Based on verification results, the Disclosee makes a decision:

• Accept: The presentation satisfies all requirements and verification passes
• Reject: Verification fails or requirements are not met
• Request Additional Information: The Disclosee may request fuller disclosure or additional credentials

The Disclosee may respond with:

• An acknowledgment of successful verification
• A request for additional disclosure
• An error message indicating verification failure
• A subsequent presentation exchange if mutual authentication is required

Technical Requirements

Cryptographic Requirements

Presentation exchanges rely on several cryptographic mechanisms:

Digital Signatures: All credentials in the presentation MUST be signed by their respective issuers using CESR-encoded signatures. The Discloser MUST also sign the presentation itself to prove control over the presented credentials.

SAID Integrity: Every field map in an ACDC includes a SAID that cryptographically binds the content. During presentation, the Disclosee MUST verify that:

• The SAID of each disclosed field map matches the computed digest of its content
• SAIDs referenced in compact disclosure resolve to valid field maps when later disclosed
• The top-level ACDC SAID commits to all nested field maps

Key State Verification: The Disclosee MUST verify the Discloser's key state by:

• Resolving the Discloser's AID to obtain their current KEL
• Verifying that the signing keys used in the presentation were authoritative at the time of signing
• Checking for any duplicity in the Discloser's KEL

Chain Integrity: The DAG of chained credentials MUST maintain cryptographic integrity through:

• Edge references using SAIDs that commit to referenced credentials
• Signatures from each issuer in the chain
• Unbroken provenance from root authority to presented credential

Timing Considerations

Presentation exchanges must account for temporal factors:

Credential Validity Periods: Credentials include issuance timestamps (dt field) and may have expiration dates. The Disclosee MUST verify that:

• Credentials were valid at the time of presentation
• Any time-bounded authorizations have not expired
• Issuance timestamps are within acceptable ranges (not future-dated)

Key State Synchronization: The Discloser and Disclosee may have different views of key state if KEL updates have not fully propagated. The Disclosee SHOULD:

• Query witnesses to obtain the latest key state
• Use watchers to detect any duplicity
• Allow for reasonable propagation delays in distributed systems

Revocation Checking: Credential status may change between presentation preparation and verification. The Disclosee MUST:

• Check TEL registries at verification time, not relying on cached status
• Account for the possibility of recent revocations
• Implement appropriate grace periods for status propagation

Replay Attack Protection: Presentations may include timestamps or nonces to prevent replay attacks, particularly in authentication scenarios. The Disclosee SHOULD:

• Verify that presentation timestamps are recent
• Maintain a record of recently seen presentations to detect replays
• Use challenge-response protocols when appropriate

Error Handling

Presentation exchanges must handle various error conditions:

Verification Failures:

• Invalid signatures: Reject the presentation and log the failure
• SAID mismatches: Indicate data integrity violation
• Revoked credentials: Reject and potentially notify the Discloser
• Expired credentials: Reject with indication of expiration

Missing Credentials:

• Incomplete DAG: Request missing credentials from the Discloser
• Unresolvable SAIDs: Request full disclosure of compact references
• Missing edge targets: Request the complete credential chain

Trust Policy Violations:

• Untrusted issuer: Reject with indication of trust policy failure
• Invalid edge operators: Reject with indication of authorization failure
• Schema violations: Reject with specific schema validation errors

Network Failures:

• Witness unavailability: Retry with alternative witnesses or use cached key state
• TEL registry unavailability: Implement fallback verification strategies
• Timeout conditions: Implement appropriate retry logic with exponential backoff

Usage Patterns

Typical Scenarios

Authentication Scenario: A user presents an OOR (Official Organizational Role) credential to access a corporate system:

1. System requests OOR credential with specific role requirements
2. User's wallet selects appropriate OOR credential
3. Wallet includes the Legal Entity credential (referenced by OOR credential)
4. Wallet includes the QVI credential (that authorized the LE credential)
5. User signs the presentation with their personal AID
6. System verifies the complete chain and grants access based on the role

Authorization Scenario: A Legal Entity authorizes a QVI to issue ECR credentials:

1. Legal Entity creates an ECR Authorization credential
2. Legal Entity presents this credential to the QVI
3. QVI verifies the Legal Entity's authority through the LE credential chain
4. QVI uses the authorization credential to issue ECR credentials to specified individuals
5. When those individuals present their ECR credentials, verifiers can trace back through the authorization chain

Graduated Disclosure Scenario: A credential holder progressively reveals information:

1. Initial presentation uses compact disclosure (only SAIDs)
2. Verifier examines structure and determines additional information is needed
3. Holder provides partial disclosure of specific field maps
4. After contractual protections are established, holder provides full disclosure
5. Each stage maintains cryptographic integrity through SAID verification

Best Practices

Minimize Information Disclosure: Always use the most compact disclosure level that satisfies the Disclosee's requirements. Start with compact disclosure and progressively reveal information only as needed.

Verify Complete Chains: Never accept a credential in isolation. Always verify the complete DAG of chained credentials back to a trusted root authority.

Check Revocation Status: Always query TEL registries at verification time. Cached status information may be stale.

Implement Proper Error Handling: Provide clear error messages that help diagnose verification failures without leaking sensitive information.

Use Contractual Protections: For sensitive information, establish chain-link confidentiality agreements before full disclosure.

Maintain Audit Trails: Log all presentation exchanges for compliance and debugging purposes, including verification results and any errors encountered.

Support Multiple Disclosure Levels: Implement support for compact, partial, selective, and full disclosure to enable flexible privacy-preserving presentations.

Validate Edge Operators: Ensure that credential chains satisfy the appropriate edge operators (I2I, DI2I, NI2I) according to your trust policies.

Integration Considerations

IPEX Protocol Integration: Presentation exchanges are typically implemented using the IPEX protocol, which provides standardized message formats and exchange patterns. Implementations should:

• Support IPEX message types for presentation requests and responses
• Implement IPEX state machines for managing exchange lifecycle
• Handle IPEX error conditions and retry logic

KERI Infrastructure Integration: Presentation exchanges depend on KERI infrastructure components:

• Witnesses for key state verification
• Watchers for duplicity detection
• OOBI (Out-Of-Band Introduction) for endpoint discovery
• KEL resolution for key state queries

TEL Registry Integration: Credential status verification requires integration with TEL registries:

• Query TEL endpoints for credential status
• Handle TEL registry unavailability gracefully
• Cache TEL responses appropriately while respecting freshness requirements

Schema Registry Integration: Credential verification requires access to schema definitions:

• Resolve schema SAIDs to obtain schema definitions
• Validate credentials against their declared schemas
• Support schema versioning and evolution

Wallet Integration: For user-facing applications, presentation exchanges integrate with digital wallets:

• Wallet selects appropriate credentials based on presentation requests
• Wallet manages disclosure levels and user consent
• Wallet signs presentations using user's AID
• Wallet handles credential storage and retrieval

Trust Policy Integration: Verifiers must integrate presentation verification with their trust policies:

• Define acceptable issuers and credential types
• Specify required credential chains and edge operators
• Implement business logic for authorization decisions based on verified credentials
• Handle policy updates and versioning