keymaster.h revision 9271d04d888c5676ccd9707378d18cad0f06d607 
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
42struct keystore_module {
43    hw_module_t common;
44};
45
46/**
47 * Asymmetric key pair types.
48 */
49typedef enum {
50    TYPE_RSA = 1,
51} keymaster_keypair_t;
52
53/**
54 * Parameters needed to generate an RSA key.
55 */
56typedef struct {
57    uint32_t modulus_size;
58    uint64_t public_exponent;
59} keymaster_rsa_keygen_params_t;
60
61/**
62 * Digest type used for RSA operations.
63 */
64typedef enum {
65    DIGEST_NONE,
66} keymaster_rsa_digest_t;
67
68/**
69 * Type of padding used for RSA operations.
70 */
71typedef enum {
72    PADDING_NONE,
73} keymaster_rsa_padding_t;
74
75typedef struct {
76    keymaster_rsa_digest_t digest_type;
77    keymaster_rsa_padding_t padding_type;
78} keymaster_rsa_sign_params_t;
79
80/**
81 * The parameters that can be set for a given keymaster implementation.
82 */
83struct keymaster_device {
84    struct hw_device_t common;
85
86    uint32_t client_version;
87
88    void* context;
89
90    /**
91     * Generates a public and private key. The key-blob returned is opaque
92     * and must subsequently provided for signing and verification.
93     *
94     * Returns: 0 on success or an error code less than 0.
95     */
96    int (*generate_keypair)(const struct keymaster_device* dev,
97            const keymaster_keypair_t key_type, const void* key_params,
98            uint8_t** key_blob, size_t* key_blob_length);
99
100    /**
101     * Imports a public and private key pair. The imported keys will be in
102     * PKCS#8 format with DER encoding (Java standard). The key-blob
103     * returned is opaque and will be subsequently provided for signing
104     * and verification.
105     *
106     * Returns: 0 on success or an error code less than 0.
107     */
108    int (*import_keypair)(const struct keymaster_device* dev,
109            const uint8_t* key, const size_t key_length,
110            uint8_t** key_blob, size_t* key_blob_length);
111
112    /**
113     * Gets the public key part of a key pair. The public key must be in
114     * X.509 format (Java standard) encoded byte array.
115     *
116     * Returns: 0 on success or an error code less than 0.
117     * On error, x509_data should not be allocated.
118     */
119    int (*get_keypair_public)(const struct keymaster_device* dev,
120            const uint8_t* key_blob, const size_t key_blob_length,
121            uint8_t** x509_data, size_t* x509_data_length);
122
123    /**
124     * Deletes the key pair associated with the key blob.
125     */
126    int (*delete_keypair)(const struct keymaster_device* dev,
127            const uint8_t* key_blob, const size_t key_blob_length);
128
129    /**
130     * Signs data using a key-blob generated before. This can use either
131     * an asymmetric key or a secret key.
132     *
133     * Returns: 0 on success or an error code less than 0.
134     */
135    int (*sign_data)(const struct keymaster_device* dev,
136            const void* signing_params,
137            const uint8_t* key_blob, const size_t key_blob_length,
138            const uint8_t* data, const size_t data_length,
139            uint8_t** signed_data, size_t* signed_data_length);
140
141    /**
142     * Verifies data signed with a key-blob. This can use either
143     * an asymmetric key or a secret key.
144     *
145     * Returns: 0 on successful verification or an error code less than 0.
146     */
147    int (*verify_data)(const struct keymaster_device* dev,
148            const void* signing_params,
149            const uint8_t* key_blob, const size_t key_blob_length,
150            const uint8_t* signed_data, const size_t signed_data_length,
151            const uint8_t* signature, const size_t signature_length);
152};
153typedef struct keymaster_device keymaster_device_t;
154
155
156/* Convenience API for opening and closing keymaster devices */
157
158static inline int keymaster_open(const struct hw_module_t* module,
159        keymaster_device_t** device)
160{
161    int rc = module->methods->open(module, KEYSTORE_KEYMASTER,
162            (struct hw_device_t**) device);
163
164    if (!rc) {
165        (*device)->client_version = KEYMASTER_API_VERSION;
166    }
167
168    return rc;
169}
170
171static inline int keymaster_close(keymaster_device_t* device)
172{
173    return device->common.close(&device->common);
174}
175
176__END_DECLS
177
178#endif  // ANDROID_HARDWARE_KEYMASTER_H
179
180