Inter-Wallet Credential Exchange

Inter-Wallet Credential Exchange describes a simple way to exchange [=identity=] information in a secure, decentralized, and scalable manner. It uses standardized data structures, formats, and transport protocols to enable applications (particularly [=identity=] [=wallets=]) from different manufacturers to communicate with each other, without a third party or an intermediary. The main purpose of this approach is to establish a [=claim=]-based [=identity=] management model in the World Wide Web.

Terminology

blockchain: Also referred to as distributed ledger, is a non-centralized system for recording events. These systems establish sufficient confidence for participants to rely upon the data recorded by others to make operational decisions. They typically use distributed databases where different nodes use a consensus protocol to confirm the ordering of cryptographically signed transactions. The linking of digitally signed transactions over time often makes the history of the ledger effectively immutable.
content-addressable storage: Content-addressable storage, also referred to as content-addressed storage or abbreviated CAS, is a way to store information so it can be retrieved based on its content, not its location. CAS typically uses a cryptographic [=hash=] function's digest generated from the document to identify that document in the storage system.
credential request: A data structure to make a request for a [=verifiable presentation=] containing one or more [=verifiable credentials=].
credential response: A data structure to make a response to a [=credential request=] containing one [=verifiable presentation=] with one or more [=verifiable credentials=]. Additionally, one or more [=plaintext credentials=] may be provided.
decentralized identifier: A globally unique URL-based [=identifier=], also known as a DID, associated with an [=entity=]. These [=identifiers=] are mostly used in a [=verifiable credential=] to identify its [=subject=].
DID document: A document that is accessible from a [=verifiable data registry=] using a [=DID resolver=] and contains information related to a specific [=decentralized identifier=], such as the associated public key information.
DID method: A definition of how a specific DID method scheme is implemented. A DID method is defined by a DID method specification, which specifies the precise operations by which DIDs and [=DID documents=] are created, resolved, updated, and deactivated
DID resolver: A DID resolver is a software and/or hardware component that performs the DID resolution function by taking a DID as input and producing a conforming [=DID document=] as output.
identity: The means for keeping track of [=entities=] across contexts. Digital identities enable tracking and customization of [=entity=] interactions across digital contexts, typically using [=identifiers=] and attributes.
entity: A thing with distinct and independent existence, such as a person, organization, or device that performs one or more roles in the ecosystem.
identifier: An identifier is a name that identifies either a unique object or a unique class of objects, where the "object" or class may be an idea, [=entity=] (or class thereof), physical object (or class thereof), or other. An identifier may be a word, number, letter, symbol, or any combination of those.
perfect forward secrecy: In cryptography, this is a feature of specific key agreement protocols that gives assurances that session keys will not be compromised even if long-term secrets used in the session key exchange are compromised. For HTTPS, the long-term secret is typically the Private signing key of the server. Forward secrecy protects past sessions against future compromises of keys or passwords.
plaintext credential: A data structure that stores plain values and [=salts=] serving as input to a [=hash=] function. It is used to implement the [=selective disclosure=] feature in a [=verifiable credential=].
public key infrastructure: A set of roles, policies, hardware, software, and procedures that are needed to create, manage, distribute, use, store and revoke digital certificates and manage public-key encryption.
single sign-on: An authentication scheme that allows a user to log in with a single [=identifier=] and password to any of several related, yet independent, software systems.
Transport Layer Security: A cryptographic protocol designed to provide communications security over a computer network. It aims primarily to provide privacy and data integrity between two or more communicating computer applications.
verifiable credential: A standard data model and representation format for cryptographically-verifiable digital credentials as defined by the W3C Verifiable Credentials specification [[vc-data-model]].
verifiable presentation: A standard data model and representation format for tamper-evident presentation of data derived from one or more [=verifiable credentials=] as defined by the W3C Verifiable Credentials specification [[vc-data-model]].
wallet: A wallet in the context of cryptocurrency or [=identity=] is a device, physical medium, program, or service which stores the public and/or private keys for cryptocurrency transactions or other data structures. In addition, a wallet usually offers the functionality of encrypting and/or signing data.
zero-knowledge proof: In cryptography, a zero-knowledge proof or zero-knowledge protocol is a method by which one party (the prover or [=holder=]) can prove to another party (the [=verifier=]) that they know a value, without conveying any information apart from the fact that they know this value.
holder: A role an [=entity=] might perform by possessing one or more [=verifiable credentials=] and generating [= verifiable presentations=] from them. A holder is usually, but not always, a [=subject=] of the [=verifiable credentials=] they are holding.
issuer: A role an [=entity=] can perform by asserting [=claims=] about one or more [=subjects=], creating a [=verifiable credential=] from these [=claims=], and transmitting the [=verifiable credential=] to a [=holder=].
subject: A thing about which [=claims=] are made.
verifier: A role an [=entity=] performs by receiving one or more [=verifiable credentials=] inside a [=verifiable presentation=] for processing. Other specifications might refer to this concept as a relying party.
Uniform Resource Identifier: A Uniform Resource Identifier, as defined by [[rfc3986]]. A special subtype of an URI is the Uniform Resource Locator.
digital signature: A mathematical scheme for demonstrating the authenticity of a digital message.
claim: An assertion made about a [=subject=].
selective disclosure: The ability of a [=holder=] to make fine-grained decisions about what information of a [=verifiable credential=] to share.
verifiable data registry: A system that facilitates the creation, verification, updating, and/or deactivation of [=decentralized identifiers=] and [=DID documents=]. A verifiable data registry might also be used for other cryptographically verifiable data structures such as [=verifiable credentials=]. For more information, see the W3C Verifiable Credentials specification [[vc-data-model]].
hash: The values returned by a hash function are called hash values, hash codes, digests, or simply hashes. A hash function is any one-way function that can be used to map data of arbitrary size to fixed-size values.
salt: In cryptography, a salt is random data that is used as an additional input to a one-way function that [=hashes=] data, a password, or a passphrase.
Hypertext Transfer Protocol: An application layer protocol for distributed, collaborative, hypermedia information systems designed within the framework of the Internet protocol suite. HTTP resources are identified and located on the network by URLs. An extension of HTTP is Hypertext Transfer Protocol Secure, which uses TLS to encrypt the communication protocol.
Time to live: A mechanism that limits the lifespan or lifetime of data in a computer or network. TTL may be implemented as a counter or timestamp attached to or embedded in the data.
Universally Unique Identifier: A 128-bit number described by [[rfc4122]] and used to uniquely identify some object or [=entity=] on the Internet. When generated according to the standard methods, UUIDs are, for practical purposes, unique. Their uniqueness does not depend on a central registration authority or coordination between the parties generating them.
Network address translation: A method of mapping an IP address space into another by modifying network address information in the IP header of packets while they are in transit across a traffic routing device.
firewall: A network security system that monitors and controls the incoming and outgoing network traffic based on predetermined security rules.

