2 * Copyright (C) 2011 The Android Open Source Project
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
17 #ifndef ANDROID_HARDWARE_KEYMASTER_H
18 #define ANDROID_HARDWARE_KEYMASTER_H
21 #include <sys/cdefs.h>
22 #include <sys/types.h>
24 #include <hardware/hardware.h>
29 * The id of this module
31 #define KEYSTORE_HARDWARE_MODULE_ID "keystore"
33 #define KEYSTORE_KEYMASTER "keymaster"
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.
40 #define KEYMASTER_API_VERSION 1
43 * Flags for keymaster_device::flags
47 * Indicates this keymaster implementation does not have hardware that
48 * keeps private keys out of user space.
50 * This should not be implemented on anything other than the default
53 KEYMASTER_SOFTWARE_ONLY
= 0x00000001,
56 struct keystore_module
{
61 * Asymmetric key pair types.
65 } keymaster_keypair_t
;
68 * Parameters needed to generate an RSA key.
71 uint32_t modulus_size
;
72 uint64_t public_exponent
;
73 } keymaster_rsa_keygen_params_t
;
76 * Digest type used for RSA operations.
80 } keymaster_rsa_digest_t
;
83 * Type of padding used for RSA operations.
87 } keymaster_rsa_padding_t
;
90 keymaster_rsa_digest_t digest_type
;
91 keymaster_rsa_padding_t padding_type
;
92 } keymaster_rsa_sign_params_t
;
95 * The parameters that can be set for a given keymaster implementation.
97 struct keymaster_device
{
98 struct hw_device_t common
;
100 uint32_t client_version
;
103 * See flags defined for keymaster_device::flags above.
110 * Generates a public and private key. The key-blob returned is opaque
111 * and must subsequently provided for signing and verification.
113 * Returns: 0 on success or an error code less than 0.
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
);
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
125 * Returns: 0 on success or an error code less than 0.
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
);
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.
135 * Returns: 0 on success or an error code less than 0.
136 * On error, x509_data should not be allocated.
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
);
143 * Deletes the key pair associated with the key blob.
145 * This function is optional and should be set to NULL if it is not
148 * Returns 0 on success or an error code less than 0.
150 int (*delete_keypair
)(const struct keymaster_device
* dev
,
151 const uint8_t* key_blob
, const size_t key_blob_length
);
154 * Deletes all keys in the hardware keystore. Used when keystore is
157 * This function is optional and should be set to NULL if it is not
160 * Returns 0 on success or an error code less than 0.
162 int (*delete_all
)(const struct keymaster_device
* dev
);
165 * Signs data using a key-blob generated before. This can use either
166 * an asymmetric key or a secret key.
168 * Returns: 0 on success or an error code less than 0.
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
);
177 * Verifies data signed with a key-blob. This can use either
178 * an asymmetric key or a secret key.
180 * Returns: 0 on successful verification or an error code less than 0.
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
);
188 typedef struct keymaster_device keymaster_device_t
;
191 /* Convenience API for opening and closing keymaster devices */
193 static inline int keymaster_open(const struct hw_module_t
* module
,
194 keymaster_device_t
** device
)
196 int rc
= module
->methods
->open(module
, KEYSTORE_KEYMASTER
,
197 (struct hw_device_t
**) device
);
200 (*device
)->client_version
= KEYMASTER_API_VERSION
;
206 static inline int keymaster_close(keymaster_device_t
* device
)
208 return device
->common
.close(&device
->common
);
213 #endif // ANDROID_HARDWARE_KEYMASTER_H