attestationChallenge property

Android Server-issued, single-use challenge (1–128 bytes) for hardware key attestation. Requires Android 7.0 (API 24) or newer.

When set, the keystore embeds the challenge in an X.509 attestation certificate for the new signing key, and createKeys returns the chain in KeyCreationResult.attestationCertificateChain so your server can verify that the key was generated in secure hardware (TEE or StrongBox). The plugin neither parses nor verifies the chain.

Attestation is an explicit opt-in, so by default (AttestationMode.enforceOnChallenge) it fails instead of silently returning an unattested key (attestationMode can allow falling back):

• BiometricError.invalidInput: the challenge is empty or longer than 128 bytes.
• BiometricError.notSupported: Android 6 (API 23), or the device's keystore cannot attest the key.
• BiometricError.notAvailable: the keystore reported a transient failure (e.g. attestation keys are not provisioned yet). Retry later with a fresh challenge. Detected on Android 13+; older versions report BiometricError.notSupported instead.

The input checks (and failIfExists) run before anything is deleted. A failure during key generation happens after the existing key under the same alias was removed — as with any createKeys failure — and never leaves an unattested key behind. Use failIfExists or a fresh alias to protect an existing key.

If StrongBox key generation fails, the plugin retries once in the TEE; the chain's attestationSecurityLevel tells your server which one produced the key. In hybrid mode (signatureType: ecdsa + enableDecryption: true) only the keystore EC signing key is attested; the software-generated decryption key cannot be.

iOS/macOS/Windows: setting this field to a valid challenge makes createKeys return BiometricError.notSupported without touching existing keys, unless attestationMode allows falling back. This deliberately departs from how other platform-specific fields are ignored: ignoring it would hand back an unattested key the caller believes is attested. Apple has no public API to attest an individual Secure Enclave key, and Windows attestation is not implemented.