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