Password encryption

Add password protection to embedded wallets for enhanced security

If the user loses their password, they will lose access to their wallet. There is no way to recover the password or the wallet without it.

Password encryption adds an extra layer of security to embedded wallets by requiring a password to decrypt the user’s key share. This ensures that even if an attacker gains access to the stored key share, they cannot use it without the password.

How it works

When password encryption is enabled, it specifically protects the client-side key share:

1. The user’s client key share is encrypted with their password.
2. This encrypted share is sent through an encryption proxy which adds a second layer of encryption before storing it on Dynamic’s servers. This ensures the share is double-encrypted and accessible from any device.
3. Operations like signing transactions require the password to decrypt this share once per session; after unlocking, the user is not prompted again until the next session.
4. The password is never sent to Dynamic; decryption happens entirely client-side.
5. No single party (Dynamic, encryption provider) can access the key share alone.

Requiring password for wallets

You can require all wallets to have a password in the Dynamic Developer Console:

1. Navigate to Embedded Wallets.
2. Toggle Require Password to enforce that all wallets must be created with a password.

When Require Password is enabled, a password must be provided when creating a wallet. Attempting to create a wallet without a password will return an error. Once the wallet is created and unlocked, it remains unlocked for the rest of the session, so the password is not required for every operation.

Creating a password-protected wallet

Use the createWallet method with a password parameter:

import DynamicSDKSwift

let sdk = DynamicSDK.instance()

func createSecureWallet(password: String) async throws {
    try await sdk.wallets.embedded.createWallet(
        chain: "EVM",
        password: password
    )

    print("Password-protected wallet created")
}

Password management

• Users set their own password during wallet creation
• They must enter the password to unlock the wallet
• Important: If the user forgets their password, wallet recovery is not possible without a backup.

Unlocking a wallet

If you use Dynamic’s built-in UI, the user is prompted for their password when needed; you do not need to call unlock yourself. The following applies when you build a custom UI.

Custom UI flow

If you are building a custom UI implementation, you must check the wallet lock state and unlock the wallet programmatically before performing any wallet operations. If you skip this step, Dynamic’s default password modal will appear, which defeats the purpose of a custom UI integration.

The required flow for custom UI implementations is:

1. Check wallet state: Call getWalletRecoveryState to determine if the wallet is password-encrypted and currently locked.
2. Unlock if needed: If the wallet is encrypted, collect the password in your own UI and call unlockWallet.
3. Proceed with operations: Only after the wallet is unlocked should you perform signing, transactions, or other wallet operations.

import DynamicSDKSwift

let sdk = DynamicSDK.instance()

func ensureWalletUnlocked(wallet: BaseWallet, password: String) async throws {
    guard let walletId = wallet.id else {
        throw NSError(domain: "WalletError", code: 0, userInfo: [NSLocalizedDescriptionKey: "Wallet ID is nil"])
    }

    // 1. Check if wallet is locked
    let state = try await sdk.wallets.waas.getWalletRecoveryState(
        walletId: walletId,
        accountAddress: wallet.address
    )

    if state.walletReadyState == "encrypted" {
        // 2. Unlock with the user's password
        try await sdk.wallets.waas.unlockWallet(
            walletId: walletId,
            accountAddress: wallet.address,
            password: password
        )
    }

    // 3. Wallet is now ready for operations
}

Using unlockWallet directly

Before performing operations with a password-protected wallet in your own flow, unlock it using the unlockWallet method.

import DynamicSDKSwift

let sdk = DynamicSDK.instance()

func handleUnlock(wallet: BaseWallet, password: String) async throws {
    guard let walletId = wallet.id else {
        print("Wallet has no ID")
        return
    }

    try await sdk.wallets.waas.unlockWallet(
        walletId: walletId,
        accountAddress: wallet.address,
        password: password
    )

    print("Wallet unlocked for this session")
}

Once unlocked, the wallet remains unlocked for the rest of the user session (until logout). The user is only asked for the password once per session.

Unlocking one wallet unlocks all wallets associated with the user account. As a result, all wallets for a user must share the same password.

Locking wallets

Re-lock unlocked wallets when the user should be prompted for their password again, for example when they step away from a sensitive screen or when your app enforces a re-authentication timeout. Locking clears the decrypted key shares held for the session, so the next wallet operation requires the password again. Only password-encrypted wallets are affected.

Call lockWallets to re-lock every unlocked wallet:

