keymaster.h revision 8ae65e71996ce871cda97cc9114cb5211cb273bf
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 * This function is optional and should be set to NULL if it is not 127 * implemented. 128 * 129 * Returns 0 on success or an error code less than 0. 130 */ 131 int (*delete_keypair)(const struct keymaster_device* dev, 132 const uint8_t* key_blob, const size_t key_blob_length); 133 134 /** 135 * Deletes all keys in the hardware keystore. Used when keystore is 136 * reset completely. 137 * 138 * This function is optional and should be set to NULL if it is not 139 * implemented. 140 * 141 * Returns 0 on success or an error code less than 0. 142 */ 143 int (*delete_all)(const struct keymaster_device* dev); 144 145 /** 146 * Signs data using a key-blob generated before. This can use either 147 * an asymmetric key or a secret key. 148 * 149 * Returns: 0 on success or an error code less than 0. 150 */ 151 int (*sign_data)(const struct keymaster_device* dev, 152 const void* signing_params, 153 const uint8_t* key_blob, const size_t key_blob_length, 154 const uint8_t* data, const size_t data_length, 155 uint8_t** signed_data, size_t* signed_data_length); 156 157 /** 158 * Verifies data signed with a key-blob. This can use either 159 * an asymmetric key or a secret key. 160 * 161 * Returns: 0 on successful verification or an error code less than 0. 162 */ 163 int (*verify_data)(const struct keymaster_device* dev, 164 const void* signing_params, 165 const uint8_t* key_blob, const size_t key_blob_length, 166 const uint8_t* signed_data, const size_t signed_data_length, 167 const uint8_t* signature, const size_t signature_length); 168}; 169typedef struct keymaster_device keymaster_device_t; 170 171 172/* Convenience API for opening and closing keymaster devices */ 173 174static inline int keymaster_open(const struct hw_module_t* module, 175 keymaster_device_t** device) 176{ 177 int rc = module->methods->open(module, KEYSTORE_KEYMASTER, 178 (struct hw_device_t**) device); 179 180 if (!rc) { 181 (*device)->client_version = KEYMASTER_API_VERSION; 182 } 183 184 return rc; 185} 186 187static inline int keymaster_close(keymaster_device_t* device) 188{ 189 return device->common.close(&device->common); 190} 191 192__END_DECLS 193 194#endif // ANDROID_HARDWARE_KEYMASTER_H 195 196