# Aries RFC 0xxx: Device Binding 0.1

- Authors: [Paul Bastian]([e-mail])
- Status: [PROPOSED](/README.md#proposed)
- Since: 2022-02-21
- Start Date: 2022-02-21
- Tags: [feature](/tags.md#feature), [protocol](/tags.md#protocol)

## Summary

Describe a standard way for issuers and holders to perform a device binding preliminary to the issuance process.

## Motivation

Device Binding is a building block for the wallet security that enables a high level in the differential credential security model by anchoring a hardware-generated public key to the credential. This hardware-generated key might originate from TEE, SecureEnclave, Secure Elements or TPMs. Device binding is always to be understood as an optional feature for improved wallet security. Device binding is intended to fulfill higher requirements for regulated use cases.

## Tutorial

This protocol provides an implementable process for the specification and guidance provided by the DIF Wallet Security working group and its device binding work item.

### Roles

There are two roles in this protocol: the Issuer requesting and validating the device binding and the Holder generating and providing the hardware-backed key and additional meta information. The control flow is stateless.

### Messages

This protocol defines two messages:
- device binding request
- device binding response

#### Device Binding Request

The device binding interaction begins with the Issuer sending a request with the following schema:

{
  "@type": "https://didcomm.org/devicebinding/1.0/request",
  "@id": "518be002-de8e-456e-b3d5-8fe472477a86",
  "comment" : "some comment",
  "requests" : [
    {
      "acceptedKeyStorage" : [
        "TEE",
        "Strongbox",
        "SecureEnclave",
        "SecureElement"
      ],
      "nonce": "9F200A1BB4381330C0d722C38DFAB1B8"
    }
  ]
}  

Description:
`@type` : DIDComm protocol identifier
`@id` : Identifier of the message
`comment` : Human readable comment
`requests` : Array of device binding requests
`requests.acceptedKeyStorage` : Ordered list of references to key store mechanisms accepted and preferred by the issuer

#### Device Binding Response

The Holder can process the device binding request and repond with the following schema:

{
  "@type": "https://didcomm.org/devicebinding/1.0/response",
  "@id": "d9390ce2-8ba1-4544-9596-9870065ad08a",
  "comment" : "some comment",
  "responses" : [
    {
      "keyStorageType" : "TEE_v1"
      "id" : <attach@id value>
    }
  ],
  "responses~attach" : [
    {
      "@id" : "<TEE_v1 attachment identifier>",
      "mime-type" : application/json,
      "data" : {
        "androidCertificateChain" : <base64-encoded/ASCII-armored certificates>
        "keyChallengeSignature" : <base64-encoded ECDSA signature result>
      }
    }
  ]
}  

**todo**: define attachments for iOS and SecureElement

The usage and further processing of the hardware-backed key material might differentiate. The following are suggestions:
- for W3C Verifiable credentials: use the hardware-secured key as `did:key:<multibasekey>` in the `proof.verificationMethod` attribute
- for AnonCreds: credentials: use the hardware-secured key as `did:key:<multibasekey>` in a standardized attribute with name `hardwareDid`

The latter can be proven together with a Present Proof v1/2 with the following complementary DIDComm messages:

#### Device Binding Proof Request

{
  "@type": "https://didcomm.org/devicebinding/1.0/proof-request",
  "@id": "518be002-de8e-456e-b3d5-8fe472477a86",
  "comment" : "some comment",
  "requests" : [
    {
      "keyId" : "did:key:<multibasekey>"
      "nonce": "30C0d722C38DFAB1B89F200A1BB43813"
    }
  ]
}  

#### Device Binding Proof Response

{
  "@type": "https://didcomm.org/devicebinding/1.0/proof-response",
  "@id": "518be002-de8e-456e-b3d5-8fe472477a86",
  "comment" : "some comment",
  "requests" : [
    {
      "keyId" : "did:key:<multibasekey>"
      "signature": "2f5a8d15f64199ac961fa207212814429065f9a6a044391f0526c215eed194e0"
    }
  ]
}  

## Implementations

The following lists the implementations (if any) of this RFC. Please do a pull
request to add your implementation. If the implementation is open source,
include a link to the repo or to the implementation within the repo. Please be
consistent in the "Name" field so that a mechanical processing of the RFCs can
generate a list of all RFCs supported by an Aries implementation.

Name / Link | Implementation Notes
--- | ---