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 integrity handling - HMAC, CMAC and digital signature.
28 #include <yaca_types.h>
35 * @addtogroup CAPI_YACA_INTEGRITY_MODULE
40 * @brief Initializes a signature context for asymmetric signatures.
44 * @remarks For verification use yaca_verify_initialize(), yaca_verify_update() and
45 * yaca_verify_finalize() functions with matching public key.
47 * @remarks For RSA operations the default padding used is #YACA_PADDING_PKCS1. It can be
48 * changed using yaca_context_set_property() with #YACA_PROPERTY_PADDING.
50 * @remarks The @a ctx should be released using yaca_context_destroy()
52 * @param[out] ctx Newly created context
53 * @param[in] algo Digest algorithm that will be used
54 * @param[in] prv_key Private key that will be used, algorithm is deduced based
55 * on key type, supported key types:
56 * - #YACA_KEY_TYPE_RSA_PRIV,
57 * - #YACA_KEY_TYPE_DSA_PRIV,
58 * - #YACA_KEY_TYPE_EC_PRIV
60 * @return #YACA_ERROR_NONE on success, negative on error
61 * @retval #YACA_ERROR_NONE Successful
62 * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL,
63 * invalid algo or key)
64 * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
65 * @retval #YACA_ERROR_INTERNAL Internal error
67 * @see #yaca_key_type_e
68 * @see #yaca_digest_algorithm_e
69 * @see #yaca_padding_e
70 * @see yaca_context_set_property()
71 * @see yaca_sign_update()
72 * @see yaca_sign_finalize()
73 * @see yaca_verify_initialize()
74 * @see yaca_verify_update()
75 * @see yaca_verify_finalize()
76 * @see yaca_context_destroy()
78 int yaca_sign_initialize(yaca_context_h *ctx,
79 yaca_digest_algorithm_e algo,
80 const yaca_key_h prv_key);
83 * @brief Initializes a signature context for HMAC.
87 * @remarks For verification, calculate message HMAC and compare with received MAC using
90 * @remarks The @a ctx should be released using yaca_context_destroy()
92 * @param[out] ctx Newly created context
93 * @param[in] algo Digest algorithm that will be used
94 * @param[in] sym_key Symmetric key that will be used, supported key types:
95 * - #YACA_KEY_TYPE_SYMMETRIC,
96 * - #YACA_KEY_TYPE_DES
98 * @return #YACA_ERROR_NONE on success, negative on error
99 * @retval #YACA_ERROR_NONE Successful
100 * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL,
101 * invalid algo or key)
102 * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
103 * @retval #YACA_ERROR_INTERNAL Internal error
105 * @see #yaca_key_type_e
106 * @see #yaca_digest_algorithm_e
107 * @see yaca_sign_update()
108 * @see yaca_sign_finalize()
110 * @see yaca_context_destroy()
112 int yaca_sign_initialize_hmac(yaca_context_h *ctx,
113 yaca_digest_algorithm_e algo,
114 const yaca_key_h sym_key);
117 * @brief Initializes a signature context for CMAC.
121 * @remarks For verification, calculate message CMAC and compare with received MAC using
124 * @remarks The @a ctx should be released using yaca_context_destroy()
126 * @param[out] ctx Newly created context
127 * @param[in] algo Encryption algorithm that will be used
128 * @param[in] sym_key Symmetric key that will be used, supported key types:
129 * - #YACA_KEY_TYPE_SYMMETRIC,
130 * - #YACA_KEY_TYPE_DES
132 * @return #YACA_ERROR_NONE on success, negative on error
133 * @retval #YACA_ERROR_NONE Successful
134 * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL,
135 * invalid algo or key)
136 * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
137 * @retval #YACA_ERROR_INTERNAL Internal error
139 * @see #yaca_key_type_e
140 * @see #yaca_encrypt_algorithm_e
141 * @see yaca_sign_update()
142 * @see yaca_sign_finalize()
144 * @see yaca_context_destroy()
146 int yaca_sign_initialize_cmac(yaca_context_h *ctx,
147 yaca_encrypt_algorithm_e algo,
148 const yaca_key_h sym_key);
151 * @brief Feeds the message into the digital signature or MAC algorithm.
155 * @param[in,out] ctx Context created by yaca_sign_initialize(),
156 * yaca_sign_initialize_hmac() or yaca_sign_initialize_cmac()
157 * @param[in] message Message to be signed
158 * @param[in] message_len Length of the message
160 * @return #YACA_ERROR_NONE on success, negative on error
161 * @retval #YACA_ERROR_NONE Successful
162 * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0,
164 * @retval #YACA_ERROR_INTERNAL Internal error
166 * @see yaca_sign_initialize()
167 * @see yaca_sign_finalize()
168 * @see yaca_sign_initialize_hmac()
169 * @see yaca_sign_initialize_cmac()
171 int yaca_sign_update(yaca_context_h ctx,
176 * @brief Calculates the final signature or MAC.
180 * @remarks Skipping yaca_sign_update() and calling only yaca_sign_finalize() will produce a
181 * signature or MAC of an empty message.
183 * @param[in,out] ctx A valid sign context
184 * @param[out] signature Buffer for the MAC or the message signature
185 * (must be allocated by client, see yaca_context_get_output_length())
186 * @param[out] signature_len Length of the MAC or the signature,
187 * actual number of bytes written will be returned here
189 * @return #YACA_ERROR_NONE on success, negative on error
190 * @retval #YACA_ERROR_NONE Successful
191 * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL,
193 * @retval #YACA_ERROR_INTERNAL Internal error
195 * @see yaca_sign_initialize()
196 * @see yaca_sign_update()
197 * @see yaca_sign_initialize_hmac()
198 * @see yaca_sign_initialize_cmac()
199 * @see yaca_context_get_output_length()
201 int yaca_sign_finalize(yaca_context_h ctx,
203 size_t *signature_len);
206 * @brief Initializes a signature verification context for asymmetric signatures
210 * @remarks For RSA operations the default padding used is #YACA_PADDING_PKCS1. It can be
211 * changed using yaca_context_set_property() with #YACA_PROPERTY_PADDING.
212 * For verify to succeed it has to be set to the same value it was signed with.
214 * @remarks The @a ctx should be released using yaca_context_destroy()
216 * @param[out] ctx Newly created context
217 * @param[in] algo Digest algorithm that will be used
218 * @param[in] pub_key Public key that will be used, algorithm is deduced based on
219 * key type, supported key types:
220 * - #YACA_KEY_TYPE_RSA_PUB,
221 * - #YACA_KEY_TYPE_DSA_PUB,
222 * - #YACA_KEY_TYPE_EC_PUB
224 * @return #YACA_ERROR_NONE on success, negative on error
225 * @retval #YACA_ERROR_NONE Successful
226 * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL,
227 * invalid algo or key)
228 * @retval #YACA_ERROR_OUT_OF_MEMORY Out of memory error
229 * @retval #YACA_ERROR_INTERNAL Internal error
231 * @see #yaca_key_type_e
232 * @see #yaca_digest_algorithm_e
233 * @see #yaca_padding_e
234 * @see yaca_context_set_property()
235 * @see yaca_verify_update()
236 * @see yaca_verify_finalize()
237 * @see yaca_context_destroy()
239 int yaca_verify_initialize(yaca_context_h *ctx,
240 yaca_digest_algorithm_e algo,
241 const yaca_key_h pub_key);
244 * @brief Feeds the message into the digital signature verification algorithm.
248 * @param[in,out] ctx Context created by yaca_verify_initialize()
249 * @param[in] message Message
250 * @param[in] message_len Length of the message
252 * @return #YACA_ERROR_NONE on success, negative on error
253 * @retval #YACA_ERROR_NONE Successful
254 * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL, 0,
256 * @retval #YACA_ERROR_INTERNAL Internal error
258 * @see yaca_verify_initialize()
259 * @see yaca_verify_finalize()
261 int yaca_verify_update(yaca_context_h ctx,
266 * @brief Performs the verification.
270 * @remarks Skipping yaca_verify_update() and calling only yaca_verify_finalize() will verify
271 * the signature of an empty message.
273 * @param[in,out] ctx A valid verify context
274 * @param[in] signature Message signature to be verified
275 * @param[in] signature_len Length of the signature
277 * @return #YACA_ERROR_NONE on success, negative on error
278 * @retval #YACA_ERROR_NONE Successful
279 * @retval #YACA_ERROR_INVALID_PARAMETER Required parameters have incorrect values (NULL,
281 * @retval #YACA_ERROR_INTERNAL Internal error
282 * @retval #YACA_ERROR_DATA_MISMATCH The verification failed
284 * @see yaca_verify_initialize()
285 * @see yaca_verify_update()
286 * @see yaca_sign_finalize()
288 int yaca_verify_finalize(yaca_context_h ctx,
289 const char *signature,
290 size_t signature_len);
300 #endif /* YACA_SIGN_H */