include/key-manager-se-backend.h

   1 /*
   2  *  Copyright (c) 2016 Samsung Electronics Co., Ltd All Rights Reserved
   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  * @file        key-manager-se-backend.h
  18  * @author      Dongsun Lee (ds73.lee@samsung.com)
  19  * @version     1.0
  20  * @brief       provides fucntions for Key Manager SE Backend
  21  */
  22
  23
  24 #ifndef _KEY_MANAGER_SE_BACKEND_H_
  25 #define _KEY_MANAGER_SE_BACKEND_H_
  26
  27 #ifdef __cplusplus
  28 extern "C" {
  29 #endif
  30
  31 #include <tizen.h>
  32
  33 //################################################################################
  34 // Common
  35 //################################################################################
  36 /* Tizen Key Manager SE Backend Error */
  37 #define TIZEN_ERROR_KEY_MANAGER_SE_BACKEND        TIZEN_ERROR_KEY_MANAGER | 0x0100
  38
  39 /**
  40  * @brief Enumeration for errors of Key Manager SE Backend.
  41  */
  42 typedef enum {
  43     KMSB_ERROR_NONE = TIZEN_ERROR_NONE,                             /**< Successful */
  44     KMSB_ERROR_NO_KEY = TIZEN_ERROR_KEY_NOT_AVAILABLE,              /**< No Key Available */
  45     KMSB_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY,           /**< Out of memory */
  46     KMSB_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER,   /**< Invalid parameter */
  47     KMSB_ERROR_NOT_PERMITTED = TIZEN_ERROR_NOT_PERMITTED,           /**< Not permitted operation*/
  48     KMSB_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED,           /**< Not supported(implemented) operation*/
  49     KMSB_ERROR_OPERATION_FAILED = TIZEN_ERROR_TRY_AGAIN,            /**< Operation failed */
  50     KMSB_ERROR_VERIFICATION_FAILED = TIZEN_ERROR_KEY_MANAGER_SE_BACKEND | 0x01, /**< Verification failed */
  51 } kmsb_error_e;
  52
  53 //################################################################################
  54 // For Supporting Key Manager DB Encryption with SE Key
  55 //################################################################################
  56
  57 /**
  58  * @brief Version of DB Protection Key(DBP Key) Scheme.
  59  *
  60  * @note  This information is used in case of DBP Scheme upgrade.
  61  *        Version 1 : AES Key with 256 bit and CBC encrypiton mode
  62  */
  63 const unsigned int SE_BACKEND_DBP_SCHEME_VERSION = 1;
  64
  65 /**
  66  * @brief Encrypts input with DB Protection Key(DBP Key) in AES CBC mode.
  67  *
  68  * @param    dbp_scheme  [in]    Version of DB Protection Key(DBP Key) Scheme. This must be 1.
  69  * @param    input       [in]    pointer for input data to encrypt
  70  * @param    input_len   [in]    length for input data
  71  * @param    iv          [in]    pointer for initial vector
  72  * @param    iv_len      [in]    length for initial vector
  73  * @param    output      [out]   double pointer for output data.
  74  *                               The memory for this is allocated by SE backend
  75  *                               and it must be freed using `free()` by a caller after the usage.
  76  * @param    output_len  [out]   pointer for output data length.
  77  * @return  kmsb_error_e: TIZEN_ERROR_NONE means success, and other means fail
  78  *             - KMSB_ERROR_NO_KEY: when DBK is not generated.
  79  *             - KMSB_ERROR_OUT_OF_MEMORY: when there is no available memory
  80  *             - KMSB_ERROR_INVALID_PARAMETER: when input parameter is not valid
  81  *             - KMSB_ERROR_OPERATION_FAILED: when operation fails with unknown reason
  82  */
  83 kmsb_error_e kmsb_encrypt_with_dbp_key(const int dbp_scheme,
  84     const unsigned char *input, const unsigned int input_len,
  85     const unsigned char *iv, const unsigned int iv_len,
  86     unsigned char **output, unsigned int *output_len);
  87
  88 /**
  89  * @brief Generates a DB Protection Key(DBP Key).
  90  *
  91  * @param delete_old  [in]    flag for overriding an existing key.
  92  *                            if deleted_old == true, the existing key will be deleted before generation of a new key.
  93  *                            if deleted_odd == false, the error(KMSB_ERROR_NOT_PERMITTED) will be returned when an old key exists.
  94  * @return  kmsb_error_e: TIZEN_ERROR_NONE means success, and other means fail
  95  *             - KMSB_ERROR_NOT_PERMITTED: when deleted_odd == false and an old key exists.
  96  *             - KMSB_ERROR_OUT_OF_MEMORY: when there is no available memory
  97  *             - KMSB_ERROR_OPERATION_FAILED: when operation fails with unknown reason
  98  *
  99  * @note  The DBP Key is AES key with 256 bit.
 100  *        This key is used in kmsb_encrypt_with_dbp_key().
 101  */
 102 kmsb_error_e kmsb_generate_dbp_key(const bool delete_old);
 103
 104
 105 //################################################################################
 106 // For Supporting Preloaded SE Data
 107 //################################################################################
 108
 109 /**
 110  * @brief Enumeration for AES Mode.
 111  */
 112 typedef enum __kmsb_aes_mode {
 113     KMSB_ALGO_AES_CTR = 1,  /**< AES-CTR algorithm
 114                             Supported parameters in kmsb_aes_param_s:
 115                             - mode : KMSB_ALGO_AES_CTR(mandatory),
 116                             - iv = 16-byte initialization vector(mandatory)
 117                             - iv_len = 16(mandatory)
 118                             - ctr_len = length of counter block in bits
 119                             (optional, only 128b is supported at the moment) */
 120     KMSB_ALGO_AES_CBC,      /**< AES-CBC algorithm
 121                                Supported parameters in kmsb_aes_param_s:
 122                             - mode = KMSB_ALGO_AES_CBC(mandatory),
 123                             - iv = 16-byte initialization vector(mandatory)
 124                             - iv_len = 16(mandatory) */
 125     KMSB_ALGO_AES_GCM,      /**< AES-GCM algorithm
 126                             Supported parameters in kmsb_aes_param_s:
 127                             - mode = KMSB_ALGO_AES_GCM(mandatory),
 128                             - iv = initialization vector(mandatory)
 129                             - iv_len = IV lenghth in bytes(mandatory)
 130                             - tag_bit_len = GCM tag length in bits. One of
 131                             {32, 64, 96, 104, 112, 120, 128} (mandatory)
 132                             - tag = pointer to tag(mandatory)
 133                             For encryption case, the resulting tag is written to this pointer.
 134                             The memory of tag must be assigned by a caller in advance
 135                             and its size must be larget than tag_bit_len.
 136                             For decryption case, the caller must set tag value to this pointer in advance.
 137                             - aad = additional authentication data(optional)
 138                             - aad_len = AAD lenghth in bytes(optional) */
 139     KMSB_ALGO_AES_CFB,      /**< AES-CFB algorithm
 140                             Supported parameters in kmsb_aes_param_s:
 141                             - mode = KMSB_ALGO_AES_CFB(mandatory),
 142                             - iv = 16-byte initialization vector(mandatory)
 143                             - iv_len = 16(mandatory) */
 144 } kmsb_aes_mode_e;
 145
 146 /**
 147  * @brief The structure for AES parameter.
 148  */
 149 typedef struct __kmsb_aes_param {
 150     kmsb_aes_mode_e mode;      /**< AES mode */
 151     unsigned char *iv;         /**< Pointer to initialization vector */
 152     unsigned int iv_len;       /**< Length to initialization vector */
 153     unsigned int ctr_bit_len;  /**< Length of counter block in bits */
 154     unsigned int tag_bit_len;  /**< GCM tag length in bits */
 155     unsigned char *tag;        /**< Pointer to tag */
 156     unsigned char *aad;        /**< Additional authentication data*/
 157     unsigned int aad_len;      /**< Length of additional authentication data*/
 158 } kmsb_aes_param_s;
 159
 160 /*
 161  * @brief   Encrypts input using AES
 162  *
 163  * @param   key_idx      [in]     Key index to use
 164  * @param   param        [in/out] Parameters for AES algorithm.
 165  *                                Tag is out in GCM mode.
 166  * @param   input        [in]     pointer for input data to encrypt
 167  * @param   input_len    [in]     length for input data
 168  * @param   output       [out]    double pointer for output data.
 169  *                                The memory for this is allocated by SE backend
 170  *                                and it must be freed using `free()` by a caller after the usage.
 171  * @param    output_len   [out]   pointer for output data length.
 172  * @return  kmsb_error_e: TIZEN_ERROR_NONE means success, and other means fail
 173  *             - KMSB_ERROR_NO_KEY: when there is no key with key_idx.
 174  *             - KMSB_ERROR_OUT_OF_MEMORY: when there is no available memory
 175  *             - KMSB_ERROR_INVALID_PARAMETER: when input parameter is not valid
 176  *             - KMSB_ERROR_NOT_SUPPORTED: when specified algorithms in param is not supported
 177  *                                      or this operation is not supported
 178  *             - KMSB_ERROR_OPERATION_FAILED: when operation fails with unknown reason
 179  */
 180 kmsb_error_e kmsb_aes_encrypt(const unsigned int key_idx,
 181                             kmsb_aes_param_s *param,
 182                             const unsigned char *input, const unsigned int input_len,
 183                             unsigned char **output, unsigned int *output_len);
 184
 185 /*
 186  * @brief   Decrypts input using AES
 187  *
 188  * @param   key_idx      [in]    Key index to use
 189  * @param   param        [in]    Parameters for AES algorithm.
 190  * @param   input        [in]    pointer for input data to decrypt
 191  * @param   input_len    [in]    length for input data
 192  * @param   output       [out]   double pointer for output data.
 193  *                               The memory for this is allocated by SE backend
 194  *                               and it must be freed using `frsecp192r1Cee()` by a caller after the usage.
 195  * @param    output_len  [out]   pointer for output data length.
 196  * @return  kmsb_error_e: TIZEN_ERROR_NONE means success, and other means fail
 197  *             - KMSB_ERROR_NO_KEY: when there is no key with key_idx.
 198  *             - KMSB_ERROR_OUT_OF_MEMORY: when there is no available memory
 199  *             - KMSB_ERROR_INVALID_PARAMETER: when input parameter is not valid
 200  *             - KMSB_ERROR_VERIFICATION_FAILED: when GCM tag verification fails
 201  *             - KMSB_ERROR_NOT_SUPPORTED: when specified algorithms in param is not supported
 202  *                                      or this operation is not supported
 203  *             - KMSB_ERROR_OPERATION_FAILED: when operation fails with unknown reason
 204  */
 205 kmsb_error_e kmsb_aes_decrypt(const unsigned int key_idx,
 206                             kmsb_aes_param_s *param,
 207                             const unsigned char *input, const unsigned int input_len,
 208                             unsigned char **output, unsigned int *output_len);
 209
 210 /**
 211  * @brief Enumeration for elliptic curve.
 212  *
 213  * @note  This is the same as ckmc_ec_type_e in key-manager.
 214  */
 215 typedef enum __kmsb_ec_type {
 216     KMSB_EC_PRIME192V1 = 0, /**< Elliptic curve domain "secp192r1" listed in "SEC 2" recommended
 217                                   elliptic curve domain */
 218     KMSB_EC_PRIME256V1,      /**< "SEC 2" recommended elliptic curve domain - secp256r1 */
 219     KMSB_EC_SECP384R1        /**< NIST curve P-384(covers "secp384r1", the elliptic curve domain
 220                                   listed in See SEC 2 */
 221 } kmsb_ec_type_e;
 222
 223 /**
 224  * @brief Enumeration for hash algorithm.
 225  *
 226  * @note  This is the same as ckmc_hash_algo_e in key-manager.
 227  */
 228 typedef enum __kmsb_hash_algo {
 229     KMSB_HASH_NONE = 0, /**< No Hash Algorithm */
 230     KMSB_HASH_SHA1,     /**< Hash Algorithm SHA1 */
 231     KMSB_HASH_SHA256,   /**< Hash Algorithm SHA256 */
 232     KMSB_HASH_SHA384,   /**< Hash Algorithm SHA384 */
 233     KMSB_HASH_SHA512    /**< Hash Algorithm SHA512 */
 234 } kmsb_hash_algo_e;
 235
 236 /**
 237  * @brief The structure for signing parameter.
 238  */
 239 typedef struct __kmsb_sign_param {
 240     kmsb_ec_type_e ec_type;         /**< EC type(curve) of a key. (mandatory) */
 241     kmsb_hash_algo_e hash_algo;     /**< hash algorithm to digest in before processing. (mandatory) */
 242 } kmsb_sign_param_s;
 243
 244 /*
 245  * @brief   Sign message with hashing
 246  *
 247  * @param   key_idx     [in]    Key index of key to use
 248  * @param   param       [in]    Parameters for signing.
 249  * @param   msg         [in]    pointer for message to sign
 250  * @param   msg_len     [in]    length for message
 251  * @param   sig         [out]   double pointer for signature.
 252  *                              The memory for this is allocated by SE backend
 253  *                              and it must be freed using `free()` by a caller after the usage.
 254  * @param   sig_len     [out]   pointer for signature length.
 255  * @return  kmsb_error_e: TIZEN_ERROR_NONE means success, and other means fail
 256  *             - KMSB_ERROR_NO_KEY: when there is no key with key_idx.
 257  *             - KMSB_ERROR_OUT_OF_MEMORY: when there is no available memory
 258  *             - KMSB_ERROR_INVALID_PARAMETER: when input parameter is not valid
 259  *             - KMSB_ERROR_NOT_SUPPORTED: when specified algorithms in param is not supported
 260  *                                      or this operation is not supported
 261  *             - KMSB_ERROR_OPERATION_FAILED: when operation fails with unknown reason
 262  */
 263 kmsb_error_e kmsb_create_signature(const unsigned int key_idx,
 264                     const kmsb_sign_param_s *param,
 265                     const unsigned char *msg, const unsigned int msg_len,
 266                     unsigned char **sig, unsigned int *sig_len);
 267
 268 /*
 269  * @brief   Verify signature
 270  *
 271  * @param   key_idx     [in]    Key index of key to use
 272  * @param   param       [in]    Parameters for signing.
 273  * @param   msg         [in]    pointer for message to sign
 274  * @param   msg_len     [in]    length for message
 275  * @param   sig         [in]    pointer for signature.
 276  * @param   sig_len     [in]    signature length.
 277  * @return  kmsb_error_e: TIZEN_ERROR_NONE means success of verification, and other means fail
 278  *             - KMSB_ERROR_VERIFICATION_FAILED: when signature verification fails
 279  *             - KMSB_ERROR_NO_KEY: when there is no key with key_idx.
 280  *             - KMSB_ERROR_OUT_OF_MEMORY: when there is no available memory
 281  *             - KMSB_ERROR_INVALID_PARAMETER: when input parameter is not valid
 282  *             - KMSB_ERROR_NOT_SUPPORTED: when specified algorithms in param is not supported
 283  *                                      or this operation is not supported
 284  *             - KMSB_ERROR_OPERATION_FAILED: when operation fails with unknown reason
 285  */
 286 kmsb_error_e kmsb_verify_signature(const unsigned int key_idx,
 287                     const kmsb_sign_param_s *param,
 288                     const unsigned char *msg, const unsigned int msg_len,
 289                     const unsigned char *sig, const unsigned int sig_len);
 290
 291 /*
 292  * @brief   Get a key value from SE
 293  *
 294  * @note  Only the value of public key can be extracted from SE.
 295  *        Private keys or symmetric keys can not be extracted from SE.
 296  *
 297  * @param   key_idx     [in]    Key index to get
 298  * @param   output      [out]   double pointer for output data.
 299  *                              The memory for this is allocated by SE backend
 300  *                              and it must be freed using `free()` by a caller after the usage.
 301  * @param   output_len  [out]   pointer for output data length.
 302  * @return  kmsb_error_e: TIZEN_ERROR_NONE means success, and other means fail
 303  *             - KMSB_ERROR_NO_KEY: when there is no key with key_idx.
 304  *             - KMSB_ERROR_NOT_PERMITTED: when the key is not allowed to be exported from SE.
 305  *             - KMSB_ERROR_OUT_OF_MEMORY: when there is no available memory
 306  *             - KMSB_ERROR_INVALID_PARAMETER: when input parameter is not valid
 307  *             - KMSB_ERROR_NOT_SUPPORTED: when this operation is not supported
 308  *             - KMSB_ERROR_OPERATION_FAILED: when operation fails with unknown reason
 309  */
 310 kmsb_error_e kmsb_get_key(const unsigned int key_idx, unsigned char **output, unsigned int *output_len);
 311
 312 /*
 313  * @brief   Get a certificate value from SE
 314  *
 315  * @note  the format of certificate is the DER encoded form of X.509.
 316  *
 317  * @param   cert_idx    [in]    Certificate index to get
 318  * @param   output      [out]   double pointer for output data.
 319  *                              The memory for this is allocated by SE backend
 320  *                              and it must be freed using `free()` by a caller after the usage.
 321  * @param   output_len  [out]   pointer for output data length.
 322  * @return  kmsb_error_e: TIZEN_ERROR_NONE means success, and other means fail
 323  *             - KMSB_ERROR_NO_KEY: when there is no certificate with cert_idx.
 324  *             - KMSB_ERROR_NOT_PERMITTED: when the certificate is not allowed to be exported from SE.
 325  *             - KMSB_ERROR_OUT_OF_MEMORY: when there is no available memory
 326  *             - KMSB_ERROR_INVALID_PARAMETER: when input parameter is not valid
 327  *             - KMSB_ERROR_NOT_SUPPORTED: when this operation is not supported
 328  *             - KMSB_ERROR_OPERATION_FAILED: when operation fails with unknown reason
 329  */
 330 kmsb_error_e kmsb_get_certificate(const unsigned int cert_idx, unsigned char **output, unsigned int *output_len);
 331
 332 /*
 333  * @brief   Get a data value from SE
 334  *
 335  * @param   data_idx    [in]    Certificate index to get
 336  * @param   output      [out]   double pointer for output data.
 337  *                              The memory for this is allocated by SE backend
 338  *                              and it must be freed using `free()` by a caller after the usage.
 339  * @param   output_len  [out]   pointer for output data length.
 340  * @return  kmsb_error_e: TIZEN_ERROR_NONE means success, and other means fail
 341  *             - KMSB_ERROR_NO_KEY: when there is no certificate with data_idx.
 342  *             - KMSB_ERROR_NOT_PERMITTED: when the data is not allowed to be exported from SE.
 343  *             - KMSB_ERROR_OUT_OF_MEMORY: when there is no available memory
 344  *             - KMSB_ERROR_INVALID_PARAMETER: when input parameter is not valid
 345  *             - KMSB_ERROR_NOT_SUPPORTED: when this operation is not supported
 346  *             - KMSB_ERROR_OPERATION_FAILED: when operation fails with unknown reason
 347  */
 348 kmsb_error_e kmsb_get_data(const unsigned int data_idx, unsigned char **output, unsigned int *output_len);
 349
 350 #ifdef __cplusplus
 351 }
 352 #endif
 353
 354 #endif /*_KEY_MANAGER_SE_BACKEND_H_*/