Assumptions

Decentralized Identifiers

DIDs as defined in [[did-core]] are a new type of [=identifiers=]. They are generated and controlled by an [=entity=] itself. Therefore the number of DIDs an [=entity=] can create is unlimited. Proof of control over a DID is provided by cryptographic methods, e.g. [=digital signatures=].

A DID contains the names of a schema and a [=DID method=] as well as the [=identifier=] itself. These parts are separated by a colon:

            did:example:123456789abcdefghi

The schema denotes that it is a DID. The [=DID method=] identifies the way the [=identifier=] can be created and managed. The W3C maintains an official list of [=DID methods=] and their specifications for this purpose [[did-spec-registries]]. The specification of a [=DID method=] contains information about all important operations, such as creating, reading, updating, and deleting DIDs.

A DID is resolved by a [=DID resolver=] into a [=DID document=] stored on a [=verifiable data registry=]. This can be a [=blockchain=], [=content-addressable storage=] (CAS), or any other (web) server. The [=DID document=] contains additional information about a DID, such as further public keys, authentication and authorization methods, or so-called service endpoints. The latter are details of services or storage locations that can be linked to the [=identifier=]. A [=DID document=] never contains personal information.

In some [=DID methods=], the [=identifiers=] have cryptographic material or a fingerprint of a public key, just as they do in a [=blockchain=]. In this way, a DID can authenticate directly against a smart contract in the corresponding [=blockchain=]. Furthermore, some [=digital signature=] methods such as the Elliptic Curve Digital Signature Algorithm (ECDSA) allow the recovery of the public key directly from a [=digital signature=]. This feature makes it possible to use a signed message directly for authentication between two hosts. The method for generating the [=identifier=], e.g. a DID or an address in the context of [=blockchain=], from a public key is usually known. From this point of view, it is not urgent to keep a [=DID document=] as long as the relationship between private key, public key, and the [=identifier=] is computable. For example, in the ETHR DID Method (`did:ethr:xyz`) the [=DID document=] is created by the [=DID resolver=].

