Secure Credential Transfer

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 24 April 2022.¶

Copyright Notice

Copyright (c) 2021 IETF Trust and the persons identified as the document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.¶

Table of Contents

1. Introduction

Today, there is no standard way of transferring digital credentials securely between two devices belonging to the same platform or two different platforms. This document proposes a solution to this problem by introducing a Relay server which allows two devices to exchange encrypted Provisioning Information securely. The Relay server solves this problem by creating and managing temporary mailbox storage.¶

Each mailbox can be referenced by devices using a unique mailbox identifier in a URL. The URL pointing to encrypted Provisioning Information is to be passed between devices directly over various channels (e.g. SMS, email, messaging applications). The Security Considerations section provides recommendations on passing the URL and the Secret securely.¶

This document describes a Hypertext (HTTP) Application Programming Interface (API) that allows Sender and Receiver devices to interact with a Relay server in order to perform secure credential transfer.¶

2. Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

General terms:¶

• Relay Server - Web application exposing Secure Credential Transfer API to devices. It serves to securely transfer Provisioning Information between two devices (Sender and Receiver).¶
• Sender device - a device initiating a transfer of Provisioning Information to a Receiver device so that Receiver can register or provision this credential.¶
• Receiver device - a device that receives Provisioning Information from Sender device and uses it to register or provision Credential Information.¶
• Provisioning Partner - an entity which facilitates Credential Information lifecycle on a device. Lifecycle may include provisioning of credential, credential termination, credential update. API to Provisioning Partner is out of scope for this document.¶
• Provisioning Information - a set of data fields, allowing a device to generate Credential Information or receive it from Provisioning Partner and install it locally. The entire content of Provisioning Information is encrypted by Sender or Receiver device. Therefore, it is not visible to the Relay Server. The structure of Provisioning Information is specific to Provisioning Partner or type of Credential and out of the scope of this document.¶
• Credential Information - a set of data fields used to facilitate registration or provisioning of Credential Information on the Receiver's device.¶
• Secret - a symmetric encryption key shared by a pair of Sender and Receiver devices, used to encrypt Provisioning Information stored on a the Relay server. Secret stays the same for the entire credential transfer flow (one Secret per complete transfer). Provisioning Information stored on Relay server is always encrypted using the Secret. In Stateful flow all information exchanged by Sender and Receiver devices through Relay server is encrypted with the same Secret. Thus, effectively, Secret has a one-to-one relation with the mailbox.¶

API parameters:¶

• Device Claim - a unique token allowing the caller to read from / write data to the mailbox. Exactly one Sender device and one Receiver device should be able to read from / write secure payload to the mailbox. Sender device provides a Device Claim in order to create a mailbox. When the Relay server, having received a request from the Sender device, creates a mailbox, it binds this Sender's Device Claim to the mailbox. When the Receiver device first reads data from the mailbox it presents its Device Claim to the Relay Server, which binds the mailbox to the given Receiver device. Thus both Sender and Receiver devices are bound to the mailbox (allowed to read from / write to it). Only Sender and Receiver devices that present valid Device Claims are allowed to send subsequent read/update/delete calls to the mailbox. The value shall be a UUID [RFC4122].¶
• Notification Token - a short or long-lived unique token stored by the Sender or Receiver device in a mailbox on the Relay server, which allows Relay server to send a push notification to the Sender or Receiver device, informing them of updates in the mailbox.¶
• MailboxIdentifier - Sender device-defined unique identifier for the given mailbox. The value shall be a UUID [RFC4122].¶

3. Credential transfer workflows

We define two flows for credential transfer: 1. Stateless (Relay server facilitates a single credential data transfer: Sender -> Relay -> Receiver) and 2. Stateful (Relay facilitates additional data transfers - there are multiple data transfers in this flow to prepare credential data for registering or provisioning by Receiver). The details are provided below.¶

Both stateless and stateful share the following common steps. The processes start with a Sender device composing a set of Provisioning Information, encrypting it with a Secret and storing encrypted Provisioning Information on a Relay server in a mailbox. A unique Mailbox Identifier is generated by the Sender device, created using a good source of entropy (preferrably hardware-based entropy). Sender device generates a unique token - a Sender Device Claim - and stores it to the mailbox. Device Claim allows the Sender device presenting it to read and write data to / from the mailbox, thus binding it to the mailbox.¶

