hardware/keymaster.h

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