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 /** 58 * Keymaster 2.0 module version provides third API, slightly modified and extended from 1.0. 59 */ 60 #define KEYMASTER_MODULE_API_VERSION_2_0 HARDWARE_MODULE_API_VERSION(2, 0) 61 #define KEYMASTER_DEVICE_API_VERSION_2_0 HARDWARE_DEVICE_API_VERSION(2, 0) 62 63 struct keystore_module { 64 /** 65 * Common methods of the keystore module. This *must* be the first member of keystore_module as 66 * users of this structure will cast a hw_module_t to keystore_module pointer in contexts where 67 * it's known the hw_module_t references a keystore_module. 68 */ 69 hw_module_t common; 70 71 /* There are no keystore module methods other than the common ones. */ 72 }; 73 74 /** 75 * Flags for keymaster0_device::flags 76 */ 77 enum { 78 /* 79 * Indicates this keymaster implementation does not have hardware that 80 * keeps private keys out of user space. 81 * 82 * This should not be implemented on anything other than the default 83 * implementation. 84 */ 85 KEYMASTER_SOFTWARE_ONLY = 1 << 0, 86 87 /* 88 * This indicates that the key blobs returned via all the primitives 89 * are sufficient to operate on their own without the trusted OS 90 * querying userspace to retrieve some other data. Key blobs of 91 * this type are normally returned encrypted with a 92 * Key Encryption Key (KEK). 93 * 94 * This is currently used by "vold" to know whether the whole disk 95 * encryption secret can be unwrapped without having some external 96 * service started up beforehand since the "/data" partition will 97 * be unavailable at that point. 98 */ 99 KEYMASTER_BLOBS_ARE_STANDALONE = 1 << 1, 100 101 /* 102 * Indicates that the keymaster module supports DSA keys. 103 */ 104 KEYMASTER_SUPPORTS_DSA = 1 << 2, 105 106 /* 107 * Indicates that the keymaster module supports EC keys. 108 */ 109 KEYMASTER_SUPPORTS_EC = 1 << 3, 110 }; 111 112 /** 113 * Asymmetric key pair types. 114 */ 115 typedef enum { 116 TYPE_RSA = 1, 117 TYPE_DSA = 2, 118 TYPE_EC = 3, 119 } keymaster_keypair_t; 120 121 /** 122 * Parameters needed to generate an RSA key. 123 */ 124 typedef struct { 125 uint32_t modulus_size; 126 uint64_t public_exponent; 127 } keymaster_rsa_keygen_params_t; 128 129 /** 130 * Parameters needed to generate a DSA key. 131 */ 132 typedef struct { 133 uint32_t key_size; 134 uint32_t generator_len; 135 uint32_t prime_p_len; 136 uint32_t prime_q_len; 137 const uint8_t* generator; 138 const uint8_t* prime_p; 139 const uint8_t* prime_q; 140 } keymaster_dsa_keygen_params_t; 141 142 /** 143 * Parameters needed to generate an EC key. 144 * 145 * Field size is the only parameter in version 2. The sizes correspond to these required curves: 146 * 147 * 192 = NIST P-192 148 * 224 = NIST P-224 149 * 256 = NIST P-256 150 * 384 = NIST P-384 151 * 521 = NIST P-521 152 * 153 * The parameters for these curves are available at: http://www.nsa.gov/ia/_files/nist-routines.pdf 154 * in Chapter 4. 155 */ 156 typedef struct { 157 uint32_t field_size; 158 } keymaster_ec_keygen_params_t; 159 160 161 /** 162 * Digest type. 163 */ 164 typedef enum { 165 DIGEST_NONE, 166 } keymaster_digest_algorithm_t; 167 168 /** 169 * Type of padding used for RSA operations. 170 */ 171 typedef enum { 172 PADDING_NONE, 173 } keymaster_rsa_padding_t; 174 175 176 typedef struct { 177 keymaster_digest_algorithm_t digest_type; 178 } keymaster_dsa_sign_params_t; 179 180 typedef struct { 181 keymaster_digest_algorithm_t digest_type; 182 } keymaster_ec_sign_params_t; 183 184 typedef struct { 185 keymaster_digest_algorithm_t digest_type; 186 keymaster_rsa_padding_t padding_type; 187 } keymaster_rsa_sign_params_t; 188 189 __END_DECLS 190 191 #endif // ANDROID_HARDWARE_KEYMASTER_COMMON_H 192