1 /*
2 * Copyright (C) 2011 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_H
18 #define ANDROID_HARDWARE_KEYMASTER_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 * Settings for "module_api_version" and "hal_api_version"
37 * fields in the keymaster_module initialization.
38 */
39 #define KEYMASTER_HEADER_VERSION 3
40
41 #define KEYMASTER_MODULE_API_VERSION_0_2 HARDWARE_MODULE_API_VERSION(0, 2)
42 #define KEYMASTER_DEVICE_API_VERSION_0_2 HARDWARE_DEVICE_API_VERSION_2(0, 2, KEYMASTER_HEADER_VERSION)
43
44 #define KEYMASTER_MODULE_API_VERSION_0_3 HARDWARE_MODULE_API_VERSION(0, 3)
45 #define KEYMASTER_DEVICE_API_VERSION_0_3 HARDWARE_DEVICE_API_VERSION_2(0, 3, KEYMASTER_HEADER_VERSION)
46
47 /**
48 * Flags for keymaster_device::flags
49 */
50 enum {
51 /*
52 * Indicates this keymaster implementation does not have hardware that
53 * keeps private keys out of user space.
54 *
55 * This should not be implemented on anything other than the default
56 * implementation.
57 */
58 KEYMASTER_SOFTWARE_ONLY = 1 << 0,
59
60 /*
61 * This indicates that the key blobs returned via all the primitives
62 * are sufficient to operate on their own without the trusted OS
63 * querying userspace to retrieve some other data. Key blobs of
64 * this type are normally returned encrypted with a
65 * Key Encryption Key (KEK).
66 *
67 * This is currently used by "vold" to know whether the whole disk
68 * encryption secret can be unwrapped without having some external
69 * service started up beforehand since the "/data" partition will
70 * be unavailable at that point.
71 */
72 KEYMASTER_BLOBS_ARE_STANDALONE = 1 << 1,
73
74 /*
75 * Indicates that the keymaster module supports DSA keys.
76 */
77 KEYMASTER_SUPPORTS_DSA = 1 << 2,
78
79 /*
80 * Indicates that the keymaster module supports EC keys.
81 */
82 KEYMASTER_SUPPORTS_EC = 1 << 3,
83 };
84
85 struct keystore_module {
86 /**
87 * Common methods of the keystore module. This *must* be the first member of
88 * keystore_module as users of this structure will cast a hw_module_t to
89 * keystore_module pointer in contexts where it's known the hw_module_t references a
90 * keystore_module.
91 */
92 hw_module_t common;
93 };
94
95 /**
96 * Asymmetric key pair types.
97 */
98 typedef enum {
99 TYPE_RSA = 1,
100 TYPE_DSA = 2,
101 TYPE_EC = 3,
102 } keymaster_keypair_t;
103
104 /**
105 * Parameters needed to generate an RSA key.
106 */
107 typedef struct {
108 uint32_t modulus_size;
109 uint64_t public_exponent;
110 } keymaster_rsa_keygen_params_t;
111
112 /**
113 * Parameters needed to generate a DSA key.
114 */
115 typedef struct {
116 uint32_t key_size;
117 uint32_t generator_len;
118 uint32_t prime_p_len;
119 uint32_t prime_q_len;
120 const uint8_t* generator;
121 const uint8_t* prime_p;
122 const uint8_t* prime_q;
123 } keymaster_dsa_keygen_params_t;
124
125 /**
126 * Parameters needed to generate an EC key.
127 *
128 * Field size is the only parameter in version 2. The sizes correspond to these required curves:
129 *
130 * 192 = NIST P-192
131 * 224 = NIST P-224
132 * 256 = NIST P-256
133 * 384 = NIST P-384
134 * 521 = NIST P-521
135 *
136 * The parameters for these curves are available at: http://www.nsa.gov/ia/_files/nist-routines.pdf
137 * in Chapter 4.
138 */
139 typedef struct {
140 uint32_t field_size;
141 } keymaster_ec_keygen_params_t;
142
143 /**
144 * Digest type.
145 */
146 typedef enum {
147 DIGEST_NONE,
148 } keymaster_digest_t;
149
150 /**
151 * Type of padding used for RSA operations.
152 */
153 typedef enum {
154 PADDING_NONE,
155 } keymaster_rsa_padding_t;
156
157
158 typedef struct {
159 keymaster_digest_t digest_type;
160 } keymaster_dsa_sign_params_t;
161
162 typedef struct {
163 keymaster_digest_t digest_type;
164 } keymaster_ec_sign_params_t;
165
166 typedef struct {
167 keymaster_digest_t digest_type;
168 keymaster_rsa_padding_t padding_type;
169 } keymaster_rsa_sign_params_t;
170
171 /**
172 * The parameters that can be set for a given keymaster implementation.
173 */
174 struct keymaster_device {
175 /**
176 * Common methods of the keymaster device. This *must* be the first member of
177 * keymaster_device as users of this structure will cast a hw_device_t to
178 * keymaster_device pointer in contexts where it's known the hw_device_t references a
179 * keymaster_device.
180 */
181 struct hw_device_t common;
182
183 /**
184 * THIS IS DEPRECATED. Use the new "module_api_version" and "hal_api_version"
185 * fields in the keymaster_module initialization instead.
186 */
187 uint32_t client_version;
188
189 /**
190 * See flags defined for keymaster_device::flags above.
191 */
192 uint32_t flags;
193
194 void* context;
195
196 /**
197 * Generates a public and private key. The key-blob returned is opaque
198 * and must subsequently provided for signing and verification.
199 *
200 * Returns: 0 on success or an error code less than 0.
201 */
202 int (*generate_keypair)(const struct keymaster_device* dev,
203 const keymaster_keypair_t key_type, const void* key_params,
204 uint8_t** key_blob, size_t* key_blob_length);
205
206 /**
207 * Imports a public and private key pair. The imported keys will be in
208 * PKCS#8 format with DER encoding (Java standard). The key-blob
209 * returned is opaque and will be subsequently provided for signing
210 * and verification.
211 *
212 * Returns: 0 on success or an error code less than 0.
213 */
214 int (*import_keypair)(const struct keymaster_device* dev,
215 const uint8_t* key, const size_t key_length,
216 uint8_t** key_blob, size_t* key_blob_length);
217
218 /**
219 * Gets the public key part of a key pair. The public key must be in
220 * X.509 format (Java standard) encoded byte array.
221 *
222 * Returns: 0 on success or an error code less than 0.
223 * On error, x509_data should not be allocated.
224 */
225 int (*get_keypair_public)(const struct keymaster_device* dev,
226 const uint8_t* key_blob, const size_t key_blob_length,
227 uint8_t** x509_data, size_t* x509_data_length);
228
229 /**
230 * Deletes the key pair associated with the key blob.
231 *
232 * This function is optional and should be set to NULL if it is not
233 * implemented.
234 *
235 * Returns 0 on success or an error code less than 0.
236 */
237 int (*delete_keypair)(const struct keymaster_device* dev,
238 const uint8_t* key_blob, const size_t key_blob_length);
239
240 /**
241 * Deletes all keys in the hardware keystore. Used when keystore is
242 * reset completely.
243 *
244 * This function is optional and should be set to NULL if it is not
245 * implemented.
246 *
247 * Returns 0 on success or an error code less than 0.
248 */
249 int (*delete_all)(const struct keymaster_device* dev);
250
251 /**
252 * Signs data using a key-blob generated before. This can use either
253 * an asymmetric key or a secret key.
254 *
255 * Returns: 0 on success or an error code less than 0.
256 */
257 int (*sign_data)(const struct keymaster_device* dev,
258 const void* signing_params,
259 const uint8_t* key_blob, const size_t key_blob_length,
260 const uint8_t* data, const size_t data_length,
261 uint8_t** signed_data, size_t* signed_data_length);
262
263 /**
264 * Verifies data signed with a key-blob. This can use either
265 * an asymmetric key or a secret key.
266 *
267 * Returns: 0 on successful verification or an error code less than 0.
268 */
269 int (*verify_data)(const struct keymaster_device* dev,
270 const void* signing_params,
271 const uint8_t* key_blob, const size_t key_blob_length,
272 const uint8_t* signed_data, const size_t signed_data_length,
273 const uint8_t* signature, const size_t signature_length);
274 };
275 typedef struct keymaster_device keymaster_device_t;
276
277
278 /* Convenience API for opening and closing keymaster devices */
279
keymaster_open(const struct hw_module_t * module,keymaster_device_t ** device)280 static inline int keymaster_open(const struct hw_module_t* module,
281 keymaster_device_t** device)
282 {
283 int rc = module->methods->open(module, KEYSTORE_KEYMASTER,
284 (struct hw_device_t**) device);
285
286 return rc;
287 }
288
keymaster_close(keymaster_device_t * device)289 static inline int keymaster_close(keymaster_device_t* device)
290 {
291 return device->common.close(&device->common);
292 }
293
294 __END_DECLS
295
296 #endif // ANDROID_HARDWARE_KEYMASTER_H
297