[=Credentials=] are integral to our daily lives; driver's licenses confirm our capability to operate motor vehicles, university degrees assert our level of education, and government-issued passports permit travel between countries. The [[[?VC-DATA-MODEL-2.0]]] specification provides a mechanism to express these sorts of [=credentials=] on the Web in cryptographically secure, privacy-respecting, and machine-verifiable way. At times it is useful to be able to transmit these sorts of credentials in a peer-to-peer setting where wide area network connectivity is not available. This specification establishes a number of wireless protocols that can be used to request and present verifiable credentials over electromagnetic communication devices such ones supporting Near Field Communication (NFC) and Bluetooth Low Energy (BLE).

This specification is EXPERIMENTAL and is NOT INTENDED for production deployment.

Comments regarding this specification are welcome at any time. Please file issues directly on GitHub, or send them to public-credentials@w3.org if that is not possible. (subscribe, archives).

Introduction

[=Credentials=] are integral to our daily lives; driver's licenses confirm our capability to operate motor vehicles, university degrees assert our level of education, and government-issued passports permit travel between countries. The [[[?VC-DATA-MODEL-2.0]]] specification provides a mechanism to express these sorts of [=credentials=] on the Web in cryptographically secure, privacy-respecting, and machine-verifiable way. At times it is useful to be able to transmit these sorts of credentials in a peer-to-peer setting where wide area network connectivity is not available. This specification establishes a number of wireless protocols that can be used to request and present verifiable credentials over electromagnetic communication devices such ones supporting Near Field Communication (NFC) and Bluetooth Low Energy (BLE).

Use Cases

Legacy Presentation

The State of Utopia's digital transformation team would like to transition their vendors to use the [[[VC-DATA-MODEL-2.0]]] but would like to continue to support legacy systems using their proprietary NFC transit passes. They would like to instruct their new vendors to embed the legacy NFC transit pass codes into the new [=verifiable credentials=] that they will be issuing.

Non-Interactive Presentation

Ricardo purchased a movie ticket online and would like to use his mobile device to present the digital ticket at the entry gate at the movie theatre. He sees that the movie ticket has a NFC logo on it labeled "Tap to Share", which then instructs him to hold his phone close to the entry gate. The entry gate, recognizing the validity of the ticket, opens and Ricardo enters to enjoy his movie.

Interactive Presentation

Summer is crossing the border into Utopia and would like to use her new digital permanent resident card to speed her transit through the border crossing. In order to use the digital permanent resident card, border control challenges her devices to demonstrate that it is among the devices that Utopia resident services verified when they first issued the digital permanent resident card to Summer. This requires the border control software to send a cryptographic challenge to Summer's device, which it fulfils along with providing her permanent resident card, allowing Summer to cross the border.

Wireless Protocol Upgrade

Ular is a digital notary in a rural area of their country and, after verifying the physical documents that Meena has provided, encodes digital images for each of them and includes them in a [=verifiable credential=] with Ular's digital signature. In order to transmit them to Meena, Ular needs a high bandwidth channel as data transmission over the mobile phone network is costly and slow in their area. Ular's software, which is configured to choose more cost effective options, choses to send the [=verifiable credential=] over a peer-to-peer short range wireless protocol.

Optical Initiation

Mel would like to check out at a retail location which does not have any non-payment NFC technologies in their point of sale, but does support WiFi and Bluetooth at the store. Mel generates a QR Code and scans it at the point of sale to enable it to connect to their phone over Bluetooth to complete the transaction.

The conformance classes for this specification will be specified at a future date.

This document also contains examples that contain characters that are invalid JSON, such as inline comments (`//`) and the use of ellipsis (`...`) to denote information that adds little value to the example. Implementers are cautioned to remove this content if they desire to use the information as a valid document.

Examples provided throughout this document include descriptive properties, such as `name` and `description`, with values in English to simplify the concepts in each example of the specification. These examples do not necessarily reflect the data structures needed for international use, described in more detail in the Internationalization Considerations section in the Verifiable Credentials specification.

Terminology