Verifiable Credentials and Selective Disclosure

This proposal makes use of VCs and VPs according to the [[[vc-data-model]]]. VCs are data structures making statements about a person or an object according to the principles of [=claim=]-based [=identity=]. They are cryptographically verifiable because they are signed by an [=issuer=]. The [=claims=] are simple statements associated with an [=identifier=] and some metadata. Basically, anyone can act as an [=issuer=], e.g., a trusted [=entity=] or even oneself. The latter type of VCs are called self-issued credentials and are useful, for example, for delegating one's own credential to another [=identifier=]. What should be considered as a trusted [=entity=] for certain statements is not part of this proposal.

Additionally to VCs described in the aforementioned specification [[[vc-data-model]]] this proposal supports a special way that implementing the [=selective disclosure=] feature. This feature allows the credential [=holder=] to choose which attributes should be shown to the [=verifier=]. To achieve this, every attribute value a [=verifiable credential=] contains, is hashed with a cryptographic [=salt=]. The final [=verifiable credential=] will only contain these [=hashes=] - the [=salts=] and the values are stored in a separate JSON data object, called the [=plaintext credential=]. The following examples will show such a [=plaintext credential=] and its corresponding VC.

[=Plaintext credential=]

            {
              "id": "did:example:0x1611994c317bed3102D65A93B667Dbe0591Da41c",
              "type": ["HashedPlaintextCredential2021","NameAgeCredential"],
              "hashAlg": "keccak-256",
              "name": {
                  "value": "Max",
                  "salt": "dc0931a0-60c6-4bc8-a27d-b3fd13e62c63",
              },
              "age": {
                  "value": 20,
                  "salt": "3e9bacd3-aa74-42c1-9895-e490e3931a73",
              },
            }

Corresponding [=verifiable credential=]

            {
              "@context": ["https://www.w3.org/2018/credentials/v1",
                  "https://some.example.com/credentials/ld-context/"],
              "type": ["VerifiableCredential"],
              "credentialSubject": {
                  "id": "did:example:0x1611994c317bed3102D65A93B667Dbe0591Da41c",
                  "type": "NameAgeCredential",
                  "name": "0xd8925653ed000200d2b491bcabe2ea69f378abb91f056993a6d3e3b28ad4ccc4",
                  "age": "0x43bde6fcd11015c6a996206dadd25e149d131c69a7249280bae723c6bad53888"
              },
              "issuer": "did:example:0x6d32738382c6389eF0D79045a76411C42Fff3a5e",
              "issuanceDate": "2020-11-30T11:06:39.423520Z",
              "proof": {
                  "type": "EcdsaSecp256k1RecoverySignature2020",
                  "proofPurpose": "assertionMethod",
                  "verificationMethod": "did:example:0x6d32738382c6389eF0D79045a76411C42Fff3a5e",
                  "created": "2020-11-30T11:06:39.497073Z",
                  "jws": "ey..E="
              }
            }

Verifiable Credentials and Verifiable Presentations

The VCs are issued to a [=subject=] (owned by a [=holder=]) and its [=identifier=], e.g. a DID. This [=holder=] can generate a VP with one or more VCs, in which he can prove by a [=digital signature=] that he controls the [=identifier=](s) of one or more VCs. The aggregation of this information typically expresses some aspect of a person, organization, or other [=entity=]. He finally sends the VP to a [=verifier=] that can cryptographically validate the VC's trustworthiness.

