api/yaca/yaca_key.h

   1 /*
   2  *  Copyright (c) 2016 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  *  Contact: Krzysztof Jackiewicz <k.jackiewicz@samsung.com>
   5  *
   6  *  Licensed under the Apache License, Version 2.0 (the "License");
   7  *  you may not use this file except in compliance with the License.
   8  *  You may obtain a copy of the License at
   9  *
  10  *      http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  *  Unless required by applicable law or agreed to in writing, software
  13  *  distributed under the License is distributed on an "AS IS" BASIS,
  14  *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  *  See the License for the specific language governing permissions and
  16  *  limitations under the License
  17  */
  18
  19 /**
  20  * @file yaca_key.h
  21  * @brief
  22  */
  23
  24 #ifndef YACA_KEY_H
  25 #define YACA_KEY_H
  26
  27 #include <stddef.h>
  28 #include <yaca_types.h>
  29
  30 #ifdef __cplusplus
  31 extern "C" {
  32 #endif
  33
  34 /**
  35  * @defgroup  Key  Advanced API for the key and IV handling.
  36  *
  37  *
  38  * @{
  39  */
  40
  41 /**
  42  * @brief  NULL value for yaca_key_h type.
  43  *
  44  * @since_tizen 3.0
  45  */
  46 #define YACA_KEY_NULL ((yaca_key_h) NULL)
  47
  48 /**
  49  * @brief  Get key's type.
  50  *
  51  * @since_tizen 3.0
  52  *
  53  * @param[in]  key       Key which type we return
  54  * @param[out] key_type  Key type
  55  *
  56  * @return #YACA_ERROR_NONE on success, negative on error
  57  * @retval #YACA_ERROR_NONE Successful
  58  * @retval #YACA_ERROR_INVALID_PARAMETER Either of the params is NULL
  59  */
  60 int yaca_key_get_type(const yaca_key_h key, yaca_key_type_e *key_type);
  61
  62 /**
  63  * @brief  Get key's length (in bits).
  64  *
  65  * @since_tizen 3.0
  66  *
  67  * @param[in]  key          Key which length we return
  68  * @param[out] key_bit_len  Key length in bits
  69  *
  70  * @return #YACA_ERROR_NONE on success, negative on error
  71  * @retval #YACA_ERROR_NONE Successful
  72  * @retval #YACA_ERROR_INVALID_PARAMETER Either of the params is NULL
  73  * @retval #YACA_ERROR_INTERNAL Internal error
  74  */
  75 int yaca_key_get_bit_length(const yaca_key_h key, size_t *key_bit_len);
  76
  77 /**
  78  * @brief  Imports a key.
  79  *
  80  * @since_tizen 3.0
  81  *
  82  * @remarks  This function imports a key trying to match it to the key_type specified.
  83  *           It should autodetect both the key format and the file format.
  84  *
  85  * @remarks  For symmetric, IV and DES keys RAW binary format and BASE64 encoded
  86  *           binary format are supported.
  87  *           For asymmetric keys PEM and DER file formats are supported.
  88  *
  89  * @remarks  Asymmetric keys can be in PKCS#1 or SSleay key formats (for RSA and
  90  *           DSA respectively). Asymmetric private keys can also be in PKCS#8
  91  *           format. Additionally it is possible to import public RSA key from
  92  *           X509 certificate.
  93  *
  94  * @remarks  If the key is encrypted the algorithm will be autodetected and password
  95  *           used. If it's not known if the key is encrypted one should pass NULL as
  96  *           password and check for the #YACA_ERROR_INVALID_PASSWORD return code.
  97  *
  98  * @remarks  The @a key should be released using yaca_key_destroy()
  99  *
 100  * @param[in]  key_type  Type of the key
 101  * @param[in]  password  null terminated password for the key (can be NULL)
 102  * @param[in]  data      Blob containing the key
 103  * @param[in]  data_len  Size of the blob
 104  * @param[out] key       Returned key
 105  *
 106  * @return #YACA_ERROR_NONE on success, negative on error
 107  * @retval #YACA_ERROR_NONE Successful
 108  * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0,
 109  *                                       invalid key_type or data_len too big)
 110  * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
 111  * @retval #YACA_ERROR_INTERNAL Internal error
 112  * @retval #YACA_ERROR_INVALID_PASSWORD Invalid password given or password was required
 113  *                                      and none was given
 114  *
 115  * @see #yaca_key_type_e
 116  * @see yaca_key_export()
 117  * @see yaca_key_destroy()
 118  */
 119 int yaca_key_import(yaca_key_type_e key_type,
 120                     const char *password,
 121                     const char *data,
 122                     size_t data_len,
 123                     yaca_key_h *key);
 124
 125 /**
 126  * @brief  Exports a key to arbitrary format. Export may fail if key is HW-based.
 127  *
 128  * @since_tizen 3.0
 129  *
 130  * @remarks  This function exports the key to an arbitrary key format and key file format.
 131  *
 132  * @remarks  For key formats two values are allowed:
 133  *           - #YACA_KEY_FORMAT_DEFAULT: this is the only option possible in case of symmetric
 134  *                                       keys (or IV), for asymmetric keys it will choose PKCS#1
 135  *                                       for RSA and SSLeay for DSA.
 136  *           - #YACA_KEY_FORMAT_PKCS8: this will only work for private asymmetric keys.
 137  *
 138  * @remarks  The following file formats are supported:
 139  *           - #YACA_KEY_FILE_FORMAT_RAW:    used only for symmetric, raw binary format
 140  *           - #YACA_KEY_FILE_FORMAT_BASE64: used only for symmetric, BASE64 encoded binary form
 141  *           - #YACA_KEY_FILE_FORMAT_PEM:    used only for asymmetric, PEM file format
 142  *           - #YACA_KEY_FILE_FORMAT_DER:    used only for asymmetric, DER file format
 143  *
 144  * @remarks  If no password is provided the exported key will be unencrypted. Only private
 145  *           RSA/DSA exported as PEM can be encrypted.
 146  *
 147  * @remarks  TODO:document the default encryption algorithm (AES256 for FORMAT_DEFAULT,
 148  *           unknown yet for the FORMAT_PKCS8).
 149  *
 150  * @param[in]  key           Key to be exported
 151  * @param[in]  key_fmt       Format of the key
 152  * @param[in]  key_file_fmt  Format of the key file
 153  * @param[in]  password      Password used for the encryption (can be NULL)
 154  * @param[out] data          Data, allocated by the library, containing exported key
 155  *                           (must be freed with yaca_free())
 156  * @param[out] data_len      Size of the output data
 157  *
 158  * @return #YACA_ERROR_NONE on success, negative on error
 159  * @retval #YACA_ERROR_NONE Successful
 160  * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0,
 161  *                                       invalid key/file format or data_len too big)
 162  * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
 163  * @retval #YACA_ERROR_INTERNAL Internal error
 164  *
 165  * @see #yaca_key_format_e
 166  * @see #yaca_key_file_format_e
 167  * @see yaca_key_import()
 168  * @see yaca_key_destroy()
 169  */
 170 int yaca_key_export(const yaca_key_h key,
 171                     yaca_key_format_e key_fmt,
 172                     yaca_key_file_format_e key_file_fmt,
 173                     const char *password,
 174                     char **data,
 175                     size_t *data_len);
 176
 177 /**
 178  * @brief  Generates a secure key (or an initialization vector).
 179  *
 180  * @since_tizen 3.0
 181  *
 182  * @remarks  This function is used to generate symmetric and private asymmetric keys.
 183  *
 184  * @remarks  Supported key lengths:
 185  *           - RSA: length >= 256bits
 186  *           - DSA: length >= 512bits, multiple of 64
 187  *
 188  * @remarks  The @a key should be released using yaca_key_destroy()
 189  *
 190  * @param[in]  key_type     Type of the key to be generated
 191  * @param[in]  key_bit_len  Length of the key (in bits) to be generated
 192  * @param[out] key          Newly generated key
 193  *
 194  * @return #YACA_ERROR_NONE on success, negative on error
 195  * @retval #YACA_ERROR_NONE Successful
 196  * @retval #YACA_ERROR_INVALID_PARAMETER key is NULL, incorrect key_type or
 197  *                                       key_bit_len is not dividable by 8
 198  * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
 199  * @retval #YACA_ERROR_INTERNAL Internal error
 200  *
 201  * @see #yaca_key_type_e
 202  * @see #yaca_key_bit_length_e
 203  * @see yaca_key_destroy()
 204  */
 205 int yaca_key_generate(yaca_key_type_e key_type,
 206                       size_t key_bit_len,
 207                       yaca_key_h *key);
 208
 209 /**
 210  * @brief  Extracts public key from a private one.
 211  *
 212  * @since_tizen 3.0
 213  *
 214  * @remarks  The @a pub_key should be released using yaca_key_destroy()
 215  *
 216  * @param[in]  prv_key   Private key to extract the public one from
 217  * @param[out] pub_key   Extracted public key
 218  *
 219  * @return #YACA_ERROR_NONE on success, negative on error
 220  * @retval #YACA_ERROR_NONE Successful
 221  * @retval #YACA_ERROR_INVALID_PARAMETER prv_key is of invalid type or pub_key is NULL
 222  * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
 223  * @retval #YACA_ERROR_INTERNAL Internal error
 224  *
 225  * @see yaca_key_generate()
 226  * @see yaca_key_import()
 227  * @see yaca_key_destroy()
 228  */
 229 int yaca_key_extract_public(const yaca_key_h prv_key, yaca_key_h *pub_key);
 230
 231 /**
 232  * @brief  Frees the key created by the library. Passing YACA_KEY_NULL is allowed.
 233  *
 234  * @since_tizen 3.0
 235  *
 236  * @param[in,out] key  Key to be freed
 237  *
 238  * @return #YACA_ERROR_NONE on success
 239  * @retval #YACA_ERROR_NONE Successful
 240  *
 241  * @see yaca_key_import()
 242  * @see yaca_key_export()
 243  * @see yaca_key_generate()
 244  */
 245 int yaca_key_destroy(yaca_key_h key);
 246
 247 /**@}*/
 248
 249 /**
 250  * @defgroup  Key-Derivation  Advanced API for the key derivation.
 251  *
 252  *
 253  * @{
 254  */
 255
 256 /**
 257  * @brief  Derives a key from user password (PKCS #5 a.k.a. pbkdf2 algorithm).
 258  *
 259  * @since_tizen 3.0
 260  *
 261  * @remarks  The @a key should be released using yaca_key_destroy()
 262  *
 263  * @param[in]  password     User password as a NULL-terminated string
 264  * @param[in]  salt         Salt, should be a non-empty string
 265  * @param[in]  salt_len     Length of the salt
 266  * @param[in]  iterations   Number of iterations
 267  * @param[in]  algo         Digest algorithm that should be used in key generation
 268  * @param[in]  key_bit_len  Length of a key (in bits) to be generated
 269  * @param[out] key          Newly generated key
 270  *
 271  * @return #YACA_ERROR_NONE on success, negative on error
 272  * @retval #YACA_ERROR_NONE Successful
 273  * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0,
 274  *                                       invalid algo or key_bit_len not dividable by 8)
 275  * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
 276  * @retval #YACA_ERROR_INTERNAL Internal error
 277  *
 278  * @see #yaca_digest_algorithm_e
 279  * @see yaca_key_destroy()
 280  */
 281 int yaca_key_derive_pbkdf2(const char *password,
 282                            const char *salt,
 283                            size_t salt_len,
 284                            int iterations,
 285                            yaca_digest_algorithm_e algo,
 286                            size_t key_bit_len,
 287                            yaca_key_h *key);
 288
 289 /**@}*/
 290
 291 #ifdef __cplusplus
 292 } /* extern */
 293 #endif
 294
 295 #endif /* YACA_KEY_H */