keymaster.h
Go to the documentation of this file.
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  */
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  */
73 
74  /*
75  * Indicates that the keymaster module supports DSA keys.
76  */
78 
79  /*
80  * Indicates that the keymaster module supports EC keys.
81  */
83 };
84 
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  */
93 };
94 
95 /**
96  * Asymmetric key pair types.
97  */
98 typedef enum {
99  TYPE_RSA = 1,
100  TYPE_DSA = 2,
101  TYPE_EC = 3,
103 
104 /**
105  * Parameters needed to generate an RSA key.
106  */
107 typedef struct {
108  uint32_t modulus_size;
109  uint64_t public_exponent;
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;
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;
142 
143 /**
144  * Digest type.
145  */
146 typedef enum {
149 
150 /**
151  * Type of padding used for RSA operations.
152  */
153 typedef enum {
156 
157 
158 typedef struct {
161 
162 typedef struct {
165 
166 typedef struct {
170 
171 /**
172  * The parameters that can be set for a given keymaster implementation.
173  */
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  */
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 };
276 
277 
278 /* Convenience API for opening and closing keymaster devices */
279 
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 
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
hw_module_t common
Definition: keymaster.h:92
int(* open)(const struct hw_module_t *module, const char *id, struct hw_device_t **device)
Definition: hardware.h:158
int(* close)(struct hw_device_t *device)
Definition: hardware.h:200
uint32_t client_version
Definition: keymaster.h:187
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)
Definition: keymaster.h:257
keymaster_digest_t
Definition: keymaster.h:146
keymaster_rsa_padding_t padding_type
Definition: keymaster.h:168
keymaster_digest_t digest_type
Definition: keymaster.h:159
keymaster_digest_t digest_type
Definition: keymaster.h:163
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)
Definition: keymaster.h:269
int(* delete_all)(const struct keymaster_device *dev)
Definition: keymaster.h:249
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)
Definition: keymaster.h:225
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)
Definition: keymaster.h:214
struct hw_module_methods_t * methods
Definition: hardware.h:142
struct hw_device_t common
Definition: keymaster.h:181
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)
Definition: keymaster.h:202
int(* delete_keypair)(const struct keymaster_device *dev, const uint8_t *key_blob, const size_t key_blob_length)
Definition: keymaster.h:237
uint32_t flags
Definition: keymaster.h:192
keymaster_keypair_t
Definition: keymaster.h:98
const uint8_t * generator
Definition: keymaster.h:120
keymaster_rsa_padding_t
Definition: keymaster.h:153
keymaster_digest_t digest_type
Definition: keymaster.h:167
#define KEYSTORE_KEYMASTER
Definition: keymaster.h:33