Home | History | Annotate | Download | only in hardware 
      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 
    215