Android Hardware Abstraction Layer
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 2
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 /**
45  * Flags for keymaster_device::flags
46  */
47 enum {
48  /*
49  * Indicates this keymaster implementation does not have hardware that
50  * keeps private keys out of user space.
51  *
52  * This should not be implemented on anything other than the default
53  * implementation.
54  */
56 };
57 
60 };
61 
62 /**
63  * Asymmetric key pair types.
64  */
65 typedef enum {
66  TYPE_RSA = 1,
67  TYPE_DSA = 2,
68  TYPE_EC = 3,
70 
71 /**
72  * Parameters needed to generate an RSA key.
73  */
74 typedef struct {
75  uint32_t modulus_size;
76  uint64_t public_exponent;
78 
79 /**
80  * Parameters needed to generate a DSA key.
81  */
82 typedef struct {
83  uint32_t key_size;
84  uint32_t generator_len;
85  uint32_t prime_p_len;
86  uint32_t prime_q_len;
87  const uint8_t* generator;
88  const uint8_t* prime_p;
89  const uint8_t* prime_q;
91 
92 /**
93  * Parameters needed to generate an EC key.
94  *
95  * Field size is the only parameter in version 2. The sizes correspond to these required curves:
96  *
97  * 192 = NIST P-192
98  * 224 = NIST P-224
99  * 256 = NIST P-256
100  * 384 = NIST P-384
101  * 521 = NIST P-521
102  *
103  * The parameters for these curves are available at: http://www.nsa.gov/ia/_files/nist-routines.pdf
104  * in Chapter 4.
105  */
106 typedef struct {
107  uint32_t field_size;
109 
110 /**
111  * Digest type.
112  */
113 typedef enum {
116 
117 /**
118  * Type of padding used for RSA operations.
119  */
120 typedef enum {
123 
124 
125 typedef struct {
128 
129 typedef struct {
132 
133 typedef struct {
137 
138 /**
139  * The parameters that can be set for a given keymaster implementation.
140  */
143 
144  /**
145  * THIS IS DEPRECATED. Use the new "module_api_version" and "hal_api_version"
146  * fields in the keymaster_module initialization instead.
147  */
148  uint32_t client_version;
149 
150  /**
151  * See flags defined for keymaster_device::flags above.
152  */
153  uint32_t flags;
154 
155  void* context;
156 
157  /**
158  * Generates a public and private key. The key-blob returned is opaque
159  * and must subsequently provided for signing and verification.
160  *
161  * Returns: 0 on success or an error code less than 0.
162  */
163  int (*generate_keypair)(const struct keymaster_device* dev,
164  const keymaster_keypair_t key_type, const void* key_params,
165  uint8_t** key_blob, size_t* key_blob_length);
166 
167  /**
168  * Imports a public and private key pair. The imported keys will be in
169  * PKCS#8 format with DER encoding (Java standard). The key-blob
170  * returned is opaque and will be subsequently provided for signing
171  * and verification.
172  *
173  * Returns: 0 on success or an error code less than 0.
174  */
175  int (*import_keypair)(const struct keymaster_device* dev,
176  const uint8_t* key, const size_t key_length,
177  uint8_t** key_blob, size_t* key_blob_length);
178 
179  /**
180  * Gets the public key part of a key pair. The public key must be in
181  * X.509 format (Java standard) encoded byte array.
182  *
183  * Returns: 0 on success or an error code less than 0.
184  * On error, x509_data should not be allocated.
185  */
186  int (*get_keypair_public)(const struct keymaster_device* dev,
187  const uint8_t* key_blob, const size_t key_blob_length,
188  uint8_t** x509_data, size_t* x509_data_length);
189 
190  /**
191  * Deletes the key pair associated with the key blob.
192  *
193  * This function is optional and should be set to NULL if it is not
194  * implemented.
195  *
196  * Returns 0 on success or an error code less than 0.
197  */
198  int (*delete_keypair)(const struct keymaster_device* dev,
199  const uint8_t* key_blob, const size_t key_blob_length);
200 
201  /**
202  * Deletes all keys in the hardware keystore. Used when keystore is
203  * reset completely.
204  *
205  * This function is optional and should be set to NULL if it is not
206  * implemented.
207  *
208  * Returns 0 on success or an error code less than 0.
209  */
210  int (*delete_all)(const struct keymaster_device* dev);
211 
212  /**
213  * Signs data using a key-blob generated before. This can use either
214  * an asymmetric key or a secret key.
215  *
216  * Returns: 0 on success or an error code less than 0.
217  */
218  int (*sign_data)(const struct keymaster_device* dev,
219  const void* signing_params,
220  const uint8_t* key_blob, const size_t key_blob_length,
221  const uint8_t* data, const size_t data_length,
222  uint8_t** signed_data, size_t* signed_data_length);
223 
224  /**
225  * Verifies data signed with a key-blob. This can use either
226  * an asymmetric key or a secret key.
227  *
228  * Returns: 0 on successful verification or an error code less than 0.
229  */
230  int (*verify_data)(const struct keymaster_device* dev,
231  const void* signing_params,
232  const uint8_t* key_blob, const size_t key_blob_length,
233  const uint8_t* signed_data, const size_t signed_data_length,
234  const uint8_t* signature, const size_t signature_length);
235 };
237 
238 
239 /* Convenience API for opening and closing keymaster devices */
240 
241 static inline int keymaster_open(const struct hw_module_t* module,
242  keymaster_device_t** device)
243 {
244  int rc = module->methods->open(module, KEYSTORE_KEYMASTER,
245  (struct hw_device_t**) device);
246 
247  return rc;
248 }
249 
250 static inline int keymaster_close(keymaster_device_t* device)
251 {
252  return device->common.close(&device->common);
253 }
254 
255 __END_DECLS
256 
257 #endif // ANDROID_HARDWARE_KEYMASTER_H
258