import DynamicSDKSwift

let sdk = DynamicSDK.instance()

func lockAllWallets() async throws {
    try await sdk.wallets.waas.lockWallets()
}

Call lockWallet with a walletId to re-lock a single wallet:

import DynamicSDKSwift

func lockOneWallet(wallet: BaseWallet) async throws {
    guard let walletId = wallet.id else { return }
    try await sdk.wallets.waas.lockWallet(walletId: walletId)
}

After locking, getWalletRecoveryState reports the wallet as encrypted again. Unlock it with unlockWallet before performing further operations, as described in Unlocking a wallet.

Operations requiring password

Any operation that changes the underlying key shares requires the password to be provided again, even if the wallet is currently unlocked. These operations include:

• Refreshing shares
• Resharing (Cloud backup)
• Delegation

This is because the new shares generated during these processes must be encrypted with the password before they are stored.

Dynamic’s UI does not prompt for the password during these operations. You must implement refresh, reshare (e.g. cloud backup), and delegation with a custom UI: obtain the password in your own flow and pass it programmatically into the SDK when triggering these operations. Do not rely on Dynamic to show a password field for share-changing operations.

Setting a password on an existing account

If a wallet was created without a password, you can add password protection later using setPassword.

import DynamicSDKSwift

let sdk = DynamicSDK.instance()

func addPasswordToWallet(wallet: BaseWallet, newPassword: String) async throws {
    guard let walletId = wallet.id else {
        print("Wallet has no ID")
        return
    }

    try await sdk.wallets.waas.setPassword(
        walletId: walletId,
        accountAddress: wallet.address,
        password: newPassword
    )

    print("Password added to existing wallet")
}

Updating the password

Change an existing password using updatePassword. This will update the password for all wallets associated with the user account.

import DynamicSDKSwift

let sdk = DynamicSDK.instance()

func changePassword(
    wallet: BaseWallet,
    currentPassword: String,
    newPassword: String
) async throws {
    guard let walletId = wallet.id else {
        print("Wallet has no ID")
        return
    }

    try await sdk.wallets.waas.updatePassword(
        walletId: walletId,
        accountAddress: wallet.address,
        existingPassword: currentPassword,
        newPassword: newPassword
    )

    print("Password updated")
}

Migrating a signer share from a temporary password

When you add an end-user signer to a Business Account wallet, use targetSignerPassword to encrypt the new signer share. Deliver this temporary password to the signer through an approved secure channel.

When the signer already has other password-encrypted wallets, those wallets use the signer’s existing password while the new share uses targetSignerPassword. Pass the temporary password in a wallet-specific WaasPasswordOverride entry:

try await sdk.wallets.waas.updatePassword(
    wallet: newlyAddedSignerWallet,
    existingPassword: userPassword,
    newPassword: userPassword,
    passwordOverrides: [
        WaasPasswordOverride(
            walletId: newlyAddedSignerWallet.id!,
            existingPassword: targetSignerPassword
        )
    ]
)

The update applies to all wallets associated with the signer. Use the wallet’s id for walletId, and do not call setPassword for an already encrypted share. Keep the temporary password available until the update succeeds, and never log or transmit it through an unsecured channel.

Checking wallet lock state

You can check if a wallet is currently locked or ready to use with getWalletRecoveryState.

import DynamicSDKSwift

let sdk = DynamicSDK.instance()

func checkRecoveryState(wallet: BaseWallet) async throws {
    guard let walletId = wallet.id else {
        print("Wallet has no ID")
        return
    }

    let state = try await sdk.wallets.waas.getWalletRecoveryState(
        walletId: walletId,
        accountAddress: wallet.address
    )

    if state.walletReadyState == "encrypted" {
        print("Wallet is locked. User needs to enter a password.")
    } else if state.walletReadyState == "ready" {
        print("Wallet is unlocked and ready to use.")
    }
}

Security considerations

Password-protected wallets are only as secure as the password itself. Enforce strong password requirements and educate users about password security.

• Password strength: Require minimum length and complexity
• No password recovery: If using user-provided passwords, there’s no way to recover a forgotten password without a backup.
• Session-based unlock: Wallets remain unlocked for the session, reducing friction while maintaining security

Related

• Password encryption (React) - React SDK guide
• Password encryption (React Native) - React Native guide
• Password encryption (JavaScript) - Vanilla JS SDK guide