| /* |
| * 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 <stdint.h> |
| #include <sys/cdefs.h> |
| #include <sys/types.h> |
| |
| #include <hardware/hardware.h> |
| |
| __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 |