Presentation exchange

Definition of the standards allowing a presentation exchange between a wallet and a verifier of any technology provider under the Verifier Universal Interface protocol, as well as its relations with other protocols in VUI.

Decentralized digital identity, or "self-sovereign" identity (SSI), is a new paradigm proposed for managing digital identities. Relying on Decentralized identifiers (DIDs) and Verifiable Credentials (VC), the subject and his personal credentials are independent from any centralized registry, identity provider, or certificate authority.

On the Decentralized Identity model, the role associated to requesting and verifying credentials is defined as the Verifier.

In order to retrieve those credentials in an interporative way, a standard exchange protocol supporting all the needs of wallet providers and verifiers providers is required. As there are multiple interoperability and standarization efforts present, the goal of this spec is to build upon the existing protocols and explain its usage by any verifier and it's relation with other possible verifier needs.

Despite its format, this document doesn't aim to be published on the W3C as a standard normative, rather it aims to propose extensions of existing protocols to allow to connect them with other interfaces and/or add additional features. Those extensions must be discussed and included if considered deemed on said protocols.

Context

There are multiple known and well adopted technology solutions or standards focused on the presentation exchange between a wallet and a verifier. There are framework solutions such as Hyperledger Aries, as well as other standardization efforts, that could be compatible or not with other protocols, such as:

It seems however that the [DIF Presentation Exchange] Data Model is a well accepted starting point, as it is the foundation of or supported by most of those listed approaches.

Terminology

Decentralized Identifier (DID)
As defined in [[DID-CORE]].
DID document
As defined in [[DID-CORE]].
DID resolution
As defined in [[DID-RESOLUTION]].
DID resolver
As defined in [[DID-RESOLUTION]].
Verifiable Credential (VC)
As defined in [[VC-DATA-MODEL]].
Verifiable Presentation (VP)
As defined in [[VC-DATA-MODEL]].
Linked Data Proofs
As defined in [[LD-PROOFS]].
Presentation Exchange
As defined in [[DIF-PRESENTATION-EXCHANGE]]
Presentation Definition
As defined in [[DIF-PRESENTATION-EXCHANGE]]
Presentation Submission
As defined in [[DIF-PRESENTATION-EXCHANGE]]
Data Agreements
As defined in [[DATA-AGREEMENTS]]
Data Agreement Template
As defined in [[DATA-AGREEMENTS]]

Data Model

The base data model for the presentation exchange is the one defined by DIF Presentation Exchange, considering both the Presentation Definition and the Presentation Submission

However, a few extensions of the data models are suggested with the goal of allowing the usage of Data Agremeents and improving verifier capacities in order to trust the source of the presentation.

Extensions

All extensions are RECOMMENDED. Both the verifier and the holder MAY decide not to trust the other party if the extensions are not fulfilled.

There are 3 extensions suggested:

Data Agreement

The inclusion of data agreements inside a Presentation Exchange MAY be achieved by integrating a Data Agreement inside the exchange.

Presentation Definition

To do this, the following field MAY be added on the Presentation Definition object:

data_agreement
The data agreement property MUST either 
                                        
{ 
    "presentation_definition": {
        "dataAgreement": {
            "@context": "https://schema.igrant.io/data-agreements/v1",
            "data_receiver": { ...},
            "events": [...],
            "id": "BUuzq96T7EBvohJngS6xuz5tWc5P7PLmjFDW7KtAQe9y",
            "personal_data": [...],
            "purposes": [...],
            "template_id": "x76ShERoQReZmWlLdJZWhWmWQx8bhGa",
            "template_version": "v1.0",
            "version": "0"
        },
        "name": "Gataca",
        "id": "CAajN2Z9z2pDW5jYfLdN5iemXutsK5mYDXE8porx79f",
        "purpose": "Demo",
        "format": {...},
        "submission_requirements": [...],
        "input_descriptors": [...]
    }
}
                                        


                
                                                        