Corresponding [=verifiable presentation=]

            {
              "@context": [
                "https://www.w3.org/2018/credentials/v1",
              ],
              "type": "VerifiablePresentation",
              "verifiableCredential": [{
                "@context": ["https://www.w3.org/2018/credentials/v1",
                    "https://some.example.com/credentials/ld-context/"],
                "type": ["VerifiableCredential"],
                "credentialSubject": {
                    "id": "did:example:0x1611994c317bed3102D65A93B667Dbe0591Da41c",
                    "type": "NameAgeCredential",
                    "name": "0xd8925653ed000200d2b491bcabe2ea69f378abb91f056993a6d3e3b28ad4ccc4",
                    "age": "0x43bde6fcd11015c6a996206dadd25e149d131c69a7249280bae723c6bad53888"
                },
                "issuer": "did:example:0x6d32738382c6389eF0D79045a76411C42Fff3a5e",
                "issuanceDate": "2020-11-30T11:06:39.423520Z",
                "proof": {
                    "type": "EcdsaSecp256k1RecoverySignature2020",
                    "proofPurpose": "assertionMethod",
                    "verificationMethod": "did:example:0x6d32738382c6389eF0D79045a76411C42Fff3a5e",
                    "created": "2020-11-30T11:06:39.497073Z",
                    "jws": "ey..E="
                }
              }],
              "proof": [{
                  "type": "EcdsaSecp256k1RecoverySignature2020",
                  "proofPurpose": "authentication",
                  "verificationMethod": "did:example:0x1611994c317bed3102D65A93B667Dbe0591Da41c",
                  "challenge": "1f44d55f-f161-4938-a659-f8026467f126",
                  "created": "2020-11-30T11:06:39.497073Z",
                  "jws": "ey..n="
              }]
            }

In addition, a VP itself can also have an [=identifier=]. It is also possible for each of the VCs to be issued to a different [=identifier=]. For each of these [=identifiers=] (of each [=subject=]), the corresponding proof can be included in the array of proofs in the VP. A challenge within one or more proofs authenticates for example a session.

[=Verifiable presentation=] containing an [=identifier=] and several [=verifiable credentials=], as well as their associated proofs

            {
              "@context": [
                "https://www.w3.org/2018/credentials/v1",
              ],
              "id": "did:anotherexample:xyv2-xzpq-q9wa-p7t",
              "type": "VerifiablePresentation",
              "verifiableCredential": [{
                "@context": ["https://www.w3.org/2018/credentials/v1",
                    "https://some.example.com/credentials/ld-context/"],
                "type": ["VerifiableCredential"],
                "credentialSubject": {
                    "id": "did:example:0x1611994c317bed3102D65A93B667Dbe0591Da41c",
                    "type": "NameCredential",
                    "name": "0xd8925653ed000200d2b491bcabe2ea69f378abb91f056993a6d3e3b28ad4ccc4",
                },
                "issuer": "did:example:0x6d32738382c6389eF0D79045a76411C42Fff3a5e",
                "issuanceDate": "2020-11-30T11:06:39.423520Z",
                "proof": {
                    "type": "EcdsaSecp256k1RecoverySignature2020",
                    "proofPurpose": "assertionMethod",
                    "verificationMethod": "did:example:0x6d32738382c6389eF0D79045a76411C42Fff3a5e",
                    "created": "2020-11-30T11:06:39.497073Z",
                    "jws": "ey..E="
                }
              }, {
                "@context": ["https://www.w3.org/2018/credentials/v1",
                    "https://some.example.com/credentials/ld-context/"],
                "type": ["VerifiableCredential"],
                "credentialSubject": {
                    "id": "did:example:0x7c0296fb88ec930a2a31361ca1b579603bc18892",
                    "type": "AgeCredential",
                    "age": "0x43bde6fcd11015c6a996206dadd25e149d131c69a7249280bae723c6bad53888"
                },
                "issuer": "did:example:0x6d32738382c6389eF0D79045a76411C42Fff3a5e",
                "issuanceDate": "2020-11-30T11:06:39.423520Z",
                "proof": {
                    "type": "EcdsaSecp256k1RecoverySignature2020",
                    "proofPurpose": "assertionMethod",
                    "verificationMethod": "did:example:0x6d32738382c6389eF0D79045a76411C42Fff3a5e",
                    "created": "2020-11-30T11:06:39.497073Z",
                    "jws": "ey..G"
                }
              }],
              "proof": [{
                  "type": "EcdsaSecp256k1RecoverySignature2020",
                  "proofPurpose": "authentication",
                  "verificationMethod": "did:example:0x1611994c317bed3102D65A93B667Dbe0591Da41c",
                  "challenge": "1f44d55f-f161-4938-a659-f8026467f126",
                  "created": "2020-11-30T11:06:39.497073Z",
                  "jws": "ey..v="
                }, {
                  "type": "EcdsaSecp256k1RecoverySignature2020",
                  "proofPurpose": "authentication",
                  "verificationMethod": "did:example:0x7c0296fb88ec930a2a31361ca1b579603bc18892",
                  "challenge": "1f44d55f-f161-4938-a659-f8026467f126",
                  "created": "2020-11-30T11:06:39.497073Z",
                  "jws": "ey..6"
                }, {
                  "type": "EcdsaSecp256k1RecoverySignature2020",
                  "proofPurpose": "authentication",
                  "verificationMethod": "did:anotherexample:xyv2-xzpq-q9wa-p7t",
                  "challenge": "1f44d55f-f161-4938-a659-f8026467f126",
                  "created": "2020-11-30T11:06:39.497073Z",
                  "jws": "ey..r"
                }]
            }

