KeyGenParameterSpec.Builder.SetUnlockedDeviceRequired(Boolean) Method
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Sets whether this key is authorized to be used only while the device is unlocked.
[Android.Runtime.Register("setUnlockedDeviceRequired", "(Z)Landroid/security/keystore/KeyGenParameterSpec$Builder;", "", ApiSince=28)]
public Android.Security.Keystore.KeyGenParameterSpec.Builder SetUnlockedDeviceRequired(bool unlockedDeviceRequired);[<Android.Runtime.Register("setUnlockedDeviceRequired", "(Z)Landroid/security/keystore/KeyGenParameterSpec$Builder;", "", ApiSince=28)>]
member this.SetUnlockedDeviceRequired : bool -> Android.Security.Keystore.KeyGenParameterSpec.BuilderParameters
- unlockedDeviceRequired
- Boolean
Returns
- Attributes
Remarks
Sets whether this key is authorized to be used only while the device is unlocked.
The device is considered to be locked for a user when the user's apps are currently inaccessible and some form of lock screen authentication is required to regain access to them. For the full definition, see KeyguardManager.isDeviceLocked().
Public key operations aren't restricted by setUnlockedDeviceRequired(true) and may be performed even while the device is locked. In Android 11 (API level 30) and lower, encryption and verification operations with symmetric keys weren't restricted either.
Keys that use setUnlockedDeviceRequired(true) can be imported and generated even while the device is locked, as long as the device has been unlocked at least once since the last reboot. However, such keys cannot be used (except for the unrestricted operations mentioned above) until the device is unlocked. Apps that need to encrypt data while the device is locked such that it can only be decrypted while the device is unlocked can generate a key and encrypt the data in software, import the key into Keystore using setUnlockedDeviceRequired(true), and zeroize the original key.
setUnlockedDeviceRequired(true) is related to but distinct from setUserAuthenticationRequired(true). setUnlockedDeviceRequired(true) requires that the device be unlocked, whereas setUserAuthenticationRequired(true) requires that a specific type of strong authentication has happened within a specific time period. They may be used together or separately; there are cases in which one requirement can be satisfied but not the other.
Warning: Be careful using setUnlockedDeviceRequired(true) on Android 14 (API level 34) and lower, since the following bugs existed in Android 12 through 14: When the user didn't have a secure lock screen, unlocked-device-required keys couldn't be generated, imported, or used; When the user's secure lock screen was removed, all of that user's unlocked-device-required keys were automatically deleted; Unlocking the device with a non-strong biometric, such as face on many devices, didn't re-authorize the use of unlocked-device-required keys; Unlocking the device with a biometric didn't re-authorize the use of unlocked-device-required keys in profiles that share their parent user's lock. These issues are fixed in Android 15, so apps can avoid them by using setUnlockedDeviceRequired(true) only on Android 15 and higher. Apps that use both setUnlockedDeviceRequired(true) and setUserAuthenticationRequired(true) are unaffected by the first two issues, since the first two issues describe expected behavior for setUserAuthenticationRequired(true).
Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.