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  Advanced API for the key and Initialization Vector handling.
  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  * @brief  NULL value for yaca_key_h type.
  41  *
  42  * @since_tizen 3.0
  43  */
  44 #define YACA_KEY_NULL ((yaca_key_h) NULL)
  45
  46 /**
  47  * @brief  Gets key's type.
  48  *
  49  * @since_tizen 3.0
  50  *
  51  * @param[in]  key       Key which type we return
  52  * @param[out] key_type  Key type
  53  *
  54  * @return #YACA_ERROR_NONE on success, negative on error
  55  * @retval #YACA_ERROR_NONE Successful
  56  * @retval #YACA_ERROR_INVALID_PARAMETER Either of the params is NULL
  57  *
  58  * @see #yaca_key_type_e
  59  */
  60 int yaca_key_get_type(const yaca_key_h key, yaca_key_type_e *key_type);
  61
  62 /**
  63  * @brief  Gets key's length (in bits).
  64  *
  65  * @since_tizen 3.0
  66  *
  67  * @remarks  @a key can be any symmetric (including an Initialization Vector) or
  68  *           asymmetric key (including key generation parameters).
  69  *
  70  * @remarks  For Diffie-Helmann @a key_bit_len returns prime length in bits. Values
  71  *           used to generate the key/parameters in yaca_key_generate() are not
  72  *           restored. Neither generator number nor values from #yaca_key_bit_length_dh_rfc_e.
  73  *
  74  * @remarks  For Elliptic Curves @a key_bit_len returns values from #yaca_key_bit_length_ec_e.
  75  *
  76  * @param[in]  key          Key which length we return
  77  * @param[out] key_bit_len  Key length in bits
  78  *
  79  * @return #YACA_ERROR_NONE on success, negative on error
  80  * @retval #YACA_ERROR_NONE Successful
  81  * @retval #YACA_ERROR_INVALID_PARAMETER Either of the params is NULL
  82  * @retval #YACA_ERROR_INTERNAL Internal error
  83  *
  84  * @see #yaca_key_bit_length_e
  85  * @see #yaca_key_bit_length_dh_rfc_e
  86  * @see #yaca_key_bit_length_ec_e
  87  */
  88 int yaca_key_get_bit_length(const yaca_key_h key, size_t *key_bit_len);
  89
  90 /**
  91  * @brief  Imports a key or key generation parameters.
  92  *
  93  * @since_tizen 3.0
  94  *
  95  * @remarks  Everywhere where either a key (of any type) or an asymmetric key is referred
  96  *           in the documentation of this function key generator parameters are also included.
  97  *
  98  * @remarks  This function imports a key trying to match it to the @a key_type specified.
  99  *           It should autodetect both the key format and the file format.
 100  *
 101  * @remarks  For symmetric, Initialization Vector and DES keys RAW binary format and BASE64 encoded
 102  *           binary format are supported.
 103  *           For asymmetric keys PEM and DER file formats are supported.
 104  *
 105  * @remarks  Asymmetric keys can be in their default ASN1 structure formats (like
 106  *           PKCS#1, SSleay or PKCS#3). Private asymmetric keys can also be in
 107  *           PKCS#8 format. Additionally it is possible to import public RSA/DSA/EC
 108  *           keys from X509 certificate.
 109  *
 110  * @remarks  If the key is encrypted the algorithm will be autodetected and password
 111  *           used. If it's not known if the key is encrypted one should pass NULL as
 112  *           password and check for the #YACA_ERROR_INVALID_PASSWORD return code.
 113  *
 114  * @remarks  If the imported key will be detected as a format that does not support
 115  *           encryption and password was passed #YACA_ERROR_INVALID_PARAMETER will
 116  *           be returned. For a list of keys and formats that do support encryption
 117  *           see yaca_key_export() documentation.
 118  *
 119  * @remarks  The @a key should be released using yaca_key_destroy()
 120  *
 121  * @param[in]  key_type  Type of the key
 122  * @param[in]  password  null terminated password for the key (can be NULL)
 123  * @param[in]  data      Blob containing the key
 124  * @param[in]  data_len  Size of the blob
 125  * @param[out] key       Returned key
 126  *
 127  * @return #YACA_ERROR_NONE on success, negative on error
 128  * @retval #YACA_ERROR_NONE Successful
 129  * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0,
 130  *                                       invalid @a key_type or @a data_len too big)
 131  * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
 132  * @retval #YACA_ERROR_INTERNAL Internal error
 133  * @retval #YACA_ERROR_INVALID_PASSWORD Invalid password given or password was required
 134  *                                      and none was given
 135  *
 136  * @see #yaca_key_type_e
 137  * @see yaca_key_export()
 138  * @see yaca_key_destroy()
 139  */
 140 int yaca_key_import(yaca_key_type_e key_type,
 141                     const char *password,
 142                     const char *data,
 143                     size_t data_len,
 144                     yaca_key_h *key);
 145
 146 /**
 147  * @brief  Exports a key or key generation parameters to arbitrary format.
 148  *
 149  * @since_tizen 3.0
 150  *
 151  * @remarks  Everywhere where either a key (of any type) or an asymmetric key is referred
 152  *           in the documentation of this function key generator parameters are also included.
 153  *
 154  * @remarks  This function exports the key to an arbitrary key format and key file format.
 155  *
 156  * @remarks  For key formats two values are allowed:
 157  *           - #YACA_KEY_FORMAT_DEFAULT: this is the only option possible in case of symmetric keys
 158  *                                       (or Initialization Vector), for asymmetric keys it will
 159  *                                       export to their default ASN1 structure format
 160  *                                       (e.g. PKCS#1, SSLeay, PKCS#3).
 161  *           - #YACA_KEY_FORMAT_PKCS8: this will only work for private asymmetric keys.
 162  *
 163  * @remarks  The following file formats are supported:
 164  *           - #YACA_KEY_FILE_FORMAT_RAW:    used only for symmetric, raw binary format
 165  *           - #YACA_KEY_FILE_FORMAT_BASE64: used only for symmetric, BASE64 encoded binary form
 166  *           - #YACA_KEY_FILE_FORMAT_PEM:    used only for asymmetric, PEM file format
 167  *           - #YACA_KEY_FILE_FORMAT_DER:    used only for asymmetric, DER file format
 168  *
 169  * @remarks  Encryption is supported and optional for RSA/DSA private keys in the
 170  *           #YACA_KEY_FORMAT_DEFAULT with #YACA_KEY_FILE_FORMAT_PEM format. If no password is
 171  *           provided the exported key will be unencrypted. The encryption algorithm used
 172  *           in this case is AES-256-CBC.
 173  *
 174  * @remarks  Encryption is obligatory for #YACA_KEY_FORMAT_PKCS8 format (for both, PEM and DER
 175  *           file formats). If no password is provided the #YACA_ERROR_INVALID_PARAMETER will
 176  *           be returned. The encryption algorithm used in this case is AES-256-CBC. The key is
 177  *           generated from password using PBKDF2 with HMAC-SHA1 function and 2048 iterations.
 178  *
 179  * @remarks  Encryption is not supported for the symmetric, public keys and key generation
 180  *           parameters in all their supported formats. If a password is provided in such
 181  *           case the #YACA_ERROR_INVALID_PARAMETER will be returned.
 182  *
 183  * @param[in]  key           Key to be exported
 184  * @param[in]  key_fmt       Format of the key
 185  * @param[in]  key_file_fmt  Format of the key file
 186  * @param[in]  password      Password used for the encryption (can be NULL)
 187  * @param[out] data          Data, allocated by the library, containing exported key
 188  *                           (must be freed with yaca_free())
 189  * @param[out] data_len      Size of the output data
 190  *
 191  * @return #YACA_ERROR_NONE on success, negative on error
 192  * @retval #YACA_ERROR_NONE Successful
 193  * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0,
 194  *                                       invalid key/file format or @ data_len too big)
 195  * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
 196  * @retval #YACA_ERROR_INTERNAL Internal error
 197  *
 198  * @see #yaca_key_format_e
 199  * @see #yaca_key_file_format_e
 200  * @see yaca_key_import()
 201  * @see yaca_key_destroy()
 202  */
 203 int yaca_key_export(const yaca_key_h key,
 204                     yaca_key_format_e key_fmt,
 205                     yaca_key_file_format_e key_file_fmt,
 206                     const char *password,
 207                     char **data,
 208                     size_t *data_len);
 209
 210 /**
 211  * @brief  Generates a secure key or key generation parameters (or an Initialization Vector).
 212  *
 213  * @since_tizen 3.0
 214  *
 215  * @remarks  This function is used to generate symmetric keys, private asymmetric keys
 216  *           or key generation parameters for key types that support them (DSA, DH and EC).
 217  *
 218  * @remarks  Supported key lengths:
 219  *           - RSA: length >= 256bits
 220  *           - DSA: length >= 512bits, multiple of 64
 221  *           - DH: a value taken from #yaca_key_bit_length_dh_rfc_e or
 222  *                 (YACA_KEY_LENGTH_DH_GENERATOR_* | prime_length_in_bits),
 223  *                 where prime_length_in_bits can be any positive number
 224  *           - EC: a value taken from #yaca_key_bit_length_ec_e
 225  *
 226  * @remarks  The @a key should be released using yaca_key_destroy()
 227  *
 228  * @param[in]  key_type     Type of the key to be generated
 229  * @param[in]  key_bit_len  Length of the key (in bits) to be generated
 230  * @param[out] key          Newly generated key
 231  *
 232  * @return #YACA_ERROR_NONE on success, negative on error
 233  * @retval #YACA_ERROR_NONE Successful
 234  * @retval #YACA_ERROR_INVALID_PARAMETER key is NULL, incorrect @a key_type or
 235  *                                       @a key_bit_len is not dividable by 8
 236  * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
 237  * @retval #YACA_ERROR_INTERNAL Internal error
 238  *
 239  * @see #yaca_key_type_e
 240  * @see #yaca_key_bit_length_e
 241  * @see #yaca_key_bit_length_dh_rfc_e
 242  * @see #YACA_KEY_LENGTH_DH_GENERATOR_2
 243  * @see #YACA_KEY_LENGTH_DH_GENERATOR_5
 244  * @see #yaca_key_bit_length_ec_e
 245  * @see yaca_key_destroy()
 246  */
 247 int yaca_key_generate(yaca_key_type_e key_type,
 248                       size_t key_bit_len,
 249                       yaca_key_h *key);
 250
 251 /**
 252  * @brief  Generates a secure private asymmetric key from parameters.
 253  *
 254  * @since_tizen 3.0
 255  *
 256  * @remarks  This function is used to generate private asymmetric keys
 257  *           based on pre-generated parameters.
 258  *
 259  * @remarks  The @a key should be released using yaca_key_destroy()
 260  *
 261  * @param[in]  params   Pre-generated parameters
 262  * @param[out] prv_key  Newly generated private key
 263  *
 264  * @return #YACA_ERROR_NONE on success, negative on error
 265  * @retval #YACA_ERROR_NONE Successful
 266  * @retval #YACA_ERROR_INVALID_PARAMETER key is NULL or incorrect @a params
 267  * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
 268  * @retval #YACA_ERROR_INTERNAL Internal error
 269  *
 270  * @see yaca_key_destroy()
 271  * @see yaca_key_generate()
 272  * @see yaca_key_extract_parameters()
 273  */
 274 int yaca_key_generate_from_parameters(const yaca_key_h params, yaca_key_h *prv_key);
 275
 276 /**
 277  * @brief  Extracts public key from a private one.
 278  *
 279  * @since_tizen 3.0
 280  *
 281  * @remarks  The @a pub_key should be released using yaca_key_destroy()
 282  *
 283  * @param[in]  prv_key  Private key to extract the public one from
 284  * @param[out] pub_key  Extracted public key
 285  *
 286  * @return #YACA_ERROR_NONE on success, negative on error
 287  * @retval #YACA_ERROR_NONE Successful
 288  * @retval #YACA_ERROR_INVALID_PARAMETER @a prv_key is of invalid type or @a pub_key is NULL
 289  * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
 290  * @retval #YACA_ERROR_INTERNAL Internal error
 291  *
 292  * @see yaca_key_generate()
 293  * @see yaca_key_import()
 294  * @see yaca_key_destroy()
 295  */
 296 int yaca_key_extract_public(const yaca_key_h prv_key, yaca_key_h *pub_key);
 297
 298 /**
 299  * @brief  Extracts parameters from a private or a public key.
 300  *
 301  * @since_tizen 3.0
 302  *
 303  * @remarks  The @a params_key should be released using yaca_key_destroy()
 304  *
 305  * @param[in]  key      A key to extract the parameters from
 306  * @param[out] params   Extracted parameters
 307  *
 308  * @return #YACA_ERROR_NONE on success, negative on error
 309  * @retval #YACA_ERROR_NONE Successful
 310  * @retval #YACA_ERROR_INVALID_PARAMETER @a key is of invalid type or @a params is NULL
 311  * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
 312  * @retval #YACA_ERROR_INTERNAL Internal error
 313  *
 314  * @see yaca_key_generate()
 315  * @see yaca_key_generate_from_parameters()
 316  * @see yaca_key_import()
 317  * @see yaca_key_destroy()
 318  */
 319 int yaca_key_extract_parameters(const yaca_key_h key, yaca_key_h *params);
 320
 321 /**
 322  * @brief  Derives a shared secret using Diffie-Helmann or EC Diffie-Helmann key exchange protocol.
 323  *
 324  * @since_tizen 3.0
 325  *
 326  * @remarks  The @a secret should not be used as a symmetric key,
 327  *           to produce a symmetric key pass the secret to a key derivation function (KDF)
 328  *           or a message digest function
 329  *
 330  * @remarks  The @a secret should be freed with yaca_free()
 331  *
 332  * @param[in]  prv_key      Our private key
 333  * @param[in]  pub_key      Peer public key
 334  * @param[out] secret       Generated shared secret
 335  * @param[out] secret_len   Size of the shared secret
 336  *
 337  * @return #YACA_ERROR_NONE on success, negative on error
 338  * @retval #YACA_ERROR_NONE Successful
 339  * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (invalid key)
 340  * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
 341  * @retval #YACA_ERROR_INTERNAL Internal error
 342  *
 343  * @see yaca_key_derive_kdf()
 344  * @see yaca_simple_calculate_digest()
 345  * @see yaca_free()
 346  */
 347 int yaca_key_derive_dh(const yaca_key_h prv_key,
 348                        const yaca_key_h pub_key,
 349                        char **secret,
 350                        size_t *secret_len);
 351
 352 /**
 353  * @brief  Derives a key material from shared secret.
 354  *
 355  * @since_tizen 3.0
 356  *
 357  * @remarks  The @a info parameter is ANSI X9.42 OtherInfo or ANSI X9.62 SharedInfo structure,
 358  *           more information can be found in ANSI X9.42/62 standard specification
 359  *
 360  * @remarks  The @a key_material or separate parts of it can be used to import a symmetric key
 361  *           with yaca_key_import()
 362  *
 363  * @remarks  The @a key_material should be freed using yaca_free()
 364  *
 365  * @param[in]  kdf               Key derivation function
 366  * @param[in]  algo              Digest algorithm that should be used in key derivation
 367  * @param[in]  secret            Shared secret
 368  * @param[in]  secret_len        Size of the shared secret
 369  * @param[in]  info              Optional additional info, use NULL if not appending extra info
 370  * @param[in]  info_len          Length of additional info, use 0 if not using additional info
 371  * @param[in]  key_material_len  Length of a key material to be generated
 372  * @param[out] key_material      Newly generated key material
 373  *
 374  * @return #YACA_ERROR_NONE on success, negative on error
 375  * @retval #YACA_ERROR_NONE Successful
 376  * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0,
 377  *                                       invalid algo or kdf)
 378  * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
 379  * @retval #YACA_ERROR_INTERNAL Internal error
 380  *
 381  * @see #yaca_kdf_e
 382  * @see #yaca_digest_algorithm_e
 383  * @see yaca_key_derive_dh()
 384  * @see yaca_key_import()
 385  * @see yaca_free()
 386  */
 387 int yaca_key_derive_kdf(yaca_kdf_e kdf,
 388                         yaca_digest_algorithm_e algo,
 389                         const char *secret,
 390                         size_t secret_len,
 391                         const char *info,
 392                         size_t info_len,
 393                         size_t key_material_len,
 394                         char **key_material);
 395
 396 /**
 397  * @brief  Derives a key from user password (PKCS #5 a.k.a. pbkdf2 algorithm).
 398  *
 399  * @since_tizen 3.0
 400  *
 401  * @remarks  The @a key should be released using yaca_key_destroy()
 402  *
 403  * @param[in]  password     User password as a NULL-terminated string
 404  * @param[in]  salt         Salt, should be a non-empty string
 405  * @param[in]  salt_len     Length of the salt
 406  * @param[in]  iterations   Number of iterations
 407  * @param[in]  algo         Digest algorithm that should be used in key generation
 408  * @param[in]  key_bit_len  Length of a key (in bits) to be generated
 409  * @param[out] key          Newly generated key
 410  *
 411  * @return #YACA_ERROR_NONE on success, negative on error
 412  * @retval #YACA_ERROR_NONE Successful
 413  * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0,
 414  *                                       invalid algo or key_bit_len not dividable by 8)
 415  * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
 416  * @retval #YACA_ERROR_INTERNAL Internal error
 417  *
 418  * @see #yaca_digest_algorithm_e
 419  * @see yaca_key_destroy()
 420  */
 421 int yaca_key_derive_pbkdf2(const char *password,
 422                            const char *salt,
 423                            size_t salt_len,
 424                            size_t iterations,
 425                            yaca_digest_algorithm_e algo,
 426                            size_t key_bit_len,
 427                            yaca_key_h *key);
 428
 429 /**
 430  * @brief  Release the key created by the library. Passing YACA_KEY_NULL is allowed.
 431  *
 432  * @since_tizen 3.0
 433  *
 434  * @param[in,out] key  Key to be released
 435  *
 436  * @see yaca_key_import()
 437  * @see yaca_key_export()
 438  * @see yaca_key_generate()
 439  */
 440 void yaca_key_destroy(yaca_key_h key);
 441
 442 /**
 443   * @}
 444   */
 445
 446 #ifdef __cplusplus
 447 } /* extern */
 448 #endif
 449
 450 #endif /* YACA_KEY_H */