The following terms are used to describe concepts in this specification.

interaction offer
A protocol that [=issuers=], [=holders=], and [=verifiers=] use to determine the protocols over which an interaction can occur.

Interaction Offers

An [=interaction offer=] is a protocol that peers use to determine the protocols over which an interaction can occur. The protocol is composed of one peer providing an interaction offer URL while the other peer fetches the interaction offer response. An example of the [=interaction offer URL=] is provided below: 

https://interaction.example/interactions/123/request

The URL consists of the following query parameters:

nfc
An OPTIONAL parameter that, if present, specifies that further communication can occur over NFC.
bt
An OPTIONAL parameter that, if present, specifies Bluetooth connection details such as address and access credentials. An example of such a URL is: `btspp://00:11:22:33:FF:EE:97c44c80-5fcc-11ef-81a2-bf5f90ac9110;vcapi`
wifi
An OPTIONAL parameter that, if present, specifies WiFi connection details such as an access point address and access credentials. An example of such a URL is: `WIFI:S:38f2bcc5a0b71;T:WPA;P:J3Klq9c2KlPPcJkwzU02K;;vcapi`

When a request is made to the [=interaction offer URL=] URL, an [=interaction offer response=] is provided. An example of an interaction offer response is provided below: 

{
  // these are protocols that can be used
  "protocols": {
    "nfc": true,
    "website": "https://website.example/interaction/123",
    "vcapi": [
      "btspp://00:11:22:33:FF:EE:97c44c80-5fcc-11ef-81a2-bf5f90ac9110",
      "WIFI:S:38f2bcc5a0b71;T:WPA;P:J3Klq9c2KlPPcJkwzU02K;;",
      "https://vcapi.example/workflows/z1A1FjMfnG/exchanges/z19mxakBFecZ",
    ],
    "oid4vp": "openid4vp://authorize?response_type=vp_token&client_id=...",
    "otherRetailApi": "https://retail.example/checkout_api/763DAKX7diL5BFecZ"
  }
}

Verifiable Credentials Over NFC

The NFC protocol is used to wirelessly communicate between devices in a peer-to-peer fashion. It's range is typically limited to 10 centimeters or less based on the power levels used by the NFC device. The following sections describe how NFC can be used to request and receive verifiable credential presentations over NFC using the [[[WEB-NFC]]] specification.

Non-interactive NFC Presentation

Non-interactive NFC transmission of [=verifiable presentations=] are useful when the presentation of the information in a [=verifiable credential=] is enough to proceed with a workflow without needing to provide a challenge to the [=holder=] of the [=verifiable credential=] such as the use of a bearer token such as a public transit card or movie ticket.

To perform such a [=presentation=], the [=holder=] is expected to use their device to select a [=verifiable credential=] for transmission and activate their device to transmit the information contained in `payload` value of the NFC `renderMethod` entry.

For example, given the [=verifiable credential=] below: 

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://www.w3.org/ns/credentials/examples/v2"
  ],
  "type": [
    "VerifiableCredential",
    "PublicTransportationTicket"
  ],
  "name": "Utopia Public Transport Ticket",
  "description": "Utopia 30-day metro area subway and bus transportation ticket.",
  "issuer": "did:key:zDnaeW9VZZs7NH1ykvS5EMFmdodu2wj4dPcrV3DzTAadrXJee",
  "validFrom": "2024-08-03T12:19:52Z",
  "validUntil": "2024-09-03T12:19:52Z",
  "credentialSubject": {
    "id": "did:example:b34ca6cd37bbf23",
    "type": [
      "Person",
      "TicketedPassenger"
    ],
    "ticket": {
      "type": "PublicTransportTicket",
      "identifier": "83627465934729",
      "modes": ["rail", "bus"],
      "areaOfValidity": {
        "locality": "Utopia"
      }
    }
  },
  "renderMethod": [{
    "type": "NfcRenderingTemplate2024",
    "name": "Present over NFC",
    "payload": "uODM2Mjc0NjU5MzQ3Mjk"
  }],
  "proof": {
    "type": "DataIntegrityProof",
    "created": "2024-09-14T16:30:55Z",
    "verificationMethod": "did:key:zDnaeW9VZZs7NH1ykvS5EMFmdodu2wj4dPcrV3DzTAadrXJee#zDnaeW9VZZs7NH1ykvS5EMFmdodu2wj4dPcrV3DzTAadrXJee"
    "cryptosuite": "ecdsa-rdfc-2019",
    "proofPurpose": "assertionMethod",
    "proofValue": "zxsiJdPoFZrEz...EZcBvBiE"
}

