/* * Copyright (C) 2011 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ #ifndef ANDROID_HARDWARE_KEYMASTER_H #define ANDROID_HARDWARE_KEYMASTER_H #include #include #include #include __BEGIN_DECLS /** * The id of this module */ #define KEYSTORE_HARDWARE_MODULE_ID "keystore" #define KEYSTORE_KEYMASTER "keymaster" /** * Settings for "module_api_version" and "hal_api_version" * fields in the keymaster_module initialization. */ #define KEYMASTER_HEADER_VERSION 3 #define KEYMASTER_MODULE_API_VERSION_0_2 HARDWARE_MODULE_API_VERSION(0, 2) #define KEYMASTER_DEVICE_API_VERSION_0_2 HARDWARE_DEVICE_API_VERSION_2(0, 2, KEYMASTER_HEADER_VERSION) #define KEYMASTER_MODULE_API_VERSION_0_3 HARDWARE_MODULE_API_VERSION(0, 3) #define KEYMASTER_DEVICE_API_VERSION_0_3 HARDWARE_DEVICE_API_VERSION_2(0, 3, KEYMASTER_HEADER_VERSION) /** * Flags for keymaster_device::flags */ enum { /* * Indicates this keymaster implementation does not have hardware that * keeps private keys out of user space. * * This should not be implemented on anything other than the default * implementation. */ KEYMASTER_SOFTWARE_ONLY = 1 << 0, /* * This indicates that the key blobs returned via all the primitives * are sufficient to operate on their own without the trusted OS * querying userspace to retrieve some other data. Key blobs of * this type are normally returned encrypted with a * Key Encryption Key (KEK). * * This is currently used by "vold" to know whether the whole disk * encryption secret can be unwrapped without having some external * service started up beforehand since the "/data" partition will * be unavailable at that point. */ KEYMASTER_BLOBS_ARE_STANDALONE = 1 << 1, /* * Indicates that the keymaster module supports DSA keys. */ KEYMASTER_SUPPORTS_DSA = 1 << 2, /* * Indicates that the keymaster module supports EC keys. */ KEYMASTER_SUPPORTS_EC = 1 << 3, }; struct keystore_module { /** * Common methods of the keystore module. This *must* be the first member of * keystore_module as users of this structure will cast a hw_module_t to * keystore_module pointer in contexts where it's known the hw_module_t references a * keystore_module. */ hw_module_t common; }; /** * Asymmetric key pair types. */ typedef enum { TYPE_RSA = 1, TYPE_DSA = 2, TYPE_EC = 3, } keymaster_keypair_t; /** * Parameters needed to generate an RSA key. */ typedef struct { uint32_t modulus_size; uint64_t public_exponent; } keymaster_rsa_keygen_params_t; /** * Parameters needed to generate a DSA key. */ typedef struct { uint32_t key_size; uint32_t generator_len; uint32_t prime_p_len; uint32_t prime_q_len; const uint8_t* generator; const uint8_t* prime_p; const uint8_t* prime_q; } keymaster_dsa_keygen_params_t; /** * Parameters needed to generate an EC key. * * Field size is the only parameter in version 2. The sizes correspond to these required curves: * * 192 = NIST P-192 * 224 = NIST P-224 * 256 = NIST P-256 * 384 = NIST P-384 * 521 = NIST P-521 * * The parameters for these curves are available at: http://www.nsa.gov/ia/_files/nist-routines.pdf * in Chapter 4. */ typedef struct { uint32_t field_size; } keymaster_ec_keygen_params_t; /** * Digest type. */ typedef enum { DIGEST_NONE, } keymaster_digest_t; /** * Type of padding used for RSA operations. */ typedef enum { PADDING_NONE, } keymaster_rsa_padding_t; typedef struct { keymaster_digest_t digest_type; } keymaster_dsa_sign_params_t; typedef struct { keymaster_digest_t digest_type; } keymaster_ec_sign_params_t; typedef struct { keymaster_digest_t digest_type; keymaster_rsa_padding_t padding_type; } keymaster_rsa_sign_params_t; /** * The parameters that can be set for a given keymaster implementation. */ struct keymaster_device { /** * Common methods of the keymaster device. This *must* be the first member of * keymaster_device as users of this structure will cast a hw_device_t to * keymaster_device pointer in contexts where it's known the hw_device_t references a * keymaster_device. */ struct hw_device_t common; /** * THIS IS DEPRECATED. Use the new "module_api_version" and "hal_api_version" * fields in the keymaster_module initialization instead. */ uint32_t client_version; /** * See flags defined for keymaster_device::flags above. */ uint32_t flags; void* context; /** * Generates a public and private key. The key-blob returned is opaque * and must subsequently provided for signing and verification. * * Returns: 0 on success or an error code less than 0. */ int (*generate_keypair)(const struct keymaster_device* dev, const keymaster_keypair_t key_type, const void* key_params, uint8_t** key_blob, size_t* key_blob_length); /** * Imports a public and private key pair. The imported keys will be in * PKCS#8 format with DER encoding (Java standard). The key-blob * returned is opaque and will be subsequently provided for signing * and verification. * * Returns: 0 on success or an error code less than 0. */ int (*import_keypair)(const struct keymaster_device* dev, const uint8_t* key, const size_t key_length, uint8_t** key_blob, size_t* key_blob_length); /** * Gets the public key part of a key pair. The public key must be in * X.509 format (Java standard) encoded byte array. * * Returns: 0 on success or an error code less than 0. * On error, x509_data should not be allocated. */ int (*get_keypair_public)(const struct keymaster_device* dev, const uint8_t* key_blob, const size_t key_blob_length, uint8_t** x509_data, size_t* x509_data_length); /** * Deletes the key pair associated with the key blob. * * This function is optional and should be set to NULL if it is not * implemented. * * Returns 0 on success or an error code less than 0. */ int (*delete_keypair)(const struct keymaster_device* dev, const uint8_t* key_blob, const size_t key_blob_length); /** * Deletes all keys in the hardware keystore. Used when keystore is * reset completely. * * This function is optional and should be set to NULL if it is not * implemented. * * Returns 0 on success or an error code less than 0. */ int (*delete_all)(const struct keymaster_device* dev); /** * Signs data using a key-blob generated before. This can use either * an asymmetric key or a secret key. * * Returns: 0 on success or an error code less than 0. */ int (*sign_data)(const struct keymaster_device* dev, const void* signing_params, const uint8_t* key_blob, const size_t key_blob_length, const uint8_t* data, const size_t data_length, uint8_t** signed_data, size_t* signed_data_length); /** * Verifies data signed with a key-blob. This can use either * an asymmetric key or a secret key. * * Returns: 0 on successful verification or an error code less than 0. */ int (*verify_data)(const struct keymaster_device* dev, const void* signing_params, const uint8_t* key_blob, const size_t key_blob_length, const uint8_t* signed_data, const size_t signed_data_length, const uint8_t* signature, const size_t signature_length); }; typedef struct keymaster_device keymaster_device_t; /* Convenience API for opening and closing keymaster devices */ static inline int keymaster_open(const struct hw_module_t* module, keymaster_device_t** device) { int rc = module->methods->open(module, KEYSTORE_KEYMASTER, (struct hw_device_t**) device); return rc; } static inline int keymaster_close(keymaster_device_t* device) { return device->common.close(&device->common); } __END_DECLS #endif // ANDROID_HARDWARE_KEYMASTER_H