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  * @addtogroup CAPI_YACA_KEY_MODULE
  36  * @{
  37  */
  38
  39 /**
  40  * Note:  Key  Advanced API for the key and IV handling.
  41  *
  42  *
  43  */
  44
  45 /**
  46  * @brief  NULL value for yaca_key_h type.
  47  *
  48  * @since_tizen 3.0
  49  */
  50 #define YACA_KEY_NULL ((yaca_key_h) NULL)
  51
  52 /**
  53  * @brief  Get key's type.
  54  *
  55  * @since_tizen 3.0
  56  *
  57  * @param[in]  key       Key which type we return
  58  * @param[out] key_type  Key type
  59  *
  60  * @return #YACA_ERROR_NONE on success, negative on error
  61  * @retval #YACA_ERROR_NONE Successful
  62  * @retval #YACA_ERROR_INVALID_PARAMETER Either of the params is NULL
  63  */
  64 int yaca_key_get_type(const yaca_key_h key, yaca_key_type_e *key_type);
  65
  66 /**
  67  * @brief  Get key's length (in bits).
  68  *
  69  * @since_tizen 3.0
  70  *
  71  * @param[in]  key          Key which length we return
  72  * @param[out] key_bit_len  Key length in bits
  73  *
  74  * @return #YACA_ERROR_NONE on success, negative on error
  75  * @retval #YACA_ERROR_NONE Successful
  76  * @retval #YACA_ERROR_INVALID_PARAMETER Either of the params is NULL
  77  * @retval #YACA_ERROR_INTERNAL Internal error
  78  */
  79 int yaca_key_get_bit_length(const yaca_key_h key, size_t *key_bit_len);
  80
  81 /**
  82  * @brief  Imports a key.
  83  *
  84  * @since_tizen 3.0
  85  *
  86  * @remarks  This function imports a key trying to match it to the key_type specified.
  87  *           It should autodetect both the key format and the file format.
  88  *
  89  * @remarks  For symmetric, IV and DES keys RAW binary format and BASE64 encoded
  90  *           binary format are supported.
  91  *           For asymmetric keys PEM and DER file formats are supported.
  92  *
  93  * @remarks  Asymmetric keys can be in PKCS#1 or SSleay key formats (for RSA and
  94  *           DSA respectively). Asymmetric private keys can also be in PKCS#8
  95  *           format. Additionally it is possible to import public RSA key from
  96  *           X509 certificate.
  97  *
  98  * @remarks  If the key is encrypted the algorithm will be autodetected and password
  99  *           used. If it's not known if the key is encrypted one should pass NULL as
 100  *           password and check for the #YACA_ERROR_INVALID_PASSWORD return code.
 101  *
 102  * @remarks  If the imported key will be detected as a format that does not support
 103  *           encryption and password was passed #YACA_ERROR_INVALID_PARAMETER will
 104  *           be returned. For a list of keys and formats that do support encryption
 105  *           see yaca_key_export() documentation.
 106  *
 107  * @remarks  The @a key should be released using yaca_key_destroy()
 108  *
 109  * @param[in]  key_type  Type of the key
 110  * @param[in]  password  null terminated password for the key (can be NULL)
 111  * @param[in]  data      Blob containing the key
 112  * @param[in]  data_len  Size of the blob
 113  * @param[out] key       Returned key
 114  *
 115  * @return #YACA_ERROR_NONE on success, negative on error
 116  * @retval #YACA_ERROR_NONE Successful
 117  * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0,
 118  *                                       invalid key_type or data_len too big)
 119  * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
 120  * @retval #YACA_ERROR_INTERNAL Internal error
 121  * @retval #YACA_ERROR_INVALID_PASSWORD Invalid password given or password was required
 122  *                                      and none was given
 123  *
 124  * @see #yaca_key_type_e
 125  * @see yaca_key_export()
 126  * @see yaca_key_destroy()
 127  */
 128 int yaca_key_import(yaca_key_type_e key_type,
 129                     const char *password,
 130                     const char *data,
 131                     size_t data_len,
 132                     yaca_key_h *key);
 133
 134 /**
 135  * @brief  Exports a key to arbitrary format. Export may fail if key is HW-based.
 136  *
 137  * @since_tizen 3.0
 138  *
 139  * @remarks  This function exports the key to an arbitrary key format and key file format.
 140  *
 141  * @remarks  For key formats two values are allowed:
 142  *           - #YACA_KEY_FORMAT_DEFAULT: this is the only option possible in case of symmetric
 143  *                                       keys (or IV), for asymmetric keys it will choose PKCS#1
 144  *                                       for RSA keys and SSLeay for DSA keys.
 145  *           - #YACA_KEY_FORMAT_PKCS8: this will only work for private asymmetric keys.
 146  *
 147  * @remarks  The following file formats are supported:
 148  *           - #YACA_KEY_FILE_FORMAT_RAW:    used only for symmetric, raw binary format
 149  *           - #YACA_KEY_FILE_FORMAT_BASE64: used only for symmetric, BASE64 encoded binary form
 150  *           - #YACA_KEY_FILE_FORMAT_PEM:    used only for asymmetric, PEM file format
 151  *           - #YACA_KEY_FILE_FORMAT_DER:    used only for asymmetric, DER file format
 152  *
 153  * @remarks  Encryption is supported and optional for RSA/DSA private keys in the
 154  *           #YACA_KEY_FORMAT_DEFAULT with #YACA_KEY_FILE_FORMAT_PEM format. If no password is
 155  *           provided the exported key will be unencrypted. The encryption algorithm used
 156  *           in this case is AES-256-CBC.
 157  *
 158  * @remarks  Encryption is obligatory for #YACA_KEY_FORMAT_PKCS8 format (for both, PEM and DER
 159  *           file formats). If no password is provided the #YACA_ERROR_INVALID_PARAMETER will
 160  *           be returned. The encryption algorithm used in this case is PBE with DES-CBC.
 161  *
 162  * @remakrs  Encryption is not supported for the symmetric and public keys in all their
 163  *           supported formats. If a password is provided in such case the
 164  *           #YACA_ERROR_INVALID_PARAMETER will be returned.
 165  *
 166  * @param[in]  key           Key to be exported
 167  * @param[in]  key_fmt       Format of the key
 168  * @param[in]  key_file_fmt  Format of the key file
 169  * @param[in]  password      Password used for the encryption (can be NULL)
 170  * @param[out] data          Data, allocated by the library, containing exported key
 171  *                           (must be freed with yaca_free())
 172  * @param[out] data_len      Size of the output data
 173  *
 174  * @return #YACA_ERROR_NONE on success, negative on error
 175  * @retval #YACA_ERROR_NONE Successful
 176  * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0,
 177  *                                       invalid key/file format or data_len too big)
 178  * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
 179  * @retval #YACA_ERROR_INTERNAL Internal error
 180  *
 181  * @see #yaca_key_format_e
 182  * @see #yaca_key_file_format_e
 183  * @see yaca_key_import()
 184  * @see yaca_key_destroy()
 185  */
 186 int yaca_key_export(const yaca_key_h key,
 187                     yaca_key_format_e key_fmt,
 188                     yaca_key_file_format_e key_file_fmt,
 189                     const char *password,
 190                     char **data,
 191                     size_t *data_len);
 192
 193 /**
 194  * @brief  Generates a secure key (or an initialization vector).
 195  *
 196  * @since_tizen 3.0
 197  *
 198  * @remarks  This function is used to generate symmetric and private asymmetric keys.
 199  *
 200  * @remarks  Supported key lengths:
 201  *           - RSA: length >= 256bits
 202  *           - DSA: length >= 512bits, multiple of 64
 203  *
 204  * @remarks  The @a key should be released using yaca_key_destroy()
 205  *
 206  * @param[in]  key_type     Type of the key to be generated
 207  * @param[in]  key_bit_len  Length of the key (in bits) to be generated
 208  * @param[out] key          Newly generated key
 209  *
 210  * @return #YACA_ERROR_NONE on success, negative on error
 211  * @retval #YACA_ERROR_NONE Successful
 212  * @retval #YACA_ERROR_INVALID_PARAMETER key is NULL, incorrect key_type or
 213  *                                       key_bit_len is not dividable by 8
 214  * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
 215  * @retval #YACA_ERROR_INTERNAL Internal error
 216  *
 217  * @see #yaca_key_type_e
 218  * @see #yaca_key_bit_length_e
 219  * @see yaca_key_destroy()
 220  */
 221 int yaca_key_generate(yaca_key_type_e key_type,
 222                       size_t key_bit_len,
 223                       yaca_key_h *key);
 224
 225 /**
 226  * @brief  Extracts public key from a private one.
 227  *
 228  * @since_tizen 3.0
 229  *
 230  * @remarks  The @a pub_key should be released using yaca_key_destroy()
 231  *
 232  * @param[in]  prv_key   Private key to extract the public one from
 233  * @param[out] pub_key   Extracted public key
 234  *
 235  * @return #YACA_ERROR_NONE on success, negative on error
 236  * @retval #YACA_ERROR_NONE Successful
 237  * @retval #YACA_ERROR_INVALID_PARAMETER prv_key is of invalid type or pub_key is NULL
 238  * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
 239  * @retval #YACA_ERROR_INTERNAL Internal error
 240  *
 241  * @see yaca_key_generate()
 242  * @see yaca_key_import()
 243  * @see yaca_key_destroy()
 244  */
 245 int yaca_key_extract_public(const yaca_key_h prv_key, yaca_key_h *pub_key);
 246
 247 /**
 248  * @brief  Release the key created by the library. Passing YACA_KEY_NULL is allowed.
 249  *
 250  * @since_tizen 3.0
 251  *
 252  * @param[in,out] key  Key to be released
 253  *
 254  * @see yaca_key_import()
 255  * @see yaca_key_export()
 256  * @see yaca_key_generate()
 257  */
 258 void yaca_key_destroy(yaca_key_h key);
 259
 260
 261 /**
 262  * Note:  Key-Derivation  Advanced API for the key derivation.
 263  *
 264  *
 265  */
 266
 267 /**
 268  * @brief  Derives a key from user password (PKCS #5 a.k.a. pbkdf2 algorithm).
 269  *
 270  * @since_tizen 3.0
 271  *
 272  * @remarks  The @a key should be released using yaca_key_destroy()
 273  *
 274  * @param[in]  password     User password as a NULL-terminated string
 275  * @param[in]  salt         Salt, should be a non-empty string
 276  * @param[in]  salt_len     Length of the salt
 277  * @param[in]  iterations   Number of iterations
 278  * @param[in]  algo         Digest algorithm that should be used in key generation
 279  * @param[in]  key_bit_len  Length of a key (in bits) to be generated
 280  * @param[out] key          Newly generated key
 281  *
 282  * @return #YACA_ERROR_NONE on success, negative on error
 283  * @retval #YACA_ERROR_NONE Successful
 284  * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0,
 285  *                                       invalid algo or key_bit_len not dividable by 8)
 286  * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
 287  * @retval #YACA_ERROR_INTERNAL Internal error
 288  *
 289  * @see #yaca_digest_algorithm_e
 290  * @see yaca_key_destroy()
 291  */
 292 int yaca_key_derive_pbkdf2(const char *password,
 293                            const char *salt,
 294                            size_t salt_len,
 295                            size_t iterations,
 296                            yaca_digest_algorithm_e algo,
 297                            size_t key_bit_len,
 298                            yaca_key_h *key);
 299
 300 /**
 301   * @}
 302   */
 303
 304 #ifdef __cplusplus
 305 } /* extern */
 306 #endif
 307
 308 #endif /* YACA_KEY_H */