Secure Vault

Edit on Github Send Feedback vdocs-experimental

Secure Vault lets an application obtain a base KDK (Key Derivation Key) after a successful strong user authentication. The base KDK is not an encryption or MAC key and cannot be used directly — instead, the application can derive purpose-specific keys from it. This functionality is available only when the activation is already on protocol version 4.0.

Use Secure Vault when you need a stable, high-entropy root for deriving multiple scoped keys (encryption, MAC, wrapping keys, etc.) tied to the user’s successful strong authentication, without persisting those child keys. The PowerAuth Mobile SDK guarantees that the base KDKs remain stable during the lifetime of an activation.

Key identifiers

Two base KDKs are available, depending on the authentication factors used:

knowledge - available after successful authentication with possession + knowledge factors.
knowledgeOrBiometry - available after any successful 2FA authentication. This key is at least as strong as knowledge and can be used wherever a biometry-backed flow is acceptable.

Obtaining the “knowledge” base KDK

let auth = PowerAuthAuthentication.possessionWithPassword(password: "1234")
sdk.fetchSecureVaultKey(authentication: auth, keyIdentifier: .knowledge) { vaultKey, error in
    if let vaultKey {
        do {
            // Derive a 32-byte key
            let derivedKey = try vaultKey.deriveKey(withIndex: 1000, keySize: 32)
            let keyData = derivedKey.sensitiveData
        } catch {
            // handle derivation error
        }
    } else {
        // handle acquisition error
    }
}

Obtaining the “knowledgeOrBiometry” base KDK

let auth = PowerAuthAuthentication.possessionWithBiometry()
sdk.fetchSecureVaultKey(authentication: auth, keyIdentifier: .knowledgeOrBiometry) { vaultKey, error in
    if let vaultKey {
        do {
            // Derive a 32-byte key
            let derivedKey = try vaultKey.deriveKey(withIndex: 1000, keySize: 32)
            let keyData = derivedKey.sensitiveData
        } catch {
            // handle derivation error
        }
    } else {
        // handle acquisition error
    }
}

Security Recommendations

Do not store derived keys on the device. Always acquire the base KDK when needed and derive the keys for each specific purpose.
Destroy the base KDK as soon as possible.
Never reuse a derived key for multiple purposes (e.g., don’t use one key for both encryption and authentication).
When encrypting different data sets, derive a new key with a different index.
If your application uses multiple keys, maintain a registry of derivation indices to avoid accidental key reuse.

Obtaining Legacy Encryption Key

If your activation is still using PowerAuth protocol 3.3, you can obtain the legacy encryption key as follows:

// 2FA authentication
let auth = PowerAuthAuthentication.possessionWithPassword(password: "1234")

// Select custom key index
let index = UInt64(1000)

// Fetch the encryption key with the given index
powerAuthSDK.fetchEncryptionKey(auth, index: index) { (encryptionKey, error) in
    if error == nil {
        // ... use the encryption key to encrypt or decrypt data
        let keyData = encryptionKey.sensitiveData
    } else {
        // Report error
    }
}

This function is useful if you still have local data encrypted with a key generated by an older SDK version. It is recommended to decrypt the data with the old key and re-encrypt it using the new key, acquired via the fetchSecureVaultKey() function.