2 * Copyright (c) 2016 Samsung Electronics Co., Ltd All Rights Reserved
4 * Contact: Krzysztof Jackiewicz <k.jackiewicz@samsung.com>
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
10 * http://www.apache.org/licenses/LICENSE-2.0
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
22 * @brief Advanced API for the key and Initialization Vector handling.
31 #include <yaca_types.h>
40 * @addtogroup CAPI_YACA_KEY_MODULE
46 * @brief Definition for NULL value for yaca_key_h type.
49 #define YACA_KEY_NULL ((yaca_key_h) NULL)
53 * @brief Gets key's type.
55 * @param[in] key Key which type we return
56 * @param[out] key_type Key type
57 * @return #YACA_ERROR_NONE on success,
59 * @retval #YACA_ERROR_NONE Successful
60 * @retval #YACA_ERROR_INVALID_PARAMETER Either of the params is NULL
61 * @see #yaca_key_type_e
63 int yaca_key_get_type(const yaca_key_h key, yaca_key_type_e *key_type);
67 * @brief Gets key's length (in bits).
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,
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
86 int yaca_key_get_bit_length(const yaca_key_h key, size_t *key_bit_len);
90 * @brief Imports a key or key generation parameters.
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,
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
125 * @see #yaca_key_type_e
126 * @see yaca_key_export()
127 * @see yaca_key_destroy()
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);
133 * @brief Exports a key or key generation parameters to arbitrary format.
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,
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()
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);
183 * @brief Generates a secure key or key generation parameters (or an Initialization Vector).
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,
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()
213 int yaca_key_generate(yaca_key_type_e key_type, size_t key_bit_len, yaca_key_h *key);
217 * @brief Generates a secure private asymmetric key from parameters.
219 * @remarks This function is used to generate private asymmetric keys
220 * based on pre-generated parameters.
221 * @remarks The @a key should be released using yaca_key_destroy().
222 * @param[in] params Pre-generated parameters
223 * @param[out] prv_key Newly generated private key
224 * @return #YACA_ERROR_NONE on success,
226 * @retval #YACA_ERROR_NONE Successful
227 * @retval #YACA_ERROR_INVALID_PARAMETER @a prv_key is NULL or incorrect @a params
228 * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
229 * @retval #YACA_ERROR_INTERNAL Internal error
230 * @see yaca_key_destroy()
231 * @see yaca_key_generate()
232 * @see yaca_key_extract_parameters()
234 int yaca_key_generate_from_parameters(const yaca_key_h params, yaca_key_h *prv_key);
238 * @brief Extracts public key from a private one.
240 * @remarks The @a pub_key should be released using yaca_key_destroy().
241 * @param[in] prv_key Private key to extract the public one from
242 * @param[out] pub_key Extracted public key
243 * @return #YACA_ERROR_NONE on success,
245 * @retval #YACA_ERROR_NONE Successful
246 * @retval #YACA_ERROR_INVALID_PARAMETER @a prv_key is of invalid type or @a pub_key is NULL
247 * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
248 * @retval #YACA_ERROR_INTERNAL Internal error
249 * @see yaca_key_generate()
250 * @see yaca_key_import()
251 * @see yaca_key_destroy()
253 int yaca_key_extract_public(const yaca_key_h prv_key, yaca_key_h *pub_key);
257 * @brief Extracts parameters from a private or a public key.
259 * @remarks The @a params should be released using yaca_key_destroy().
260 * @param[in] key A key to extract the parameters from
261 * @param[out] params Extracted parameters
262 * @return #YACA_ERROR_NONE on success,
264 * @retval #YACA_ERROR_NONE Successful
265 * @retval #YACA_ERROR_INVALID_PARAMETER @a key is of invalid type or @a params is NULL
266 * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
267 * @retval #YACA_ERROR_INTERNAL Internal error
268 * @see yaca_key_generate()
269 * @see yaca_key_generate_from_parameters()
270 * @see yaca_key_import()
271 * @see yaca_key_destroy()
273 int yaca_key_extract_parameters(const yaca_key_h key, yaca_key_h *params);
277 * @brief Derives a shared secret using Diffie-Helmann or EC Diffie-Helmann key exchange protocol.
279 * @remarks The @a secret should not be used as a symmetric key,
280 * to produce a symmetric key pass the secret to a key derivation function (KDF)
281 * or a message digest function.
282 * @remarks The @a secret should be freed with yaca_free().
283 * @param[in] prv_key Our private key
284 * @param[in] pub_key Peer public key
285 * @param[out] secret Generated shared secret
286 * @param[out] secret_len Size of the shared secret
287 * @return #YACA_ERROR_NONE on success,
289 * @retval #YACA_ERROR_NONE Successful
290 * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values
291 * (invalid @a prv_key or @a pub_key)
292 * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
293 * @retval #YACA_ERROR_INTERNAL Internal error
294 * @see yaca_key_derive_kdf()
295 * @see yaca_simple_calculate_digest()
298 int yaca_key_derive_dh(const yaca_key_h prv_key, const yaca_key_h pub_key, char **secret, size_t *secret_len);
302 * @brief Derives a key material from shared secret.
304 * @remarks The @a info parameter is ANSI X9.42 OtherInfo or ANSI X9.62 SharedInfo structure,
305 * more information can be found in ANSI X9.42/62 standard specification.
306 * @remarks The @a key_material or separate parts of it can be used to import a symmetric key
307 * with yaca_key_import().
308 * @remarks The @a key_material should be freed using yaca_free().
309 * @param[in] kdf Key derivation function
310 * @param[in] algo Digest algorithm that should be used in key derivation
311 * @param[in] secret Shared secret
312 * @param[in] secret_len Size of the shared secret
313 * @param[in] info Optional additional info, use NULL if not appending extra info
314 * @param[in] info_len Length of additional info, use 0 if not using additional info
315 * @param[in] key_material_len Length of a key material to be generated
316 * @param[out] key_material Newly generated key material
317 * @return #YACA_ERROR_NONE on success,
319 * @retval #YACA_ERROR_NONE Successful
320 * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0,
321 * invalid @a algo or @a kdf)
322 * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
323 * @retval #YACA_ERROR_INTERNAL Internal error
325 * @see #yaca_digest_algorithm_e
326 * @see yaca_key_derive_dh()
327 * @see yaca_key_import()
330 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);
334 * @brief Derives a key from user password (PKCS #5 a.k.a. pbkdf2 algorithm).
336 * @remarks The @a key should be released using yaca_key_destroy().
337 * @param[in] password User password as a null-terminated string
338 * @param[in] salt Salt, should be a non-empty string
339 * @param[in] salt_len Length of the salt
340 * @param[in] iterations Number of iterations
341 * @param[in] algo Digest algorithm that should be used in key generation
342 * @param[in] key_bit_len Length of a key (in bits) to be generated
343 * @param[out] key Newly generated key
344 * @return #YACA_ERROR_NONE on success,
346 * @retval #YACA_ERROR_NONE Successful
347 * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0,
348 * invalid @a algo or @a key_bit_len not dividable by 8)
349 * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
350 * @retval #YACA_ERROR_INTERNAL Internal error
351 * @see #yaca_digest_algorithm_e
352 * @see yaca_key_destroy()
354 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);
358 * @brief Releases the key created by the library. Passing YACA_KEY_NULL is allowed.
360 * @param[in,out] key Key to be released
361 * @see yaca_key_import()
362 * @see yaca_key_export()
363 * @see yaca_key_generate()
365 void yaca_key_destroy(yaca_key_h key);
378 #endif /* YACA_KEY_H */