Verifiable Credentials and Revocation

In addition to an expiration date (`expirationDate` or `validUntil`) for credentials, [=issuers=] also have the option to revoke it. For this purpose, the [[[vc-data-model]]] defines the property `credentialStatus`, which links to a revocation list. This list can be stored on a [=blockchain=], [=content-addressable storage=] (CAS), or any other (web) server.

Expiration date and status in a [=verifiable credential=]

            {
                "expirationDate": "2020-01-01T19:23:24Z",
                "credentialStatus": {
                  "id": "0x06012c8cf97bead5deae237070f9587f8e7a266d",
                  "type": "EthereumMainnetStatusList2021"
                },
            }

Universal / App Links

Universal or app links are a way in mobile operating systems to retrieve certain data from an app using a URL. For Apple's iOS, they are documented as universal links [[universallinks]], for Google they are called Android App Links [[applinks]]. These links are a form of deep links that are handled specifically in the operating systems. During the installation of an app, a handler for a specific URL is created in the operating system that uniquely identifies the app. To prove ownership of a URL, a check is made for a specific machine-readable document that must be provided under the URLs domain. After this check is successful, requests to this URL are passed directly to the installed app without any further interaction from the user. Binding to a domain ensures uniqueness and the mandatory use of HTTPS ensures authenticity and secrecy.

If a request is made to the URL and there is no corresponding app installed, it will be opened in the browser. The request, therefore, does not end in an error state but can be answered by the own web server as desired. For example, the user gets a hint to install the corresponding app or is redirected to an online application.

Protocol Flow

Credential Request

To request VCs within a VP the following simple JSON data structure MUST be used, which MUST then be encoded with Base64url [[rfc4648]] and attached as a query parameter with key `ìwce` to a URL. The URIs used comply with the [[[rfc3986]]] specification. VCs and VPs are compliant with the [[[vc-data-model]]].

A [=credential request=] is defined with the following properties:

type

The `type` property is required and MUST be an URI. The value `"CredentialRequest"` MUST be used to determine that it is a [=credential request=].

accept

The `accept` property is required and describes the accepted data of a [=credential response=] to a [=credential request=]. It is defined with the following properties:

type

The `type` property is required and MUST be an URI. The value `"CredentialResponse"` MUST be used to determine that the requested data has to be provided in the form of a [=credential response=].

verifiablePresentation

The `verifiablePresentation` property is required.

type: The `type` property is required and MUST be an URI. It denotes the expected type of the [=verifiable presentation=].
credentialTypes: The `credentialTypes` property is required and MUST be an array of URIs. It denotes the accepted URIs of [=verifiable credential=] types within a [=verifiable presentation=].

selectiveDisclosure

The `selectiveDisclosure` property is optional. If it is not set, no method for [=selective disclosure=] is accepted.