{
    "presentation_definition": {
        "dataAgreement": "https://universalverifier.io/api/v1/sessions/CAajN2Z9z2pDW5jYfLdN5iemXutsK5mYDXE8porx79f/dataAgreement",
        "name": "Gataca",
        "id": "CAajN2Z9z2pDW5jYfLdN5iemXutsK5mYDXE8porx79f",
        "purpose": "Demo",
        "format": {...},
        "submission_requirements": [...],
        "input_descriptors": [...]
    }
}

Presentation Submission

If a Data Agreement Template is introduced by the verifier in the Presentation Definition, then the Holder MUST ensure that he has provided that verifier with a valid Data Agreement .

As defined in [[DATA-AGREEMENTS]]:

The Holder MAY reuse a previously existing Data Agreement Record if he already possesses one with the same

template_id
and
template_version
as the one required on the Data Agreement Template on the Presentation Definition

The Holder MAY generate and share a new Data Agreement Record fulfilling the defined template.

Once ensured the existance of a Data Agreement Record according to this submission, the Holder MUST include the following property in his submission:

data_agreement_id
The data agreement property MUST be the Id of the Data Agreement Record to validate this exchange

The

data_agreement_id
property must be included at the same level as the
presentation_submission
in the presentation document, regardless of the presentation format. See Embed targets 

    
                {
                    "verifiablePresentation": {
                        "@context": ["https://www.w3.org/2018/credentials/v1", "https://identity.foundation/presentation-exchange/submission/v1"],
                        "data_agreement_id": "G5Numq3USqDJLzpZ4R9vB6zuQ4djGPwy6cY9usDYGqNn",
                        "holder": "did:gatc:NzdlMDBhMDZlYjdkZGYxYzQwZjJkOTYx",
                        "presentation_submission": {...},
                        "proof": [...],
                        "type": ["VerifiablePresentation", "PresentationSubmission"],
                        "verifiableCredential": [...]
                    }
                }

Proofing

It could be desirable for a Holder to know the source of a Presentation Definition for multiple reasons:

  • Avoid phishing problems
  • Improve user experience
  • Add additional security to off-channel communication, especially if the authenticating device needs to read a QR.
In general, any attacks focused on the impersonation of a verifier would be considerably difficulted by the requirement of signing the presentation definition with the verifier DID.

The Presentation Definition MAY be improved by the usage of Data Proofs, making them a "Verifiable" object. 

                        
                                {
                                    "verifiablePresentation": {
                                        "dataAgreement":"https://universalverifier.io/api/v1/sessions/CAajN2Z9z2pDW5jYfLdN5iemXutsK5mYDXE8porx79f/dataAgreement",
                                        "name": "Gataca",
                                        "id": "CAajN2Z9z2pDW5jYfLdN5iemXutsK5mYDXE8porx79f",
                                        "purpose": "Demo",
                                        "format": {...},
                                        "submission_requirements": [...],
                                        "input_descriptors": [...],
                                        "proof": {
                                            "created": "2022-01-07T11:53:21Z",
                                            "creator": "did:gatc:24gsRbsURij3edoveHv81jt9EnhggrnR#keys-1",
                                            "domain": "gataca.io",
                                            "nonce": "sUzybVzzg1ZXFw-xDqSeMP3-TiZqKOtxszk0K4Ag5X8=",
                                            "proofPurpose": "assertionMethod",
                                            "signatureValue": "qGIh5JLxollEek5l1yFUcwmHj2H1ZYn3PR8uTa5bDtIcpW6MKKJDpc5_YQjqHGVUKbre8EMDI7e07lgR1ZJ9Bg",
                                            "type": "JcsEd25519Signature2020",
                                            "verificationMethod": "did:gatc:24gsRbsURij3edoveHv81jt9EnhggrnR#keys-1"
                                        }
                                    }
                                }

Source Authentication

There may be additional requirements by the verifier to trust the source of credentials:

