Recovering a Key

Depending on whether the user has automatic key recovery or password based key recovery:

User with Password Recovery

The user tries to recover the key trough the iFrame. For that, it'll attempt to reconstruct its key and fail due to not having the local share. This share is stored in each device after the user recovers it in that device for the first time.

Instead, the iFrame will fetch the hot and cold shares with the JWT token it'll obtain from the auth service, reconstruct the key, split it again, and:

• Discard the cold share.
• Store the local share in the device.
• Store the hot share in the hot storage.

The diagram below shows this process in greater detail.

User with Automatic Recovery

The user can now use this device without accessing the cold storage again; by using the local and hot shares to reconstruct the private key. The diagram leaves the private key reconstruction happening in the cold storage ambiguous, let's delve into it a bit more.

The cold storage has the cold share, but it is encrypted with a key it has no access to. They key used to encrypt the cold share was split into shares and deleted after its first usage. The cold storage kept one of these shares, while the admin kept the other share. When the admin called the cold storage /v1/devices/register endpoint, it lent its share as a one-time way of reconstructing the encryption key and decrypting the cold share.

To enforce this one-time usage, the cold storage will delete the encryption key share passed by the admin after using it once.

2FA with Automatic Recovery

User with Passkey Recovery

When cold shares are encrypted using passkeys, OpenSigner stores the necessary information for it to know which passkey it should ask for.

If a user wants to retrieve their cold share they will be prompted to authenticate with the passkey they used to created the account. Most passkey authentication providers still show some kind of prompt even if they don't find the passkey within the local authenticator (e.g. a picture w/ a QR code in case the passkey was created using some phone).

Once properly authenticated, no further interaction is required from the user: both the PRF generation and the key derivation/share encryption will happen under the hood, leaving the unencrypted cold share available for full key recovery.