type: The `type` property is required and MUST be an URI. It denotes the expected method of the [=selective disclosure=] feature.
requiredProperties: The `requiredProperties` property is type-specific. For the [=selective disclosure=] feature proposed in section [[[#selective-disclosure]]], the `requiredProperties` property MUST be an object that contains one or more arrays of strings corresponding to the property names of one or more [=plaintext credentials=] mandatorily being disclosed. To refer to properties in nested objects within the [=plaintext credential=] the notation `parentObjectKey.childPropertyKey` MUST be used. The key of each set MUST correspond to the credential type specified in property `credentialTypes`. Which properties are then really returned is not guaranteed and has to be checked in the response.

endpoint

The `endpoint` property is required. It describes the endpoint to which the requested data has to be sent.

type: The `type` property is required and MUST be an URI. It can take either the value `"AppLink"` or `"WebAddress"`. `"AppLink"` determines that the endpoint is a universal or app link and is RECOMMENDED for best decentralization, see section [[[#uniapplinks]]]. The value `"WebAddress"` determines that the endpoint is a normal web resource (web address). Future types could be e.g. `"DIDComm"` or similar.
location: The `location` property is required and MUST be an URL that links to a resource with HTTPS enabled.

challenge

The `challenge` property is required and MUST be a long random number. It is RECOMMENDED to use at least 128 bits. For example, an UUID [[rfc4122]] might be helpful for this task. The challenge is computed by the [=verifier=] and MUST have a [=Time to Live=] (TTL).

domain

The `domain` property is optional and MUST be an URI. It is used to announce domain-specific extensions in a [=credential request=].

[=Credential request=] data object

            {
                "type": "CredentialRequest",
                "accept": {
                    "type": "CredentialResponse",
                    "verifiablePresentation": {
                        "type": "VerifiablePresentation",
                        "credentialTypes": ["AgeCredential","NameCredential"],
                    },
                    "selectiveDisclosure": {
                        "type": "HashedPlaintextCredential2021",
                        "requiredProperties": {
                            "AgeCredential": ["age"]
                        },
                    },
                    "endpoint": {
                        "type": "AppLink",
                        "location": "https://verifier-app.another-example.com/responses"
                    }
                },
                "challenge": "1f44d55f-f161-4938-a659-f8026467f126",
                "domain": "example.com"
            }

Encoded [=credential request=]

            https://issuer-app.example.com/requests?iwce=eyAidHlwZSI6ICJDc...IgfQ

Credential Response

To respond to a request for a VP the following data structure MUST be used, which MUST be encoded with Base64url [[rfc4648]] and attached as a query parameter with key `iwce` to a URL. The URIs used comply with the [[[rfc3986]]] specification. VCs and VPs are compliant with the [[[vc-data-model]]].

type

The `type` property is required and MUST be an URI. The value `"CredentialResponse"` MUST be used to determine that it is a [=credential response=].

verifiablePresentation

The `verifiablePresentation` property is required and defined as an object that contains exactly one [=verifiable presentation=]. The proofs within a [=verifiable presentation=] MUST contain the `challenge` property that was received with a [=credential request=]. The proofs can also contain the `domain` property to announce domain-specific extensions

selectiveDisclosure

The `selectiveDisclosure` property is optional. If it is not set, no method for [=selective disclosure=] is supported.

type: The `type` property is required and MUST be an URI. It denotes the expected method of the [=selective disclosure=] feature.
plaintextCredential: The `plaintextCredential` property is type-specific. The expected return value is data conforming to the `type` information from a [=credential request=]. For the [=selective disclosure=] feature proposed in section [[[#selective-disclosure]]], the `plaintextCredential` property is defined as an array of objects containing one or more [=plaintext credentials=].

[=Credential response=] data object

              {
                  "type": "CredentialResponse",
                  "verifiablePresentation": {},
                  "selectiveDisclosure": {
                      "type": "HashedPlaintextCredential2021",
                      "plaintextCredential": [{},{}]
                  }
              }

Encoded [=credential response=]

            https://verifier-app.another-example.com/responses?iwce=eyZXJpZmlhYmxlUHJ...JodH

Introduction

Scope

Terminology

Assumptions

Decentralized Identifiers

Verifiable Credentials and Selective Disclosure

Verifiable Credentials and Verifiable Presentations

Verifiable Credentials and Revocation

Universal / App Links

Protocol Flow

Credential Request

Credential Response

Strict Domain Separation

User Experience

Security Considerations

Perfect Forward Secrecy

Trust

Privacy Considerations

Anti-correlation

Bootstrapping