About Trusted Devices

When a user authenticates with SSO on an already-trusted device:

1. The user's Public Key-Encrypted User Key, which is an encrypted version of the account encryption key used to decrypt vault data, is sent from the server to the client.

2. The user's Device Key-Encrypted Private Key, the unencrypted version of which is required to decrypt the Public Key-Encrypted User Key, is sent from the server to the client.

3. The client decrypts the Device Key-Encrypted Private Key using the Device Key, which never leaves the client.

4. The now-unencrypted Device Private Key is used to decrypt the Public Key-Encrypted User Key, resulting in the user's account encryption key.

5. The user's account encryption key decrypts vault data.

When a user authenticates with SSO and opts to decrypt their vault with an un-trusted device (i.e. a Device Symmetric Key does not exist on that device), they are required to choose a method of approving the device and optionally trusting it for future use without further approval. What happens next depends on the selected option:

• Approve from another device:

  1. The process documented here is triggered, resulting in the client having obtained and decrypted the account encryption key.

  2. The user can now decrypt their vault data with the decrypted account encryption key. If they have chosen to trust the device, trust is established with the client as described in the Onboarding tab.

• Request admin approval:

  1. The initiating client POSTs a request, which includes the account email address, a unique auth-request public keyª, and an access code, to an Authentication Request table in the Bitwarden database.

  2. Administrators can approve or deny the request on the Device approvals page.

  3. When the request is approved by an administrator, the approving client encrypts the user's account encryption key using the auth-request public key enclosed in the request.

  4. The approving client then PUTs the encrypted account encryption key to the Authentication Request record and marks the request fulfilled.

  5. The initiating client GETs the encrypted account encryption key and locally decrypts it using the auth-request private key.

  6. Using the decrypted account encryption key, trust is established with the client as described in the Onboarding tab.

ª - Auth-request public and private keys are uniquely generated for each passwordless login request and only exist for as long as the request does. Unapproved requests will expire after 1 week.

• Approve with master password:

  1. The users's account encryption key is retrieved and decrypted as documented in the User Login section of the Security Whitepaper.

  2. Using the decrypted account encryption key, trust is established with the client as described in the Onboarding tab.

When a user rotates their account encryption key, during the normal rotation process:

1. The User-Key Encrypted Public Key is sent from the server to the client, and subsequently decrypted with the old account encryption key (a.k.a. User Key), resulting in the Device Public Key.

2. The user's new account encryption key is encrypted with the unencrypted Device Public Key and the resultant value is sent to the server as the new Public Key-Encrypted User Key.

3. The Device Public Key is encrypted with the user's new account encryption key and the resultant value is sent to the server as the new User Key-Encrypted Public Key.

4. Trusted device encryption keys for all other devices that are persisted to server storage are cleared for the user. This leaves only the three required keys (Public Key-Encrypted User Key, User Key-Encrypted Public Key, and Device Key-Encrypted Private Key which was not changed by this process) for that single device persisted to the server.

Any now-untrusted client will be required to re-established trust through one of the methods described in the Approving tab.