Privy’s security architecture leverages secure execution environments to protect your users’ assets. Wallet private keys are only temporarily reconstructed within these strictly isolated, secure execution environments when needed for specific operations, under the wallet owner’s control.

Privy provides two types of secure execution environments: 1) via TEEs and 2) on the user’s device. Each environment ensures that private keys are never stored in complete form and are only temporarily reconstructed when needed.

By default, Privy uses trusted execution environments (TEEs), also known as secure enclaves, for secure wallet operations. As an advanced setting, Privy also enables wallets to be reassembled directly on user devices.

On-device execution is an advanced configuration. Please reach out to [email protected] to enable this setting.

  • On-device execution enables the fastest-possible signing speed (20 ms), but involves a more limited feature set.
  • If you have on-device execution enabled, you will see an indicator in the Advanced settings in the Privy Dashboard. If you do not see this indicator, your app’s wallet execute within TEEs.
  • You can migrate from on-device to TEE execution. Apps may only operate in one environment.

​
Browser-isolated execution environments on user devices

With on-device execution, Privy secures wallets directly on user devices using browser-enforced isolation via iframes. This relies on the same browser security boundaries that have been battle-tested for decades, securing billions of dollars in daily financial transactions across the modern internet.

The Privy iframe runs in a separate process with its own isolated memory space, completely separated from your application. This isolation is enforced by:

  • Hardware-level memory protection
  • Browser process separation
  • Strict origin and frame ancestor validation
  • Content Security Policy controls that strictly lock down network access

Browser security boundaries have been battle-tested for decades, securing billions of dollars in daily financial transactions across the modern internet.

​
Key shares

Privy’s security model is based on distributed key sharding. This means critical key entropy is split into encrypted shares, protected by separate security boundaries.

With on-device execution, there are three share types:

  • Device share, which is persisted on the user’s device. In a browser environment, this is stored in the browser’s domain-partitioned local storage via the iframe.
  • Auth share, which is encrypted and stored by Privy. This share is accessible only with valid user authentication.
  • Recovery share is used to provision the wallet on new user devices. This share is encrypted and secured either through user-managed methods (password or cloud backup) or Privy’s recovery key management system.

Two shares must be present to reconstruct the private key, which only happens temporarily within the iframe on the user’s device.

Typical operation involves sets of 2-of-2 shares, where a device-specific share and an auth share are provisioned for each device on which a wallet is used. Similarly, a recovery share and recovery-specific auth share are provisioned to enable recovery on new devices.

Wallet key shares in on-device execution

​
Securing the recovery share

Privy offers two approaches to securing the recovery share:

Automatic recovery

Privy’s key management system secures the encrypted recovery share, allowing users to provision their wallet on new devices through normal authentication. Privy infrastructure ensures only the user can decrypt their recovery share on their device.

When using automatic recovery, you are trusting Privy’s infrastructure to secure the user’s recovery share, and the user’s authentication token as the sole root of trust for their wallet.

User-managed recovery

With user-managed recovery, the recovery share is encrypted via a recovery factor managed by the user. This takes two forms:

  • Passwords: users can set a strong memorable password to secure the recovery share for their wallet. Privy has no knowledge of the user’s password and cannot decrypt the recovery share.
  • Cloud-backup: the recovery share is secured by a recovery decryption key that is backed up to the user’s cloud storage account (e.g. Google Drive or iCloud). Privy cannot access this backup and cannot decrypt the recovery share.

​
Key management operations

​
Creating a wallet

When a user creates a wallet, the secure execution environment generates strong entropy (128 bits) from a cryptographically secure random number generator (CSPRNG). This is converted to a mnemonic using BIP-39, from which Privy derives the wallet’s public key and private key. All Privy wallets are hierarchical deterministic (HD) wallets.

Immediately after creation, the wallet entropy is sharded into key shares, and the key shares are encrypted and distributed across separate security boundaries. This ensures that wallets can never be accessed outside of the secure execution environment.

​
Signing a transaction

Two shares must be present to reconstruct the private key. During regular operation, Privy reassembles the wallet using a device share and auth share. A device-specific share and an auth share are provisioned for each device on which a wallet is used.

In other words, when signing a transaction:

  1. Your application passes the transaction data through the Privy SDK
  2. The secure iframe validates authentication and retrieves necessary encrypted shares
  3. Key reconstruction occurs only in the iframe’s isolated memory
  4. The key is used temporarily in-memory for cryptographic signing
  5. Only the signature is returned to your application

Because Privy wallets are provisioned directly on user devices, cryptographic signing is extremely fast (20 ms).

Signing a transaction

​
Provision new devices

Users provision their wallet on a new device using the recovery share and auth share. This set of recovery shares is created on initialization of a new wallet.

When a user accesses your app on a new device, the iframe will retrieve the auth share for your user during the login process. Then, depending on how you’ve configured recovery, the iframe will decrypt the recovery share for your user by:

  • requesting the recovery decryption key using the user’s auth token, if using automatic recovery
  • having the user decrypt the key using their recovery factor (password or cloud account), if using user-managed recovery

With the auth share and the recovery share, the iframe provisions a new device share for the new device. This device share allows your user to continue using the wallet on that device.

Learn how to provision new devices in our docs.

Provision a new device

​
External key recovery

With Privy’s architecture, a user is able to recover their private key even if they lose their device or if they lose access to your app.

  • If the user loses access to their device and is unable to retrieve their device share, they can combine their auth share and decrypt their recovery share to reconstitute the full private key.
  • If the user loses access to your app and is unable to retrieve their auth share, Privy enables an external recovery service so that users are always able to export their wallet.

In all of these cases, Privy rotates keys to ensure compromised devices or authentication methods cannot be combined to maliciously reconstitute the private key.