Secure Credential Transfer

3.3.1. Credential Vertical in share url

When a user interacts with a share URL on a Receiver device it can be helpful to know what Credential Vertical this share is for. This is particularly important if the Receiver device has multiple applications that can handle a share URL. For example, a Receiver device might want to handle a general access share in their wallet app, but handle car key shares in a specific car application.¶

To properly route a share URL, the sender can include the Credential Vertical in the share URL as a query parameter. The Credential Vertical can't be included in the encrypted payload because the Receiver device might need to open the right application before retrieving the secure payload. The Credential Vertical query parameter uses the "v" key and supports the below types. If no Credential Vertical is provided it will be assumed that this is a general access share URL.¶

Example car key share url: http://relayserver.com/v1/m/2bba630e-519b-11ec-bf63-0242ac130002?v=c#hXlr6aRC7KgJpOLTNZaLsw== ¶

The Credential Vertical query parameter can be added to the share URL by the Sender device when constructing the full share URL that is going to be sent to the Receiver device.¶

6.1.1. Endpoint

POST /{version}/m¶

6.1.2. Request Parameters:

Path parameters¶

• version (String, Required) - the version of the API. At the time of writing this document, "v1".¶

Header parameters¶

• deviceAttestation (String, Optional) - optional remote OEM device proprietary attestation data.¶
• deviceClaim (String, UUID, Required) - Device Claim (refer to Terminology).¶

6.1.3. Consumes

This API call consumes the following media types via the Content-Type request header: application/json¶

6.1.4. Produces

This API call produces the following media types via the Content-Type response header: application/json¶

6.1.5. Request body

Request body is a complex structure, including the following fields:¶

• payload (Object, Required) - for the purposes of Secure Credential Transfer API, this is a data structure, describing Provisioning Information specific to Credential Provider. It consists of the following 2 key-value pairs:¶

  1. "type": "AEAD_AES_128_GCM" (refer to Encryption Format section).¶
  2. "data": BASE64-encoded binary value of ciphertext.¶

• displayInformation (String, Required) - for the purposes of the Secure Credential Transfer API, this is a JSON data blob. It allows an application running on a receiving device to build a visual representation of the credential to show to user. The data structure contains the following fields:¶

  1. title (String, Required) - the title of the credential (e.g. "Car Key")¶
  2. description (String, Required) - a brief description of the credential (e.g. "a key to my personal car")¶
  3. imageURL (String, Required) - a link to a picture representing the credential visually.¶

• notificationToken (Object, Optional) - optional notification token used to notify an appropriate remote device that the mailbox data has been updated. Data structure includes the following (if notificationToken is provided it should include both fields):¶

  1. type (String, Required) - notification token name. Used to define which Push Notification System to be used to notify appropriate remote device of a mailbox data update. (E.g. "com.apple.apns" for APNS)¶
  2. tokenData (String, Required) - notification token data (Hex or Base64 encoded based on the concrete implementation) - application-specific - refer to appropriate Push Notification System specification.¶

• mailboxConfiguration (Object, Optional) - optional mailbox configuration, defines access rights to the mailbox, mailbox expirationTime. Required at the time of the mailbox creation. OEM device may provide this data in the request, Relay server shall define a default configuration, if it is not provided in the incoming request. Data structure includes the following:¶

  1. accessRights (String, Optional) - optional access rights to the mailbox for Sender and Receiver devices. Default access to the mailbox is Read and Delete. Value is defined as a combination of the following values: "R" - for read access, "W" - for write access, "D" - for delete access. Example" "RD" - allows to read from the mailbox and delete it.¶
  2. timeToLive (String, required) - Mailbox time to live in seconds. E.g. "8640" for 24 hours. Mailbox has a limited time to live. Once expired, it SHALL be deleted - refer to DeleteMailbox endpoint. Relay server SHOULD periodically check for expired mailboxes and delete them.¶

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

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

6.1.6. Responses

200 Status: "200" (OK)¶

ResponseBody:¶

• urlLink (String, Required) - a full URL link to the mailbox including fully qualified domain name and mailbox Identifier.¶
• isPushNotificationSupported (boolean, Required) - indicates whether push notification is supported or not. The device uses this field to decide whether it should listen on the push topic or do long-polling.¶

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

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.¶

400 Bad Request - invalid request has been passed (can not parse or required fields missing).¶

401 Unauthorized - calling device is not authorized to create a mailbox. E.g. a device presented the incorrect deviceClaim or mailbox with the provided mailboxIdentifier already exists.¶

6.2.1. Endpoint

PUT /{version}/m/{mailboxIdentifier}¶

6.2.2. Request Parameters

Path parameters:¶

• version (String, Required) - the version of the API. At the time of writing this document, "v1".¶
• mailboxIdentifier(String, Required) - MailboxIdentifier (refer to Terminology).¶

Header parameters:¶

• deviceAttestation (String, Optional) - optional remote OEM device proprietary attestation data.¶
• deviceClaim (String, UUID, Required) - Device Claim (refer to Terminology).¶

6.2.3. Consumes

This API call consumes the following media types via the Content-Type request header: application/json¶

6.2.4. Produces

This API call produces a response with empty body, no content type is required¶

6.2.5. Request body

Request body is a complex structure, including the following fields:¶

• payload (Object, Required) - for the purposes of Secure Credential Transfer API, this is a data structure, describing Provisioning Information specific to Credential Provider. It consists of the following 2 key-value pairs:¶

  1. "type": "AEAD_AES_128_GCM" (refer to Encryption Format section).¶
  2. "data": BASE64-encoded binary value of ciphertext.¶

