1 /* 2 * Copyright (C) 2015 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #ifndef ANDROID_HARDWARE_KEYMASTER_COMMON_H 18 #define ANDROID_HARDWARE_KEYMASTER_COMMON_H 19 20 #include <stdint.h> 21 #include <sys/cdefs.h> 22 #include <sys/types.h> 23 24 #include <hardware/hardware.h> 25 26 __BEGIN_DECLS 27 28 /** 29 * The id of this module 30 */ 31 #define KEYSTORE_HARDWARE_MODULE_ID "keystore" 32 33 #define KEYSTORE_KEYMASTER "keymaster" 34 35 36 /** 37 * Settings for "module_api_version" and "hal_api_version" 38 * fields in the keymaster_module initialization. 39 */ 40 41 /** 42 * Keymaster 0.X module version provide the same APIs, but later versions add more options 43 * for algorithms and flags. 44 */ 45 #define KEYMASTER_MODULE_API_VERSION_0_2 HARDWARE_MODULE_API_VERSION(0, 2) 46 #define KEYMASTER_DEVICE_API_VERSION_0_2 HARDWARE_DEVICE_API_VERSION(0, 2) 47 48 #define KEYMASTER_MODULE_API_VERSION_0_3 HARDWARE_MODULE_API_VERSION(0, 3) 49 #define KEYMASTER_DEVICE_API_VERSION_0_3 HARDWARE_DEVICE_API_VERSION(0, 3) 50 51 /** 52 * Keymaster 1.0 module version provides a completely different API, incompatible with 0.X. 53 */ 54 #define KEYMASTER_MODULE_API_VERSION_1_0 HARDWARE_MODULE_API_VERSION(1, 0) 55 #define KEYMASTER_DEVICE_API_VERSION_1_0 HARDWARE_DEVICE_API_VERSION(1, 0) 56 57 struct keystore_module { 58 /** 59 * Common methods of the keystore module. This *must* be the first member of keystore_module as 60 * users of this structure will cast a hw_module_t to keystore_module pointer in contexts where 61 * it's known the hw_module_t references a keystore_module. 62 */ 63 hw_module_t common; 64 65 /* There are no keystore module methods other than the common ones. */ 66 }; 67 68 /** 69 * Flags for keymaster0_device::flags 70 */ 71 enum { 72 /* 73 * Indicates this keymaster implementation does not have hardware that 74 * keeps private keys out of user space. 75 * 76 * This should not be implemented on anything other than the default 77 * implementation. 78 */ 79 KEYMASTER_SOFTWARE_ONLY = 1 << 0, 80 81 /* 82 * This indicates that the key blobs returned via all the primitives 83 * are sufficient to operate on their own without the trusted OS 84 * querying userspace to retrieve some other data. Key blobs of 85 * this type are normally returned encrypted with a 86 * Key Encryption Key (KEK). 87 * 88 * This is currently used by "vold" to know whether the whole disk 89 * encryption secret can be unwrapped without having some external 90 * service started up beforehand since the "/data" partition will 91 * be unavailable at that point. 92 */ 93 KEYMASTER_BLOBS_ARE_STANDALONE = 1 << 1, 94 95 /* 96 * Indicates that the keymaster module supports DSA keys. 97 */ 98 KEYMASTER_SUPPORTS_DSA = 1 << 2, 99 100 /* 101 * Indicates that the keymaster module supports EC keys. 102 */ 103 KEYMASTER_SUPPORTS_EC = 1 << 3, 104 }; 105 106 /** 107 * Asymmetric key pair types. 108 */ 109 typedef enum { 110 TYPE_RSA = 1, 111 TYPE_DSA = 2, 112 TYPE_EC = 3, 113 } keymaster_keypair_t; 114 115 /** 116 * Parameters needed to generate an RSA key. 117 */ 118 typedef struct { 119 uint32_t modulus_size; 120 uint64_t public_exponent; 121 } keymaster_rsa_keygen_params_t; 122 123 /** 124 * Parameters needed to generate a DSA key. 125 */ 126 typedef struct { 127 uint32_t key_size; 128 uint32_t generator_len; 129 uint32_t prime_p_len; 130 uint32_t prime_q_len; 131 const uint8_t* generator; 132 const uint8_t* prime_p; 133 const uint8_t* prime_q; 134 } keymaster_dsa_keygen_params_t; 135 136 /** 137 * Parameters needed to generate an EC key. 138 * 139 * Field size is the only parameter in version 2. The sizes correspond to these required curves: 140 * 141 * 192 = NIST P-192 142 * 224 = NIST P-224 143 * 256 = NIST P-256 144 * 384 = NIST P-384 145 * 521 = NIST P-521 146 * 147 * The parameters for these curves are available at: http://www.nsa.gov/ia/_files/nist-routines.pdf 148 * in Chapter 4. 149 */ 150 typedef struct { 151 uint32_t field_size; 152 } keymaster_ec_keygen_params_t; 153 154 155 /** 156 * Digest type. 157 */ 158 typedef enum { 159 DIGEST_NONE, 160 } keymaster_digest_algorithm_t; 161 162 /** 163 * Type of padding used for RSA operations. 164 */ 165 typedef enum { 166 PADDING_NONE, 167 } keymaster_rsa_padding_t; 168 169 170 typedef struct { 171 keymaster_digest_algorithm_t digest_type; 172 } keymaster_dsa_sign_params_t; 173 174 typedef struct { 175 keymaster_digest_algorithm_t digest_type; 176 } keymaster_ec_sign_params_t; 177 178 typedef struct { 179 keymaster_digest_algorithm_t digest_type; 180 keymaster_rsa_padding_t padding_type; 181 } keymaster_rsa_sign_params_t; 182 183 __END_DECLS 184 185 #endif // ANDROID_HARDWARE_KEYMASTER_COMMON_H 186