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 */
45enum {
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
56struct keystore_module {
57    hw_module_t common;
58};
59
60/**
61 * Asymmetric key pair types.
62 */
63typedef enum {
64    TYPE_RSA = 1,
65} keymaster_keypair_t;
66
67/**
68 * Parameters needed to generate an RSA key.
69 */
70typedef 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 */
78typedef enum {
79    DIGEST_NONE,
80} keymaster_rsa_digest_t;
81
82/**
83 * Type of padding used for RSA operations.
84 */
85typedef enum {
86    PADDING_NONE,
87} keymaster_rsa_padding_t;
88
89typedef 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 */
97struct 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};
188typedef struct keymaster_device keymaster_device_t;
189
190
191/* Convenience API for opening and closing keymaster devices */
192
193static 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
206static 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
215