Skip to main content

Devices

Users in e2esdk access the API through authorized devices.

A device is the combination of a physical machine (laptop, mobile phone) and a storage context (localStorage for a browser).

For example, Firefox and Chrome both installed on the same Macbook are considered two different devices.

Devices are the entrypoint for authentication in e2esdk, as they provide the OPAQUE credentials to initiate a login flow.

Device management​

The following device operations are available in e2esdk:

  • Enrolling a new device
  • Registering an enrolled device using a URI
  • Revoking devices

Device enrollment​

A new device can be enrolled from a valid session on an already enrolled device.

This involves:

  • Creating an OPAQUE password (device secret)
  • Performing the OPAQUE registration flow to obtain an export key
  • Using that export key to wrap the main account key
  • Storing a Device entity in the database that contains:
    • The device ID (UUIDv4 generated by the database)
    • The OPAQUE server-side credentials (for mutual authentication)
    • The wrapped main key
    • An optional string label to identify the device
    • A pointer to the device that was used to enroll this one (for audits)

Once the database entity has been saved, the source device can then produce a device registration URI, containing the following information:

  • The user ID whom the device belongs to
  • The device ID (returned from the database)
  • The device secret for OPAQUE authentication

That URI should then be transmitted securely to the device to register. The use of an offline channel (like a QR code) is strongly recommended.

Recovery​

A device dedicated to account recovery can be created, for which the registration URI can be stored offline (eg: printed on a piece of paper and kept in a safe), or backed up in a secure store (eg: a password manager).

If access to all the other devices are lost, this recovery device can be used to gain access to the account, revoke the lost devices and provision new ones.

Device labels​

To identify devices, an optional string label can be passed at enrollment time.

This label is encrypted with an account-level key, derived from the keychain base key, in order for any device to decrypt any other device's label.

Initial registration​

Since we need an enrolled device to enroll a new device, the initial signup operation performs both the identity registration and an initial device registration for the calling device.