Possessing a DID and some credentials does not guarantee that they can be trusted, as they can come from a non-secure wallet or belong to malificient users colluding to fake an identity.

There is a lot of discussion regarding how to bind the wallet or the subject to the holder. See for instance holder and subject binding

The verifier MAY require specific keys to sign the presentation.

There are two kind of keys that the verifier MAY require:

Wallet keys

Wallet providers SHOULD embed a private key in their app.

Different wallets SHOULD be uniquely identified by a unique DID.

The app private key MUST be referred to on the DID with a verification method containing the identifier

#appAuth

The verifier MAY require a presentation submission to also be signed with the wallet DID.

Embedding private keys in applications is never completely secure. Any attacker will have full access to the code. Obfuscation mechanisms MUST be applied.
Rotating the embeded private keys frequently to make retrieval more difficult is RECOMMENDED.

Second Factor Keys

Holder DIDs SHOULD contain multiple authentication keys.

The usage of Peer DIDs as Holder DIDs instead of the subject root DID is RECOMMENDED.

Each different authentication key should be retrieved after executing an additional authentication process in the wallet, a second factor authentication. Some of those processes could be:

silent
No other authentication process other than having the wallet open
biometric
Fingerprint or face validation authentication
email
Authentication via email OTP
phone
Authentication via SMS OTP
faceSDK
Authentication using a face validation SDK
authenticator
2FA performed on an authenticator application

The key identifier MUST represent the authentication process performed.

Presentation Definition

This solution has been suggested to avoid modifications on the Presentation definition data model. Other more elegant solutions are also possible with the inclusion of additional properties.

Specific signing keys MAY be required on the Presentation Definition by including a specific configuration:

Submission requirements

Include a specific submission requirement with the following properties: 

                                                                            
                    {
                        name: 'Identity_binding',
                        purpose:
                        'Assert wallet source and bind the subject and the holder to the presentation',
                        rule: 'all',
                        from: 'identity'
                    }

Input descriptors

Multiple Input descriptors MAY be included to satisfy the identity binding needs.

All those Input descriptors MUST belong to the group

identity

All those Input descriptors MUST refer to the

path
{
                    path: ['vp.proof.creator'],
                    }

The pattern MUST contain the format of the required authentication keys. The logical requirements of which keys must be used (AND and OR logic) is inherited from the presentation submission logic. 

                                    
{
                                            id: 'wallet_auth',
                                            name: 'Wallet Application Authentication',
                                            purpose:'We need to assert the source of the credentials as a trusted wallet',
                                            group: ['identity'],
                                            constraints: {
                                                fields: [{
                                                    path: ['vp.proof.creator'],
                                                    purpose: 'The presentation must be signed with one of the trusted app dids',
                                                    filter: {
                                                        type: 'string',
                                                        pattern: '^(did:gatc:183y59466qw9816323|did:gatc:ctq98AHNE8dJG1KsbbW9CIIe8Hp97yF9)#appAuth$'
                                                    }
                                                }]
                                            }
                                        }
                                    

                
                    
{
                        id: 'authnfactors',
                        name: 'Identity verification enforced',
                        purpose: "We need to assert the holder's identity matching the subject",
                        group: ['identity'],
                        constraints: {
                            fields: [{
                                path: ['vp.proof.creator'],
                                purpose: 'A second factor must be enforced',
                                filter: {
                                    type: 'string',
                                    pattern: '^did:(.*)#(silent|biometric)$'
                                }   
                            }]
                        }
                    }

Exchange Protocol

DID SIOP

DID SIOP is RECOMMENDED as Exchange Protocol.

Alternatives

Any protocol using the Presentation Exchange protocol is susceptible of extension to support the full verifier capabilities. That would include DID Comm if following the WACI Specification.

Additionally, a specific API based on VC-HTTP-APIS has been defined for interop testing. This API doesn't cover the exchange communication protocol, just the logic at data model validation.

The testing API also covers the endpoints necessary for Data Agreement integration.