Sender device sends MailboxIdentifier to the Relay server as a part of CreateMailbox request. Once a mailbox is created, it has limited time to live. When expired, the mailbox shall be deleted - refer to DeleteMailbox endpoint. TimeToLive mailbox configuration in the request is required to use with the CreateMailbox call (refer to mailboxConfiguration request parameter).¶

Relay server builds a unique URL link to a mailbox (for example, "http://relayserver.com/m/1234567890") and returns it to the Sender device, which sends the link directly to the Receiver device over communication channel (e.g. SMS, email, iMessage). Please refer to section "Security Considerations" for more details.¶

Receiver device, having obtained both the URL link and the Secret, generates a unique token - a Receiver Device Claim - and passes it to the Relay server in order to read the encrypted Provisioning Information from the mailbox.¶

Relay server now binds a given pair of Sender and Receiver devices to the mailbox by provided Sender and Receiver Device Claims. Only bound devices are allowed to read or write data to the mailbox or to delete the mailbox.¶

                      Sender              Relay                          Receiver
                        |                   |                               |
    Create and encrypt  |                   |                               |
    Provisioning Info   |——---------------->|                               |
                        |    CreateMailbox  |                               |
                        |<------------------|                               |
                        |URL link to mailbox|                               |
    Send URL link       |                   |                               |
    and Secret          |-------------------------------------------------->|
                        |                   | ReadSecureContent FromMailbox |
                        |                   |<------------------------------|
                        |                   |                               | Decrypt Provisioning Info with Secret
                        |                   |<------------------------------|
                        |                   |     DeleteMailbox             | Provision credentials

                     Sender                       Relay                     Receiver
                        |                            |                            |
    Create and encrypt  |    CreateMailbox           |                            |
    Provisioning Info 1 |--------------------------->|                            |
                        |    encrypted info          |                            |
                        |<---------------------------|                            |
                        |   URL link to mailbox      |                            |
                        |                            |                            |
    Send URL link       |-------------------------------------------------------->|
    and Secret          |                            |ReadSecureContentFromMailbox|
                        |                            |                            |
                        |                            |<---------------------------| Decrypt w Secret
                        |                            |    encrypted info          |
                        |                            |    UpdateMailbox           | ProvInfo 2 = new Provisioning Info,
                        |                            |<---------------------------| encrypted info =
                        |ReadSecureContentFromMailbox|       encrypted info       | encrypt(ProvInfo2)
                        |                            |                            | with Secret
    ProvInfo 3 = new    |--------------------------->|                            |
    ProvisioningInfo    |       encrypted info       |                            |
    encrypted info =    |                            |                            |
    encrypt(ProvInfo3)  |—-----------—-------------->|ReadSecureContentFromMailbox|
    with Secret         |    encrypted info          |                            |
                        |                            |<---------------------------| Decrypt(ProvInfo3)
                        |                            |  encrypted info            |
                        |                            |<---------------------------|
                        |                            |   DeleteMailbox            | Provision or Register credentials

4. API connection details

The Relay server API endpoint MUST be accessed over HTTP using an https URI [RFC2818] and SHOULD use the default https port. Request and response bodies shall be formatted as either JSON or HTML (based on the API endpoint). The communication protocol used for all interfaces shall be HTTPs. All Strings SHOULD be UTF-8 encoded (Unicode Normalization Form C (NFC)). An API version SHOULD be included in the URI for all interfaces. The version at the time of this document's latest update is v1. The version shall be incremented by 1 for major API changes or backward incompatible iterations on existing APIs.¶

5. HTTP Headers: Mailbox-Correlation-ID

All requests to and from Relay server will have an HTTP header "Mailbox-Correlation-ID". The corresponding response to the API will have the same HTTP header, which SHOULD echo the value in the request header. This is used to identify the request associated to the response for a particular API request and response pair. The value SHOULD be a UUID [RFC4122]. The request originator shall match the value of this header in the response with the one sent in the request. If response is not received, caller may retry sending the request with the same value of "Mailbox-Correlation-ID". Relay server SHOULD store the value of the last successfully processed "Mailbox-Correlation-ID" for each device based on the caller's Device Claim. A key-value pair of "Device Claim" to "Mailbox-Correlation-ID" is suggested to store the last successfully processed request for each device. In case of receiving a request with duplicated "Mailbox-Correlation-ID", Relay SHOULD respond to the caller with status code 201, ignoring the duplicate request body content.¶

