Commit | Line | Data |
---|---|---|
1e494cf4 JB |
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 | * The API level of this version of the header. The allows the implementing | |
37 | * module to recognize which API level of the client it is dealing with in | |
38 | * the case of pre-compiled binary clients. | |
39 | */ | |
40 | #define KEYMASTER_API_VERSION 1 | |
41 | ||
42 | /** | |
43 | * Flags for keymaster_device::flags | |
44 | */ | |
45 | enum { | |
46 | /* | |
47 | * Indicates this keymaster implementation does not have hardware that | |
48 | * keeps private keys out of user space. | |
49 | * | |
50 | * This should not be implemented on anything other than the default | |
51 | * implementation. | |
52 | */ | |
53 | KEYMASTER_SOFTWARE_ONLY = 0x00000001, | |
54 | }; | |
55 | ||
56 | struct keystore_module { | |
57 | hw_module_t common; | |
58 | }; | |
59 | ||
60 | /** | |
61 | * Asymmetric key pair types. | |
62 | */ | |
63 | typedef enum { | |
64 | TYPE_RSA = 1, | |
65 | } keymaster_keypair_t; | |
66 | ||
67 | /** | |
68 | * Parameters needed to generate an RSA key. | |
69 | */ | |
70 | typedef struct { | |
71 | uint32_t modulus_size; | |
72 | uint64_t public_exponent; | |
73 | } keymaster_rsa_keygen_params_t; | |
74 | ||
75 | /** | |
76 | * Digest type used for RSA operations. | |
77 | */ | |
78 | typedef enum { | |
79 | DIGEST_NONE, | |
80 | } keymaster_rsa_digest_t; | |
81 | ||
82 | /** | |
83 | * Type of padding used for RSA operations. | |
84 | */ | |
85 | typedef enum { | |
86 | PADDING_NONE, | |
87 | } keymaster_rsa_padding_t; | |
88 | ||
89 | typedef struct { | |
90 | keymaster_rsa_digest_t digest_type; | |
91 | keymaster_rsa_padding_t padding_type; | |
92 | } keymaster_rsa_sign_params_t; | |
93 | ||
94 | /** | |
95 | * The parameters that can be set for a given keymaster implementation. | |
96 | */ | |
97 | struct keymaster_device { | |
98 | struct hw_device_t common; | |
99 | ||
100 | uint32_t client_version; | |
101 | ||
102 | /** | |
103 | * See flags defined for keymaster_device::flags above. | |
104 | */ | |
105 | uint32_t flags; | |
106 | ||
107 | void* context; | |
108 | ||
109 | /** | |
110 | * Generates a public and private key. The key-blob returned is opaque | |
111 | * and must subsequently provided for signing and verification. | |
112 | * | |
113 | * Returns: 0 on success or an error code less than 0. | |
114 | */ | |
115 | int (*generate_keypair)(const struct keymaster_device* dev, | |
116 | const keymaster_keypair_t key_type, const void* key_params, | |
117 | uint8_t** key_blob, size_t* key_blob_length); | |
118 | ||
119 | /** | |
120 | * Imports a public and private key pair. The imported keys will be in | |
121 | * PKCS#8 format with DER encoding (Java standard). The key-blob | |
122 | * returned is opaque and will be subsequently provided for signing | |
123 | * and verification. | |
124 | * | |
125 | * Returns: 0 on success or an error code less than 0. | |
126 | */ | |
127 | int (*import_keypair)(const struct keymaster_device* dev, | |
128 | const uint8_t* key, const size_t key_length, | |
129 | uint8_t** key_blob, size_t* key_blob_length); | |
130 | ||
131 | /** | |
132 | * Gets the public key part of a key pair. The public key must be in | |
133 | * X.509 format (Java standard) encoded byte array. | |
134 | * | |
135 | * Returns: 0 on success or an error code less than 0. | |
136 | * On error, x509_data should not be allocated. | |
137 | */ | |
138 | int (*get_keypair_public)(const struct keymaster_device* dev, | |
139 | const uint8_t* key_blob, const size_t key_blob_length, | |
140 | uint8_t** x509_data, size_t* x509_data_length); | |
141 | ||
142 | /** | |
143 | * Deletes the key pair associated with the key blob. | |
144 | * | |
145 | * This function is optional and should be set to NULL if it is not | |
146 | * implemented. | |
147 | * | |
148 | * Returns 0 on success or an error code less than 0. | |
149 | */ | |
150 | int (*delete_keypair)(const struct keymaster_device* dev, | |
151 | const uint8_t* key_blob, const size_t key_blob_length); | |
152 | ||
153 | /** | |
154 | * Deletes all keys in the hardware keystore. Used when keystore is | |
155 | * reset completely. | |
156 | * | |
157 | * This function is optional and should be set to NULL if it is not | |
158 | * implemented. | |
159 | * | |
160 | * Returns 0 on success or an error code less than 0. | |
161 | */ | |
162 | int (*delete_all)(const struct keymaster_device* dev); | |
163 | ||
164 | /** | |
165 | * Signs data using a key-blob generated before. This can use either | |
166 | * an asymmetric key or a secret key. | |
167 | * | |
168 | * Returns: 0 on success or an error code less than 0. | |
169 | */ | |
170 | int (*sign_data)(const struct keymaster_device* dev, | |
171 | const void* signing_params, | |
172 | const uint8_t* key_blob, const size_t key_blob_length, | |
173 | const uint8_t* data, const size_t data_length, | |
174 | uint8_t** signed_data, size_t* signed_data_length); | |
175 | ||
176 | /** | |
177 | * Verifies data signed with a key-blob. This can use either | |
178 | * an asymmetric key or a secret key. | |
179 | * | |
180 | * Returns: 0 on successful verification or an error code less than 0. | |
181 | */ | |
182 | int (*verify_data)(const struct keymaster_device* dev, | |
183 | const void* signing_params, | |
184 | const uint8_t* key_blob, const size_t key_blob_length, | |
185 | const uint8_t* signed_data, const size_t signed_data_length, | |
186 | const uint8_t* signature, const size_t signature_length); | |
187 | }; | |
188 | typedef struct keymaster_device keymaster_device_t; | |
189 | ||
190 | ||
191 | /* Convenience API for opening and closing keymaster devices */ | |
192 | ||
193 | static inline int keymaster_open(const struct hw_module_t* module, | |
194 | keymaster_device_t** device) | |
195 | { | |
196 | int rc = module->methods->open(module, KEYSTORE_KEYMASTER, | |
197 | (struct hw_device_t**) device); | |
198 | ||
199 | if (!rc) { | |
200 | (*device)->client_version = KEYMASTER_API_VERSION; | |
201 | } | |
202 | ||
203 | return rc; | |
204 | } | |
205 | ||
206 | static inline int keymaster_close(keymaster_device_t* device) | |
207 | { | |
208 | return device->common.close(&device->common); | |
209 | } | |
210 | ||
211 | __END_DECLS | |
212 | ||
213 | #endif // ANDROID_HARDWARE_KEYMASTER_H | |
214 |