Recovery Methods

The three supported recovery methods are automatic, password and passkey based recovery. Each has different security considerations. Each refers to how the recovery share is encrypted, and how the user can access it.

Password-Based Recovery

In password-based recovery, the recovery share is encrypted with a user-provided password. Recovery share encryption and decryption happen in the iFrame, making the user the sole owner of the entropy guarding the share. Check out the password-based signup section for more details.

Passkey Recovery

Passkey recovery works similarly to password-based recovery: an encryption key is derived from user input and shares are encrypted and split following the same pattern. In passkey-based recovery the cold share plaintext never leaves the client, neither does the derived encryption key. OpenSigner stores the following information:

• The internal passkey ID, issued by the passkey authenticator
• The encrypted (cold) share
• Some environment-related information (browser name, OS, OS Version and Device information)

Automatic Recovery

In automatic recovery, key encryption and decryption happen in the cold storage. While providing the benefit of not requiring the user to remember a password, it introduces some risks:

Ownership Risk

If the entity in control of the cold storage (which contains one of the two shares required to reconstruct the encryption key) is also the one in control of the other encryption key shares, it can access the full recovery share. This, when combined with control over one of the other two shares, allows the entity to reconstruct the key.

Network Risk

The raw encryption key travels over the network from the iFrame to the cold storage and can be intercepted. Mitigate this with proper network security measures. Check out the automatic recovery signup section for more details.

The 3 Key Shares vs The 2 Encryption Parts

System 1: Key Shares (Shamir's Secret Sharing)

The user's private key is divided into 3 shares:

1. Device Share: Stored in the browser's localStorage/IndexedDB.
2. Hot Share: Stored in the Host's Hot Storage (such as Openfort).
3. Cold Share: Stored in the Host's Shield (Cold Storage).

System 2: Encryption Parts (Project Encryption Key)

The Cold Share is ENCRYPTED. To decrypt it, you need the Project Encryption Key, which is also divided:

1. Developer Encryption Part: Held by the Developer (You). Created once and must be stored securely.
2. Shield Encryption Part: Stored in the Shield database (managed by the Host).

Non-Custodial in cloud hosting (such as Openfort)

For a Cloud Host (like Openfort) to reconstruct a user's private key, it would need 2 shares.

• It has the Hot Share (1/3).
• It has the Cold Share (2/3), BUT it is encrypted.
• To decrypt the Cold Share, it needs the Developer Encryption Part, which only the Developer holds.

Therefore, the Cloud Host cannot decrypt the Cold Share and remains with only 1 usable share (Hot Share), which is insufficient to reconstruct the private key.

Secure Usage: Encryption Sessions

To avoid sending the Developer Encryption Part with every request (which would verify the "custody" rule but increase exposure risk), use Encryption Sessions.

1. Backend calls POST /project/encryption-session with the encryption_part.
2. Shield returns a temporary, one-time use session_id.
3. The iFrame uses this session_id to decrypt the Cold Share.
4. The session expires immediately after use.

This ensures the critical secret (Developer Part) is not constantly exposed on the network.

OTP Verification for Automatic Recovery

Why OTP is Essential

To enhance the security of automatic recovery, you can enable OTP verification for your Shield project. When enabled, Shield requires an OTP to create an encrypted session for share decryption. The OTP is sent to the user's contact information (either email or phone number). This reduces the control that the cold storage host has over the stored shares.

How OTP Prevents Backend Reconstruction

Enabling OTP

When OTP is enabled:

1. User initiates a recovery/signing operation
2. Shield sends an OTP to the user's registered email or phone
3. User provides the OTP to the iframe
4. Only after OTP verification can the cold share be decrypted

This ensures that even with valid authentication tokens, the backend cannot unilaterally access user keys without active user participation.