Note that in the example above, the only information transmitted over NFC is the `credentialSubject.renderMethod.payload` value, which while unsigned, allows for the transmission of any legacy fixed NFC payload value.

If an [=issuer=] desires to enable the transmission of a [=verifiable credential=] over NFC, they can encode one in the payload. Doing such an encoding can be made more efficient by compressing the [=verifiable credential=] using [[[CBOR-LD]]]. For example, the following [=verifiable credential=] contains an NFC payload that is a CBOR-LD encoded [=verifiable credential=]: 

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://w3id.org/citizenship/v2",
    "https://www.w3.org/ns/credentials/examples/v2"
  ],
  "type": [
    "VerifiableCredential",
    "EmploymentAuthorizationDocumentCredential"
  ],
  "validFrom": "2019-12-03T12:19:52Z",
  "validUntil": "2029-12-03T12:19:52Z",
  "credentialSubject": {
    "type": [
      "Person",
      "EmployablePerson"
    ],
    "givenName": "JOHN",
    "additionalName": "JACOB",
    "familyName": "SMITH",
    "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhE...QmCC",
    "gender": "Male",
    "residentSince": "2015-01-01",
    "birthCountry": "Bahamas",
    "birthDate": "1999-07-17",
    "employmentAuthorizationDocument": {
      "type": "EmploymentAuthorizationDocument",
      "identifier": "83627465",
      "lprCategory": "C09",
      "lprNumber": "999-999-999"
    }
  },
  "name": "Employment Authorization Document",
  "description": "Utopia Employment Authorization Document.",
  "issuer": {
    "id": "did:key:zDnaerPmH7xAjZoWanUBkRzY6xi9aTywRRoyAaHyRAsAYHCRq",
    "image": "data:image/png;base64,iVBORw0KGgoAA...CYII="
  },
  "renderMethod": [{
    "name": "Landscape",
    "mediaQuery": "@media (orientation: landscape)",
    "type": "SvgRenderingTemplate2024",
    "mediaType": "image/svg+xml",
    "template": "<svg ... svg>"
  },
  {
    "type": "NfcRenderingTemplate2024",
    "payload": "u2QUBqgGCGCF4H2h0dHBzOi8vdzNpZC5vcmcvY2l0aXplbnNoaXAvdjIYgngyRXhhbXBsZSBDb3VudHJ5IEVtcGxveW1lbnQgQXV0aG9yaXphdGlvbiBEb2N1bWVudC4YjIICeDF2Y3BsYXlncm91bmQub3JnL2NyZWRlbnRpYWwvUm1PeEpTSzV1RGVraFJ4dDVDdGtGGJZ4IUVtcGxveW1lbnQgQXV0aG9yaXphdGlvbiBEb2N1bWVudBidghh2GK4YyKkYnYIYuhiqGN6kGJwYrBj-aDgzNjI3NDY1GQEAY0MwORkBAms5OTktOTk5LTk5ORjkajIwMTUtMDEtMDEY5mVKQUNPQhjoZ0JhaGFtYXMY6moxOTk5LTA3LTE3GOxlU01JVEgY7mRNYWxlGPBkSk9IThjMghkEAVgjgCQDgb9kmpNghWHHT98J7T5rZTGYiWGuqBhxLKToK1mFxzwYzqYYnBhsGQEIGmbZ10oZAQoBGQEUGQEaGQEWWEF6Q_oLxTGzWdBhyCNmHR2AyXtP1b7DCgXkn5XJyCvSfT2bJMQVtdclHllKQ9aHA-_EMqW8icm3di-7xh1JU92UsBkBGIMZBAFYI4AkA4G_ZJqTYIVhx0_fCe0-a2UxmIlhrqgYcSyk6CtZhcc8WCOAJAOBv2Sak2CFYcdP3wntPmtlMZiJYa6oGHEspOgrWYXHPBjYGl3mUugY2hpwtkpo"
  }],
  "proof": {
    "type": "DataIntegrityProof",
    "created": "2024-09-12T19:57:43Z",
    "verificationMethod": "did:key:zDnaerPmH7xAjZoWanUBkRzY6xi9aTywRRoyAaHyRAsAYHCRq#zDnaerPmH7xAjZoWanUBkRzY6xi9aTywRRoyAaHyRAsAYHCRq",
    "cryptosuite": "ecdsa-rdfc-2019",
    "proofPurpose": "assertionMethod",
    "proofValue": "z3eWzCFM...rCjGrh"
  }
}

