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
28 #include <yaca_types.h>
35 * @defgroup Advanced-Encryption-Asymmetric Advanced API for the asymmetric encryption.
38 * @remarks Seal does more than just encrypt. It first generates the encryption key and IV,
39 * then encrypts whole message using this key (and selected symmetric algorithm).
40 * Finally it encrypts symmetric key with public key.
46 * @brief Initializes an asymmetric encryption context and generates symmetric key and IV.
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.
54 * @param[out] ctx Newly created context (must be freed with yaca_context_destroy())
55 * @param[in] pub_key Public key of the peer that will receive the encrypted data
56 * @param[in] algo Symmetric algorithm that will be used
57 * @param[in] bcm Block chaining mode for the symmetric algorithm
58 * @param[in] sym_key_bit_len Symmetric key length (in bits) that will be generated
59 * @param[out] sym_key Generated symmetric key that will be used,
60 * it is encrypted with peer's public key
61 * (must be freed with yaca_key_destroy())
62 * @param[out] iv Generated initialization vector that will be used
63 * (must be freed with yaca_key_destroy())
65 * @return #YACA_ERROR_NONE on success, negative on error
66 * @retval #YACA_ERROR_NONE Successful
67 * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL,
68 * invalid algo, bcm, sym_key_bit_len or pub_key)
69 * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
70 * @retval #YACA_ERROR_INTERNAL Internal error
72 * @see #yaca_encrypt_algorithm_e
73 * @see #yaca_block_cipher_mode_e
74 * @see #yaca_key_bit_length_e
75 * @see yaca_seal_update()
76 * @see yaca_seal_finalize()
77 * @see yaca_open_initialize()
78 * @see yaca_key_destroy()
79 * @see yaca_context_destroy()
81 int yaca_seal_initialize(yaca_context_h *ctx,
82 const yaca_key_h pub_key,
83 yaca_encrypt_algorithm_e algo,
84 yaca_block_cipher_mode_e bcm,
85 size_t sym_key_bit_len,
90 * @brief Encrypts piece of the data.
94 * @param[in,out] ctx Context created by yaca_seal_initialize()
95 * @param[in] plaintext Plaintext to be encrypted
96 * @param[in] plaintext_len Length of the plaintext
97 * @param[out] ciphertext Buffer for the encrypted data
98 * (must be allocated by client, see yaca_context_get_output_length())
99 * @param[out] ciphertext_len Length of the encrypted data,
100 * actual number of bytes written will be returned here
102 * @return #YACA_ERROR_NONE on success, negative on error
103 * @retval #YACA_ERROR_NONE Successful
104 * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0,
106 * @retval #YACA_ERROR_INTERNAL Internal error
108 * @see yaca_seal_initialize()
109 * @see yaca_seal_finalize()
110 * @see yaca_context_get_output_length()
112 int yaca_seal_update(yaca_context_h ctx,
113 const char *plaintext,
114 size_t plaintext_len,
116 size_t *ciphertext_len);
119 * @brief Encrypts the final piece of the data.
123 * @param[in,out] ctx A valid seal context
124 * @param[out] ciphertext Final piece of the encrypted data
125 * (must be allocated by client, see yaca_context_get_output_length())
126 * @param[out] ciphertext_len Length of the final piece,
127 * actual number of bytes written will be returned here
129 * @return #YACA_ERROR_NONE on success, negative on error
130 * @retval #YACA_ERROR_NONE Successful
131 * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL,
133 * @retval #YACA_ERROR_INTERNAL Internal error
135 * @see yaca_seal_initialize()
136 * @see yaca_seal_update()
137 * @see yaca_context_get_output_length()
139 int yaca_seal_finalize(yaca_context_h ctx,
141 size_t *ciphertext_len);
144 * @brief Initializes an asymmetric decryption context.
148 * @param[out] ctx Newly created context (must be freed by yaca_context_destroy())
149 * @param[in] prv_key Private key, part of the pair that was used for the encryption
150 * @param[in] algo Symmetric algorithm that was used for the encryption
151 * @param[in] bcm Block chaining mode for the symmetric algorithm
152 * @param[in] sym_key_bit_len Symmetric key length (in bits) that was used for the encryption
153 * @param[in] sym_key Symmetric key, encrypted with the public key,
154 * that was used to encrypt the data
155 * @param[in] iv Initialization vector that was used for the encryption
157 * @return #YACA_ERROR_NONE on success, negative on error
158 * @retval #YACA_ERROR_NONE Successful
159 * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, invalid
160 * algo, bcm, sym_key_bit_len, prv_key, sym_key or iv)
161 * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
162 * @retval #YACA_ERROR_INTERNAL Internal error
164 * @see #yaca_encrypt_algorithm_e
165 * @see #yaca_block_cipher_mode_e
166 * @see #yaca_key_bit_length_e
167 * @see yaca_open_update()
168 * @see yaca_open_finalize()
169 * @see yaca_context_destroy()
171 int yaca_open_initialize(yaca_context_h *ctx,
172 const yaca_key_h prv_key,
173 yaca_encrypt_algorithm_e algo,
174 yaca_block_cipher_mode_e bcm,
175 size_t sym_key_bit_len,
176 const yaca_key_h sym_key,
177 const yaca_key_h iv);
180 * @brief Decrypts piece of the data.
184 * @param[in,out] ctx Context created by yaca_open_initialize()
185 * @param[in] ciphertext Ciphertext to be decrypted
186 * @param[in] ciphertext_len Length of the ciphertext
187 * @param[out] plaintext Buffer for the decrypted data
188 * (must be allocated by client, see yaca_context_get_output_length())
189 * @param[out] plaintext_len Length of the decrypted data,
190 * actual number of bytes written will be returned here
192 * @return #YACA_ERROR_NONE on success, negative on error
193 * @retval #YACA_ERROR_NONE Successful
194 * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0,
196 * @retval #YACA_ERROR_INTERNAL Internal error
198 * @see yaca_open_initialize()
199 * @see yaca_open_finalize()
200 * @see yaca_context_get_output_length()
202 int yaca_open_update(yaca_context_h ctx,
203 const char *ciphertext,
204 size_t ciphertext_len,
206 size_t *plaintext_len);
209 * @brief Decrypts last chunk of sealed message.
213 * @param[in,out] ctx A valid open context
214 * @param[out] plaintext Final piece of the decrypted data
215 * (must be allocated by client, see yaca_context_get_output_length())
216 * @param[out] plaintext_len Length of the final piece,
217 * actual number of bytes written will be returned here
219 * @return #YACA_ERROR_NONE on success, negative on error
220 * @retval #YACA_ERROR_NONE Successful
221 * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL,
223 * @retval #YACA_ERROR_INTERNAL Internal error
225 * @see yaca_open_initialize()
226 * @see yaca_open_update()
227 * @see yaca_context_get_output_length()
229 int yaca_open_finalize(yaca_context_h ctx,
231 size_t *plaintext_len);
239 #endif /* YACA_SEAL_H */