idnits 2.17.00 (12 Aug 2021) /tmp/idnits5055/draft-secure-credential-transfer-03.txt: -(286): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(369): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(1241): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(1248): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == There are 9 instances of lines with non-ascii characters in the document. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 81 instances of too long lines in the document, the longest one being 46 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 481 has weird spacing: '...hertext tag"...' == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'SHALL not' in this paragraph: 201 Status: "201" (Created) - response to a duplicated request (duplicated "Mailbox-Request-Id"). Relay server SHALL respond to duplicated requests with 201 without creating a new mailbox. "Mailbox-Request-Id" passed in the first CreateMailbox request's header SHOULD be stored by the Relay server and compared to the same value in the subsequent requests to identify duplicated requests. If duplicate is found, Relay SHALL not create a new mailbox, but respond with 201 instead. The value of "Mailbox-Request-Id" of the last successfully completed request SHOULD be stored based on the Device Claim passed by the caller. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'SHALL not' in this paragraph: 201 Status: "201" (Created) - response to a duplicate request (duplicate "Mailbox-Request-Id"). Relay server SHALL respond to duplicate requests with 201 without performing mailbox update. "Mailbox-Request-Id" passed in the first UpdateMailbox request's header SHALL be stored by the Relay server and compared to the same value in the subsequent requests to identify duplicate requests. If duplicate is found, Relay SHALL not perform mailbox update, but respond with 201 instead. The value of "Mailbox-Request-Id" of the last successfully completed request SHALL be stored based on the Device Claim passed by the caller. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'SHALL not' in this paragraph: 201 Status: "201" (Created) - response to a duplicate request (duplicate "Mailbox-Request-Id"). Relay server SHALL respond to duplicate requests with 201 without performing mailbox relinquish. "Mailbox-Request-Id" passed in the first RelinquishMailbox request's header SHALL be stored by the Relay server and compared to the same value in the subsequent requests to identify duplicate requests. If duplicate is found, Relay SHALL not perform mailbox relinquish, but respond with 201 instead. The value of "Mailbox-Request-Id" of the last successfully completed request SHALL be stored based on the Device Claim passed by the caller. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'SHALL not' in this paragraph: * The value of DeviceAttestation header parameter SHALL not contain information allowing the identification of the device providing it. It SHOULD also be different for every new share to prevent the Relay server from correlating different sharing. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'SHOULD not' in this paragraph: * Display Information is not encrypted, therefore, it SHOULD not contain any information allowing to identify Sender or Receiver devices. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: * Relay server MUST not receive the Secret with the MailboxIdentifier at any time. -- The document date (7 January 2022) is 127 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'CCC-Digital-Key-30' is defined on line 1240, but no explicit reference was found in the text == Unused Reference: 'ISO-18013-5' is defined on line 1246, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'CCC-Digital-Key-30' -- Possible downref: Non-RFC (?) normative reference: ref. 'ISO-18013-5' Summary: 1 error (**), 0 flaws (~~), 10 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 TODO Working Group D. Vinokurov 3 Internet-Draft M. Byington 4 Intended status: Standards Track M. Lerch 5 Expires: 11 July 2022 A. Pelletier 6 Apple Inc 7 N. Sha 8 Alphabet Inc 9 7 January 2022 11 Secure Credential Transfer 12 draft-secure-credential-transfer-03 14 Abstract 16 This document describes a mechanism to transfer digital credentials 17 securely between two devices. Secure credentials may represent a 18 digital key to a hotel room, a digital key to a door lock in a house 19 or a digital key to a car. Devices that share credentials may belong 20 to the same or two different platforms (e.g. iOS and Android). 21 Secure transfer may include one or more write and read operations. 22 Credential transfer needs to be performed securely due to the 23 sensitive nature of the information. 25 Discussion Venues 27 This note is to be removed before publishing as an RFC. 29 Source for this draft and an issue tracker can be found at 30 https://github.com/dimmyvi/secure-credential-transfer. 32 Status of This Memo 34 This Internet-Draft is submitted in full conformance with the 35 provisions of BCP 78 and BCP 79. 37 Internet-Drafts are working documents of the Internet Engineering 38 Task Force (IETF). Note that other groups may also distribute 39 working documents as Internet-Drafts. The list of current Internet- 40 Drafts is at https://datatracker.ietf.org/drafts/current/. 42 Internet-Drafts are draft documents valid for a maximum of six months 43 and may be updated, replaced, or obsoleted by other documents at any 44 time. It is inappropriate to use Internet-Drafts as reference 45 material or to cite them other than as "work in progress." 47 This Internet-Draft will expire on 11 July 2022. 49 Copyright Notice 51 Copyright (c) 2022 IETF Trust and the persons identified as the 52 document authors. All rights reserved. 54 This document is subject to BCP 78 and the IETF Trust's Legal 55 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 56 license-info) in effect on the date of publication of this document. 57 Please review these documents carefully, as they describe your rights 58 and restrictions with respect to this document. Code Components 59 extracted from this document must include Revised BSD License text as 60 described in Section 4.e of the Trust Legal Provisions and are 61 provided without warranty as described in the Revised BSD License. 63 Table of Contents 65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 66 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 67 3. Credential transfer workflows . . . . . . . . . . . . . . . . 6 68 3.1. Stateless workflow . . . . . . . . . . . . . . . . . . . 7 69 3.2. Stateful workflow . . . . . . . . . . . . . . . . . . . . 7 70 3.3. Provisioning Information Structure . . . . . . . . . . . 9 71 3.3.1. Provisioning Information Format . . . . . . . . . . . 10 72 3.3.2. Provisioning Information Encryption . . . . . . . . . 11 73 3.4. Share URL . . . . . . . . . . . . . . . . . . . . . . . . 12 74 3.4.1. Credential Vertical in Share URL . . . . . . . . . . 13 75 4. API connection details . . . . . . . . . . . . . . . . . . . 14 76 5. HTTP Headers: Mailbox-Request-ID . . . . . . . . . . . . . . 14 77 6. HTTP access methods . . . . . . . . . . . . . . . . . . . . . 14 78 6.1. CreateMailbox . . . . . . . . . . . . . . . . . . . . . . 14 79 6.1.1. Endpoint . . . . . . . . . . . . . . . . . . . . . . 15 80 6.1.2. Request Parameters: . . . . . . . . . . . . . . . . . 15 81 6.1.3. Consumes . . . . . . . . . . . . . . . . . . . . . . 15 82 6.1.4. Produces . . . . . . . . . . . . . . . . . . . . . . 15 83 6.1.5. Request body . . . . . . . . . . . . . . . . . . . . 15 84 6.1.6. Responses . . . . . . . . . . . . . . . . . . . . . . 17 85 6.2. UpdateMailbox . . . . . . . . . . . . . . . . . . . . . . 18 86 6.2.1. Endpoint . . . . . . . . . . . . . . . . . . . . . . 18 87 6.2.2. Request Parameters . . . . . . . . . . . . . . . . . 18 88 6.2.3. Consumes . . . . . . . . . . . . . . . . . . . . . . 19 89 6.2.4. Produces . . . . . . . . . . . . . . . . . . . . . . 19 90 6.2.5. Request body . . . . . . . . . . . . . . . . . . . . 19 91 6.2.6. Responses . . . . . . . . . . . . . . . . . . . . . . 20 92 6.3. DeleteMailbox . . . . . . . . . . . . . . . . . . . . . . 21 93 6.3.1. Endpoint . . . . . . . . . . . . . . . . . . . . . . 21 94 6.3.2. Request Parameters . . . . . . . . . . . . . . . . . 21 95 6.3.3. Responses . . . . . . . . . . . . . . . . . . . . . . 21 96 6.4. ReadDisplayInformationFromMailbox . . . . . . . . . . . . 22 97 6.4.1. Endpoint . . . . . . . . . . . . . . . . . . . . . . 22 98 6.4.2. Request Parameters . . . . . . . . . . . . . . . . . 22 99 6.4.3. Produces . . . . . . . . . . . . . . . . . . . . . . 22 100 6.4.4. Responses . . . . . . . . . . . . . . . . . . . . . . 22 101 6.5. ReadSecureContentFromMailbox . . . . . . . . . . . . . . 23 102 6.5.1. Endpoint . . . . . . . . . . . . . . . . . . . . . . 23 103 6.5.2. Request Parameters . . . . . . . . . . . . . . . . . 23 104 6.5.3. Produces . . . . . . . . . . . . . . . . . . . . . . 23 105 6.5.4. Responses . . . . . . . . . . . . . . . . . . . . . . 24 106 6.6. RelinquishMailbox . . . . . . . . . . . . . . . . . . . . 25 107 6.6.1. Endpoint . . . . . . . . . . . . . . . . . . . . . . 25 108 6.6.2. Request Parameters . . . . . . . . . . . . . . . . . 25 109 6.6.3. Responses . . . . . . . . . . . . . . . . . . . . . . 25 110 7. Security Considerations . . . . . . . . . . . . . . . . . . . 26 111 7.1. Sender/Receiver privacy . . . . . . . . . . . . . . . . . 27 112 7.2. Credential's confidentiality and integrity . . . . . . . 27 113 7.3. Second factor authentication for Receiver credential 114 provisioning . . . . . . . . . . . . . . . . . . . . . . 28 115 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 28 116 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 29 117 9.1. Normative References . . . . . . . . . . . . . . . . . . 29 118 9.2. Informative References . . . . . . . . . . . . . . . . . 29 119 Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 30 120 Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 30 121 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 30 123 1. Introduction 125 Today, there is no standard way of transferring digital credentials 126 securely between two devices belonging to the same platform or two 127 different platforms. This document proposes a solution to this 128 problem by introducing a Relay server which allows two devices to 129 exchange encrypted Provisioning Information securely. The Relay 130 server solves this problem by creating and managing temporary mailbox 131 storage. 133 Each mailbox can be referenced by devices using a unique mailbox 134 identifier in a URL. The URL pointing to encrypted Provisioning 135 Information is to be passed between devices directly over various 136 channels (e.g. SMS, email, messaging applications). The Security 137 Considerations section provides recommendations on passing the URL 138 and the Secret securely. 140 This document describes a Hypertext (HTTP) Application Programming 141 Interface (API) that allows Sender and Receiver devices to interact 142 with a Relay server in order to perform secure credential transfer. 144 2. Terminology 146 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 147 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 148 "OPTIONAL" in this document are to be interpreted as described in 149 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 150 capitals, as shown here. 152 General terms: 154 * Relay Server - Web application exposing Secure Credential Transfer 155 API to devices. It serves to securely transfer Provisioning 156 Information between two devices (Sender and Receiver). 158 * Sender device - a device initiating a transfer of Provisioning 159 Information to a Receiver device so that Receiver can register or 160 provision this credential. 162 * Receiver device - a device that receives Provisioning Information 163 from Sender device and uses it to register or provision Credential 164 Information. 166 * Provisioning Partner - an entity which facilitates Credential 167 Information lifecycle on a device. Lifecycle may include 168 provisioning of credential, credential termination, credential 169 update. API to Provisioning Partner is out of scope for this 170 document. 172 * Provisioning Information - a set of data fields, allowing a device 173 to generate Credential Information or receive it from Provisioning 174 Partner and install it locally. The entire content of 175 Provisioning Information is encrypted by Sender or Receiver 176 device. Therefore, it is not visible to the Relay Server. The 177 structure of Provisioning Information is specific to Provisioning 178 Partner or type of Credential and out of the scope of this 179 document. 181 * Credential Information - a set of data fields used to facilitate 182 registration or provisioning of Credential Information on the 183 Receiver's device. 185 * Secret - a symmetric encryption key shared by a pair of Sender and 186 Receiver devices, used to encrypt Provisioning Information stored 187 on the Relay server. Secret stays the same for the entire 188 credential transfer flow (one Secret per complete transfer). 189 Provisioning Information stored on Relay server is always 190 encrypted using the Secret. In Stateful flow all information 191 exchanged by Sender and Receiver devices through Relay server is 192 encrypted with the same Secret. Thus, effectively, Secret has a 193 one-to-one relation with the mailbox. 195 * Credential Vertical - The broad industry vertical that the 196 credential belongs to. For example, the credential could belong 197 to the car or home vertical. 199 API parameters: 201 * Device Claim - a unique token allowing the caller to read from / 202 write data to the mailbox. Exactly one Sender device and one 203 Receiver device SHOULD be able to read from / write secure payload 204 to the mailbox. Sender device provides a Device Claim in order to 205 create a mailbox. When the Relay server, having received a 206 request from the Sender device, creates a mailbox, it binds this 207 Sender's Device Claim to the mailbox. When the Receiver device 208 first reads data from the mailbox it presents its Device Claim to 209 the Relay Server, which binds the mailbox to the given Receiver 210 device. Thus, both Sender and Receiver devices are bound to the 211 mailbox (allowed to read from / write to it). Only Sender and 212 Receiver devices that present valid Device Claims are allowed to 213 send subsequent read/update/delete calls to the mailbox. The 214 value SHALL be a UUID [RFC4122]. 216 * Notification Token - a short or long-lived unique token stored by 217 the Sender or Receiver device in a mailbox on the Relay server, 218 which allows Relay server to send a push notification to the 219 Sender or Receiver device, informing them of updates in the 220 mailbox. 222 * MailboxIdentifier - a unique identifier for the given mailbox, 223 generated by the Relay server at the time of mailbox creation. 224 The value \ be a UUID [RFC4122]. 226 3. Credential transfer workflows 228 We define two flows for credential transfer: 1. Stateless (Relay 229 server facilitates a single credential data transfer: Sender -> Relay 230 -> Receiver) and 2. Stateful (Relay server facilitates additional 231 data transfers - there are multiple data transfers in this flow to 232 prepare credential data for registering or provisioning by Receiver). 233 Relay server does not limit the number of such data tranfsfers 234 between Sender and Receiver devices. The details are provided below. 236 Both stateless and stateful share the following common steps. The 237 processes start with a Sender device composing a set of Provisioning 238 Information, encrypting it with a Secret and storing encrypted 239 Provisioning Information on a Relay server in a mailbox. A unique 240 Mailbox Identifier is generated by the Relay server as a part of 241 CreateMailbox call, created using a good source of entropy 242 (preferably hardware-based entropy). Sender device generates a 243 unique token - a Sender Device Claim - and stores it to the mailbox. 244 Device Claim allows the Sender device presenting it to read and write 245 data to / from the mailbox, thus binding it to the mailbox. 247 Sender device calls CreateMailbox API endpoint on a Relay server in 248 order to create a mailbox. Once a mailbox is created, it has limited 249 time to live. When expired, the mailbox SHALL be deleted - refer to 250 DeleteMailbox endpoint. TimeToLive mailbox configuration in the 251 request is required to use with the CreateMailbox call (refer to 252 mailboxConfiguration request parameter). Relay server is responsible 253 to periodically check for mailboxes with expired TimeToLive and 254 delete them. 256 Relay server builds a unique URL link to a mailbox (for example, 257 "http://relayserver.com/m/1234567890") and returns it to the Sender 258 device, which sends the link directly to the Receiver device over 259 communication channel (e.g. SMS, email, iMessage). Please refer to 260 section "Security Considerations" for more details. 262 Receiver device, having obtained both the URL link and the Secret, 263 generates a unique token - a Receiver Device Claim - and passes it to 264 the Relay server in order to read the encrypted Provisioning 265 Information from the mailbox. 267 Relay server now binds a given pair of Sender and Receiver devices to 268 the mailbox by provided Sender and Receiver Device Claims. Only 269 bound devices are allowed to read or write data to the mailbox or to 270 delete the mailbox. 272 3.1. Stateless workflow 274 The stateless workflow completes the common steps described in 275 "Credential transfer workflows" section, then finishes the transfer 276 completing the following steps. Receiver device, having read the 277 encrypted Provisioning Information from the Relay mailbox, decrypts 278 it with the Secret received from the Sender and starts credential 279 registering or provisioning process on the device. Once the Receiver 280 device has successfully provisioned credentials, it deletes the 281 mailbox by sending a DeleteMailbox call to the Relay server. 283 Sender Relay Receiver 284 | | | 285 Create mailbox w | CreateMailbox | | 286 Provisioning Info |——---------------->| | 287 encrypted w Secret |<<-.-.-.-.-.-.-.-.-| | 288 |URL link to mailbox| | 289 | | | 290 Send URL link to | | URL link and Secret | 291 mailbox and Secret |-------------------------------------------------->| 292 | | | 293 | | ReadSecureContentFromMailbox | 294 | |<------------------------------| 295 | |-.-.-.-.-.-.-.-.-.-.-.-.-.-.->>| Decrypt w Secret to get Prov Info 296 | | encrypted info | 297 | | | 298 | | DeleteMailbox | 299 | |<------------------------------| Provision or Register credentials 300 | |-.-.-.-.-.-.-.-.-.-.-.-.-.-.->>| 301 | | OK | 303 Figure 1: Sample stateless workflow 305 3.2. Stateful workflow 307 The stateful workflow completes the common steps described in 308 "Credential transfer workflows" section, then finishes the transfer 309 completing the following steps. 311 Then the Receiver device, having downloaded the encrypted 312 Provisioning Information from the mailbox by URL and decrypted it 313 with the Secret, generates a new structure of Provisioning 314 Information, e.g. a digital key, and encrypts it with the same 315 Secret, received from the Sender device. It then stores the payload 316 in the same mailbox on the Relay server. In addition to the 317 encrypted payload, Receiver stores a Receiver Notification Token in 318 the given mailbox. 320 Having received the encrypted Provisioning Information, the Relay 321 server sends a Notification to the Sender device using the Sender 322 Notification Token. 324 Sender device, having received the notification from the Relay 325 server, reads secure content from the mailbox and decrypts all using 326 the same Secret. Sender device generates new Provisioning 327 Information, encrypts all fields using the Secret and stores all data 328 in the same mailbox on the Relay server. 330 Relay server, having stored the data above, sends a notification to 331 the Receiver device using Receiver Notification Token. Receiver 332 device, having received the notification, reads the encrypted 333 Provisioning Information, decrypts the data using the same Secret and 334 uses this data to finalize credential registration or provisioning on 335 device. 337 Once the Receiver device has successfully registered or provisioned 338 credentials, it deletes the mailbox by sending a DeleteMailbox call 339 to the Relay server. Sender device may terminate the secure 340 credential transfer by deleting the mailbox it created at any time. 341 Deletion of the mailbox on the Relay server stops any on-going 342 credential transfer process. 344 Sender Relay Receiver 345 | | | 346 Create and encrypt | CreateMailbox | | 347 Provisioning Info 1|---------------------------->| | 348 encrypted w Secret |<<-.-.-.-.-.-.-.-.-.-.-.-.-.-| | 349 | URL link to mailbox | | 350 | | | 351 | | URL link and Secret | 352 Send URL link to |---------------------------------------------------------->| 353 mailbox and Secret | | | 354 | |ReadSecureContentFromMailbox | 355 | |<----------------------------| 356 | |-.-.-.-.-.-.-.-.-.-.-.-.-.->>| Decrypt w Secret for ProvInfo1 357 | | encrypted info | 358 | | | 359 | |UpdateMailbox(encrypted info)| Update with ProvInfo2 360 | |<----------------------------| encrypted with Secret 361 | |-.-.-.-.-.-.-.-.-.-.-.-.-.->>| ProvInfo2 = new Provisioning Info 362 | | OK | 363 |ReadSecureContentFromMailbox | | 364 |---------------------------->| | 365 Decrypt w Secret to |<<-.-.-.-.-.-.-.-.-.-.-.-.-.-| | 366 get ProvInfo2 | encrypted info | | 367 | | | 368 |UpdateMailbox(encrypted info)| | 369 Update w ProvInfo3 |—-----------—--------------->| | 370 encrypted w Secret |<<-.-.-.-.-.-.-.-.-.-.-.-.-.-|ReadSecureContentFromMailbox | 371 ProvInfo3 = new | OK |<----------------------------| 372 Provisioning Info | |-.-.-.-.-.-.-.-.-.-.-.-.-.->>| Decrypt w Secret for ProvInfo3 373 | | encrypted info | 374 | | | 375 | | DeleteMailbox | 376 | |<----------------------------| Provision or Register credentials 377 | |-.-.-.-.-.-.-.-.-.-.-.-.-.->>| 378 | | OK | 380 Figure 2: Sample stateful workflow 382 3.3. Provisioning Information Structure 384 The Provisioning Information is the data transfered via the Relay 385 Server between the Sender device and Receiver device. Each use case 386 defines its own specalized Provisioning Information format, but all 387 formats must at least adhear to the following structure. Formats are 388 free to define new top level keys, so clients shouldn't be surprised 389 if a message of an unexpected format has specalized top level keys. 391 +=============+============+==================================+ 392 | Key | Type | Description | 393 +=============+============+==================================+ 394 | format | String | The Provisioning Information | 395 | | | format that the message follows. | 396 | | | This is used by the Sender | 397 | | | device and Receiver device to | 398 | | | know how to parse the message. | 399 +-------------+------------+----------------------------------+ 400 | genericData | Dictionary | A dictionary of generic sharing | 401 | | | data that can be used for cross | 402 | | | platform credential transfers. | 403 | | | See each format's specification | 404 | | | for exact fields. | 405 +-------------+------------+----------------------------------+ 407 Table 1 409 3.3.1. Provisioning Information Format 411 Each Provisioning Information format must have the message structure 412 defined in an external specification. 414 +================================+====================+==============+ 415 |Format Type |Spec Link |Description | 416 +================================+====================+==============+ 417 |digitalwallet.carkey.ccc |[CCC-Digital-Key-30]|A digital | 418 | | |wallet | 419 | | |Provisioning | 420 | | |Information | 421 | | |for sharing a | 422 | | |car key that | 423 | | |follows the | 424 | | |Car | 425 | | |Connectivity | 426 | | |Consortium | 427 | | |specification.| 428 +--------------------------------+--------------------+--------------+ 429 |digitalwallet.authorizationToken|[ISO-18013-5] |A digital | 430 | | |wallet | 431 | | |Provisioning | 432 | | |Information | 433 | | |for sharing a | 434 | | |generic pass | 435 | | |that relies | 436 | | |solely on an | 437 | | |authorization | 438 | | |token. | 439 +--------------------------------+--------------------+--------------+ 441 Table 2 443 { 444 "format" : "digitalwallet.carkey.ccc", 445 // Additional use case specific fields 446 } 448 Figure 3: Provisioning Information format 450 3.3.2. Provisioning Information Encryption 452 Provisioning Information will be stored on the Relay Server 453 encrypted. The Secret used to encrypt the Provisioning Information 454 should given to the Receiver Device via a "Share URL" (a URL link to 455 a mailbox). The encrypted payload should be a data structure having 456 the following key-value pairs: 458 * "type" (String, Required) - the encryption algorithm and mode 459 used. 461 * "data" (String, Required) - Base64 encoded binary value of the 462 encrypted Provisioning Information, aka the ciphertext. 464 Please refer to [RFC5116] for the details of the encryption 465 algorithm. 467 The following algorithms and modes are mandatory to implement: 469 * "AEAD_AES_128_GCM": AES symmetric encryption algorithm with key 470 length 128 bits, in GCM mode with no padding. Initialization 471 Vector (IV) has the length of 96 bits randomly generated and tag 472 length of 128 bits. 474 * "AEAD_AES_256_GCM": AES symmetric encryption algorithm with key 475 length 256 bits, in GCM mode with no padding. Initialization 476 Vector (IV) has the length of 96 bits randomly generated and tag 477 length of 128 bits. 479 { 480 "type" : "AEAD_AES_128_GCM", 481 "data" : "IV ciphertext tag" 482 } 484 Figure 4: Secure Payload Format example 486 3.4. Share URL 488 A "Share URL" is the url a Sender device sends to the Receiver device 489 allowing them to retreive the Provisioning Information stored on the 490 Relay Server. A Share URL is made up of the following fields: 492 http://{RelayServerHost}/v{ApiVersion}/m/{MailboxIdentifier}?v={CredentialVertical}#{Secret} 494 Figure 5: Share URL example 496 +====================+====================+==========+ 497 | Field | Location | Required | 498 +====================+====================+==========+ 499 | RelayServerHost | URL Host | Yes | 500 +--------------------+--------------------+----------+ 501 | ApiVersion | URI Path Parameter | Yes | 502 +--------------------+--------------------+----------+ 503 | MailboxIdentifier | URI Path Parameter | Yes | 504 +--------------------+--------------------+----------+ 505 | CredentialVertical | Query Parameter | No | 506 +--------------------+--------------------+----------+ 507 | Secret | Fragment | No | 508 +--------------------+--------------------+----------+ 510 Table 3 512 3.4.1. Credential Vertical in Share URL 514 When a user interacts with a share URL on a Receiver device it can be 515 helpful to know what Credential Vertical this share is for. This is 516 particularly important if the Receiver device has multiple 517 applications that can handle a share URL. For example, a Receiver 518 device might want to handle a general access share in their wallet 519 app, but handle car key shares in a specific car application. 521 To properly route a share URL, the sender can include the Credential 522 Vertical in the share URL as a query parameter. The Credential 523 Vertical can't be included in the encrypted payload because the 524 Receiver device might need to open the right application before 525 retrieving the secure payload. The Credential Vertical query 526 parameter uses the "v" key and supports the below types. If no 527 Credential Vertical is provided it will be assumed that this is a 528 general access share URL. 530 +================+=============+ 531 | Vertical | Value | 532 +================+=============+ 533 | General Access | a or _None_ | 534 +----------------+-------------+ 535 | Home Key | h | 536 +----------------+-------------+ 537 | Car Key | c | 538 +----------------+-------------+ 540 Table 4 542 http://relayserver.com/v1/m/2bba630e-519b-11ec-bf63-0242ac130002?v=c#hXlr6aRC7KgJpOLTNZaLsw== 543 Figure 6: Car Key Share URL example 545 The Credential Vertical query parameter can be added to the share URL 546 by the Sender device when constructing the full share URL that is 547 going to be sent to the Receiver device. 549 4. API connection details 551 The Relay server API endpoint MUST be accessed over HTTP using an 552 https URI [RFC2818] and SHOULD use the default https port. Request 553 and response bodies SHALL be formatted as either JSON or HTML (based 554 on the API endpoint). The communication protocol used for all 555 interfaces SHALL be HTTPs. All Strings SHOULD be UTF-8 encoded 556 (Unicode Normalization Form C (NFC)). An API version SHOULD be 557 included in the URI for all interfaces. The version at the time of 558 this document's latest update is v1. The version SHALL be 559 incremented by 1 for major API changes or backward incompatible 560 iterations on existing APIs. 562 5. HTTP Headers: Mailbox-Request-ID 564 All requests to and from Relay server will have an HTTP header 565 "Mailbox-Request-ID". The corresponding response to the API will 566 have the same HTTP header, which SHALL echo the value in the request 567 header. This is used to identify the request associated to the 568 response for a particular API request and response pair. The value 569 SHOULD be a UUID [RFC4122]. The request originator SHALL match the 570 value of this header in the response with the one sent in the 571 request. If response is not received, caller may retry sending the 572 request with the same value of "Mailbox-Request-ID". Relay server 573 SHOULD store the value of the last successfully processed "Mailbox- 574 Request-ID" for each device based on the caller's Device Claim. A 575 key-value pair of "Device Claim" to "Mailbox-Request-ID" is suggested 576 to store the last successfully processed request for each device. In 577 case of receiving a request with duplicated "Mailbox-Request-ID", 578 Relay SHOULD respond to the caller with status code 201, ignoring the 579 duplicate request body content. 581 6. HTTP access methods 583 6.1. CreateMailbox 585 An application running on a remote device can invoke this API on 586 Relay Server to create a mailbox and store secure data content to it 587 (encrypted data specific to a provisioning partner). 588 MailboxIdentifier is created by the Relay server as an UUID 589 [RFC4122], using cryptographic entropy. A URL to the created mailbox 590 to be returned to the caller in the response. 592 6.1.1. Endpoint 594 POST /{version}/m 596 6.1.2. Request Parameters: 598 Path parameters 600 * version (String, Required) - the version of the API. At the time 601 of writing this document, "v1". 603 Header parameters 605 * deviceAttestation (String, Optional) - optional remote OEM device 606 proprietary attestation data. 608 * deviceClaim (String, UUID, Required) - Device Claim (refer to 609 Terminology). 611 6.1.3. Consumes 613 This API call consumes the following media types via the Content-Type 614 request header: application/json 616 6.1.4. Produces 618 This API call produces the following media types via the Content-Type 619 response header: application/json 621 6.1.5. Request body 623 Request body is a complex structure, including the following fields: 625 * payload (Object, Required) - for the purposes of Secure Credential 626 Transfer API, this is a data structure, describing Provisioning 627 Information specific to Credential Provider. It consists of the 628 following 2 key-value pairs: 630 1. "type": "AEAD_AES_128_GCM" (refer to Encryption Format 631 section). 633 2. "data": BASE64-encoded binary value of ciphertext. 635 * displayInformation (String, Required) - for the purposes of the 636 Secure Credential Transfer API, this is a JSON data blob. It 637 allows an application running on a receiving device to build a 638 visual representation of the credential to show to user. The data 639 structure contains the following fields: 641 1. title (String, Required) - the title of the credential (e.g. 642 "Car Key") 644 2. description (String, Required) - a brief description of the 645 credential (e.g. "a key to my personal car") 647 3. imageURL (String, Required) - a link to a picture representing 648 the credential visually. 650 * notificationToken (Object, Optional) - optional notification token 651 used to notify an appropriate remote device that the mailbox data 652 has been updated. Data structure includes the following (if 653 notificationToken is provided it should include both fields): 655 1. type (String, Required) - notification token name. Used to 656 define which Push Notification System to be used to notify 657 appropriate remote device of a mailbox data update. (E.g. 658 "com.apple.apns" for APNS) 660 2. tokenData (String, Required) - notification token data (Hex or 661 Base64 encoded based on the concrete implementation) - 662 application-specific - refer to appropriate Push Notification 663 System specification. 665 * mailboxConfiguration (Object, Optional) - optional mailbox 666 configuration, defines access rights to the mailbox, mailbox 667 expirationTime. Required at the time of the mailbox creation. 668 OEM device may provide this data in the request, Relay server 669 shall define a default configuration, if it is not provided in the 670 incoming request. Data structure includes the following: 672 1. accessRights (String, Optional) - optional access rights to 673 the mailbox for Sender and Receiver devices. Default access 674 to the mailbox is Read and Delete. Value is defined as a 675 combination of the following values: "R" - for read access, 676 "W" - for write access, "D" - for delete access. Example" 677 "RD" - allows to read from the mailbox and delete it. 679 2. timeToLive (String, required) - Mailbox time to live in 680 seconds. E.g. "8640" for 24 hours. Mailbox has a limited 681 time to live. Once expired, it SHALL be deleted - refer to 682 DeleteMailbox endpoint. Relay server SHOULD periodically 683 check for expired mailboxes and delete them. 685 { 686 "notificationToken": { 687 "type":"com.apple.apns", 688 "tokenData":"APNS1234...QW" 689 } 690 } 692 Figure 7: Apple Push Token Example 694 { 695 "displayInformation" : { 696 "title" : "Hotel Pass", 697 "description" : "Some Hotel Pass", 698 "imageURL" : "https://hotel.com/sharingImage" 699 }, 700 "payload" : { 701 "type": "AEAD_AES_128_GCM", 702 "data": "FDEC...987654321" 703 }, 704 "notificationToken" : { 705 "type" : "com.apple.apns", 706 "tokenData" : “APNS...1234" 707 }, 708 "mailboxConfiguration" : { 709 "accessRights" : "RWD", 710 "timeToLive" : "8640” 711 } 712 } 714 Figure 8: Create Mailbox Request Example 716 6.1.6. Responses 718 200 Status: "200" (OK) 720 ResponseBody: 722 * urlLink (String, Required) - a full URL link to the mailbox 723 including fully qualified domain name and mailbox Identifier. 725 * isPushNotificationSupported (boolean, Required) - indicates 726 whether push notification is supported or not. The device uses 727 this field to decide whether it should listen on the push topic or 728 do long-polling. 730 { 731 "urlLink":"relayserver.com/m/12345678-9...A-BCD", 732 "isPushNotificationSupported":true 733 } 735 Figure 9: Create Mailbox Response Example 737 201 Status: "201" (Created) - response to a duplicated request 738 (duplicated "Mailbox-Request-Id"). Relay server SHALL respond to 739 duplicated requests with 201 without creating a new mailbox. 740 "Mailbox-Request-Id" passed in the first CreateMailbox request's 741 header SHOULD be stored by the Relay server and compared to the same 742 value in the subsequent requests to identify duplicated requests. If 743 duplicate is found, Relay SHALL not create a new mailbox, but respond 744 with 201 instead. The value of "Mailbox-Request-Id" of the last 745 successfully completed request SHOULD be stored based on the Device 746 Claim passed by the caller. 748 400 Bad Request - invalid request has been passed (can not parse or 749 required fields missing). 751 401 Unauthorized - calling device is not authorized to create a 752 mailbox. E.g. a device presented the incorrect deviceClaim or 753 mailbox with the provided mailboxIdentifier already exists. 755 6.2. UpdateMailbox 757 An application running on a remote device can invoke this API on 758 Relay Server to update secure data content in an existing mailbox 759 (encrypted data specific to a Provisioning Partner). The update 760 effectively overwrites the secure payload previously stored in the 761 mailbox. 763 6.2.1. Endpoint 765 PUT /{version}/m/{mailboxIdentifier} 767 6.2.2. Request Parameters 769 Path parameters: 771 * version (String, Required) - the version of the API. At the time 772 of writing this document, "v1". 774 * mailboxIdentifier(String, Required) - MailboxIdentifier (refer to 775 Terminology). 777 Header parameters: 779 * deviceAttestation (String, Optional) - optional remote OEM device 780 proprietary attestation data. 782 * deviceClaim (String, UUID, Required) - Device Claim (refer to 783 Terminology). 785 6.2.3. Consumes 787 This API call consumes the following media types via the Content-Type 788 request header: application/json 790 6.2.4. Produces 792 This API call produces a response with empty body, no content type is 793 required 795 6.2.5. Request body 797 Request body is a complex structure, including the following fields: 799 * payload (Object, Required) - for the purposes of Secure Credential 800 Transfer API, this is a data structure, describing Provisioning 801 Information specific to Credential Provider. It consists of the 802 following 2 key-value pairs: 804 1. "type": "AEAD_AES_128_GCM" (refer to Encryption Format 805 section). 807 2. "data": BASE64-encoded binary value of ciphertext. 809 * notificationToken (Object, Optional) - optional notification token 810 used to notify an appropriate remote device that the mailbox data 811 has been updated. Data structure includes the following (if 812 notificationToken is provided it should include both fields): 814 1. type (String, Required) - notification token name. Used to 815 define which Push Notification System to be used to notify 816 appropriate remote device of a mailbox data update. (E.g. 817 "com.apple.apns" for APNS) 819 2. tokenData (String, Required) - notification token data (Hex or 820 Base64 encoded based on the concrete implementation) - 821 application-specific - refer to appropriate Push Notification 822 System specification. 824 { 825 "payload" : { 826 "type": "AEAD_AES_128_GCM", 827 "data": "FDEC...987654321" 828 }, 829 "notificationToken":{ 830 "type" : "com.apple.apns", 831 "tokenData" : “APNS...1234" 832 } 833 } 835 Figure 10: Update Mailbox Request Example 837 6.2.6. Responses 839 ResponseBody: 841 * isPushNotificationSupported (boolean, Required) - indicates 842 whether push notification is supported or not. The device uses 843 this field to decide whether it should listen on the push topic or 844 do long-polling. 846 { 847 "isPushNotificationSupported":true 848 } 850 Figure 11: Create Mailbox Response Example 852 200 Status: "200" (OK) 854 201 Status: "201" (Created) - response to a duplicate request 855 (duplicate "Mailbox-Request-Id"). Relay server SHALL respond to 856 duplicate requests with 201 without performing mailbox update. 857 "Mailbox-Request-Id" passed in the first UpdateMailbox request's 858 header SHALL be stored by the Relay server and compared to the same 859 value in the subsequent requests to identify duplicate requests. If 860 duplicate is found, Relay SHALL not perform mailbox update, but 861 respond with 201 instead. The value of "Mailbox-Request-Id" of the 862 last successfully completed request SHALL be stored based on the 863 Device Claim passed by the caller. 865 400 Bad Request - invalid request has been passed (can not parse or 866 required fields missing). 868 401 Unauthorized - calling device is not authorized to update the 869 mailbox. E.g. a device presented the incorrect deviceClaim. 871 404 Not Found - mailbox with provided mailboxIdentifier not found. 873 6.3. DeleteMailbox 875 An application running on a remote device can invoke this API on 876 Relay Server to close the existing mailbox after it served its 877 purpose. Receiver or Sender device needs to present a deviceClaim in 878 order to close the mailbox. 880 6.3.1. Endpoint 882 DELETE /{version}/m/{mailboxIdentifier} 884 6.3.2. Request Parameters 886 Path parameters: 888 * version (String, Required) - the version of the API. At the time 889 of writing this document, "v1". 891 * mailboxIdentifier(String, Required) - MailboxIdentifier (refer to 892 Terminology). 894 Header parameters: 896 * deviceAttestation (String, Optional) - optional remote OEM device 897 proprietary attestation data. 899 * deviceClaim (String, UUID, Required) - Device Claim (refer to 900 Terminology). 902 6.3.3. Responses 904 200 Status: "200" (OK) 906 401 Unauthorized - calling device is not authorized to delete a 907 mailbox. E.g. a device presented the incorrect deviceClaim. 909 404 Not Found - mailbox with provided mailboxIdentifier not found. 910 Relay server may respond with 404 if the Mailbox Identifier passed by 911 the caller is invalid or mailbox has already been deleted (as a 912 result of duplicate DeleteMailbox request). 914 6.4. ReadDisplayInformationFromMailbox 916 An application running on a remote device can invoke this API on 917 Relay Server to retrieve public display information content from a 918 mailbox. Display Information shall be returned in OpenGraph format 919 (please refer to https://ogp.me for details). OpenGraph-formatted 920 display information is required to display a preview of credential in 921 a messaging application, e.g. iMessage or WhatsApp. 923 6.4.1. Endpoint 925 GET /{version}/m/{mailboxIdentifier} 927 6.4.2. Request Parameters 929 Path parameters: 931 * version (String, Required)- the version of the API. At the time 932 of writing this document, "v1". 934 * mailboxIdentifier(String, Required) - MailboxIdentifier (refer to 935 Terminology). 937 6.4.3. Produces 939 This API call produces the following media types via the Content-Type 940 response header: text/html 942 6.4.4. Responses 944 200 Status: "200" (OK) 946 ResponseBody : 948 * displayInformation (String, Required) - visual representation of 949 digital credential in OpenGraph format (please refer to 950 https://ogp.me for details). 952 " 953 954 Hotel Pass 955 956 957 958 959 960 961 962 " 964 Figure 12: Read Display Information Response Example 966 404 Not Found - mailbox with provided mailboxIdentifier not found. 968 6.5. ReadSecureContentFromMailbox 970 An application running on a remote device can invoke this API on 971 Relay Server to retrieve secure payload content from a mailbox 972 (encrypted data specific to a Provisioning Information Provider). 974 6.5.1. Endpoint 976 POST /{version}/m/{mailboxIdentifier} 978 6.5.2. Request Parameters 980 Path parameters: 982 * version (String, Required) - the version of the API. At the time 983 of writing this document, "v1". 985 * mailboxIdentifier(String, Required) - MailboxIdentifier (refer to 986 Terminology). 988 Header parameters: 990 * deviceAttestation (String, Optional) - optional remote OEM device 991 proprietary attestation data. 993 * deviceClaim (String, UUID, Required) - Device Claim (refer to 994 Terminology). 996 6.5.3. Produces 998 This API call produces the following media types via the Content-Type 999 response header: application/json 1001 6.5.4. Responses 1003 200 Status: "200" (OK) 1005 ResponseBody : 1007 * payload (String, Required) - for the purposes of Secure Credential 1008 Transfer API, this is a JSON metadata blob, describing 1009 Provisioning Information specific to Credential Provider. 1011 * displayInformation (String, Required) - for the purposes of the 1012 Secure Credential Transfer API, this is a JSON data blob. It 1013 allows an application running on a receiving device to build a 1014 visual representation of the credential to show to user. Specific 1015 to Credential Provider. 1017 * expiration (String, Required) - the date that the mailbox will 1018 expire. The mailbox expiration is set during mailbox creation. 1019 This expiration should be a complete [RFC3339] date string, and 1020 can be used to allow receiving clients to show when a share will 1021 expire. 1023 { 1024 “displayInformation" : { 1025 "title" : "Hotel Pass", 1026 "description" : "Some Hotel Pass", 1027 "imageURL" : "https://hotel.com/sharingImage" 1028 }, 1029 "payload" : { 1030 "type": "AEAD_AES_128_GCM", 1031 "data": "FDEC...987654321" 1032 }, 1033 "expiration": "2021-11-03T20:32:34+0000" 1034 } 1036 Figure 13: Read Secure Content Response Example 1038 401 Unauthorized - calling device is not authorized to read the 1039 secure content of the mailbox. E.g. a device presented the incorrect 1040 deviceClaim. 1042 404 Not Found - mailbox with provided mailboxIdentifier not found. 1044 6.6. RelinquishMailbox 1046 An application running on a remote device can invoke this API on 1047 Relay Server to relinquish their ownership of the mailbox. Receiver 1048 device needs to present the currently established Receiver 1049 deviceClaim in order to relinquish their ownership of the mailbox. 1050 Once relinquished, the mailbox can be bound to a different Receiver 1051 device that presents its deviceClaim in a 1052 ReadSecureContentFromMailbox call. 1054 6.6.1. Endpoint 1056 PATCH /{version}/m/{mailboxIdentifier} 1058 6.6.2. Request Parameters 1060 Path parameters: 1062 * version (String, Required) - the version of the API. At the time 1063 of writing this document, "v1". 1065 * mailboxIdentifier(String, Required) - MailboxIdentifier (refer to 1066 Terminology). 1068 Header parameters: 1070 * deviceAttestation (String, Optional) - optional remote OEM device 1071 proprietary attestation data. 1073 * deviceClaim (String, UUID, Required) - Device Claim (refer to 1074 Terminology). 1076 6.6.3. Responses 1078 200 Status: "200" (OK) 1080 201 Status: "201" (Created) - response to a duplicate request 1081 (duplicate "Mailbox-Request-Id"). Relay server SHALL respond to 1082 duplicate requests with 201 without performing mailbox relinquish. 1083 "Mailbox-Request-Id" passed in the first RelinquishMailbox request's 1084 header SHALL be stored by the Relay server and compared to the same 1085 value in the subsequent requests to identify duplicate requests. If 1086 duplicate is found, Relay SHALL not perform mailbox relinquish, but 1087 respond with 201 instead. The value of "Mailbox-Request-Id" of the 1088 last successfully completed request SHALL be stored based on the 1089 Device Claim passed by the caller. 1091 401 Unauthorized - calling device is not authorized to relinquish a 1092 mailbox. E.g. a device presented the incorrect deviceClaim, or the 1093 device is not bound to the mailbox. 1095 404 Not Found - mailbox with provided mailboxIdentifier not found. 1096 Relay server may respond with 404 if the Mailbox Identifier passed by 1097 the caller is invalid. 1099 7. Security Considerations 1101 The following threats and mitigations have been considered: 1103 * Sender shares with the wrong receiver 1105 - Sender SHOULD be encouraged to share Secret over a channel 1106 allowing authentication of the receiver (e.g. voice). 1108 - Provisioning Partners SHALL allow senders to cancel existing 1109 shares. 1111 * Malicious receiver forwards the share to 3rd party without 1112 redeeming it or the Receiver's device is compromised. 1114 - No mitigation, the Sender SHOULD only share with receivers they 1115 trust. 1117 * Malicious receiver attempts re-use share 1119 - Provisioning Partners SHALL ensure that the Provisioning 1120 Information of a share can only be redeemed once. 1122 * Share URL accidental disclosure. (e.g. share URL sent as a message 1123 which gets displayed on a locked screen) 1125 - Knowledge of Secret is required to access Provisioning 1126 Information and it SHOULD have been sent in a separate channel. 1128 - Device Claim is required (if sender and receiver have already 1129 both contacted the Relay server) 1131 * Network attacks 1133 - Machine-in-the-middle: Relay server SHALL only allow TLS 1134 connections. URLs displayed to user SHOULD include the https 1135 scheme. 1137 - MailboxIdentifier guessing: the MailboxIdentifier is a version 1138 4 UUID [RFC4122] which SHOULD contain 122-bits of cryptographic 1139 entropy, making brute-force attacks impractical 1141 7.1. Sender/Receiver privacy 1143 * At no time Relay server SHALL store or track the identities of 1144 both Sender and Receiver devices. 1146 * The value of the Notification Token shall not contain information 1147 allowing the identification of the device providing it. It SHOULD 1148 also be different for every new share to prevent the Relay server 1149 from correlating different sharing. 1151 * Notification token SHOULD only inform the corresponding device 1152 that there has been a data update on the mailbox associated to it 1153 (by Device Claim). Each device SHOULD keep track of all mailboxes 1154 associated with it and make read calls to appropriate mailboxes. 1156 * Both Sender and Receiver devices SHOULD store the URL of the Relay 1157 server they use for an active act of credential transfer. 1159 * The value of DeviceAttestation header parameter SHALL not contain 1160 information allowing the identification of the device providing 1161 it. It SHOULD also be different for every new share to prevent 1162 the Relay server from correlating different sharing. 1164 * Display Information is not encrypted, therefore, it SHOULD not 1165 contain any information allowing to identify Sender or Receiver 1166 devices. 1168 7.2. Credential's confidentiality and integrity 1170 * Content of the mailbox SHALL be only visible to devices having 1171 Secret. 1173 * It is recommended to send URL to the mailbox and the Secret over 1174 different channels (out-of-band) from Sender device to Receiver 1175 device (e.g. send URL over SMS and Secret over iMessage). 1177 * Relay server MUST not receive the Secret with the 1178 MailboxIdentifier at any time. 1180 * Content of the mailbox MUST guaranty it's integrity with 1181 cryptographic checksum (e.g. MAC, AES-GCM tag). 1183 * Relay server SHALL periodically check and delete expired mailboxes 1184 ( refer to timeToLive parameter in the CreateMailbox request). 1186 * If the Sender device sends both URL and the Secret over the same 1187 channel as a single URL, the Sender MUST append the Secret as URI 1188 fragment [RFC3986], so that the resulting URL shall look as in the 1189 example below. Receiver device, upon receipt of such URL, MUST 1190 remove the Fragment (Secret) before calling the Relay server API. 1192 “http://relayserver.com/v1/m/{mailboxIdentifier}#{Secret}” 1194 Figure 14: Example of URL with Secret as URI Fragment 1196 7.3. Second factor authentication for Receiver credential provisioning 1198 * Provisioning Partner shall require an additional security 1199 confirmation (PIN code) from Receiver Device at the time of 1200 credential provisioning. 1202 * PIN code shall be generated by the Sender Device at the time when 1203 it creates a new Mailbox with Provisioning Information on a Relay 1204 Server. 1206 * PIN code shall be sent from Sender device to Receiver device in a 1207 secure way (preferrably over encrypted channel) out-of-band with 1208 the Mailbox URL and Secret 1210 * If Sender device can not send the PIN code over secure channel, it 1211 may include it into encrypted Payload stored on the relay server 1212 so that Receiver device can decrypt it and use to get Provisioning 1213 Information from Provisioning Partner. 1215 * Provisioning Partner shall limit the number of PIN code entry 1216 attempts at the time when Receiver device calls it in order to 1217 receive Provisioning Information. 1219 * The way PIN code is transferred between Sender device and Receiver 1220 device is defined by specific implementation and out of scope of 1221 this document. 1223 8. IANA Considerations 1225 This document registers a new header, "Mailbox-Request-ID", in the 1226 "Permanent Message Header Field Names" 1227 . 1229 +--------------------+----------+--------+---------------+ 1230 | Header Field Name | Protocol | Status | Reference | 1231 +--------------------+----------+--------+---------------+ 1232 | Mailbox-Request-ID | http | std | This document | 1233 +--------------------+----------+--------+---------------+ 1234 Figure 15: Registered HTTP Header 1236 9. References 1238 9.1. Normative References 1240 [CCC-Digital-Key-30] 1241 Car Connectivity Consortium, "Digital Key – The Future of 1242 Vehicle Access", November 2021, . 1246 [ISO-18013-5] 1247 Cards and security devices for personal identification, 1248 "Personal identification — ISO-compliant driving licence — 1249 Part 5: Mobile driving licence (mDL) application", 1250 September 2021, . 1252 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1253 Requirement Levels", BCP 14, RFC 2119, 1254 DOI 10.17487/RFC2119, March 1997, 1255 . 1257 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 1258 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 1259 . 1261 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1262 Resource Identifier (URI): Generic Syntax", STD 66, 1263 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1264 . 1266 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 1267 Unique IDentifier (UUID) URN Namespace", RFC 4122, 1268 DOI 10.17487/RFC4122, July 2005, 1269 . 1271 [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated 1272 Encryption", RFC 5116, DOI 10.17487/RFC5116, January 2008, 1273 . 1275 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1276 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1277 May 2017, . 1279 9.2. Informative References 1281 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 1282 DOI 10.17487/RFC2818, May 2000, 1283 . 1285 Appendix A. Contributors 1287 The following people provided substantive contributions to this 1288 document: 1290 * Ben Chester 1292 * Casey Astiz 1294 * Jean-Luc Giraud 1296 * Yogesh Karandikar 1298 * Alexey Bulgakov 1300 * Tommy Pauly 1302 * Crystal Qin 1304 * Adam Bar-Niv 1306 * Manuel Gerster 1308 Appendix B. Acknowledgments 1310 TODO acknowledge. 1312 Authors' Addresses 1314 Dmitry Vinokurov 1315 Apple Inc 1317 Email: dvinokurov@apple.com 1319 Matt Byington 1320 Apple Inc 1322 Email: mbyington@apple.com 1324 Matthias Lerch 1325 Apple Inc 1326 Email: mlerch@apple.com 1328 Alex Pelletier 1329 Apple Inc 1331 Email: a_pelletier@apple.com 1333 Nick Sha 1334 Alphabet Inc 1336 Email: nicksha@google.com