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
21 * @brief Advanced API for the asymmetric encryption.
23 * @details Seal does more than just encrypt. It first generates the encryption key and
24 * Initialization Vector, then encrypts whole message using this key
25 * (and selected symmetric algorithm).
26 * Finally it encrypts symmetric key with public key.
33 #include <yaca_types.h>
40 * @addtogroup CAPI_YACA_ENCRYPTION_MODULE
45 * @brief Initializes an asymmetric encryption context and generates
46 * symmetric key and Initialization Vector.
48 * @remarks Generated symmetric key is encrypted with public key,
49 * so can be ONLY used with yaca_open_initialize(). It can be exported,
50 * but after import it can be ONLY used with yaca_open_initialize() as well.
52 * @remarks The @a ctx should be released using yaca_context_destroy()
54 * @remarks The @a pub_key must be #YACA_KEY_TYPE_RSA_PUB
56 * @remarks The @a sym_key_bit_len must be at least 96 bits shorter than the @a pub_key bit length
58 * @remarks The @a sym_key should be released using yaca_key_destroy()
60 * @remarks The @a iv should be released using yaca_key_destroy()
64 * @param[out] ctx Newly created context
65 * @param[in] pub_key Public key of the peer that will receive the encrypted data
66 * @param[in] algo Symmetric algorithm that will be used
67 * @param[in] bcm Block chaining mode for the symmetric algorithm
68 * @param[in] sym_key_bit_len Symmetric key length (in bits) that will be generated
69 * @param[out] sym_key Generated symmetric key that will be used,
70 * it is encrypted with peer's public key
71 * @param[out] iv Generated Initialization Vector that will be used
73 * @return #YACA_ERROR_NONE on success, negative on error
74 * @retval #YACA_ERROR_NONE Successful
75 * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL,
76 * invalid algo, bcm, sym_key_bit_len or pub_key)
77 * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
78 * @retval #YACA_ERROR_INTERNAL Internal error
80 * @see #yaca_encrypt_algorithm_e
81 * @see #yaca_block_cipher_mode_e
82 * @see #yaca_key_bit_length_e
83 * @see yaca_seal_update()
84 * @see yaca_seal_finalize()
85 * @see yaca_open_initialize()
86 * @see yaca_key_destroy()
87 * @see yaca_context_destroy()
89 int yaca_seal_initialize(yaca_context_h *ctx,
90 const yaca_key_h pub_key,
91 yaca_encrypt_algorithm_e algo,
92 yaca_block_cipher_mode_e bcm,
93 size_t sym_key_bit_len,
98 * @brief Encrypts piece of the data.
102 * @param[in,out] ctx Context created by yaca_seal_initialize()
103 * @param[in] plaintext Plaintext to be encrypted
104 * @param[in] plaintext_len Length of the plaintext
105 * @param[out] ciphertext Buffer for the encrypted data
106 * (must be allocated by client, see yaca_context_get_output_length())
107 * @param[out] ciphertext_len Length of the encrypted data,
108 * actual number of bytes written will be returned here
110 * @return #YACA_ERROR_NONE on success, negative on error
111 * @retval #YACA_ERROR_NONE Successful
112 * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0,
114 * @retval #YACA_ERROR_INTERNAL Internal error
116 * @see yaca_seal_initialize()
117 * @see yaca_seal_finalize()
118 * @see yaca_context_get_output_length()
120 int yaca_seal_update(yaca_context_h ctx,
121 const char *plaintext,
122 size_t plaintext_len,
124 size_t *ciphertext_len);
127 * @brief Encrypts the final piece of the data.
129 * @remarks Skipping yaca_seal_update() and calling only yaca_seal_finalize() will produce an
130 * encryption of an empty message.
134 * @param[in,out] ctx A valid seal context
135 * @param[out] ciphertext Final piece of the encrypted data
136 * (must be allocated by client, see yaca_context_get_output_length())
137 * @param[out] ciphertext_len Length of the final piece,
138 * actual number of bytes written will be returned here
140 * @return #YACA_ERROR_NONE on success, negative on error
141 * @retval #YACA_ERROR_NONE Successful
142 * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL,
144 * @retval #YACA_ERROR_INTERNAL Internal error
146 * @see yaca_seal_initialize()
147 * @see yaca_seal_update()
148 * @see yaca_context_get_output_length()
150 int yaca_seal_finalize(yaca_context_h ctx,
152 size_t *ciphertext_len);
155 * @brief Initializes an asymmetric decryption context.
159 * @remarks The @a ctx should be released using yaca_context_destroy()
161 * @remarks The @a prv_key must be #YACA_KEY_TYPE_RSA_PRIV
163 * @param[out] ctx Newly created context
164 * @param[in] prv_key Private key, part of the pair that was used for the encryption
165 * @param[in] algo Symmetric algorithm that was used for the encryption
166 * @param[in] bcm Block chaining mode for the symmetric algorithm
167 * @param[in] sym_key_bit_len Symmetric key length (in bits) that was used for the encryption
168 * @param[in] sym_key Symmetric key, encrypted with the public key,
169 * that was used to encrypt the data
170 * @param[in] iv Initialization Vector that was used for the encryption
172 * @return #YACA_ERROR_NONE on success, negative on error
173 * @retval #YACA_ERROR_NONE Successful
174 * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, invalid
175 * algo, bcm, sym_key_bit_len, prv_key, sym_key or iv)
176 * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
177 * @retval #YACA_ERROR_INTERNAL Internal error
179 * @see #yaca_encrypt_algorithm_e
180 * @see #yaca_block_cipher_mode_e
181 * @see #yaca_key_bit_length_e
182 * @see yaca_open_update()
183 * @see yaca_open_finalize()
184 * @see yaca_context_destroy()
186 int yaca_open_initialize(yaca_context_h *ctx,
187 const yaca_key_h prv_key,
188 yaca_encrypt_algorithm_e algo,
189 yaca_block_cipher_mode_e bcm,
190 size_t sym_key_bit_len,
191 const yaca_key_h sym_key,
192 const yaca_key_h iv);
195 * @brief Decrypts piece of the data.
199 * @param[in,out] ctx Context created by yaca_open_initialize()
200 * @param[in] ciphertext Ciphertext to be decrypted
201 * @param[in] ciphertext_len Length of the ciphertext
202 * @param[out] plaintext Buffer for the decrypted data
203 * (must be allocated by client, see yaca_context_get_output_length())
204 * @param[out] plaintext_len Length of the decrypted data,
205 * actual number of bytes written will be returned here
207 * @return #YACA_ERROR_NONE on success, negative on error
208 * @retval #YACA_ERROR_NONE Successful
209 * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0,
211 * @retval #YACA_ERROR_INTERNAL Internal error
213 * @see yaca_open_initialize()
214 * @see yaca_open_finalize()
215 * @see yaca_context_get_output_length()
217 int yaca_open_update(yaca_context_h ctx,
218 const char *ciphertext,
219 size_t ciphertext_len,
221 size_t *plaintext_len);
224 * @brief Decrypts last chunk of sealed message.
226 * @remarks Skipping yaca_open_update() and calling only yaca_open_finalize() will produce a
227 * decryption of an empty ciphertext.
231 * @param[in,out] ctx A valid open context
232 * @param[out] plaintext Final piece of the decrypted data
233 * (must be allocated by client, see yaca_context_get_output_length())
234 * @param[out] plaintext_len Length of the final piece,
235 * actual number of bytes written will be returned here
237 * @return #YACA_ERROR_NONE on success, negative on error
238 * @retval #YACA_ERROR_NONE Successful
239 * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL,
241 * @retval #YACA_ERROR_INTERNAL Internal error
243 * @see yaca_open_initialize()
244 * @see yaca_open_update()
245 * @see yaca_context_get_output_length()
247 int yaca_open_finalize(yaca_context_h ctx,
249 size_t *plaintext_len);
259 #endif /* YACA_SEAL_H */