The payload above contains the following CBOR-LD data, which is a subset of the [=verifiable credential=] above without the large amounts of image data associated with the `issuer` and `image` properties. This results in a [=verifiable credential=] that is roughly 500 bytes in size and is thus easily transferred over NFC: 

1281({
  // @context
  1: [33, "https://w3id.org/citizenship/v2"],
  // type
  157: [118, 174],
  // name
  150: "Employment Authorization Document",
  // description
  130: "Utopia Employment Authorization Document.",
  // validFrom
  216: 1575375592,
  // validUntil
  218: 1890994792
  // credentialSubject
  200: {
    157: [186, 170],
    240: "JOHN"
    230: "JACOB",
    236: "SMITH",
    238: "Male",
    228: "2015-01-01",
    232: "Bahamas",
    234: "1999-07-17",
    // employmentAuthorizationDocument
    222: {
      156: 172,
      254: "83627465",
      256: "C09",
      258: "999-999-999"
    },
  },
  // proof
  206: {
    156: 108,
    264: 1725552458,
    280: [1025,
      h'80240381BF649A93608561C74FDF09ED3E6B6531988961AEA818712CA4E82B5985C73C',
      h'80240381BF649A93608561C74FDF09ED3E6B6531988961AEA818712CA4E82B5985C73C'
    ],
    266: 1,
    276: 282,
    278: h'7A43FA0BC531B359D061C823661D1D80C97B4FD5BEC30A05E49F95C9C82BD27D3D9B24C415B5D7251E594A43D68703EFC432A5BC89C9B7762FBBC61D4953DD94B0'
  },
})

When the [=verifier=] receives the payload above, it decodes the CBOR-LD back into JSON-LD, providing the uncompressed [=verifiable credential=] to be further processed by the [=verifier=]: 

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://w3id.org/citizenship/v2"
  ],
  "type": [
    "VerifiableCredential",
    "EmploymentAuthorizationDocumentCredential"
  ],
  "validFrom": "2019-12-03T12:19:52Z",
  "validUntil": "2029-12-03T12:19:52Z",
  "credentialSubject": {
    "type": [
      "Person",
      "EmployablePerson"
    ],
    "givenName": "JOHN",
    "additionalName": "JACOB",
    "familyName": "SMITH",
    "gender": "Male",
    "residentSince": "2015-01-01",
    "birthCountry": "Bahamas",
    "birthDate": "1999-07-17",
    "employmentAuthorizationDocument": {
      "type": "EmploymentAuthorizationDocument",
      "identifier": "83627465",
      "lprCategory": "C09",
      "lprNumber": "999-999-999"
    }
  },
  "name": "Employment Authorization Document",
  "description": "Utopia Employment Authorization Document.",
  "issuer": {
    "id": "did:key:zDnaerPmH7xAjZoWanUBkRzY6xi9aTywRRoyAaHyRAsAYHCRq",
  },
  "proof": {
    "type": "DataIntegrityProof",
    "created": "2024-09-12T19:57:43Z",
    "verificationMethod": "did:key:zDnaerPmH7xAjZoWanUBkRzY6xi9aTywRRoyAaHyRAsAYHCRq#zDnaerPmH7xAjZoWanUBkRzY6xi9aTywRRoyAaHyRAsAYHCRq",
    "cryptosuite": "ecdsa-rdfc-2019",
    "proofPurpose": "assertionMethod",
    "proofValue": "z3eWzCFM...rCjGrh"
  }
}

