Recovering a Key

Before recovering a key, the user must call hot storage to retrieve their list of accounts and select the one to recover. Once selected, pass the account UUID to the iFrame, which handles the recovery process.

The process differs depending on the recovery method:

• Password Recovery: User provides a password to decrypt the cold share
• Automatic Recovery: Cold share is decrypted server-side using project entropy
• Passkey Recovery: User authenticates with a passkey to derive the decryption key

Password Recovery

The user recovers the key through the iFrame. The iFrame attempts to reconstruct the key and fails because the local share is missing. This share is stored on each device after the user recovers it for the first time on that device.

Instead, the iFrame fetches the hot and cold shares with the JWT token it obtains from the auth service, reconstructs the key, splits 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 detail.

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 doesn't show the private key reconstruction in the cold storage. The following section explains it in detail.

The cold storage has the cold share, but it is encrypted with a key it has no access to. The 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 calls the cold storage /v2/devices/register endpoint, it provides its share as a one-time input for reconstructing the encryption key and decrypting the cold share.

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

OTP with Automatic Recovery

The flow is the same as with usual automatic recovery above, the only difference is in encrypted session creation - it requires some actions from user. The diagram below shows only the encrypted session creation flow.

As shown in the diagram, the admin must request an OTP for the user before proceeding with encrypted session creation. If a session is created without the OTP, the cold storage does not return the share to the iFrame, causing the entire key recovery process to fail.

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 are prompted to authenticate with the passkey they used to create the account. Most passkey authentication providers still show some kind of prompt even if they don't find the passkey within the local authenticator, such as a picture with a QR code if the passkey was created using a phone.

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