• notificationToken (Object, Optional) - optional notification token used to notify an appropriate remote device that the mailbox data has been updated. Data structure includes the following (if notificationToken is provided it should include both fields):¶

  1. type (String, Required) - notification token name. Used to define which Push Notification System to be used to notify appropriate remote device of a mailbox data update. (E.g. "com.apple.apns" for APNS)¶
  2. tokenData (String, Required) - notification token data (Hex or Base64 encoded based on the concrete implementation) - application-specific - refer to appropriate Push Notification System specification.¶

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

6.2.6. Responses

ResponseBody:¶

• isPushNotificationSupported (boolean, Required) - indicates whether push notification is supported or not. The device uses this field to decide whether it should listen on the push topic or do long-polling.¶

{
    "isPushNotificationSupported":true
}

200 Status: "200" (OK)¶

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.¶

400 Bad Request - invalid request has been passed (can not parse or required fields missing).¶

401 Unauthorized - calling device is not authorized to update the mailbox. E.g. a device presented the incorrect deviceClaim.¶

404 Not Found - mailbox with provided mailboxIdentifier not found.¶

6.3.1. Endpoint

DELETE /{version}/m/{mailboxIdentifier}¶

6.3.2. Request Parameters

Path parameters:¶

• version (String, Required) - the version of the API. At the time of writing this document, "v1".¶
• mailboxIdentifier(String, Required) - MailboxIdentifier (refer to Terminology).¶

Header parameters:¶

• deviceAttestation (String, Optional) - optional remote OEM device proprietary attestation data.¶
• deviceClaim (String, UUID, Required) - Device Claim (refer to Terminology).¶

6.3.3. Responses

200 Status: "200" (OK)¶

401 Unauthorized - calling device is not authorized to delete a mailbox. E.g. a device presented the incorrect deviceClaim.¶

404 Not Found - mailbox with provided mailboxIdentifier not found. Relay server may respond with 404 if the Mailbox Identifier passed by the caller is invalid or mailbox has already been deleted (as a result of duplicate DeleteMailbox request).¶

6.4.1. Endpoint

GET /{version}/m/{mailboxIdentifier}¶

6.4.2. Request Parameters

Path parameters:¶

• version (String, Required)- the version of the API. At the time of writing this document, "v1".¶
• mailboxIdentifier(String, Required) - MailboxIdentifier (refer to Terminology).¶

6.4.3. Produces

This API call produces the following media types via the Content-Type response header: text/html¶

6.4.4. Responses

200 Status: "200" (OK)¶

ResponseBody :¶

• displayInformation (String, Required) - visual representation of digital credential in OpenGraph format (please refer to https://ogp.me for details).¶

    "<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>"

404 Not Found - mailbox with provided mailboxIdentifier not found.¶

6.5.1. Endpoint

POST /{version}/m/{mailboxIdentifier}¶

6.5.2. Request Parameters

Path parameters:¶

• version (String, Required) - the version of the API. At the time of writing this document, "v1".¶
• mailboxIdentifier(String, Required) - MailboxIdentifier (refer to Terminology).¶

Header parameters:¶

• deviceAttestation (String, Optional) - optional remote OEM device proprietary attestation data.¶
• deviceClaim (String, UUID, Required) - Device Claim (refer to Terminology).¶

6.5.3. Produces

This API call produces the following media types via the Content-Type response header: application/json¶

6.5.4. Responses

200 Status: "200" (OK)¶

ResponseBody :¶

• payload (String, Required) - for the purposes of Secure Credential Transfer API, this is a JSON metadata blob, describing Provisioning Information specific to Credential Provider.¶
• displayInformation (String, Required) - for the purposes of the Secure Credential Transfer API, this is a JSON data blob. It allows an application running on a receiving device to build a visual representation of the credential to show to user. Specific to Credential Provider.¶
• expiration (String, Required) - the date that the mailbox will expire. The mailbox expiration is set during mailbox creation. This expiration should be a complete [RFC3339] date string, and can be used to allow receiving clients to show when a share will expire.¶

{
    “displayInformation" : {
        "title" : "Hotel Pass",
        "description" : "Some Hotel Pass",
        "imageURL" : "https://hotel.com/sharingImage"
    },
    "payload" : {
        "type": "AEAD_AES_128_GCM",
        "data": "FDEC...987654321"
    },
    "expiration": "2021-11-03T20:32:34+0000"
}

401 Unauthorized - calling device is not authorized to read the secure content of the mailbox. E.g. a device presented the incorrect deviceClaim.¶

404 Not Found - mailbox with provided mailboxIdentifier not found.¶

6.6.1. Endpoint

PATCH /{version}/m/{mailboxIdentifier}¶

6.6.2. Request Parameters

Path parameters:¶

• version (String, Required) - the version of the API. At the time of writing this document, "v1".¶
• mailboxIdentifier(String, Required) - MailboxIdentifier (refer to Terminology).¶

Header parameters:¶

• deviceAttestation (String, Optional) - optional remote OEM device proprietary attestation data.¶
• deviceClaim (String, UUID, Required) - Device Claim (refer to Terminology).¶

6.6.3. Responses

200 Status: "200" (OK)¶

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.¶

401 Unauthorized - calling device is not authorized to relinquish a mailbox. E.g. a device presented the incorrect deviceClaim, or the device is not bound to the mailbox.¶

404 Not Found - mailbox with provided mailboxIdentifier not found. Relay server may respond with 404 if the Mailbox Identifier passed by the caller is invalid.¶