Interactive NFC Presentation

Interactive [=presentation=] over NFC is useful when a [=verifier=] needs to engage with a [=holder=] in a way that requires more than one message to be exchanged. Examples of this interaction pattern include a [=verifier=] providing a [=verifiable credential=] to the [=holder=] that demonstrates that the [=verifier=] has a legitimate need for the information that they are requesting. Another example using this interaction pattern is when the [=verifier=] desires to send a cryptographic challenge to the [=holder=] such that the [=holder=] can increase the confidence that the [=verifier=] has that the [=holder=] is the [=subject=] of the [=verifiable credential=] that has been requested.

An interactive NFC presentation starts with a [=interaction offer=] as described in Section [[[#interaction-offers]]] and then uses a [[[VC-API]]] workflow to perform the exchange. See Workflows and Exchanges in the [[[VC-API]]] for the specific messages exchanged between the NFC peers to achieve an interactive presentation.

An example interactive exchange is shown below for performing a DID-based authentication over NFC. 


// holder transmits interaction offer URL to verifier over NFC
https://interaction.example/interactions/123/request?nfc

// verifier acquires interaction offer response over NFC
{
  "protocols": {
    "nfc": true,
    "website": "https://website.example/interaction/123",
    "vcapi": [
      "btspp://00:11:22:33:FF:EE:97c44c80-5fcc-11ef-81a2-bf5f90ac9110",
      "WIFI:S:38f2bcc5a0b71;T:WPA;P:J3Klq9c2KlPPcJkwzU02K;;",
      "https://vcapi.example/workflows/z1A1FjMfnG/exchanges/z19mxakBFecZ",
    ],
    "otherRetailApi": "https://retail.example/checkout_api/763DAKX7diL5BFecZ"
  }
}

// verifier sends DIDAuthentication request over NFC using VC API protocol
{
  "query": [{
    "type": "DIDAuthentication",
    "acceptedMethods": [{"method": "example"}]
  }],
  "challenge": "99612b24-63d9-11ea-b99f-4f66f3e4f81a",
  "domain": "interaction.example"
}

// holder sends DIDAuthentication response over NFC using VC API protocol
{
  "@context": ["https://www.w3.org/ns/credentials/v2"],
  "type": "VerifiablePresentation",
  "holder": "did:example:12345",
  "proof": {
    "type": "DataIntegrityProof",
    "cryptosuite": "eddsa-rdfc-2022",
    "verificationMethod": "did:example:12345#key-1",
    "challenge": "99612b24-63d9-11ea-b99f-4f66f3e4f81a",
    "domain": "interaction.example",
    "created": "2024-02-25T14:58:42Z",
    "proofPurpose": "authentication",
    "proofValue": "z3FXQjecWufY46...UAUL5n2Brbx"
  }
}

Protocol Upgrades From NFC

An application that desires to share a [=verifiable presentation=] might detect that continuing over an NFC channel will create a bad experience for the [=holder=] due to NFC limitations such as bandwidth, transmission distance, or latency. In these instances, when starting from an NFC-based [=interaction offer=], it is possible to upgrade to a more ideal transmission medium.

In order to upgrade from NFC, an implementation merely does not include NFC options resulting in an [=interaction offer=] that looks similar to the following: 


// holder transmits interaction offer URL to verifier over NFC
https://interaction.example/interactions/123/request?nfc

// verifier acquires interaction offer response over NFC
{
  "protocols": {
    // holder forces an upgrade to Bluetooth
    "vcapi": "btspp://00:11:22:33:FF:EE:97c44c80-5fcc-11ef-81a2-bf5f90ac9110",
  }
}

// ... the rest of the workflow proceeds over Bluetooth

Verifiable Credentials Over Bluetooth

The Bluetooth protocol is used to wirelessly communicate between devices in a peer-to-peer fashion. It's range is typically limited to 10 meters or less based on the power levels used by the Bluetooth device. The following sections describe how Bluetooth can be used to request and receive verifiable credential presentations over Bluetooth using the [[[WEB-BLUETOOTH]]] specification.

Interactive Bluetooth Presentation

Interactive [=presentation=] over Bluetooth is useful when a [=verifier=] needs to engage with a [=holder=] in a way that requires more than one message to be exchanged. Examples of this interaction pattern include a [=verifier=] providing a [=verifiable credential=] to the [=holder=] that demonstrates that the [=verifier=] has a legitimate need for the information that they are requesting. Another example using this interaction pattern is when the [=verifier=] desires to send a cryptographic challenge to the [=holder=] such that the [=holder=] can increase the confidence that the [=verifier=] has that the [=holder=] is the [=subject=] of the [=verifiable credential=] that has been requested.

An interactive Bluetooth presentation starts with a [=interaction offer=] as described in Section [[[#interaction-offers]]] and then uses a [[[VC-API]]] workflow to perform the exchange. See Workflows and Exchanges in the [[[VC-API]]] for the specific messages exchanged between the Bluetooth peers to achieve an interactive presentation.

An example interactive exchange is shown below for performing a DID-based authentication over Bluetooth. 


// holder transmits interaction offer URL to verifier over NFC or QR Code
https://interaction.example/interactions/123/request?bt=btspp%3A%2F%2F00%3A11%3A22%3A33%3AFF%3AEE%3A97c44c80-5fcc-11ef-81a2-bf5f90ac9110

// verifier acquires interaction offer response over Bluetooth
{
  "protocols": {
    "nfc": true,
    "website": "https://website.example/interaction/123",
    "vcapi": [
      "btspp://00:11:22:33:FF:EE:97c44c80-5fcc-11ef-81a2-bf5f90ac9110",
      "WIFI:S:38f2bcc5a0b71;T:WPA;P:J3Klq9c2KlPPcJkwzU02K;;",
      "https://vcapi.example/workflows/z1A1FjMfnG/exchanges/z19mxakBFecZ",
    ],
    "otherRetailApi": "https://retail.example/checkout_api/763DAKX7diL5BFecZ"
  }
}

// verifier sends DIDAuthentication request over Bluetooth using VC API protocol
{
  "query": [{
    "type": "DIDAuthentication",
    "acceptedMethods": [{"method": "example"}]
  }],
  "challenge": "99612b24-63d9-11ea-b99f-4f66f3e4f81a",
  "domain": "interaction.example"
}

// holder sends DIDAuthentication response over Bluetooth using VC API protocol
{
  "@context": ["https://www.w3.org/ns/credentials/v2"],
  "type": "VerifiablePresentation",
  "holder": "did:example:12345",
  "proof": {
    "type": "DataIntegrityProof",
    "cryptosuite": "eddsa-rdfc-2022",
    "verificationMethod": "did:example:12345#key-1",
    "challenge": "99612b24-63d9-11ea-b99f-4f66f3e4f81a",
    "domain": "interaction.example",
    "created": "2024-02-25T14:58:42Z",
    "proofPurpose": "authentication",
    "proofValue": "z3FXQjecWufY46...UAUL5n2Brbx"
  }
}

Security Considerations

Before reading this section, readers are urged to familiarize themselves with general security advice provided in the Security Considerations section of the Verifiable Credential Data Model specification and the Security Considerations section of the Data Integrity specification.

Privacy Considerations

Before reading this section, readers are urged to familiarize themselves with general privacy advice provided in the Privacy Considerations section of the Verifiable Credential Data Model specification and the Privacy Considerations section of the Data Integrity specification.

Acknowledgements

The Working Group thanks the following individuals ...

Work on this specification has been supported by ...

Portions of the work on this specification have been funded by ...

The Working Group would like to thank the following individuals for reviewing and providing feedback on the specification (in alphabetical order): ...