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 */
47enum {
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     */
55    KEYMASTER_SOFTWARE_ONLY = 0x00000001,
56};
57
58struct keystore_module {
59    hw_module_t common;
60};
61
62/**
63 * Asymmetric key pair types.
64 */
65typedef enum {
66    TYPE_RSA = 1,
67    TYPE_DSA = 2,
68    TYPE_EC = 3,
69} keymaster_keypair_t;
70
71/**
72 * Parameters needed to generate an RSA key.
73 */
74typedef struct {
75    uint32_t modulus_size;
76    uint64_t public_exponent;
77} keymaster_rsa_keygen_params_t;
78
79/**
80 * Parameters needed to generate a DSA key.
81 */
82typedef 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;
90} keymaster_dsa_keygen_params_t;
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 */
106typedef struct {
107    uint32_t field_size;
108} keymaster_ec_keygen_params_t;
109
110/**
111 * Digest type.
112 */
113typedef enum {
114    DIGEST_NONE,
115} keymaster_digest_t;
116
117/**
118 * Type of padding used for RSA operations.
119 */
120typedef enum {
121    PADDING_NONE,
122} keymaster_rsa_padding_t;
123
124
125typedef struct {
126    keymaster_digest_t digest_type;
127} keymaster_dsa_sign_params_t;
128
129typedef struct {
130    keymaster_digest_t digest_type;
131} keymaster_ec_sign_params_t;
132
133typedef struct {
134    keymaster_digest_t digest_type;
135    keymaster_rsa_padding_t padding_type;
136} keymaster_rsa_sign_params_t;
137
138/**
139 * The parameters that can be set for a given keymaster implementation.
140 */
141struct keymaster_device {
142    struct hw_device_t common;
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};
236typedef struct keymaster_device keymaster_device_t;
237
238
239/* Convenience API for opening and closing keymaster devices */
240
241static 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
250static 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
259