6. HTTP access methods

{
   "notificationToken": {
        "name":"com.apple.apns",
        "tokenData":"APNS1234...QW"
    }
}

{    "mailboxIdentifier" : "12345678-9...A-BCD",
    "displayInformation" : {
        "title" : "Hotel Pass",
        "description" : "Some Hotel Pass",
        "imageURL" : "https://hotel.com/sharingImage"
    },
    "payload" : {
        "type": "AES128",
        "data": "FDEC...987654321"
    },
    "notificationToken" : {
        "type" : "com.apple.apns",
        "tokenData" : “APNS...1234"
    },
    "mailboxConfiguration" : {
        "accessRights" : "RWD",
        "timeToLive" : "8640”
    }
}

{
    "urlLink":"relayserver.com/m/12345678-9...A-BCD"
}

{
     "payload" : {
        "type": "AES128",
        "data": "FDEC...987654321"
    },
    "notificationToken":{
        "type" : "com.apple.apns",
        "tokenData" : “APNS...1234"
    }
}

    "<html prefix="og: https://ogp.me/ns#">
     <head>
     <title>Hotel Pass</title>
     <meta property="og:title" content="Hotel Pass" />
     <meta property="og:type" content="image/jpeg" />
     <meta property="og:description" content="Some Hotel Pass" />
     <meta property="og:url" content="share://" />
     <meta property="og:image" content="https://website.com/photos/photo.jpg" />
     <meta property="og:image:width" content="612" />
     <meta property="og:image:height" content="408" /></head>
     </html>"

{
    “displayInformation" : {
        "title" : "Hotel Pass",
        "description" : "Some Hotel Pass",
        "imageURL" : "https://hotel.com/sharingImage"
    },
    "payload" : {
        "type": "AES128",
        "data": "FDEC...987654321"
    }
}

7. Encryption format

The encrypted payload (Provisioning Information) should be a data structure having the following key-value pairs: "type", which defines the encryption algorithm and mode used and "data", which contains BASE-64 encoded binary value of ciphertext.¶

Currently proposed "type" includes the following algorithm and mode:¶

• "AES128": AES symmetric encryption algorithm with key length 128 bits, in GCM mode with no padding. Initialization Vector (IV) has the length of 96 bits randomly generated and tag length of 128 bits. The IV shall be prepended to the payload, and the tag shall be appended to the payload before sending (the resulting format is IV || encrypted payload || tag). Please refer to [NIST-SP800-38D] for the details of the encryption algorithm.¶
• "AES256": AES symmetric encryption algorithm with key length 256 bits, in GCM mode with no padding. Initialization Vector (IV) has the length of 96 bits randomly generated and tag length of 128 bits. The IV shall be prepended to the payload, and the tag shall be appended to the payload before sending (the resulting format is IV || encrypted payload || tag). Please refer to [NIST-SP800-38D] for the details of the encryption algorithm.¶

{
    "type" : "AES128",
    "data" : "IV  ciphertext  tag"
}

8. Security Considerations

The following threats and mitigations have been considered: - Sender shares with the wrong receiver - Sender should be encouraged to share Secret over a channel allowing authentication of the receiver (e.g. voice). - Provisioning Partners shall allow senders to cancel existing shares. - Malicious receiver forwards the share to 3rd party without redeeming it or the Receiver's device is compromised. - No mitigation, the Sender should only share with receivers they trust. - Malicious receiver attempts re-use share - Provisioning Partners shall ensure that the Provisioning Information of a share can only be redeemed once. - Share URL accidental disclosure. (e.g. share URL sent as a message which gets displayed on a locked screen) - Knowledge of Secret is required to access Provisioning Information and it should have been sent in a separate channel. - Device Claim is required (if sender and receiver have already both contacted the Relay server) - Network attacks - Machine-in-the-middle - Relay server shall only allow TLS connections - URLs displayed to user should include the https scheme - MailboxIdentifier guessing - The MailboxIdentifier is a version 4 UUID [RFC4122] which should contain 122-bits of cryptographic entropy, making brute-force attacks impractical¶

“http://relayserver.com/v1/{mailboxIdentifier}#{Secret}”

9. IANA Considerations

This document has no IANA actions.¶

Appendix A. Acknowledgments

TODO acknowledge.¶

Authors' Addresses