Share via


DevicePolicyManager.GenerateKeyPair Method

Definition

This API can be called by the following to generate a new private/public key pair: <ul> <li>Device owner</li> <li>Profile owner</li> <li>Delegated certificate installer</li> <li>Credential management app</li> <li>An app that holds the android.Manifest.permission#MANAGE_DEVICE_POLICY_CERTIFICATES permission</li> </ul> If the device supports key generation via secure hardware, this method is useful for creating a key in KeyChain that never left the secure hardware.

[Android.Runtime.Register("generateKeyPair", "(Landroid/content/ComponentName;Ljava/lang/String;Landroid/security/keystore/KeyGenParameterSpec;I)Landroid/security/AttestedKeyPair;", "GetGenerateKeyPair_Landroid_content_ComponentName_Ljava_lang_String_Landroid_security_keystore_KeyGenParameterSpec_IHandler", ApiSince=28)]
[Android.Runtime.RequiresPermission("android.permission.MANAGE_DEVICE_POLICY_CERTIFICATES")]
public virtual Android.Security.AttestedKeyPair? GenerateKeyPair (Android.Content.ComponentName? admin, string algorithm, Android.Security.Keystore.KeyGenParameterSpec keySpec, Android.App.Admin.IdAttestationFlags idAttestationFlags);
[<Android.Runtime.Register("generateKeyPair", "(Landroid/content/ComponentName;Ljava/lang/String;Landroid/security/keystore/KeyGenParameterSpec;I)Landroid/security/AttestedKeyPair;", "GetGenerateKeyPair_Landroid_content_ComponentName_Ljava_lang_String_Landroid_security_keystore_KeyGenParameterSpec_IHandler", ApiSince=28)>]
[<Android.Runtime.RequiresPermission("android.permission.MANAGE_DEVICE_POLICY_CERTIFICATES")>]
abstract member GenerateKeyPair : Android.Content.ComponentName * string * Android.Security.Keystore.KeyGenParameterSpec * Android.App.Admin.IdAttestationFlags -> Android.Security.AttestedKeyPair
override this.GenerateKeyPair : Android.Content.ComponentName * string * Android.Security.Keystore.KeyGenParameterSpec * Android.App.Admin.IdAttestationFlags -> Android.Security.AttestedKeyPair

Parameters

admin
ComponentName

Which DeviceAdminReceiver this request is associated with, or null if the caller is not a device admin.

algorithm
String

The key generation algorithm, see java.security.KeyPairGenerator.

keySpec
KeyGenParameterSpec

Specification of the key to generate, see java.security.KeyPairGenerator.

idAttestationFlags
IdAttestationFlags

A bitmask of the identifiers that should be included in the attestation record (ID_TYPE_BASE_INFO, ID_TYPE_SERIAL, ID_TYPE_IMEI and ID_TYPE_MEID), and ID_TYPE_INDIVIDUAL_ATTESTATION if the attestation record should be signed using an individual attestation certificate. <p> 0 should be passed in if no device identification is required in the attestation record and the batch attestation certificate should be used. <p> If any flag is specified, then an attestation challenge must be included in the keySpec.

Returns

A non-null AttestedKeyPair if the key generation succeeded, null otherwise.

Attributes

Remarks

This API can be called by the following to generate a new private/public key pair: <ul> <li>Device owner</li> <li>Profile owner</li> <li>Delegated certificate installer</li> <li>Credential management app</li> <li>An app that holds the android.Manifest.permission#MANAGE_DEVICE_POLICY_CERTIFICATES permission</li> </ul> If the device supports key generation via secure hardware, this method is useful for creating a key in KeyChain that never left the secure hardware. Access to the key is controlled the same way as in #installKeyPair.

From Android android.os.Build.VERSION_CODES#S, the credential management app can call this API. If called by the credential management app, the componentName must be null. Note, there can only be a credential management app on an unmanaged device.

Because this method might take several seconds to complete, it should only be called from a worker thread. This method returns null when called from the main thread.

This method is not thread-safe, calling it from multiple threads at the same time will result in undefined behavior. If the calling thread is interrupted while the invocation is in-flight, it will eventually terminate and return null.

Note: If the provided alias is of an existing alias, all former grants that apps have been given to access the key and certificates associated with this alias will be revoked.

Attestation: to enable attestation, set an attestation challenge in keySpec via KeyGenParameterSpec.Builder#setAttestationChallenge. By specifying flags to the idAttestationFlags parameter, it is possible to request the device's unique identity to be included in the attestation record.

Specific identifiers can be included in the attestation record, and an individual attestation certificate can be used to sign the attestation record. To find out if the device supports these features, refer to #isDeviceIdAttestationSupported() and #isUniqueDeviceAttestationSupported().

Device owner, profile owner, their delegated certificate installer and the credential management app can use #ID_TYPE_BASE_INFO to request inclusion of the general device information including manufacturer, model, brand, device and product in the attestation record. Only device owner, profile owner on an organization-owned device or affiliated user, and their delegated certificate installers can use #ID_TYPE_SERIAL, #ID_TYPE_IMEI and #ID_TYPE_MEID to request unique device identifiers to be attested (the serial number, IMEI and MEID correspondingly), if supported by the device (see #isDeviceIdAttestationSupported()). Additionally, device owner, profile owner on an organization-owned device and their delegated certificate installers can also request the attestation record to be signed using an individual attestation certificate by specifying the #ID_TYPE_INDIVIDUAL_ATTESTATION flag (if supported by the device, see #isUniqueDeviceAttestationSupported()).

If any of #ID_TYPE_SERIAL, #ID_TYPE_IMEI and #ID_TYPE_MEID is set, it is implicitly assumed that #ID_TYPE_BASE_INFO is also set.

Attestation using #ID_TYPE_INDIVIDUAL_ATTESTATION can only be requested if key generation is done in StrongBox.

Java documentation for android.app.admin.DevicePolicyManager.generateKeyPair(android.content.ComponentName, java.lang.String, android.security.keystore.KeyGenParameterSpec, int).

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.

Applies to