blob: 1fb1515cf4f2a7e618ccee684450a2214b1e2ca7 [file] [log] [blame]
Gilles Peskinee59236f2018-01-27 23:32:46 +01001/**
2 * \file psa/crypto.h
3 * \brief Platform Security Architecture cryptography module
4 */
Jaeden Amerocab54942018-07-25 13:26:13 +01005/*
6 * Copyright (C) 2018, ARM Limited, All Rights Reserved
7 * SPDX-License-Identifier: Apache-2.0
8 *
9 * Licensed under the Apache License, Version 2.0 (the "License"); you may
10 * not use this file except in compliance with the License.
11 * You may obtain a copy of the License at
12 *
13 * http://www.apache.org/licenses/LICENSE-2.0
14 *
15 * Unless required by applicable law or agreed to in writing, software
16 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
17 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
18 * See the License for the specific language governing permissions and
19 * limitations under the License.
20 */
Gilles Peskinee59236f2018-01-27 23:32:46 +010021
22#ifndef PSA_CRYPTO_H
23#define PSA_CRYPTO_H
24
25#include "crypto_platform.h"
26
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +010027#include <stddef.h>
28
Gilles Peskine62a7e7e2018-02-07 21:54:47 +010029#ifdef __DOXYGEN_ONLY__
Gilles Peskinef5b9fa12018-03-07 16:40:18 +010030/* This __DOXYGEN_ONLY__ block contains mock definitions for things that
31 * must be defined in the crypto_platform.h header. These mock definitions
32 * are present in this file as a convenience to generate pretty-printed
33 * documentation that includes those definitions. */
34
Gilles Peskine62a7e7e2018-02-07 21:54:47 +010035/** \defgroup platform Implementation-specific definitions
36 * @{
37 */
38
Gilles Peskineae32aac2018-11-30 14:39:32 +010039/** \brief Key handle.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +010040 *
Gilles Peskineae32aac2018-11-30 14:39:32 +010041 * This type represents open handles to keys. It must be an unsigned integral
Gilles Peskine308b91d2018-02-08 09:47:44 +010042 * type. The choice of type is implementation-dependent.
Gilles Peskineae32aac2018-11-30 14:39:32 +010043 *
Gilles Peskine23fd2bd2018-12-11 15:51:32 +010044 * 0 is not a valid key handle. How other handle values are assigned is
45 * implementation-dependent.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +010046 */
Gilles Peskineae32aac2018-11-30 14:39:32 +010047typedef _unsigned_integral_type_ psa_key_handle_t;
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +010048
Gilles Peskine62a7e7e2018-02-07 21:54:47 +010049/**@}*/
Gilles Peskinef5b9fa12018-03-07 16:40:18 +010050#endif /* __DOXYGEN_ONLY__ */
Gilles Peskine62a7e7e2018-02-07 21:54:47 +010051
Gilles Peskinee59236f2018-01-27 23:32:46 +010052#ifdef __cplusplus
53extern "C" {
54#endif
55
Gilles Peskinef3b731e2018-12-12 13:38:31 +010056/* The file "crypto_types.h" declares types that encode errors,
57 * algorithms, key types, policies, etc. */
58#include "crypto_types.h"
59
60/* The file "crypto_values.h" declares macros to build and analyze values
61 * of integral types defined in "crypto_types.h". */
62#include "crypto_values.h"
63
64/** \defgroup initialization Library initialization
Gilles Peskinee59236f2018-01-27 23:32:46 +010065 * @{
66 */
67
68/**
Gilles Peskinee59236f2018-01-27 23:32:46 +010069 * \brief Library initialization.
70 *
71 * Applications must call this function before calling any other
72 * function in this module.
73 *
74 * Applications may call this function more than once. Once a call
75 * succeeds, subsequent calls are guaranteed to succeed.
76 *
itayzafrir18617092018-09-16 12:22:41 +030077 * If the application calls other functions before calling psa_crypto_init(),
78 * the behavior is undefined. Implementations are encouraged to either perform
79 * the operation as if the library had been initialized or to return
80 * #PSA_ERROR_BAD_STATE or some other applicable error. In particular,
81 * implementations should not return a success status if the lack of
82 * initialization may have security implications, for example due to improper
83 * seeding of the random number generator.
84 *
Gilles Peskine28538492018-07-11 17:34:00 +020085 * \retval #PSA_SUCCESS
86 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
87 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
88 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +020089 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine28538492018-07-11 17:34:00 +020090 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
Gilles Peskinee59236f2018-01-27 23:32:46 +010091 */
92psa_status_t psa_crypto_init(void);
93
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +010094/**@}*/
95
Gilles Peskine105f67f2019-07-23 18:16:05 +020096/** \addtogroup attributes
Gilles Peskine87a5e562019-04-17 12:28:25 +020097 * @{
98 */
99
Gilles Peskinea0c06552019-05-21 15:54:54 +0200100/** \def PSA_KEY_ATTRIBUTES_INIT
101 *
102 * This macro returns a suitable initializer for a key attribute structure
103 * of type #psa_key_attributes_t.
104 */
105#ifdef __DOXYGEN_ONLY__
106/* This is an example definition for documentation purposes.
107 * Implementations should define a suitable value in `crypto_struct.h`.
108 */
109#define PSA_KEY_ATTRIBUTES_INIT {0}
110#endif
111
112/** Return an initial value for a key attributes structure.
113 */
114static psa_key_attributes_t psa_key_attributes_init(void);
115
Gilles Peskinedc8219a2019-05-15 16:11:15 +0200116/** Declare a key as persistent and set its key identifier.
Gilles Peskine20628592019-04-19 19:29:50 +0200117 *
Gilles Peskinef1b76942019-05-16 16:10:59 +0200118 * If the attribute structure currently declares the key as volatile (which
119 * is the default content of an attribute structure), this function sets
Gilles Peskinedc8219a2019-05-15 16:11:15 +0200120 * the lifetime attribute to #PSA_KEY_LIFETIME_PERSISTENT.
Gilles Peskine20628592019-04-19 19:29:50 +0200121 *
Gilles Peskinef1b76942019-05-16 16:10:59 +0200122 * This function does not access storage, it merely stores the given
123 * value in the structure.
124 * The persistent key will be written to storage when the attribute
125 * structure is passed to a key creation function such as
Gilles Peskine35ef36b2019-05-16 19:42:05 +0200126 * psa_import_key(), psa_generate_key(),
Gilles Peskinea99d3fb2019-05-16 15:28:51 +0200127 * psa_key_derivation_output_key() or psa_copy_key().
Gilles Peskine20628592019-04-19 19:29:50 +0200128 *
Gilles Peskine20628592019-04-19 19:29:50 +0200129 * This function may be declared as `static` (i.e. without external
130 * linkage). This function may be provided as a function-like macro,
131 * but in this case it must evaluate each of its arguments exactly once.
132 *
133 * \param[out] attributes The attribute structure to write to.
134 * \param id The persistent identifier for the key.
Gilles Peskinedc8219a2019-05-15 16:11:15 +0200135 */
136static void psa_set_key_id(psa_key_attributes_t *attributes,
137 psa_key_id_t id);
138
139/** Set the location of a persistent key.
140 *
141 * To make a key persistent, you must give it a persistent key identifier
Gilles Peskinef1b76942019-05-16 16:10:59 +0200142 * with psa_set_key_id(). By default, a key that has a persistent identifier
143 * is stored in the default storage area identifier by
144 * #PSA_KEY_LIFETIME_PERSISTENT. Call this function to choose a storage
145 * area, or to explicitly declare the key as volatile.
Gilles Peskinedc8219a2019-05-15 16:11:15 +0200146 *
Gilles Peskinef1b76942019-05-16 16:10:59 +0200147 * This function does not access storage, it merely stores the given
148 * value in the structure.
149 * The persistent key will be written to storage when the attribute
150 * structure is passed to a key creation function such as
Gilles Peskine35ef36b2019-05-16 19:42:05 +0200151 * psa_import_key(), psa_generate_key(),
Gilles Peskinea99d3fb2019-05-16 15:28:51 +0200152 * psa_key_derivation_output_key() or psa_copy_key().
Gilles Peskinedc8219a2019-05-15 16:11:15 +0200153 *
154 * This function may be declared as `static` (i.e. without external
155 * linkage). This function may be provided as a function-like macro,
156 * but in this case it must evaluate each of its arguments exactly once.
157 *
158 * \param[out] attributes The attribute structure to write to.
Gilles Peskine20628592019-04-19 19:29:50 +0200159 * \param lifetime The lifetime for the key.
160 * If this is #PSA_KEY_LIFETIME_VOLATILE, the
Gilles Peskinedc8219a2019-05-15 16:11:15 +0200161 * key will be volatile, and the key identifier
162 * attribute is reset to 0.
Gilles Peskine20628592019-04-19 19:29:50 +0200163 */
Gilles Peskinedc8219a2019-05-15 16:11:15 +0200164static void psa_set_key_lifetime(psa_key_attributes_t *attributes,
165 psa_key_lifetime_t lifetime);
Gilles Peskine4747d192019-04-17 15:05:45 +0200166
Gilles Peskine20628592019-04-19 19:29:50 +0200167/** Retrieve the key identifier from key attributes.
168 *
169 * This function may be declared as `static` (i.e. without external
170 * linkage). This function may be provided as a function-like macro,
171 * but in this case it must evaluate its argument exactly once.
172 *
173 * \param[in] attributes The key attribute structure to query.
174 *
175 * \return The persistent identifier stored in the attribute structure.
176 * This value is unspecified if the attribute structure declares
177 * the key as volatile.
178 */
Gilles Peskine4747d192019-04-17 15:05:45 +0200179static psa_key_id_t psa_get_key_id(const psa_key_attributes_t *attributes);
180
Gilles Peskine20628592019-04-19 19:29:50 +0200181/** Retrieve the lifetime from key attributes.
182 *
183 * This function may be declared as `static` (i.e. without external
184 * linkage). This function may be provided as a function-like macro,
185 * but in this case it must evaluate its argument exactly once.
186 *
187 * \param[in] attributes The key attribute structure to query.
188 *
189 * \return The lifetime value stored in the attribute structure.
190 */
Gilles Peskine4747d192019-04-17 15:05:45 +0200191static psa_key_lifetime_t psa_get_key_lifetime(
192 const psa_key_attributes_t *attributes);
193
Gilles Peskine20628592019-04-19 19:29:50 +0200194/** Declare usage flags for a key.
195 *
196 * Usage flags are part of a key's usage policy. They encode what
197 * kind of operations are permitted on the key. For more details,
198 * refer to the documentation of the type #psa_key_usage_t.
199 *
200 * This function overwrites any usage flags
201 * previously set in \p attributes.
202 *
203 * This function may be declared as `static` (i.e. without external
204 * linkage). This function may be provided as a function-like macro,
205 * but in this case it must evaluate each of its arguments exactly once.
206 *
207 * \param[out] attributes The attribute structure to write to.
208 * \param usage_flags The usage flags to write.
209 */
Gilles Peskine4747d192019-04-17 15:05:45 +0200210static void psa_set_key_usage_flags(psa_key_attributes_t *attributes,
211 psa_key_usage_t usage_flags);
212
Gilles Peskine20628592019-04-19 19:29:50 +0200213/** Retrieve the usage flags from key attributes.
214 *
215 * This function may be declared as `static` (i.e. without external
216 * linkage). This function may be provided as a function-like macro,
217 * but in this case it must evaluate its argument exactly once.
218 *
219 * \param[in] attributes The key attribute structure to query.
220 *
221 * \return The usage flags stored in the attribute structure.
222 */
Gilles Peskine4747d192019-04-17 15:05:45 +0200223static psa_key_usage_t psa_get_key_usage_flags(
224 const psa_key_attributes_t *attributes);
225
Gilles Peskine20628592019-04-19 19:29:50 +0200226/** Declare the permitted algorithm policy for a key.
227 *
228 * The permitted algorithm policy of a key encodes which algorithm or
229 * algorithms are permitted to be used with this key.
230 *
231 * This function overwrites any algorithm policy
232 * previously set in \p attributes.
233 *
234 * This function may be declared as `static` (i.e. without external
235 * linkage). This function may be provided as a function-like macro,
236 * but in this case it must evaluate each of its arguments exactly once.
237 *
238 * \param[out] attributes The attribute structure to write to.
239 * \param alg The permitted algorithm policy to write.
240 */
Gilles Peskine4747d192019-04-17 15:05:45 +0200241static void psa_set_key_algorithm(psa_key_attributes_t *attributes,
242 psa_algorithm_t alg);
243
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +0100244
Gilles Peskine20628592019-04-19 19:29:50 +0200245/** Retrieve the algorithm policy from key attributes.
246 *
247 * This function may be declared as `static` (i.e. without external
248 * linkage). This function may be provided as a function-like macro,
249 * but in this case it must evaluate its argument exactly once.
250 *
251 * \param[in] attributes The key attribute structure to query.
252 *
253 * \return The algorithm stored in the attribute structure.
254 */
Gilles Peskine4747d192019-04-17 15:05:45 +0200255static psa_algorithm_t psa_get_key_algorithm(
256 const psa_key_attributes_t *attributes);
257
Gilles Peskine20628592019-04-19 19:29:50 +0200258/** Declare the type of a key.
259 *
Gilles Peskine24f10f82019-05-16 12:18:32 +0200260 * This function overwrites any key type
Gilles Peskine20628592019-04-19 19:29:50 +0200261 * previously set in \p attributes.
262 *
263 * This function may be declared as `static` (i.e. without external
264 * linkage). This function may be provided as a function-like macro,
265 * but in this case it must evaluate each of its arguments exactly once.
266 *
267 * \param[out] attributes The attribute structure to write to.
268 * \param type The key type to write.
269 */
Gilles Peskine4747d192019-04-17 15:05:45 +0200270static void psa_set_key_type(psa_key_attributes_t *attributes,
271 psa_key_type_t type);
272
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +0100273
Gilles Peskine3a4f1f82019-04-26 13:49:28 +0200274/** Declare the size of a key.
275 *
276 * This function overwrites any key size previously set in \p attributes.
277 *
278 * This function may be declared as `static` (i.e. without external
279 * linkage). This function may be provided as a function-like macro,
280 * but in this case it must evaluate each of its arguments exactly once.
281 *
282 * \param[out] attributes The attribute structure to write to.
283 * \param bits The key size in bits.
284 */
285static void psa_set_key_bits(psa_key_attributes_t *attributes,
286 size_t bits);
287
Gilles Peskine20628592019-04-19 19:29:50 +0200288/** Retrieve the key type from key attributes.
289 *
290 * This function may be declared as `static` (i.e. without external
291 * linkage). This function may be provided as a function-like macro,
292 * but in this case it must evaluate its argument exactly once.
293 *
294 * \param[in] attributes The key attribute structure to query.
295 *
296 * \return The key type stored in the attribute structure.
297 */
Gilles Peskine4747d192019-04-17 15:05:45 +0200298static psa_key_type_t psa_get_key_type(const psa_key_attributes_t *attributes);
299
Gilles Peskine20628592019-04-19 19:29:50 +0200300/** Retrieve the key size from key attributes.
301 *
302 * This function may be declared as `static` (i.e. without external
303 * linkage). This function may be provided as a function-like macro,
304 * but in this case it must evaluate its argument exactly once.
305 *
306 * \param[in] attributes The key attribute structure to query.
307 *
308 * \return The key size stored in the attribute structure, in bits.
309 */
Gilles Peskine4747d192019-04-17 15:05:45 +0200310static size_t psa_get_key_bits(const psa_key_attributes_t *attributes);
311
Gilles Peskine20628592019-04-19 19:29:50 +0200312/** Retrieve the attributes of a key.
313 *
314 * This function first resets the attribute structure as with
Gilles Peskine9c640f92019-04-28 11:36:21 +0200315 * psa_reset_key_attributes(). It then copies the attributes of
316 * the given key into the given attribute structure.
Gilles Peskine20628592019-04-19 19:29:50 +0200317 *
Gilles Peskine9c640f92019-04-28 11:36:21 +0200318 * \note This function may allocate memory or other resources.
319 * Once you have called this function on an attribute structure,
320 * you must call psa_reset_key_attributes() to free these resources.
Gilles Peskine20628592019-04-19 19:29:50 +0200321 *
Gilles Peskine20628592019-04-19 19:29:50 +0200322 * \param[in] handle Handle to the key to query.
323 * \param[in,out] attributes On success, the attributes of the key.
324 * On failure, equivalent to a
325 * freshly-initialized structure.
326 *
327 * \retval #PSA_SUCCESS
328 * \retval #PSA_ERROR_INVALID_HANDLE
329 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
330 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
Adrian L. Shaw29b64072019-08-06 16:02:12 +0100331 * \retval #PSA_ERROR_CORRUPTION_DETECTED
332 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +0100333 * \retval #PSA_ERROR_BAD_STATE
334 * The library has not been previously initialized by psa_crypto_init().
335 * It is implementation-dependent whether a failure to initialize
336 * results in this error code.
Gilles Peskine20628592019-04-19 19:29:50 +0200337 */
Gilles Peskine4747d192019-04-17 15:05:45 +0200338psa_status_t psa_get_key_attributes(psa_key_handle_t handle,
339 psa_key_attributes_t *attributes);
340
Gilles Peskine20628592019-04-19 19:29:50 +0200341/** Reset a key attribute structure to a freshly initialized state.
342 *
343 * You must initialize the attribute structure as described in the
344 * documentation of the type #psa_key_attributes_t before calling this
345 * function. Once the structure has been initialized, you may call this
346 * function at any time.
347 *
348 * This function frees any auxiliary resources that the structure
349 * may contain.
350 *
351 * \param[in,out] attributes The attribute structure to reset.
352 */
Gilles Peskine8c8f2ab2019-04-18 21:44:46 +0200353void psa_reset_key_attributes(psa_key_attributes_t *attributes);
Gilles Peskine4747d192019-04-17 15:05:45 +0200354
Gilles Peskine87a5e562019-04-17 12:28:25 +0200355/**@}*/
356
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100357/** \defgroup key_management Key management
358 * @{
359 */
360
Gilles Peskinef535eb22018-11-30 14:08:36 +0100361/** Open a handle to an existing persistent key.
362 *
Gilles Peskine4754cde2019-05-21 15:56:29 +0200363 * Open a handle to a persistent key. A key is persistent if it was created
364 * with a lifetime other than #PSA_KEY_LIFETIME_VOLATILE. A persistent key
365 * always has a nonzero key identifier, set with psa_set_key_id() when
366 * creating the key. Implementations may provide additional pre-provisioned
Andrew Thoelke203491c2019-08-21 17:55:30 +0100367 * keys that can be opened with psa_open_key(). Such keys have a key identifier
368 * in the vendor range, as documented in the description of #psa_key_id_t.
Gilles Peskine4754cde2019-05-21 15:56:29 +0200369 *
370 * The application must eventually close the handle with psa_close_key()
371 * to release associated resources. If the application dies without calling
372 * psa_close_key(), the implementation should perform the equivalent of a
373 * call to psa_close_key().
Gilles Peskinef535eb22018-11-30 14:08:36 +0100374 *
Andrew Thoelke9741b112019-08-21 18:20:41 +0100375 * Some implementations permit an application to open the same key multiple
376 * times. Applications that rely on this behavior will not be portable to
377 * implementations that only permit a single key handle to be opened. See
378 * also :ref:\`key-handles\`.
379 *
Gilles Peskinef535eb22018-11-30 14:08:36 +0100380 * \param id The persistent identifier of the key.
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +0100381 * \param[out] handle On success, a handle to the key.
Gilles Peskinef535eb22018-11-30 14:08:36 +0100382 *
383 * \retval #PSA_SUCCESS
384 * Success. The application can now use the value of `*handle`
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +0100385 * to access the key.
Gilles Peskinef535eb22018-11-30 14:08:36 +0100386 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
Andrew Thoelke9741b112019-08-21 18:20:41 +0100387 * The implementation does not have sufficient resources to open the
388 * key. This can be due to reaching an implementation limit on the
389 * number of open keys, the number of open key handles, or available
390 * memory.
David Saadab4ecc272019-02-14 13:48:10 +0200391 * \retval #PSA_ERROR_DOES_NOT_EXIST
Andrew Thoelke9741b112019-08-21 18:20:41 +0100392 * There is no persistent key with key identifier \p id.
Gilles Peskinef535eb22018-11-30 14:08:36 +0100393 * \retval #PSA_ERROR_INVALID_ARGUMENT
Andrew Thoelke9741b112019-08-21 18:20:41 +0100394 * \p id is not a valid persistent key identifier.
Gilles Peskinef535eb22018-11-30 14:08:36 +0100395 * \retval #PSA_ERROR_NOT_PERMITTED
396 * The specified key exists, but the application does not have the
397 * permission to access it. Note that this specification does not
398 * define any way to create such a key, but it may be possible
399 * through implementation-specific means.
Gilles Peskine225010f2019-05-06 18:44:55 +0200400 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
401 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +0100402 * \retval #PSA_ERROR_BAD_STATE
403 * The library has not been previously initialized by psa_crypto_init().
404 * It is implementation-dependent whether a failure to initialize
405 * results in this error code.
Gilles Peskinef535eb22018-11-30 14:08:36 +0100406 */
Gilles Peskine225010f2019-05-06 18:44:55 +0200407psa_status_t psa_open_key(psa_key_id_t id,
Gilles Peskinef535eb22018-11-30 14:08:36 +0100408 psa_key_handle_t *handle);
409
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +0100410
Gilles Peskinef535eb22018-11-30 14:08:36 +0100411/** Close a key handle.
412 *
Andrew Thoelke3daba812019-08-21 22:46:56 +0100413 * If the handle designates a volatile key, this will destroy the key material
414 * and free all associated resources, just like psa_destroy_key().
Gilles Peskinef535eb22018-11-30 14:08:36 +0100415 *
Andrew Thoelke3daba812019-08-21 22:46:56 +0100416 * If this is the last open handle to a persistent key, then closing the handle
417 * will free all resources associated with the key in volatile memory. The key
418 * data in persistent storage is not affected and can be opened again later
419 * with a call to psa_open_key().
Gilles Peskinef535eb22018-11-30 14:08:36 +0100420 *
Andrew Thoelke3daba812019-08-21 22:46:56 +0100421 * Closing the key handle makes the handle invalid, and the key handle
Andrew Thoelke8824dae2019-08-22 15:04:48 +0100422 * must not be used again by the application.
Andrew Thoelke3daba812019-08-21 22:46:56 +0100423 *
424 * If the key is currently in use in a multipart operation, then closing the
Andrew Thoelke8824dae2019-08-22 15:04:48 +0100425 * last remaining handle to the key will abort the multipart operation.
Gilles Peskine5f25dd02019-01-14 18:24:53 +0100426 *
Gilles Peskinef535eb22018-11-30 14:08:36 +0100427 * \param handle The key handle to close.
428 *
429 * \retval #PSA_SUCCESS
430 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskineae32aac2018-11-30 14:39:32 +0100431 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +0100432 * \retval #PSA_ERROR_BAD_STATE
433 * The library has not been previously initialized by psa_crypto_init().
434 * It is implementation-dependent whether a failure to initialize
435 * results in this error code.
Gilles Peskinef535eb22018-11-30 14:08:36 +0100436 */
437psa_status_t psa_close_key(psa_key_handle_t handle);
438
Gilles Peskine3cac8c42018-11-30 14:07:45 +0100439/**@}*/
440
441/** \defgroup import_export Key import and export
442 * @{
443 */
444
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100445/**
446 * \brief Import a key in binary format.
447 *
Gilles Peskinef5b9fa12018-03-07 16:40:18 +0100448 * This function supports any output from psa_export_key(). Refer to the
Gilles Peskinef7933932018-10-31 14:07:52 +0100449 * documentation of psa_export_public_key() for the format of public keys
450 * and to the documentation of psa_export_key() for the format for
451 * other key types.
452 *
453 * This specification supports a single format for each key type.
454 * Implementations may support other formats as long as the standard
455 * format is supported. Implementations that support other formats
456 * should ensure that the formats are clearly unambiguous so as to
457 * minimize the risk that an invalid input is accidentally interpreted
458 * according to a different format.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100459 *
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +0100460
Gilles Peskine20628592019-04-19 19:29:50 +0200461 * \param[in] attributes The attributes for the new key.
Gilles Peskine4ce2a9d2019-05-03 16:57:15 +0200462 * The key size is always determined from the
463 * \p data buffer.
464 * If the key size in \p attributes is nonzero,
465 * it must be equal to the size from \p data.
Gilles Peskine20628592019-04-19 19:29:50 +0200466 * \param[out] handle On success, a handle to the newly created key.
467 * \c 0 on failure.
Gilles Peskinef7933932018-10-31 14:07:52 +0100468 * \param[in] data Buffer containing the key data. The content of this
Gilles Peskine24f10f82019-05-16 12:18:32 +0200469 * buffer is interpreted according to the type declared
470 * in \p attributes.
Gilles Peskine20628592019-04-19 19:29:50 +0200471 * All implementations must support at least the format
472 * described in the documentation
Gilles Peskinef7933932018-10-31 14:07:52 +0100473 * of psa_export_key() or psa_export_public_key() for
Gilles Peskine20628592019-04-19 19:29:50 +0200474 * the chosen type. Implementations may allow other
475 * formats, but should be conservative: implementations
476 * should err on the side of rejecting content if it
477 * may be erroneous (e.g. wrong type or truncated data).
Gilles Peskinefa4070c2018-07-12 19:23:03 +0200478 * \param data_length Size of the \p data buffer in bytes.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100479 *
Gilles Peskine28538492018-07-11 17:34:00 +0200480 * \retval #PSA_SUCCESS
Gilles Peskine308b91d2018-02-08 09:47:44 +0100481 * Success.
Gilles Peskine23fd2bd2018-12-11 15:51:32 +0100482 * If the key is persistent, the key material and the key's metadata
483 * have been saved to persistent storage.
Gilles Peskine20628592019-04-19 19:29:50 +0200484 * \retval #PSA_ERROR_ALREADY_EXISTS
485 * This is an attempt to create a persistent key, and there is
486 * already a persistent key with the given identifier.
Gilles Peskine28538492018-07-11 17:34:00 +0200487 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskine65eb8582018-04-19 08:28:58 +0200488 * The key type or key size is not supported, either by the
Gilles Peskine20628592019-04-19 19:29:50 +0200489 * implementation in general or in this particular persistent location.
Gilles Peskine28538492018-07-11 17:34:00 +0200490 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine4ce2a9d2019-05-03 16:57:15 +0200491 * The key attributes, as a whole, are invalid.
492 * \retval #PSA_ERROR_INVALID_ARGUMENT
493 * The key data is not correctly formatted.
494 * \retval #PSA_ERROR_INVALID_ARGUMENT
495 * The size in \p attributes is nonzero and does not match the size
496 * of the key data.
Gilles Peskine28538492018-07-11 17:34:00 +0200497 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
498 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
499 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
Darryl Greend49a4992018-06-18 17:27:26 +0100500 * \retval #PSA_ERROR_STORAGE_FAILURE
Gilles Peskine28538492018-07-11 17:34:00 +0200501 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +0200502 * \retval #PSA_ERROR_CORRUPTION_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +0300503 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +0300504 * The library has not been previously initialized by psa_crypto_init().
505 * It is implementation-dependent whether a failure to initialize
506 * results in this error code.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100507 */
Gilles Peskine87a5e562019-04-17 12:28:25 +0200508psa_status_t psa_import_key(const psa_key_attributes_t *attributes,
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100509 const uint8_t *data,
Gilles Peskine73676cb2019-05-15 20:15:10 +0200510 size_t data_length,
511 psa_key_handle_t *handle);
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100512
513/**
Gilles Peskineae32aac2018-11-30 14:39:32 +0100514 * \brief Destroy a key.
Gilles Peskine154bd952018-04-19 08:38:16 +0200515 *
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +0100516 * This function destroys a key from both volatile
Gilles Peskine154bd952018-04-19 08:38:16 +0200517 * memory and, if applicable, non-volatile storage. Implementations shall
Adrian L. Shawd56456c2019-05-15 11:36:13 +0100518 * make a best effort to ensure that that the key material cannot be recovered.
Gilles Peskine154bd952018-04-19 08:38:16 +0200519 *
Gilles Peskineae32aac2018-11-30 14:39:32 +0100520 * This function also erases any metadata such as policies and frees all
521 * resources associated with the key.
Gilles Peskine154bd952018-04-19 08:38:16 +0200522 *
Andrew Thoelke07f16b72019-08-21 22:48:47 +0100523 * Destroying a key will invalidate all existing handles to the key.
524 *
525 * If the key is currently in use in a multipart operation, then destroying the
526 * key will abort the multipart operation.
527 *
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +0100528 * \param handle Handle to the key to erase.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100529 *
Gilles Peskine28538492018-07-11 17:34:00 +0200530 * \retval #PSA_SUCCESS
Adrian L. Shawd56456c2019-05-15 11:36:13 +0100531 * The key material has been erased.
Gilles Peskine28538492018-07-11 17:34:00 +0200532 * \retval #PSA_ERROR_NOT_PERMITTED
Adrian L. Shaw0a695bd2019-05-15 13:28:41 +0100533 * The key cannot be erased because it is
Gilles Peskine65eb8582018-04-19 08:28:58 +0200534 * read-only, either due to a policy or due to physical restrictions.
Gilles Peskineae32aac2018-11-30 14:39:32 +0100535 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine28538492018-07-11 17:34:00 +0200536 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
Gilles Peskine65eb8582018-04-19 08:28:58 +0200537 * There was an failure in communication with the cryptoprocessor.
538 * The key material may still be present in the cryptoprocessor.
Gilles Peskine28538492018-07-11 17:34:00 +0200539 * \retval #PSA_ERROR_STORAGE_FAILURE
Gilles Peskine65eb8582018-04-19 08:28:58 +0200540 * The storage is corrupted. Implementations shall make a best effort
541 * to erase key material even in this stage, however applications
542 * should be aware that it may be impossible to guarantee that the
543 * key material is not recoverable in such cases.
Gilles Peskine4b3eb692019-05-16 21:35:18 +0200544 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine65eb8582018-04-19 08:28:58 +0200545 * An unexpected condition which is not a storage corruption or
546 * a communication failure occurred. The cryptoprocessor may have
547 * been compromised.
itayzafrir90d8c7a2018-09-12 11:44:52 +0300548 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +0300549 * The library has not been previously initialized by psa_crypto_init().
550 * It is implementation-dependent whether a failure to initialize
551 * results in this error code.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100552 */
Gilles Peskineae32aac2018-11-30 14:39:32 +0100553psa_status_t psa_destroy_key(psa_key_handle_t handle);
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100554
555/**
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100556 * \brief Export a key in binary format.
557 *
558 * The output of this function can be passed to psa_import_key() to
559 * create an equivalent object.
560 *
Gilles Peskinef7933932018-10-31 14:07:52 +0100561 * If the implementation of psa_import_key() supports other formats
562 * beyond the format specified here, the output from psa_export_key()
563 * must use the representation specified here, not the original
564 * representation.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100565 *
Gilles Peskine308b91d2018-02-08 09:47:44 +0100566 * For standard key types, the output format is as follows:
567 *
568 * - For symmetric keys (including MAC keys), the format is the
569 * raw bytes of the key.
570 * - For DES, the key data consists of 8 bytes. The parity bits must be
571 * correct.
572 * - For Triple-DES, the format is the concatenation of the
573 * two or three DES keys.
Gilles Peskinec93b80c2019-05-16 19:39:54 +0200574 * - For RSA key pairs (#PSA_KEY_TYPE_RSA_KEY_PAIR), the format
Gilles Peskine4e1e9be2018-08-10 18:57:40 +0200575 * is the non-encrypted DER encoding of the representation defined by
576 * PKCS\#1 (RFC 8017) as `RSAPrivateKey`, version 0.
577 * ```
578 * RSAPrivateKey ::= SEQUENCE {
Gilles Peskine4f6c77b2018-08-11 01:17:53 +0200579 * version INTEGER, -- must be 0
Gilles Peskine4e1e9be2018-08-10 18:57:40 +0200580 * modulus INTEGER, -- n
581 * publicExponent INTEGER, -- e
582 * privateExponent INTEGER, -- d
583 * prime1 INTEGER, -- p
584 * prime2 INTEGER, -- q
585 * exponent1 INTEGER, -- d mod (p-1)
586 * exponent2 INTEGER, -- d mod (q-1)
587 * coefficient INTEGER, -- (inverse of q) mod p
588 * }
589 * ```
Gilles Peskine4e1e9be2018-08-10 18:57:40 +0200590 * - For elliptic curve key pairs (key types for which
Gilles Peskinec93b80c2019-05-16 19:39:54 +0200591 * #PSA_KEY_TYPE_IS_ECC_KEY_PAIR is true), the format is
Gilles Peskine6c6a0232018-11-15 17:44:43 +0100592 * a representation of the private value as a `ceiling(m/8)`-byte string
593 * where `m` is the bit size associated with the curve, i.e. the bit size
594 * of the order of the curve's coordinate field. This byte string is
595 * in little-endian order for Montgomery curves (curve types
596 * `PSA_ECC_CURVE_CURVEXXX`), and in big-endian order for Weierstrass
597 * curves (curve types `PSA_ECC_CURVE_SECTXXX`, `PSA_ECC_CURVE_SECPXXX`
598 * and `PSA_ECC_CURVE_BRAINPOOL_PXXX`).
Gilles Peskinef76aa772018-10-29 19:24:33 +0100599 * This is the content of the `privateKey` field of the `ECPrivateKey`
600 * format defined by RFC 5915.
Gilles Peskinedcaefae2019-05-16 12:55:35 +0200601 * - For Diffie-Hellman key exchange key pairs (key types for which
Gilles Peskinec93b80c2019-05-16 19:39:54 +0200602 * #PSA_KEY_TYPE_IS_DH_KEY_PAIR is true), the
Jaeden Amero8851c402019-01-11 14:20:03 +0000603 * format is the representation of the private key `x` as a big-endian byte
604 * string. The length of the byte string is the private key size in bytes
605 * (leading zeroes are not stripped).
Gilles Peskine4e1e9be2018-08-10 18:57:40 +0200606 * - For public keys (key types for which #PSA_KEY_TYPE_IS_PUBLIC_KEY is
607 * true), the format is the same as for psa_export_public_key().
Gilles Peskine308b91d2018-02-08 09:47:44 +0100608 *
Gilles Peskine4318dfc2019-05-14 14:23:32 +0200609 * The policy on the key must have the usage flag #PSA_KEY_USAGE_EXPORT set.
610 *
Gilles Peskineae32aac2018-11-30 14:39:32 +0100611 * \param handle Handle to the key to export.
Gilles Peskineedd11a12018-07-12 01:08:58 +0200612 * \param[out] data Buffer where the key data is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +0200613 * \param data_size Size of the \p data buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +0200614 * \param[out] data_length On success, the number of bytes
615 * that make up the key data.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100616 *
Gilles Peskine28538492018-07-11 17:34:00 +0200617 * \retval #PSA_SUCCESS
Gilles Peskineae32aac2018-11-30 14:39:32 +0100618 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine28538492018-07-11 17:34:00 +0200619 * \retval #PSA_ERROR_NOT_PERMITTED
Gilles Peskine4318dfc2019-05-14 14:23:32 +0200620 * The key does not have the #PSA_KEY_USAGE_EXPORT flag.
Darryl Green9e2d7a02018-07-24 16:33:30 +0100621 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskine1be949b2018-08-10 19:06:59 +0200622 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
623 * The size of the \p data buffer is too small. You can determine a
624 * sufficient buffer size by calling
625 * #PSA_KEY_EXPORT_MAX_SIZE(\c type, \c bits)
626 * where \c type is the key type
627 * and \c bits is the key size in bits.
Gilles Peskine28538492018-07-11 17:34:00 +0200628 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
629 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +0200630 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw89b71522019-08-06 16:21:00 +0100631 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shaw0542d592019-08-06 16:34:44 +0100632 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
itayzafrir90d8c7a2018-09-12 11:44:52 +0300633 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +0300634 * The library has not been previously initialized by psa_crypto_init().
635 * It is implementation-dependent whether a failure to initialize
636 * results in this error code.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100637 */
Gilles Peskineae32aac2018-11-30 14:39:32 +0100638psa_status_t psa_export_key(psa_key_handle_t handle,
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100639 uint8_t *data,
640 size_t data_size,
641 size_t *data_length);
642
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100643/**
644 * \brief Export a public key or the public part of a key pair in binary format.
645 *
646 * The output of this function can be passed to psa_import_key() to
647 * create an object that is equivalent to the public key.
648 *
Jaeden Amerod3a0c2c2019-01-11 17:15:56 +0000649 * This specification supports a single format for each key type.
650 * Implementations may support other formats as long as the standard
651 * format is supported. Implementations that support other formats
652 * should ensure that the formats are clearly unambiguous so as to
653 * minimize the risk that an invalid input is accidentally interpreted
654 * according to a different format.
655 *
Jaeden Amero6b196002019-01-10 10:23:21 +0000656 * For standard key types, the output format is as follows:
657 * - For RSA public keys (#PSA_KEY_TYPE_RSA_PUBLIC_KEY), the DER encoding of
658 * the representation defined by RFC 3279 &sect;2.3.1 as `RSAPublicKey`.
659 * ```
660 * RSAPublicKey ::= SEQUENCE {
661 * modulus INTEGER, -- n
662 * publicExponent INTEGER } -- e
663 * ```
Jaeden Amero0ae445f2019-01-10 11:42:27 +0000664 * - For elliptic curve public keys (key types for which
665 * #PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY is true), the format is the uncompressed
666 * representation defined by SEC1 &sect;2.3.3 as the content of an ECPoint.
667 * Let `m` be the bit size associated with the curve, i.e. the bit size of
668 * `q` for a curve over `F_q`. The representation consists of:
669 * - The byte 0x04;
670 * - `x_P` as a `ceiling(m/8)`-byte string, big-endian;
671 * - `y_P` as a `ceiling(m/8)`-byte string, big-endian.
Gilles Peskinedcaefae2019-05-16 12:55:35 +0200672 * - For Diffie-Hellman key exchange public keys (key types for which
673 * #PSA_KEY_TYPE_IS_DH_PUBLIC_KEY is true),
Jaeden Amero8851c402019-01-11 14:20:03 +0000674 * the format is the representation of the public key `y = g^x mod p` as a
675 * big-endian byte string. The length of the byte string is the length of the
676 * base prime `p` in bytes.
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100677 *
Gilles Peskine4318dfc2019-05-14 14:23:32 +0200678 * Exporting a public key object or the public part of a key pair is
679 * always permitted, regardless of the key's usage flags.
680 *
Gilles Peskineae32aac2018-11-30 14:39:32 +0100681 * \param handle Handle to the key to export.
Gilles Peskineedd11a12018-07-12 01:08:58 +0200682 * \param[out] data Buffer where the key data is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +0200683 * \param data_size Size of the \p data buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +0200684 * \param[out] data_length On success, the number of bytes
685 * that make up the key data.
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100686 *
Gilles Peskine28538492018-07-11 17:34:00 +0200687 * \retval #PSA_SUCCESS
Gilles Peskineae32aac2018-11-30 14:39:32 +0100688 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine28538492018-07-11 17:34:00 +0200689 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine1be949b2018-08-10 19:06:59 +0200690 * The key is neither a public key nor a key pair.
691 * \retval #PSA_ERROR_NOT_SUPPORTED
692 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
693 * The size of the \p data buffer is too small. You can determine a
694 * sufficient buffer size by calling
Gilles Peskinec93b80c2019-05-16 19:39:54 +0200695 * #PSA_KEY_EXPORT_MAX_SIZE(#PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(\c type), \c bits)
Gilles Peskine1be949b2018-08-10 19:06:59 +0200696 * where \c type is the key type
697 * and \c bits is the key size in bits.
Gilles Peskine28538492018-07-11 17:34:00 +0200698 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
699 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +0200700 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw398b3c22019-08-06 17:22:41 +0100701 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shaw88c51ad2019-08-06 17:09:33 +0100702 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
itayzafrir90d8c7a2018-09-12 11:44:52 +0300703 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +0300704 * The library has not been previously initialized by psa_crypto_init().
705 * It is implementation-dependent whether a failure to initialize
706 * results in this error code.
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100707 */
Gilles Peskineae32aac2018-11-30 14:39:32 +0100708psa_status_t psa_export_public_key(psa_key_handle_t handle,
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100709 uint8_t *data,
710 size_t data_size,
711 size_t *data_length);
712
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100713/** Make a copy of a key.
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100714 *
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100715 * Copy key material from one location to another.
Jaeden Amero70261c52019-01-04 11:47:20 +0000716 *
Gilles Peskineaec5a7f2019-02-05 20:26:09 +0100717 * This function is primarily useful to copy a key from one location
718 * to another, since it populates a key using the material from
719 * another key which may have a different lifetime.
Gilles Peskine6ac73a92018-07-12 19:47:19 +0200720 *
Adrian L. Shaw0a695bd2019-05-15 13:28:41 +0100721 * This function may be used to share a key with a different party,
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100722 * subject to implementation-defined restrictions on key sharing.
Gilles Peskine7e198532018-03-08 07:50:30 +0100723 *
Gilles Peskine8e0206a2019-05-14 14:24:28 +0200724 * The policy on the source key must have the usage flag
725 * #PSA_KEY_USAGE_COPY set.
Gilles Peskined6a8f5f2019-05-14 16:25:50 +0200726 * This flag is sufficient to permit the copy if the key has the lifetime
727 * #PSA_KEY_LIFETIME_VOLATILE or #PSA_KEY_LIFETIME_PERSISTENT.
728 * Some secure elements do not provide a way to copy a key without
729 * making it extractable from the secure element. If a key is located
730 * in such a secure element, then the key must have both usage flags
731 * #PSA_KEY_USAGE_COPY and #PSA_KEY_USAGE_EXPORT in order to make
732 * a copy of the key outside the secure element.
Gilles Peskine8e0206a2019-05-14 14:24:28 +0200733 *
Gilles Peskine20628592019-04-19 19:29:50 +0200734 * The resulting key may only be used in a way that conforms to
735 * both the policy of the original key and the policy specified in
736 * the \p attributes parameter:
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100737 * - The usage flags on the resulting key are the bitwise-and of the
Gilles Peskine20628592019-04-19 19:29:50 +0200738 * usage flags on the source policy and the usage flags in \p attributes.
739 * - If both allow the same algorithm or wildcard-based
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100740 * algorithm policy, the resulting key has the same algorithm policy.
Gilles Peskine20628592019-04-19 19:29:50 +0200741 * - If either of the policies allows an algorithm and the other policy
742 * allows a wildcard-based algorithm policy that includes this algorithm,
743 * the resulting key allows the same algorithm.
744 * - If the policies do not allow any algorithm in common, this function
745 * fails with the status #PSA_ERROR_INVALID_ARGUMENT.
Gilles Peskine6ac73a92018-07-12 19:47:19 +0200746 *
Gilles Peskine20628592019-04-19 19:29:50 +0200747 * The effect of this function on implementation-defined attributes is
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100748 * implementation-defined.
Gilles Peskine6ac73a92018-07-12 19:47:19 +0200749 *
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +0100750 * \param source_handle The key to copy. It must be a valid key handle.
Gilles Peskine20628592019-04-19 19:29:50 +0200751 * \param[in] attributes The attributes for the new key.
752 * They are used as follows:
Gilles Peskine4ce2a9d2019-05-03 16:57:15 +0200753 * - The key type and size may be 0. If either is
754 * nonzero, it must match the corresponding
755 * attribute of the source key.
Gilles Peskine20628592019-04-19 19:29:50 +0200756 * - The key location (the lifetime and, for
757 * persistent keys, the key identifier) is
758 * used directly.
759 * - The policy constraints (usage flags and
760 * algorithm policy) are combined from
761 * the source key and \p attributes so that
762 * both sets of restrictions apply, as
763 * described in the documentation of this function.
764 * \param[out] target_handle On success, a handle to the newly created key.
765 * \c 0 on failure.
Gilles Peskine6ac73a92018-07-12 19:47:19 +0200766 *
767 * \retval #PSA_SUCCESS
Gilles Peskineae32aac2018-11-30 14:39:32 +0100768 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine20628592019-04-19 19:29:50 +0200769 * \p source_handle is invalid.
David Saadab4ecc272019-02-14 13:48:10 +0200770 * \retval #PSA_ERROR_ALREADY_EXISTS
Gilles Peskine20628592019-04-19 19:29:50 +0200771 * This is an attempt to create a persistent key, and there is
772 * already a persistent key with the given identifier.
Gilles Peskine6ac73a92018-07-12 19:47:19 +0200773 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine20628592019-04-19 19:29:50 +0200774 * The lifetime or identifier in \p attributes are invalid.
775 * \retval #PSA_ERROR_INVALID_ARGUMENT
776 * The policy constraints on the source and specified in
777 * \p attributes are incompatible.
Gilles Peskine4ce2a9d2019-05-03 16:57:15 +0200778 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine24f10f82019-05-16 12:18:32 +0200779 * \p attributes specifies a key type or key size
Gilles Peskine4ce2a9d2019-05-03 16:57:15 +0200780 * which does not match the attributes of the source key.
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100781 * \retval #PSA_ERROR_NOT_PERMITTED
Gilles Peskine8e0206a2019-05-14 14:24:28 +0200782 * The source key does not have the #PSA_KEY_USAGE_COPY usage flag.
783 * \retval #PSA_ERROR_NOT_PERMITTED
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100784 * The source key is not exportable and its lifetime does not
785 * allow copying it to the target's lifetime.
786 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
787 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
Gilles Peskine6ac73a92018-07-12 19:47:19 +0200788 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
789 * \retval #PSA_ERROR_HARDWARE_FAILURE
Adrian L. Shaw60b03202019-08-06 17:26:16 +0100790 * \retval #PSA_ERROR_STORAGE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +0200791 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +0100792 * \retval #PSA_ERROR_BAD_STATE
793 * The library has not been previously initialized by psa_crypto_init().
794 * It is implementation-dependent whether a failure to initialize
795 * results in this error code.
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100796 */
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100797psa_status_t psa_copy_key(psa_key_handle_t source_handle,
Gilles Peskine87a5e562019-04-17 12:28:25 +0200798 const psa_key_attributes_t *attributes,
799 psa_key_handle_t *target_handle);
Gilles Peskine20035e32018-02-03 22:44:14 +0100800
801/**@}*/
802
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100803/** \defgroup hash Message digests
804 * @{
805 */
806
Gilles Peskine69647a42019-01-14 20:18:12 +0100807/** Calculate the hash (digest) of a message.
808 *
809 * \note To verify the hash of a message against an
810 * expected value, use psa_hash_compare() instead.
811 *
812 * \param alg The hash algorithm to compute (\c PSA_ALG_XXX value
813 * such that #PSA_ALG_IS_HASH(\p alg) is true).
814 * \param[in] input Buffer containing the message to hash.
815 * \param input_length Size of the \p input buffer in bytes.
816 * \param[out] hash Buffer where the hash is to be written.
817 * \param hash_size Size of the \p hash buffer in bytes.
818 * \param[out] hash_length On success, the number of bytes
819 * that make up the hash value. This is always
Gilles Peskined338b912019-02-15 13:01:41 +0100820 * #PSA_HASH_SIZE(\p alg).
Gilles Peskine69647a42019-01-14 20:18:12 +0100821 *
822 * \retval #PSA_SUCCESS
823 * Success.
824 * \retval #PSA_ERROR_NOT_SUPPORTED
825 * \p alg is not supported or is not a hash algorithm.
Adrian L. Shawf7d852a2019-08-06 17:50:26 +0100826 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
827 * \p hash_size is too small
Gilles Peskine69647a42019-01-14 20:18:12 +0100828 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
829 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
830 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +0200831 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +0100832 * \retval #PSA_ERROR_BAD_STATE
833 * The library has not been previously initialized by psa_crypto_init().
834 * It is implementation-dependent whether a failure to initialize
835 * results in this error code.
Gilles Peskine69647a42019-01-14 20:18:12 +0100836 */
837psa_status_t psa_hash_compute(psa_algorithm_t alg,
838 const uint8_t *input,
839 size_t input_length,
840 uint8_t *hash,
841 size_t hash_size,
842 size_t *hash_length);
843
844/** Calculate the hash (digest) of a message and compare it with a
845 * reference value.
846 *
847 * \param alg The hash algorithm to compute (\c PSA_ALG_XXX value
848 * such that #PSA_ALG_IS_HASH(\p alg) is true).
849 * \param[in] input Buffer containing the message to hash.
850 * \param input_length Size of the \p input buffer in bytes.
851 * \param[out] hash Buffer containing the expected hash value.
Gilles Peskinea05602d2019-01-17 15:25:52 +0100852 * \param hash_length Size of the \p hash buffer in bytes.
Gilles Peskine69647a42019-01-14 20:18:12 +0100853 *
854 * \retval #PSA_SUCCESS
855 * The expected hash is identical to the actual hash of the input.
856 * \retval #PSA_ERROR_INVALID_SIGNATURE
857 * The hash of the message was calculated successfully, but it
858 * differs from the expected hash.
859 * \retval #PSA_ERROR_NOT_SUPPORTED
860 * \p alg is not supported or is not a hash algorithm.
861 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
862 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
863 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +0200864 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +0100865 * \retval #PSA_ERROR_BAD_STATE
866 * The library has not been previously initialized by psa_crypto_init().
867 * It is implementation-dependent whether a failure to initialize
868 * results in this error code.
Gilles Peskine69647a42019-01-14 20:18:12 +0100869 */
870psa_status_t psa_hash_compare(psa_algorithm_t alg,
871 const uint8_t *input,
872 size_t input_length,
873 const uint8_t *hash,
874 const size_t hash_length);
875
Gilles Peskine308b91d2018-02-08 09:47:44 +0100876/** The type of the state data structure for multipart hash operations.
877 *
Jaeden Amero6a25b412019-01-04 11:47:44 +0000878 * Before calling any function on a hash operation object, the application must
879 * initialize it by any of the following means:
880 * - Set the structure to all-bits-zero, for example:
881 * \code
882 * psa_hash_operation_t operation;
883 * memset(&operation, 0, sizeof(operation));
884 * \endcode
885 * - Initialize the structure to logical zero values, for example:
886 * \code
887 * psa_hash_operation_t operation = {0};
888 * \endcode
889 * - Initialize the structure to the initializer #PSA_HASH_OPERATION_INIT,
890 * for example:
891 * \code
892 * psa_hash_operation_t operation = PSA_HASH_OPERATION_INIT;
893 * \endcode
894 * - Assign the result of the function psa_hash_operation_init()
895 * to the structure, for example:
896 * \code
897 * psa_hash_operation_t operation;
898 * operation = psa_hash_operation_init();
899 * \endcode
900 *
Gilles Peskine92b30732018-03-03 21:29:30 +0100901 * This is an implementation-defined \c struct. Applications should not
Gilles Peskine308b91d2018-02-08 09:47:44 +0100902 * make any assumptions about the content of this structure except
903 * as directed by the documentation of a specific implementation. */
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100904typedef struct psa_hash_operation_s psa_hash_operation_t;
905
Jaeden Amero6a25b412019-01-04 11:47:44 +0000906/** \def PSA_HASH_OPERATION_INIT
907 *
908 * This macro returns a suitable initializer for a hash operation object
909 * of type #psa_hash_operation_t.
910 */
911#ifdef __DOXYGEN_ONLY__
912/* This is an example definition for documentation purposes.
913 * Implementations should define a suitable value in `crypto_struct.h`.
914 */
915#define PSA_HASH_OPERATION_INIT {0}
916#endif
917
918/** Return an initial value for a hash operation object.
919 */
920static psa_hash_operation_t psa_hash_operation_init(void);
921
Gilles Peskinef45adda2019-01-14 18:29:18 +0100922/** Set up a multipart hash operation.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100923 *
924 * The sequence of operations to calculate a hash (message digest)
925 * is as follows:
926 * -# Allocate an operation object which will be passed to all the functions
927 * listed here.
Jaeden Amero6a25b412019-01-04 11:47:44 +0000928 * -# Initialize the operation object with one of the methods described in the
929 * documentation for #psa_hash_operation_t, e.g. PSA_HASH_OPERATION_INIT.
Gilles Peskineda8191d1c2018-07-08 19:46:38 +0200930 * -# Call psa_hash_setup() to specify the algorithm.
Gilles Peskine7e4acc52018-02-16 21:24:11 +0100931 * -# Call psa_hash_update() zero, one or more times, passing a fragment
Gilles Peskine308b91d2018-02-08 09:47:44 +0100932 * of the message each time. The hash that is calculated is the hash
933 * of the concatenation of these messages in order.
934 * -# To calculate the hash, call psa_hash_finish().
935 * To compare the hash with an expected value, call psa_hash_verify().
936 *
937 * The application may call psa_hash_abort() at any time after the operation
Jaeden Amero6a25b412019-01-04 11:47:44 +0000938 * has been initialized.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100939 *
Gilles Peskineda8191d1c2018-07-08 19:46:38 +0200940 * After a successful call to psa_hash_setup(), the application must
Gilles Peskineed522972018-03-20 17:54:15 +0100941 * eventually terminate the operation. The following events terminate an
942 * operation:
Gilles Peskine308b91d2018-02-08 09:47:44 +0100943 * - A failed call to psa_hash_update().
Gilles Peskine19067982018-03-20 17:54:53 +0100944 * - A call to psa_hash_finish(), psa_hash_verify() or psa_hash_abort().
Gilles Peskine308b91d2018-02-08 09:47:44 +0100945 *
Jaeden Amero6a25b412019-01-04 11:47:44 +0000946 * \param[in,out] operation The operation object to set up. It must have
947 * been initialized as per the documentation for
948 * #psa_hash_operation_t and not yet in use.
Gilles Peskineedd11a12018-07-12 01:08:58 +0200949 * \param alg The hash algorithm to compute (\c PSA_ALG_XXX value
950 * such that #PSA_ALG_IS_HASH(\p alg) is true).
Gilles Peskine308b91d2018-02-08 09:47:44 +0100951 *
Gilles Peskine28538492018-07-11 17:34:00 +0200952 * \retval #PSA_SUCCESS
Gilles Peskine308b91d2018-02-08 09:47:44 +0100953 * Success.
Gilles Peskine28538492018-07-11 17:34:00 +0200954 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskinefa4070c2018-07-12 19:23:03 +0200955 * \p alg is not supported or is not a hash algorithm.
Gilles Peskine8e1addc2019-01-10 11:51:17 +0100956 * \retval #PSA_ERROR_BAD_STATE
957 * The operation state is not valid (already set up and not
958 * subsequently completed).
Gilles Peskine28538492018-07-11 17:34:00 +0200959 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
960 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
961 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +0200962 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +0100963 * \retval #PSA_ERROR_BAD_STATE
964 * The library has not been previously initialized by psa_crypto_init().
965 * It is implementation-dependent whether a failure to initialize
966 * results in this error code.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100967 */
Gilles Peskineda8191d1c2018-07-08 19:46:38 +0200968psa_status_t psa_hash_setup(psa_hash_operation_t *operation,
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100969 psa_algorithm_t alg);
970
Gilles Peskine308b91d2018-02-08 09:47:44 +0100971/** Add a message fragment to a multipart hash operation.
972 *
Gilles Peskineda8191d1c2018-07-08 19:46:38 +0200973 * The application must call psa_hash_setup() before calling this function.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100974 *
975 * If this function returns an error status, the operation becomes inactive.
976 *
Gilles Peskineedd11a12018-07-12 01:08:58 +0200977 * \param[in,out] operation Active hash operation.
978 * \param[in] input Buffer containing the message fragment to hash.
Gilles Peskinefa4070c2018-07-12 19:23:03 +0200979 * \param input_length Size of the \p input buffer in bytes.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100980 *
Gilles Peskine28538492018-07-11 17:34:00 +0200981 * \retval #PSA_SUCCESS
Gilles Peskine308b91d2018-02-08 09:47:44 +0100982 * Success.
Gilles Peskine28538492018-07-11 17:34:00 +0200983 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +0100984 * The operation state is not valid (not set up, or already completed).
Gilles Peskine28538492018-07-11 17:34:00 +0200985 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
986 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
987 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +0200988 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +0100989 * \retval #PSA_ERROR_BAD_STATE
990 * The library has not been previously initialized by psa_crypto_init().
991 * It is implementation-dependent whether a failure to initialize
992 * results in this error code.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100993 */
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100994psa_status_t psa_hash_update(psa_hash_operation_t *operation,
995 const uint8_t *input,
996 size_t input_length);
997
Gilles Peskine308b91d2018-02-08 09:47:44 +0100998/** Finish the calculation of the hash of a message.
999 *
Gilles Peskineda8191d1c2018-07-08 19:46:38 +02001000 * The application must call psa_hash_setup() before calling this function.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001001 * This function calculates the hash of the message formed by concatenating
1002 * the inputs passed to preceding calls to psa_hash_update().
1003 *
1004 * When this function returns, the operation becomes inactive.
1005 *
1006 * \warning Applications should not call this function if they expect
1007 * a specific value for the hash. Call psa_hash_verify() instead.
1008 * Beware that comparing integrity or authenticity data such as
1009 * hash values with a function such as \c memcmp is risky
1010 * because the time taken by the comparison may leak information
1011 * about the hashed data which could allow an attacker to guess
1012 * a valid hash and thereby bypass security controls.
1013 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001014 * \param[in,out] operation Active hash operation.
1015 * \param[out] hash Buffer where the hash is to be written.
1016 * \param hash_size Size of the \p hash buffer in bytes.
1017 * \param[out] hash_length On success, the number of bytes
1018 * that make up the hash value. This is always
Gilles Peskinebe42f312018-07-13 14:38:15 +02001019 * #PSA_HASH_SIZE(\c alg) where \c alg is the
Gilles Peskineedd11a12018-07-12 01:08:58 +02001020 * hash algorithm that is calculated.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001021 *
Gilles Peskine28538492018-07-11 17:34:00 +02001022 * \retval #PSA_SUCCESS
Gilles Peskine308b91d2018-02-08 09:47:44 +01001023 * Success.
Gilles Peskine28538492018-07-11 17:34:00 +02001024 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001025 * The operation state is not valid (not set up, or already completed).
Gilles Peskine28538492018-07-11 17:34:00 +02001026 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001027 * The size of the \p hash buffer is too small. You can determine a
Gilles Peskine7256e6c2018-07-12 00:34:26 +02001028 * sufficient buffer size by calling #PSA_HASH_SIZE(\c alg)
Gilles Peskine308b91d2018-02-08 09:47:44 +01001029 * where \c alg is the hash algorithm that is calculated.
Gilles Peskine28538492018-07-11 17:34:00 +02001030 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1031 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1032 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001033 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001034 * \retval #PSA_ERROR_BAD_STATE
1035 * The library has not been previously initialized by psa_crypto_init().
1036 * It is implementation-dependent whether a failure to initialize
1037 * results in this error code.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001038 */
Gilles Peskine9ef733f2018-02-07 21:05:37 +01001039psa_status_t psa_hash_finish(psa_hash_operation_t *operation,
1040 uint8_t *hash,
1041 size_t hash_size,
1042 size_t *hash_length);
1043
Gilles Peskine308b91d2018-02-08 09:47:44 +01001044/** Finish the calculation of the hash of a message and compare it with
1045 * an expected value.
1046 *
Gilles Peskineda8191d1c2018-07-08 19:46:38 +02001047 * The application must call psa_hash_setup() before calling this function.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001048 * This function calculates the hash of the message formed by concatenating
1049 * the inputs passed to preceding calls to psa_hash_update(). It then
1050 * compares the calculated hash with the expected hash passed as a
1051 * parameter to this function.
1052 *
1053 * When this function returns, the operation becomes inactive.
1054 *
Gilles Peskine19067982018-03-20 17:54:53 +01001055 * \note Implementations shall make the best effort to ensure that the
Gilles Peskine308b91d2018-02-08 09:47:44 +01001056 * comparison between the actual hash and the expected hash is performed
1057 * in constant time.
1058 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001059 * \param[in,out] operation Active hash operation.
1060 * \param[in] hash Buffer containing the expected hash value.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001061 * \param hash_length Size of the \p hash buffer in bytes.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001062 *
Gilles Peskine28538492018-07-11 17:34:00 +02001063 * \retval #PSA_SUCCESS
Gilles Peskine308b91d2018-02-08 09:47:44 +01001064 * The expected hash is identical to the actual hash of the message.
Gilles Peskine28538492018-07-11 17:34:00 +02001065 * \retval #PSA_ERROR_INVALID_SIGNATURE
Gilles Peskine308b91d2018-02-08 09:47:44 +01001066 * The hash of the message was calculated successfully, but it
1067 * differs from the expected hash.
Gilles Peskine28538492018-07-11 17:34:00 +02001068 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001069 * The operation state is not valid (not set up, or already completed).
Gilles Peskine28538492018-07-11 17:34:00 +02001070 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1071 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1072 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001073 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001074 * \retval #PSA_ERROR_BAD_STATE
1075 * The library has not been previously initialized by psa_crypto_init().
1076 * It is implementation-dependent whether a failure to initialize
1077 * results in this error code.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001078 */
Gilles Peskine9ef733f2018-02-07 21:05:37 +01001079psa_status_t psa_hash_verify(psa_hash_operation_t *operation,
1080 const uint8_t *hash,
1081 size_t hash_length);
1082
Gilles Peskine308b91d2018-02-08 09:47:44 +01001083/** Abort a hash operation.
1084 *
Gilles Peskine308b91d2018-02-08 09:47:44 +01001085 * Aborting an operation frees all associated resources except for the
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001086 * \p operation structure itself. Once aborted, the operation object
1087 * can be reused for another operation by calling
1088 * psa_hash_setup() again.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001089 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001090 * You may call this function any time after the operation object has
1091 * been initialized by any of the following methods:
1092 * - A call to psa_hash_setup(), whether it succeeds or not.
1093 * - Initializing the \c struct to all-bits-zero.
1094 * - Initializing the \c struct to logical zeros, e.g.
1095 * `psa_hash_operation_t operation = {0}`.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001096 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001097 * In particular, calling psa_hash_abort() after the operation has been
1098 * terminated by a call to psa_hash_abort(), psa_hash_finish() or
1099 * psa_hash_verify() is safe and has no effect.
1100 *
1101 * \param[in,out] operation Initialized hash operation.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001102 *
Gilles Peskine28538492018-07-11 17:34:00 +02001103 * \retval #PSA_SUCCESS
1104 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001105 * \p operation is not an active hash operation.
Gilles Peskine28538492018-07-11 17:34:00 +02001106 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1107 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001108 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001109 * \retval #PSA_ERROR_BAD_STATE
1110 * The library has not been previously initialized by psa_crypto_init().
1111 * It is implementation-dependent whether a failure to initialize
1112 * results in this error code.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001113 */
1114psa_status_t psa_hash_abort(psa_hash_operation_t *operation);
Gilles Peskine9ef733f2018-02-07 21:05:37 +01001115
Gilles Peskineebb2c3e2019-01-19 12:03:41 +01001116/** Clone a hash operation.
1117 *
Gilles Peskinee43aa392019-01-21 14:50:37 +01001118 * This function copies the state of an ongoing hash operation to
1119 * a new operation object. In other words, this function is equivalent
1120 * to calling psa_hash_setup() on \p target_operation with the same
1121 * algorithm that \p source_operation was set up for, then
1122 * psa_hash_update() on \p target_operation with the same input that
1123 * that was passed to \p source_operation. After this function returns, the
1124 * two objects are independent, i.e. subsequent calls involving one of
1125 * the objects do not affect the other object.
1126 *
Gilles Peskineebb2c3e2019-01-19 12:03:41 +01001127 * \param[in] source_operation The active hash operation to clone.
1128 * \param[in,out] target_operation The operation object to set up.
1129 * It must be initialized but not active.
1130 *
1131 * \retval #PSA_SUCCESS
1132 * \retval #PSA_ERROR_BAD_STATE
1133 * \p source_operation is not an active hash operation.
1134 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinee43aa392019-01-21 14:50:37 +01001135 * \p target_operation is active.
Gilles Peskineebb2c3e2019-01-19 12:03:41 +01001136 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1137 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001138 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001139 * \retval #PSA_ERROR_BAD_STATE
1140 * The library has not been previously initialized by psa_crypto_init().
1141 * It is implementation-dependent whether a failure to initialize
1142 * results in this error code.
Gilles Peskineebb2c3e2019-01-19 12:03:41 +01001143 */
1144psa_status_t psa_hash_clone(const psa_hash_operation_t *source_operation,
1145 psa_hash_operation_t *target_operation);
1146
Gilles Peskine9ef733f2018-02-07 21:05:37 +01001147/**@}*/
1148
Gilles Peskine8c9def32018-02-08 10:02:12 +01001149/** \defgroup MAC Message authentication codes
1150 * @{
1151 */
1152
Gilles Peskine69647a42019-01-14 20:18:12 +01001153/** Calculate the MAC (message authentication code) of a message.
1154 *
1155 * \note To verify the MAC of a message against an
1156 * expected value, use psa_mac_verify() instead.
1157 * Beware that comparing integrity or authenticity data such as
1158 * MAC values with a function such as \c memcmp is risky
1159 * because the time taken by the comparison may leak information
1160 * about the MAC value which could allow an attacker to guess
1161 * a valid MAC and thereby bypass security controls.
1162 *
1163 * \param handle Handle to the key to use for the operation.
1164 * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
Gilles Peskine63f79302019-02-15 13:01:17 +01001165 * such that #PSA_ALG_IS_MAC(\p alg) is true).
Gilles Peskine69647a42019-01-14 20:18:12 +01001166 * \param[in] input Buffer containing the input message.
1167 * \param input_length Size of the \p input buffer in bytes.
1168 * \param[out] mac Buffer where the MAC value is to be written.
1169 * \param mac_size Size of the \p mac buffer in bytes.
1170 * \param[out] mac_length On success, the number of bytes
Gilles Peskined338b912019-02-15 13:01:41 +01001171 * that make up the MAC value.
Gilles Peskine69647a42019-01-14 20:18:12 +01001172 *
1173 * \retval #PSA_SUCCESS
1174 * Success.
1175 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine69647a42019-01-14 20:18:12 +01001176 * \retval #PSA_ERROR_NOT_PERMITTED
1177 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001178 * \p handle is not compatible with \p alg.
Gilles Peskine69647a42019-01-14 20:18:12 +01001179 * \retval #PSA_ERROR_NOT_SUPPORTED
1180 * \p alg is not supported or is not a MAC algorithm.
Adrian L. Shawd5ae06b2019-08-07 15:59:33 +01001181 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
1182 * \p mac_size is too small
Gilles Peskine69647a42019-01-14 20:18:12 +01001183 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1184 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1185 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001186 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawfa591c42019-08-07 10:47:47 +01001187 * \retval #PSA_ERROR_STORAGE_FAILURE
1188 * The key could not be retrieved from storage.
Gilles Peskine69647a42019-01-14 20:18:12 +01001189 * \retval #PSA_ERROR_BAD_STATE
1190 * The library has not been previously initialized by psa_crypto_init().
1191 * It is implementation-dependent whether a failure to initialize
1192 * results in this error code.
1193 */
1194psa_status_t psa_mac_compute(psa_key_handle_t handle,
1195 psa_algorithm_t alg,
1196 const uint8_t *input,
1197 size_t input_length,
1198 uint8_t *mac,
1199 size_t mac_size,
1200 size_t *mac_length);
1201
1202/** Calculate the MAC of a message and compare it with a reference value.
1203 *
1204 * \param handle Handle to the key to use for the operation.
1205 * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
Gilles Peskine63f79302019-02-15 13:01:17 +01001206 * such that #PSA_ALG_IS_MAC(\p alg) is true).
Gilles Peskine69647a42019-01-14 20:18:12 +01001207 * \param[in] input Buffer containing the input message.
1208 * \param input_length Size of the \p input buffer in bytes.
1209 * \param[out] mac Buffer containing the expected MAC value.
1210 * \param mac_length Size of the \p mac buffer in bytes.
1211 *
1212 * \retval #PSA_SUCCESS
1213 * The expected MAC is identical to the actual MAC of the input.
1214 * \retval #PSA_ERROR_INVALID_SIGNATURE
1215 * The MAC of the message was calculated successfully, but it
1216 * differs from the expected value.
1217 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine69647a42019-01-14 20:18:12 +01001218 * \retval #PSA_ERROR_NOT_PERMITTED
1219 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001220 * \p handle is not compatible with \p alg.
Gilles Peskine69647a42019-01-14 20:18:12 +01001221 * \retval #PSA_ERROR_NOT_SUPPORTED
1222 * \p alg is not supported or is not a MAC algorithm.
1223 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1224 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1225 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001226 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001227 * \retval #PSA_ERROR_STORAGE_FAILURE
1228 * The key could not be retrieved from storage.
1229 * \retval #PSA_ERROR_BAD_STATE
1230 * The library has not been previously initialized by psa_crypto_init().
1231 * It is implementation-dependent whether a failure to initialize
1232 * results in this error code.
Gilles Peskine69647a42019-01-14 20:18:12 +01001233 */
Gilles Peskinea05602d2019-01-17 15:25:52 +01001234psa_status_t psa_mac_verify(psa_key_handle_t handle,
1235 psa_algorithm_t alg,
Gilles Peskine69647a42019-01-14 20:18:12 +01001236 const uint8_t *input,
1237 size_t input_length,
1238 const uint8_t *mac,
1239 const size_t mac_length);
1240
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001241/** The type of the state data structure for multipart MAC operations.
1242 *
Jaeden Amero769ce272019-01-04 11:48:03 +00001243 * Before calling any function on a MAC operation object, the application must
1244 * initialize it by any of the following means:
1245 * - Set the structure to all-bits-zero, for example:
1246 * \code
1247 * psa_mac_operation_t operation;
1248 * memset(&operation, 0, sizeof(operation));
1249 * \endcode
1250 * - Initialize the structure to logical zero values, for example:
1251 * \code
1252 * psa_mac_operation_t operation = {0};
1253 * \endcode
1254 * - Initialize the structure to the initializer #PSA_MAC_OPERATION_INIT,
1255 * for example:
1256 * \code
1257 * psa_mac_operation_t operation = PSA_MAC_OPERATION_INIT;
1258 * \endcode
1259 * - Assign the result of the function psa_mac_operation_init()
1260 * to the structure, for example:
1261 * \code
1262 * psa_mac_operation_t operation;
1263 * operation = psa_mac_operation_init();
1264 * \endcode
1265 *
Gilles Peskine92b30732018-03-03 21:29:30 +01001266 * This is an implementation-defined \c struct. Applications should not
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001267 * make any assumptions about the content of this structure except
1268 * as directed by the documentation of a specific implementation. */
Gilles Peskine8c9def32018-02-08 10:02:12 +01001269typedef struct psa_mac_operation_s psa_mac_operation_t;
1270
Jaeden Amero769ce272019-01-04 11:48:03 +00001271/** \def PSA_MAC_OPERATION_INIT
1272 *
1273 * This macro returns a suitable initializer for a MAC operation object of type
1274 * #psa_mac_operation_t.
1275 */
1276#ifdef __DOXYGEN_ONLY__
1277/* This is an example definition for documentation purposes.
1278 * Implementations should define a suitable value in `crypto_struct.h`.
1279 */
1280#define PSA_MAC_OPERATION_INIT {0}
1281#endif
1282
1283/** Return an initial value for a MAC operation object.
1284 */
1285static psa_mac_operation_t psa_mac_operation_init(void);
1286
Gilles Peskinef45adda2019-01-14 18:29:18 +01001287/** Set up a multipart MAC calculation operation.
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001288 *
Gilles Peskine89167cb2018-07-08 20:12:23 +02001289 * This function sets up the calculation of the MAC
1290 * (message authentication code) of a byte string.
1291 * To verify the MAC of a message against an
1292 * expected value, use psa_mac_verify_setup() instead.
1293 *
1294 * The sequence of operations to calculate a MAC is as follows:
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001295 * -# Allocate an operation object which will be passed to all the functions
1296 * listed here.
Jaeden Amero769ce272019-01-04 11:48:03 +00001297 * -# Initialize the operation object with one of the methods described in the
1298 * documentation for #psa_mac_operation_t, e.g. PSA_MAC_OPERATION_INIT.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001299 * -# Call psa_mac_sign_setup() to specify the algorithm and key.
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001300 * -# Call psa_mac_update() zero, one or more times, passing a fragment
1301 * of the message each time. The MAC that is calculated is the MAC
1302 * of the concatenation of these messages in order.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001303 * -# At the end of the message, call psa_mac_sign_finish() to finish
1304 * calculating the MAC value and retrieve it.
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001305 *
1306 * The application may call psa_mac_abort() at any time after the operation
Jaeden Amero769ce272019-01-04 11:48:03 +00001307 * has been initialized.
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001308 *
Gilles Peskine89167cb2018-07-08 20:12:23 +02001309 * After a successful call to psa_mac_sign_setup(), the application must
1310 * eventually terminate the operation through one of the following methods:
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001311 * - A failed call to psa_mac_update().
Gilles Peskine89167cb2018-07-08 20:12:23 +02001312 * - A call to psa_mac_sign_finish() or psa_mac_abort().
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001313 *
Jaeden Amero769ce272019-01-04 11:48:03 +00001314 * \param[in,out] operation The operation object to set up. It must have
1315 * been initialized as per the documentation for
1316 * #psa_mac_operation_t and not yet in use.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001317 * \param handle Handle to the key to use for the operation.
Gilles Peskine5f25dd02019-01-14 18:24:53 +01001318 * It must remain valid until the operation
1319 * terminates.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001320 * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
Gilles Peskine63f79302019-02-15 13:01:17 +01001321 * such that #PSA_ALG_IS_MAC(\p alg) is true).
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001322 *
Gilles Peskine28538492018-07-11 17:34:00 +02001323 * \retval #PSA_SUCCESS
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001324 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001325 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine28538492018-07-11 17:34:00 +02001326 * \retval #PSA_ERROR_NOT_PERMITTED
1327 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001328 * \p handle is not compatible with \p alg.
Gilles Peskine28538492018-07-11 17:34:00 +02001329 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001330 * \p alg is not supported or is not a MAC algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02001331 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1332 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1333 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001334 * \retval #PSA_ERROR_CORRUPTION_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03001335 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskine8e1addc2019-01-10 11:51:17 +01001336 * The operation state is not valid (already set up and not
1337 * subsequently completed).
1338 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03001339 * The library has not been previously initialized by psa_crypto_init().
1340 * It is implementation-dependent whether a failure to initialize
1341 * results in this error code.
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001342 */
Gilles Peskine89167cb2018-07-08 20:12:23 +02001343psa_status_t psa_mac_sign_setup(psa_mac_operation_t *operation,
Gilles Peskineae32aac2018-11-30 14:39:32 +01001344 psa_key_handle_t handle,
Gilles Peskine89167cb2018-07-08 20:12:23 +02001345 psa_algorithm_t alg);
1346
Gilles Peskinef45adda2019-01-14 18:29:18 +01001347/** Set up a multipart MAC verification operation.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001348 *
1349 * This function sets up the verification of the MAC
1350 * (message authentication code) of a byte string against an expected value.
1351 *
1352 * The sequence of operations to verify a MAC is as follows:
1353 * -# Allocate an operation object which will be passed to all the functions
1354 * listed here.
Jaeden Amero769ce272019-01-04 11:48:03 +00001355 * -# Initialize the operation object with one of the methods described in the
1356 * documentation for #psa_mac_operation_t, e.g. PSA_MAC_OPERATION_INIT.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001357 * -# Call psa_mac_verify_setup() to specify the algorithm and key.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001358 * -# Call psa_mac_update() zero, one or more times, passing a fragment
1359 * of the message each time. The MAC that is calculated is the MAC
1360 * of the concatenation of these messages in order.
1361 * -# At the end of the message, call psa_mac_verify_finish() to finish
1362 * calculating the actual MAC of the message and verify it against
1363 * the expected value.
1364 *
1365 * The application may call psa_mac_abort() at any time after the operation
Jaeden Amero769ce272019-01-04 11:48:03 +00001366 * has been initialized.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001367 *
1368 * After a successful call to psa_mac_verify_setup(), the application must
1369 * eventually terminate the operation through one of the following methods:
1370 * - A failed call to psa_mac_update().
1371 * - A call to psa_mac_verify_finish() or psa_mac_abort().
1372 *
Jaeden Amero769ce272019-01-04 11:48:03 +00001373 * \param[in,out] operation The operation object to set up. It must have
1374 * been initialized as per the documentation for
1375 * #psa_mac_operation_t and not yet in use.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001376 * \param handle Handle to the key to use for the operation.
Gilles Peskine5f25dd02019-01-14 18:24:53 +01001377 * It must remain valid until the operation
1378 * terminates.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001379 * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
1380 * such that #PSA_ALG_IS_MAC(\p alg) is true).
Gilles Peskine89167cb2018-07-08 20:12:23 +02001381 *
Gilles Peskine28538492018-07-11 17:34:00 +02001382 * \retval #PSA_SUCCESS
Gilles Peskine89167cb2018-07-08 20:12:23 +02001383 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001384 * \retval #PSA_ERROR_INVALID_HANDLE
David Saadab4ecc272019-02-14 13:48:10 +02001385 * \retval #PSA_ERROR_DOES_NOT_EXIST
Gilles Peskine28538492018-07-11 17:34:00 +02001386 * \retval #PSA_ERROR_NOT_PERMITTED
1387 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine89167cb2018-07-08 20:12:23 +02001388 * \c key is not compatible with \c alg.
Gilles Peskine28538492018-07-11 17:34:00 +02001389 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskine89167cb2018-07-08 20:12:23 +02001390 * \c alg is not supported or is not a MAC algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02001391 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1392 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1393 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001394 * \retval #PSA_ERROR_CORRUPTION_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03001395 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskine8e1addc2019-01-10 11:51:17 +01001396 * The operation state is not valid (already set up and not
1397 * subsequently completed).
1398 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03001399 * The library has not been previously initialized by psa_crypto_init().
1400 * It is implementation-dependent whether a failure to initialize
1401 * results in this error code.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001402 */
1403psa_status_t psa_mac_verify_setup(psa_mac_operation_t *operation,
Gilles Peskineae32aac2018-11-30 14:39:32 +01001404 psa_key_handle_t handle,
Gilles Peskine89167cb2018-07-08 20:12:23 +02001405 psa_algorithm_t alg);
Gilles Peskine8c9def32018-02-08 10:02:12 +01001406
Gilles Peskinedcd14942018-07-12 00:30:52 +02001407/** Add a message fragment to a multipart MAC operation.
1408 *
1409 * The application must call psa_mac_sign_setup() or psa_mac_verify_setup()
1410 * before calling this function.
1411 *
1412 * If this function returns an error status, the operation becomes inactive.
1413 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001414 * \param[in,out] operation Active MAC operation.
1415 * \param[in] input Buffer containing the message fragment to add to
1416 * the MAC calculation.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001417 * \param input_length Size of the \p input buffer in bytes.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001418 *
1419 * \retval #PSA_SUCCESS
1420 * Success.
1421 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001422 * The operation state is not valid (not set up, or already completed).
Gilles Peskinedcd14942018-07-12 00:30:52 +02001423 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1424 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1425 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001426 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001427 * \retval #PSA_ERROR_BAD_STATE
1428 * The library has not been previously initialized by psa_crypto_init().
1429 * It is implementation-dependent whether a failure to initialize
1430 * results in this error code.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001431 */
Gilles Peskine8c9def32018-02-08 10:02:12 +01001432psa_status_t psa_mac_update(psa_mac_operation_t *operation,
1433 const uint8_t *input,
1434 size_t input_length);
1435
Gilles Peskinedcd14942018-07-12 00:30:52 +02001436/** Finish the calculation of the MAC of a message.
1437 *
1438 * The application must call psa_mac_sign_setup() before calling this function.
1439 * This function calculates the MAC of the message formed by concatenating
1440 * the inputs passed to preceding calls to psa_mac_update().
1441 *
1442 * When this function returns, the operation becomes inactive.
1443 *
1444 * \warning Applications should not call this function if they expect
1445 * a specific value for the MAC. Call psa_mac_verify_finish() instead.
1446 * Beware that comparing integrity or authenticity data such as
1447 * MAC values with a function such as \c memcmp is risky
1448 * because the time taken by the comparison may leak information
1449 * about the MAC value which could allow an attacker to guess
1450 * a valid MAC and thereby bypass security controls.
1451 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001452 * \param[in,out] operation Active MAC operation.
1453 * \param[out] mac Buffer where the MAC value is to be written.
1454 * \param mac_size Size of the \p mac buffer in bytes.
1455 * \param[out] mac_length On success, the number of bytes
1456 * that make up the MAC value. This is always
Gilles Peskinedda3bd32018-07-12 19:40:46 +02001457 * #PSA_MAC_FINAL_SIZE(\c key_type, \c key_bits, \c alg)
Gilles Peskineedd11a12018-07-12 01:08:58 +02001458 * where \c key_type and \c key_bits are the type and
Gilles Peskinedda3bd32018-07-12 19:40:46 +02001459 * bit-size respectively of the key and \c alg is the
Gilles Peskineedd11a12018-07-12 01:08:58 +02001460 * MAC algorithm that is calculated.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001461 *
1462 * \retval #PSA_SUCCESS
1463 * Success.
1464 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001465 * The operation state is not valid (not set up, or already completed).
Gilles Peskinedcd14942018-07-12 00:30:52 +02001466 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001467 * The size of the \p mac buffer is too small. You can determine a
Gilles Peskinedcd14942018-07-12 00:30:52 +02001468 * sufficient buffer size by calling PSA_MAC_FINAL_SIZE().
1469 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1470 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1471 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001472 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001473 * \retval #PSA_ERROR_BAD_STATE
1474 * The library has not been previously initialized by psa_crypto_init().
1475 * It is implementation-dependent whether a failure to initialize
1476 * results in this error code.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001477 */
Gilles Peskineacd4be32018-07-08 19:56:25 +02001478psa_status_t psa_mac_sign_finish(psa_mac_operation_t *operation,
1479 uint8_t *mac,
1480 size_t mac_size,
1481 size_t *mac_length);
Gilles Peskine8c9def32018-02-08 10:02:12 +01001482
Gilles Peskinedcd14942018-07-12 00:30:52 +02001483/** Finish the calculation of the MAC of a message and compare it with
1484 * an expected value.
1485 *
1486 * The application must call psa_mac_verify_setup() before calling this function.
1487 * This function calculates the MAC of the message formed by concatenating
1488 * the inputs passed to preceding calls to psa_mac_update(). It then
1489 * compares the calculated MAC with the expected MAC passed as a
1490 * parameter to this function.
1491 *
1492 * When this function returns, the operation becomes inactive.
1493 *
1494 * \note Implementations shall make the best effort to ensure that the
1495 * comparison between the actual MAC and the expected MAC is performed
1496 * in constant time.
1497 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001498 * \param[in,out] operation Active MAC operation.
1499 * \param[in] mac Buffer containing the expected MAC value.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001500 * \param mac_length Size of the \p mac buffer in bytes.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001501 *
1502 * \retval #PSA_SUCCESS
1503 * The expected MAC is identical to the actual MAC of the message.
1504 * \retval #PSA_ERROR_INVALID_SIGNATURE
1505 * The MAC of the message was calculated successfully, but it
1506 * differs from the expected MAC.
1507 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001508 * The operation state is not valid (not set up, or already completed).
Gilles Peskinedcd14942018-07-12 00:30:52 +02001509 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1510 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1511 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001512 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001513 * \retval #PSA_ERROR_BAD_STATE
1514 * The library has not been previously initialized by psa_crypto_init().
1515 * It is implementation-dependent whether a failure to initialize
1516 * results in this error code.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001517 */
Gilles Peskineacd4be32018-07-08 19:56:25 +02001518psa_status_t psa_mac_verify_finish(psa_mac_operation_t *operation,
1519 const uint8_t *mac,
1520 size_t mac_length);
Gilles Peskine8c9def32018-02-08 10:02:12 +01001521
Gilles Peskinedcd14942018-07-12 00:30:52 +02001522/** Abort a MAC operation.
1523 *
Gilles Peskinedcd14942018-07-12 00:30:52 +02001524 * Aborting an operation frees all associated resources except for the
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001525 * \p operation structure itself. Once aborted, the operation object
1526 * can be reused for another operation by calling
1527 * psa_mac_sign_setup() or psa_mac_verify_setup() again.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001528 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001529 * You may call this function any time after the operation object has
1530 * been initialized by any of the following methods:
1531 * - A call to psa_mac_sign_setup() or psa_mac_verify_setup(), whether
1532 * it succeeds or not.
1533 * - Initializing the \c struct to all-bits-zero.
1534 * - Initializing the \c struct to logical zeros, e.g.
1535 * `psa_mac_operation_t operation = {0}`.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001536 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001537 * In particular, calling psa_mac_abort() after the operation has been
1538 * terminated by a call to psa_mac_abort(), psa_mac_sign_finish() or
1539 * psa_mac_verify_finish() is safe and has no effect.
1540 *
1541 * \param[in,out] operation Initialized MAC operation.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001542 *
1543 * \retval #PSA_SUCCESS
1544 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001545 * \p operation is not an active MAC operation.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001546 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1547 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001548 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001549 * \retval #PSA_ERROR_BAD_STATE
1550 * The library has not been previously initialized by psa_crypto_init().
1551 * It is implementation-dependent whether a failure to initialize
1552 * results in this error code.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001553 */
Gilles Peskine8c9def32018-02-08 10:02:12 +01001554psa_status_t psa_mac_abort(psa_mac_operation_t *operation);
1555
1556/**@}*/
1557
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001558/** \defgroup cipher Symmetric ciphers
1559 * @{
1560 */
1561
Gilles Peskine69647a42019-01-14 20:18:12 +01001562/** Encrypt a message using a symmetric cipher.
1563 *
1564 * This function encrypts a message with a random IV (initialization
1565 * vector).
1566 *
1567 * \param handle Handle to the key to use for the operation.
1568 * It must remain valid until the operation
1569 * terminates.
1570 * \param alg The cipher algorithm to compute
1571 * (\c PSA_ALG_XXX value such that
1572 * #PSA_ALG_IS_CIPHER(\p alg) is true).
1573 * \param[in] input Buffer containing the message to encrypt.
1574 * \param input_length Size of the \p input buffer in bytes.
1575 * \param[out] output Buffer where the output is to be written.
1576 * The output contains the IV followed by
1577 * the ciphertext proper.
1578 * \param output_size Size of the \p output buffer in bytes.
1579 * \param[out] output_length On success, the number of bytes
1580 * that make up the output.
1581 *
1582 * \retval #PSA_SUCCESS
1583 * Success.
1584 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine69647a42019-01-14 20:18:12 +01001585 * \retval #PSA_ERROR_NOT_PERMITTED
1586 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001587 * \p handle is not compatible with \p alg.
Gilles Peskine69647a42019-01-14 20:18:12 +01001588 * \retval #PSA_ERROR_NOT_SUPPORTED
1589 * \p alg is not supported or is not a cipher algorithm.
1590 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
1591 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1592 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1593 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001594 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001595 * \retval #PSA_ERROR_BAD_STATE
1596 * The library has not been previously initialized by psa_crypto_init().
1597 * It is implementation-dependent whether a failure to initialize
1598 * results in this error code.
Gilles Peskine69647a42019-01-14 20:18:12 +01001599 */
1600psa_status_t psa_cipher_encrypt(psa_key_handle_t handle,
1601 psa_algorithm_t alg,
1602 const uint8_t *input,
1603 size_t input_length,
1604 uint8_t *output,
1605 size_t output_size,
1606 size_t *output_length);
1607
1608/** Decrypt a message using a symmetric cipher.
1609 *
1610 * This function decrypts a message encrypted with a symmetric cipher.
1611 *
1612 * \param handle Handle to the key to use for the operation.
1613 * It must remain valid until the operation
1614 * terminates.
1615 * \param alg The cipher algorithm to compute
1616 * (\c PSA_ALG_XXX value such that
1617 * #PSA_ALG_IS_CIPHER(\p alg) is true).
1618 * \param[in] input Buffer containing the message to decrypt.
1619 * This consists of the IV followed by the
1620 * ciphertext proper.
1621 * \param input_length Size of the \p input buffer in bytes.
1622 * \param[out] output Buffer where the plaintext is to be written.
1623 * \param output_size Size of the \p output buffer in bytes.
1624 * \param[out] output_length On success, the number of bytes
1625 * that make up the output.
1626 *
1627 * \retval #PSA_SUCCESS
1628 * Success.
1629 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine69647a42019-01-14 20:18:12 +01001630 * \retval #PSA_ERROR_NOT_PERMITTED
1631 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001632 * \p handle is not compatible with \p alg.
Gilles Peskine69647a42019-01-14 20:18:12 +01001633 * \retval #PSA_ERROR_NOT_SUPPORTED
1634 * \p alg is not supported or is not a cipher algorithm.
1635 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
1636 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1637 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1638 * \retval #PSA_ERROR_HARDWARE_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001639 * \retval #PSA_ERROR_BAD_STATE
1640 * The library has not been previously initialized by psa_crypto_init().
1641 * It is implementation-dependent whether a failure to initialize
1642 * results in this error code. * \retval #PSA_ERROR_CORRUPTION_DETECTED
1643
Gilles Peskine69647a42019-01-14 20:18:12 +01001644 */
1645psa_status_t psa_cipher_decrypt(psa_key_handle_t handle,
1646 psa_algorithm_t alg,
1647 const uint8_t *input,
1648 size_t input_length,
1649 uint8_t *output,
1650 size_t output_size,
1651 size_t *output_length);
1652
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001653/** The type of the state data structure for multipart cipher operations.
1654 *
Jaeden Amero5bae2272019-01-04 11:48:27 +00001655 * Before calling any function on a cipher operation object, the application
1656 * must initialize it by any of the following means:
1657 * - Set the structure to all-bits-zero, for example:
1658 * \code
1659 * psa_cipher_operation_t operation;
1660 * memset(&operation, 0, sizeof(operation));
1661 * \endcode
1662 * - Initialize the structure to logical zero values, for example:
1663 * \code
1664 * psa_cipher_operation_t operation = {0};
1665 * \endcode
1666 * - Initialize the structure to the initializer #PSA_CIPHER_OPERATION_INIT,
1667 * for example:
1668 * \code
1669 * psa_cipher_operation_t operation = PSA_CIPHER_OPERATION_INIT;
1670 * \endcode
1671 * - Assign the result of the function psa_cipher_operation_init()
1672 * to the structure, for example:
1673 * \code
1674 * psa_cipher_operation_t operation;
1675 * operation = psa_cipher_operation_init();
1676 * \endcode
1677 *
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001678 * This is an implementation-defined \c struct. Applications should not
1679 * make any assumptions about the content of this structure except
1680 * as directed by the documentation of a specific implementation. */
1681typedef struct psa_cipher_operation_s psa_cipher_operation_t;
1682
Jaeden Amero5bae2272019-01-04 11:48:27 +00001683/** \def PSA_CIPHER_OPERATION_INIT
1684 *
1685 * This macro returns a suitable initializer for a cipher operation object of
1686 * type #psa_cipher_operation_t.
1687 */
1688#ifdef __DOXYGEN_ONLY__
1689/* This is an example definition for documentation purposes.
1690 * Implementations should define a suitable value in `crypto_struct.h`.
1691 */
1692#define PSA_CIPHER_OPERATION_INIT {0}
1693#endif
1694
1695/** Return an initial value for a cipher operation object.
1696 */
1697static psa_cipher_operation_t psa_cipher_operation_init(void);
1698
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001699/** Set the key for a multipart symmetric encryption operation.
1700 *
1701 * The sequence of operations to encrypt a message with a symmetric cipher
1702 * is as follows:
1703 * -# Allocate an operation object which will be passed to all the functions
1704 * listed here.
Jaeden Amero5bae2272019-01-04 11:48:27 +00001705 * -# Initialize the operation object with one of the methods described in the
1706 * documentation for #psa_cipher_operation_t, e.g.
1707 * PSA_CIPHER_OPERATION_INIT.
Gilles Peskinefe119512018-07-08 21:39:34 +02001708 * -# Call psa_cipher_encrypt_setup() to specify the algorithm and key.
itayzafrired7382f2018-08-02 14:19:33 +03001709 * -# Call either psa_cipher_generate_iv() or psa_cipher_set_iv() to
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001710 * generate or set the IV (initialization vector). You should use
itayzafrired7382f2018-08-02 14:19:33 +03001711 * psa_cipher_generate_iv() unless the protocol you are implementing
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001712 * requires a specific IV value.
1713 * -# Call psa_cipher_update() zero, one or more times, passing a fragment
1714 * of the message each time.
1715 * -# Call psa_cipher_finish().
1716 *
1717 * The application may call psa_cipher_abort() at any time after the operation
Jaeden Amero5bae2272019-01-04 11:48:27 +00001718 * has been initialized.
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001719 *
Gilles Peskinefe119512018-07-08 21:39:34 +02001720 * After a successful call to psa_cipher_encrypt_setup(), the application must
Gilles Peskineed522972018-03-20 17:54:15 +01001721 * eventually terminate the operation. The following events terminate an
1722 * operation:
Gilles Peskinef45adda2019-01-14 18:29:18 +01001723 * - A failed call to any of the \c psa_cipher_xxx functions.
Gilles Peskine19067982018-03-20 17:54:53 +01001724 * - A call to psa_cipher_finish() or psa_cipher_abort().
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001725 *
Jaeden Amero5bae2272019-01-04 11:48:27 +00001726 * \param[in,out] operation The operation object to set up. It must have
1727 * been initialized as per the documentation for
1728 * #psa_cipher_operation_t and not yet in use.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001729 * \param handle Handle to the key to use for the operation.
Gilles Peskine5f25dd02019-01-14 18:24:53 +01001730 * It must remain valid until the operation
1731 * terminates.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001732 * \param alg The cipher algorithm to compute
1733 * (\c PSA_ALG_XXX value such that
1734 * #PSA_ALG_IS_CIPHER(\p alg) is true).
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001735 *
Gilles Peskine28538492018-07-11 17:34:00 +02001736 * \retval #PSA_SUCCESS
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001737 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001738 * \retval #PSA_ERROR_INVALID_HANDLE
David Saadab4ecc272019-02-14 13:48:10 +02001739 * \retval #PSA_ERROR_DOES_NOT_EXIST
Gilles Peskine28538492018-07-11 17:34:00 +02001740 * \retval #PSA_ERROR_NOT_PERMITTED
1741 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001742 * \p handle is not compatible with \p alg.
Gilles Peskine28538492018-07-11 17:34:00 +02001743 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001744 * \p alg is not supported or is not a cipher algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02001745 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1746 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1747 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001748 * \retval #PSA_ERROR_CORRUPTION_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03001749 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskine8e1addc2019-01-10 11:51:17 +01001750 * The operation state is not valid (already set up and not
1751 * subsequently completed).
1752 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03001753 * The library has not been previously initialized by psa_crypto_init().
1754 * It is implementation-dependent whether a failure to initialize
1755 * results in this error code.
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001756 */
Gilles Peskinefe119512018-07-08 21:39:34 +02001757psa_status_t psa_cipher_encrypt_setup(psa_cipher_operation_t *operation,
Gilles Peskineae32aac2018-11-30 14:39:32 +01001758 psa_key_handle_t handle,
Gilles Peskinefe119512018-07-08 21:39:34 +02001759 psa_algorithm_t alg);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001760
1761/** Set the key for a multipart symmetric decryption operation.
1762 *
1763 * The sequence of operations to decrypt a message with a symmetric cipher
1764 * is as follows:
1765 * -# Allocate an operation object which will be passed to all the functions
1766 * listed here.
Jaeden Amero5bae2272019-01-04 11:48:27 +00001767 * -# Initialize the operation object with one of the methods described in the
1768 * documentation for #psa_cipher_operation_t, e.g.
1769 * PSA_CIPHER_OPERATION_INIT.
Gilles Peskinefe119512018-07-08 21:39:34 +02001770 * -# Call psa_cipher_decrypt_setup() to specify the algorithm and key.
Gilles Peskinef45adda2019-01-14 18:29:18 +01001771 * -# Call psa_cipher_set_iv() with the IV (initialization vector) for the
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001772 * decryption. If the IV is prepended to the ciphertext, you can call
1773 * psa_cipher_update() on a buffer containing the IV followed by the
1774 * beginning of the message.
1775 * -# Call psa_cipher_update() zero, one or more times, passing a fragment
1776 * of the message each time.
1777 * -# Call psa_cipher_finish().
1778 *
1779 * The application may call psa_cipher_abort() at any time after the operation
Jaeden Amero5bae2272019-01-04 11:48:27 +00001780 * has been initialized.
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001781 *
Gilles Peskinefe119512018-07-08 21:39:34 +02001782 * After a successful call to psa_cipher_decrypt_setup(), the application must
Gilles Peskineed522972018-03-20 17:54:15 +01001783 * eventually terminate the operation. The following events terminate an
1784 * operation:
Gilles Peskinef45adda2019-01-14 18:29:18 +01001785 * - A failed call to any of the \c psa_cipher_xxx functions.
Gilles Peskine19067982018-03-20 17:54:53 +01001786 * - A call to psa_cipher_finish() or psa_cipher_abort().
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001787 *
Jaeden Amero5bae2272019-01-04 11:48:27 +00001788 * \param[in,out] operation The operation object to set up. It must have
1789 * been initialized as per the documentation for
1790 * #psa_cipher_operation_t and not yet in use.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001791 * \param handle Handle to the key to use for the operation.
Gilles Peskine5f25dd02019-01-14 18:24:53 +01001792 * It must remain valid until the operation
1793 * terminates.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001794 * \param alg The cipher algorithm to compute
1795 * (\c PSA_ALG_XXX value such that
1796 * #PSA_ALG_IS_CIPHER(\p alg) is true).
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001797 *
Gilles Peskine28538492018-07-11 17:34:00 +02001798 * \retval #PSA_SUCCESS
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001799 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001800 * \retval #PSA_ERROR_INVALID_HANDLE
David Saadab4ecc272019-02-14 13:48:10 +02001801 * \retval #PSA_ERROR_DOES_NOT_EXIST
Gilles Peskine28538492018-07-11 17:34:00 +02001802 * \retval #PSA_ERROR_NOT_PERMITTED
1803 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001804 * \p handle is not compatible with \p alg.
Gilles Peskine28538492018-07-11 17:34:00 +02001805 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001806 * \p alg is not supported or is not a cipher algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02001807 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1808 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1809 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001810 * \retval #PSA_ERROR_CORRUPTION_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03001811 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskine8e1addc2019-01-10 11:51:17 +01001812 * The operation state is not valid (already set up and not
1813 * subsequently completed).
1814 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03001815 * The library has not been previously initialized by psa_crypto_init().
1816 * It is implementation-dependent whether a failure to initialize
1817 * results in this error code.
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001818 */
Gilles Peskinefe119512018-07-08 21:39:34 +02001819psa_status_t psa_cipher_decrypt_setup(psa_cipher_operation_t *operation,
Gilles Peskineae32aac2018-11-30 14:39:32 +01001820 psa_key_handle_t handle,
Gilles Peskinefe119512018-07-08 21:39:34 +02001821 psa_algorithm_t alg);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001822
Gilles Peskinedcd14942018-07-12 00:30:52 +02001823/** Generate an IV for a symmetric encryption operation.
1824 *
1825 * This function generates a random IV (initialization vector), nonce
1826 * or initial counter value for the encryption operation as appropriate
1827 * for the chosen algorithm, key type and key size.
1828 *
1829 * The application must call psa_cipher_encrypt_setup() before
1830 * calling this function.
1831 *
1832 * If this function returns an error status, the operation becomes inactive.
1833 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001834 * \param[in,out] operation Active cipher operation.
1835 * \param[out] iv Buffer where the generated IV is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001836 * \param iv_size Size of the \p iv buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001837 * \param[out] iv_length On success, the number of bytes of the
1838 * generated IV.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001839 *
1840 * \retval #PSA_SUCCESS
1841 * Success.
1842 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001843 * The operation state is not valid (not set up, or IV already set).
Gilles Peskinedcd14942018-07-12 00:30:52 +02001844 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinedda3bd32018-07-12 19:40:46 +02001845 * The size of the \p iv buffer is too small.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001846 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1847 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1848 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001849 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001850 * \retval #PSA_ERROR_BAD_STATE
1851 * The library has not been previously initialized by psa_crypto_init().
1852 * It is implementation-dependent whether a failure to initialize
1853 * results in this error code.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001854 */
Gilles Peskinefe119512018-07-08 21:39:34 +02001855psa_status_t psa_cipher_generate_iv(psa_cipher_operation_t *operation,
Andrew Thoelke47629d02019-03-22 11:24:17 +00001856 uint8_t *iv,
Gilles Peskinefe119512018-07-08 21:39:34 +02001857 size_t iv_size,
1858 size_t *iv_length);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001859
Gilles Peskinedcd14942018-07-12 00:30:52 +02001860/** Set the IV for a symmetric encryption or decryption operation.
1861 *
Gilles Peskinef45adda2019-01-14 18:29:18 +01001862 * This function sets the IV (initialization vector), nonce
Gilles Peskinedcd14942018-07-12 00:30:52 +02001863 * or initial counter value for the encryption or decryption operation.
1864 *
1865 * The application must call psa_cipher_encrypt_setup() before
1866 * calling this function.
1867 *
1868 * If this function returns an error status, the operation becomes inactive.
1869 *
1870 * \note When encrypting, applications should use psa_cipher_generate_iv()
1871 * instead of this function, unless implementing a protocol that requires
1872 * a non-random IV.
1873 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001874 * \param[in,out] operation Active cipher operation.
1875 * \param[in] iv Buffer containing the IV to use.
1876 * \param iv_length Size of the IV in bytes.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001877 *
1878 * \retval #PSA_SUCCESS
1879 * Success.
1880 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001881 * The operation state is not valid (not set up, or IV already set).
Gilles Peskinedcd14942018-07-12 00:30:52 +02001882 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001883 * The size of \p iv is not acceptable for the chosen algorithm,
Gilles Peskinedcd14942018-07-12 00:30:52 +02001884 * or the chosen algorithm does not use an IV.
1885 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1886 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1887 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001888 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001889 * \retval #PSA_ERROR_BAD_STATE
1890 * The library has not been previously initialized by psa_crypto_init().
1891 * It is implementation-dependent whether a failure to initialize
1892 * results in this error code.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001893 */
Gilles Peskinefe119512018-07-08 21:39:34 +02001894psa_status_t psa_cipher_set_iv(psa_cipher_operation_t *operation,
Andrew Thoelke47629d02019-03-22 11:24:17 +00001895 const uint8_t *iv,
Gilles Peskinefe119512018-07-08 21:39:34 +02001896 size_t iv_length);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001897
Gilles Peskinedcd14942018-07-12 00:30:52 +02001898/** Encrypt or decrypt a message fragment in an active cipher operation.
1899 *
Gilles Peskine9ac94262018-07-12 20:15:32 +02001900 * Before calling this function, you must:
1901 * 1. Call either psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup().
1902 * The choice of setup function determines whether this function
1903 * encrypts or decrypts its input.
1904 * 2. If the algorithm requires an IV, call psa_cipher_generate_iv()
1905 * (recommended when encrypting) or psa_cipher_set_iv().
Gilles Peskinedcd14942018-07-12 00:30:52 +02001906 *
1907 * If this function returns an error status, the operation becomes inactive.
1908 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001909 * \param[in,out] operation Active cipher operation.
1910 * \param[in] input Buffer containing the message fragment to
1911 * encrypt or decrypt.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001912 * \param input_length Size of the \p input buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001913 * \param[out] output Buffer where the output is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001914 * \param output_size Size of the \p output buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001915 * \param[out] output_length On success, the number of bytes
1916 * that make up the returned output.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001917 *
1918 * \retval #PSA_SUCCESS
1919 * Success.
1920 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001921 * The operation state is not valid (not set up, IV required but
Gilles Peskinedcd14942018-07-12 00:30:52 +02001922 * not set, or already completed).
1923 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
1924 * The size of the \p output buffer is too small.
1925 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1926 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1927 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001928 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001929 * \retval #PSA_ERROR_BAD_STATE
1930 * The library has not been previously initialized by psa_crypto_init().
1931 * It is implementation-dependent whether a failure to initialize
1932 * results in this error code.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001933 */
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001934psa_status_t psa_cipher_update(psa_cipher_operation_t *operation,
1935 const uint8_t *input,
mohammad1603503973b2018-03-12 15:59:30 +02001936 size_t input_length,
Andrew Thoelke47629d02019-03-22 11:24:17 +00001937 uint8_t *output,
Gilles Peskine2d277862018-06-18 15:41:12 +02001938 size_t output_size,
mohammad1603503973b2018-03-12 15:59:30 +02001939 size_t *output_length);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001940
Gilles Peskinedcd14942018-07-12 00:30:52 +02001941/** Finish encrypting or decrypting a message in a cipher operation.
1942 *
1943 * The application must call psa_cipher_encrypt_setup() or
1944 * psa_cipher_decrypt_setup() before calling this function. The choice
1945 * of setup function determines whether this function encrypts or
1946 * decrypts its input.
1947 *
1948 * This function finishes the encryption or decryption of the message
1949 * formed by concatenating the inputs passed to preceding calls to
1950 * psa_cipher_update().
1951 *
1952 * When this function returns, the operation becomes inactive.
1953 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001954 * \param[in,out] operation Active cipher operation.
1955 * \param[out] output Buffer where the output is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001956 * \param output_size Size of the \p output buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001957 * \param[out] output_length On success, the number of bytes
1958 * that make up the returned output.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001959 *
1960 * \retval #PSA_SUCCESS
1961 * Success.
1962 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001963 * The operation state is not valid (not set up, IV required but
Gilles Peskinedcd14942018-07-12 00:30:52 +02001964 * not set, or already completed).
1965 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
1966 * The size of the \p output buffer is too small.
1967 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1968 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1969 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001970 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001971 * \retval #PSA_ERROR_BAD_STATE
1972 * The library has not been previously initialized by psa_crypto_init().
1973 * It is implementation-dependent whether a failure to initialize
1974 * results in this error code.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001975 */
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001976psa_status_t psa_cipher_finish(psa_cipher_operation_t *operation,
mohammad1603503973b2018-03-12 15:59:30 +02001977 uint8_t *output,
Moran Peker0071b872018-04-22 20:16:58 +03001978 size_t output_size,
mohammad1603503973b2018-03-12 15:59:30 +02001979 size_t *output_length);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001980
Gilles Peskinedcd14942018-07-12 00:30:52 +02001981/** Abort a cipher operation.
1982 *
Gilles Peskinedcd14942018-07-12 00:30:52 +02001983 * Aborting an operation frees all associated resources except for the
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001984 * \p operation structure itself. Once aborted, the operation object
1985 * can be reused for another operation by calling
1986 * psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup() again.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001987 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001988 * You may call this function any time after the operation object has
1989 * been initialized by any of the following methods:
1990 * - A call to psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup(),
1991 * whether it succeeds or not.
1992 * - Initializing the \c struct to all-bits-zero.
1993 * - Initializing the \c struct to logical zeros, e.g.
1994 * `psa_cipher_operation_t operation = {0}`.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001995 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001996 * In particular, calling psa_cipher_abort() after the operation has been
1997 * terminated by a call to psa_cipher_abort() or psa_cipher_finish()
1998 * is safe and has no effect.
1999 *
2000 * \param[in,out] operation Initialized cipher operation.
Gilles Peskinedcd14942018-07-12 00:30:52 +02002001 *
2002 * \retval #PSA_SUCCESS
2003 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002004 * \p operation is not an active cipher operation.
Gilles Peskinedcd14942018-07-12 00:30:52 +02002005 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2006 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002007 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01002008 * \retval #PSA_ERROR_BAD_STATE
2009 * The library has not been previously initialized by psa_crypto_init().
2010 * It is implementation-dependent whether a failure to initialize
2011 * results in this error code.
Gilles Peskinedcd14942018-07-12 00:30:52 +02002012 */
Gilles Peskine428dc5a2018-03-03 21:27:18 +01002013psa_status_t psa_cipher_abort(psa_cipher_operation_t *operation);
2014
2015/**@}*/
2016
Gilles Peskine3b555712018-03-03 21:27:57 +01002017/** \defgroup aead Authenticated encryption with associated data (AEAD)
2018 * @{
2019 */
2020
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002021/** Process an authenticated encryption operation.
Gilles Peskine3b555712018-03-03 21:27:57 +01002022 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01002023 * \param handle Handle to the key to use for the operation.
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002024 * \param alg The AEAD algorithm to compute
2025 * (\c PSA_ALG_XXX value such that
Gilles Peskine7256e6c2018-07-12 00:34:26 +02002026 * #PSA_ALG_IS_AEAD(\p alg) is true).
Gilles Peskineedd11a12018-07-12 01:08:58 +02002027 * \param[in] nonce Nonce or IV to use.
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002028 * \param nonce_length Size of the \p nonce buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002029 * \param[in] additional_data Additional data that will be authenticated
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002030 * but not encrypted.
2031 * \param additional_data_length Size of \p additional_data in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002032 * \param[in] plaintext Data that will be authenticated and
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002033 * encrypted.
2034 * \param plaintext_length Size of \p plaintext in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002035 * \param[out] ciphertext Output buffer for the authenticated and
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002036 * encrypted data. The additional data is not
2037 * part of this output. For algorithms where the
2038 * encrypted data and the authentication tag
2039 * are defined as separate outputs, the
2040 * authentication tag is appended to the
2041 * encrypted data.
2042 * \param ciphertext_size Size of the \p ciphertext buffer in bytes.
2043 * This must be at least
2044 * #PSA_AEAD_ENCRYPT_OUTPUT_SIZE(\p alg,
2045 * \p plaintext_length).
Gilles Peskineedd11a12018-07-12 01:08:58 +02002046 * \param[out] ciphertext_length On success, the size of the output
Gilles Peskine4c6fdbb2019-02-08 11:22:39 +01002047 * in the \p ciphertext buffer.
Gilles Peskine3b555712018-03-03 21:27:57 +01002048 *
Gilles Peskine28538492018-07-11 17:34:00 +02002049 * \retval #PSA_SUCCESS
Gilles Peskine3b555712018-03-03 21:27:57 +01002050 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01002051 * \retval #PSA_ERROR_INVALID_HANDLE
David Saadab4ecc272019-02-14 13:48:10 +02002052 * \retval #PSA_ERROR_DOES_NOT_EXIST
Gilles Peskine28538492018-07-11 17:34:00 +02002053 * \retval #PSA_ERROR_NOT_PERMITTED
2054 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002055 * \p handle is not compatible with \p alg.
Gilles Peskine28538492018-07-11 17:34:00 +02002056 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002057 * \p alg is not supported or is not an AEAD algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02002058 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2059 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2060 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002061 * \retval #PSA_ERROR_CORRUPTION_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03002062 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03002063 * The library has not been previously initialized by psa_crypto_init().
2064 * It is implementation-dependent whether a failure to initialize
2065 * results in this error code.
Gilles Peskine3b555712018-03-03 21:27:57 +01002066 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01002067psa_status_t psa_aead_encrypt(psa_key_handle_t handle,
Gilles Peskine9fb0e012018-07-19 15:51:49 +02002068 psa_algorithm_t alg,
2069 const uint8_t *nonce,
2070 size_t nonce_length,
2071 const uint8_t *additional_data,
2072 size_t additional_data_length,
2073 const uint8_t *plaintext,
2074 size_t plaintext_length,
2075 uint8_t *ciphertext,
2076 size_t ciphertext_size,
2077 size_t *ciphertext_length);
Gilles Peskine3b555712018-03-03 21:27:57 +01002078
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002079/** Process an authenticated decryption operation.
Gilles Peskine3b555712018-03-03 21:27:57 +01002080 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01002081 * \param handle Handle to the key to use for the operation.
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002082 * \param alg The AEAD algorithm to compute
2083 * (\c PSA_ALG_XXX value such that
Gilles Peskine7256e6c2018-07-12 00:34:26 +02002084 * #PSA_ALG_IS_AEAD(\p alg) is true).
Gilles Peskineedd11a12018-07-12 01:08:58 +02002085 * \param[in] nonce Nonce or IV to use.
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002086 * \param nonce_length Size of the \p nonce buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002087 * \param[in] additional_data Additional data that has been authenticated
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002088 * but not encrypted.
2089 * \param additional_data_length Size of \p additional_data in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002090 * \param[in] ciphertext Data that has been authenticated and
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002091 * encrypted. For algorithms where the
2092 * encrypted data and the authentication tag
2093 * are defined as separate inputs, the buffer
2094 * must contain the encrypted data followed
2095 * by the authentication tag.
2096 * \param ciphertext_length Size of \p ciphertext in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002097 * \param[out] plaintext Output buffer for the decrypted data.
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002098 * \param plaintext_size Size of the \p plaintext buffer in bytes.
2099 * This must be at least
2100 * #PSA_AEAD_DECRYPT_OUTPUT_SIZE(\p alg,
2101 * \p ciphertext_length).
Gilles Peskineedd11a12018-07-12 01:08:58 +02002102 * \param[out] plaintext_length On success, the size of the output
Gilles Peskine4c6fdbb2019-02-08 11:22:39 +01002103 * in the \p plaintext buffer.
Gilles Peskine3b555712018-03-03 21:27:57 +01002104 *
Gilles Peskine28538492018-07-11 17:34:00 +02002105 * \retval #PSA_SUCCESS
Gilles Peskine3b555712018-03-03 21:27:57 +01002106 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01002107 * \retval #PSA_ERROR_INVALID_HANDLE
David Saadab4ecc272019-02-14 13:48:10 +02002108 * \retval #PSA_ERROR_DOES_NOT_EXIST
Gilles Peskine28538492018-07-11 17:34:00 +02002109 * \retval #PSA_ERROR_INVALID_SIGNATURE
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002110 * The ciphertext is not authentic.
Gilles Peskine28538492018-07-11 17:34:00 +02002111 * \retval #PSA_ERROR_NOT_PERMITTED
2112 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002113 * \p handle is not compatible with \p alg.
Gilles Peskine28538492018-07-11 17:34:00 +02002114 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002115 * \p alg is not supported or is not an AEAD algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02002116 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2117 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2118 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002119 * \retval #PSA_ERROR_CORRUPTION_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03002120 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03002121 * The library has not been previously initialized by psa_crypto_init().
2122 * It is implementation-dependent whether a failure to initialize
2123 * results in this error code.
Gilles Peskine3b555712018-03-03 21:27:57 +01002124 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01002125psa_status_t psa_aead_decrypt(psa_key_handle_t handle,
Gilles Peskine9fb0e012018-07-19 15:51:49 +02002126 psa_algorithm_t alg,
2127 const uint8_t *nonce,
2128 size_t nonce_length,
2129 const uint8_t *additional_data,
2130 size_t additional_data_length,
2131 const uint8_t *ciphertext,
2132 size_t ciphertext_length,
2133 uint8_t *plaintext,
2134 size_t plaintext_size,
2135 size_t *plaintext_length);
Gilles Peskine3b555712018-03-03 21:27:57 +01002136
Gilles Peskine30a9e412019-01-14 18:36:12 +01002137/** The type of the state data structure for multipart AEAD operations.
2138 *
2139 * Before calling any function on an AEAD operation object, the application
2140 * must initialize it by any of the following means:
2141 * - Set the structure to all-bits-zero, for example:
2142 * \code
2143 * psa_aead_operation_t operation;
2144 * memset(&operation, 0, sizeof(operation));
2145 * \endcode
2146 * - Initialize the structure to logical zero values, for example:
2147 * \code
2148 * psa_aead_operation_t operation = {0};
2149 * \endcode
2150 * - Initialize the structure to the initializer #PSA_AEAD_OPERATION_INIT,
2151 * for example:
2152 * \code
2153 * psa_aead_operation_t operation = PSA_AEAD_OPERATION_INIT;
2154 * \endcode
2155 * - Assign the result of the function psa_aead_operation_init()
2156 * to the structure, for example:
2157 * \code
2158 * psa_aead_operation_t operation;
2159 * operation = psa_aead_operation_init();
2160 * \endcode
2161 *
2162 * This is an implementation-defined \c struct. Applications should not
2163 * make any assumptions about the content of this structure except
2164 * as directed by the documentation of a specific implementation. */
2165typedef struct psa_aead_operation_s psa_aead_operation_t;
2166
2167/** \def PSA_AEAD_OPERATION_INIT
2168 *
2169 * This macro returns a suitable initializer for an AEAD operation object of
2170 * type #psa_aead_operation_t.
2171 */
2172#ifdef __DOXYGEN_ONLY__
2173/* This is an example definition for documentation purposes.
2174 * Implementations should define a suitable value in `crypto_struct.h`.
2175 */
2176#define PSA_AEAD_OPERATION_INIT {0}
2177#endif
2178
2179/** Return an initial value for an AEAD operation object.
2180 */
2181static psa_aead_operation_t psa_aead_operation_init(void);
2182
2183/** Set the key for a multipart authenticated encryption operation.
2184 *
2185 * The sequence of operations to encrypt a message with authentication
2186 * is as follows:
2187 * -# Allocate an operation object which will be passed to all the functions
2188 * listed here.
2189 * -# Initialize the operation object with one of the methods described in the
2190 * documentation for #psa_aead_operation_t, e.g.
2191 * PSA_AEAD_OPERATION_INIT.
2192 * -# Call psa_aead_encrypt_setup() to specify the algorithm and key.
Gilles Peskinebc59c852019-01-17 15:26:08 +01002193 * -# If needed, call psa_aead_set_lengths() to specify the length of the
2194 * inputs to the subsequent calls to psa_aead_update_ad() and
2195 * psa_aead_update(). See the documentation of psa_aead_set_lengths()
2196 * for details.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002197 * -# Call either psa_aead_generate_nonce() or psa_aead_set_nonce() to
2198 * generate or set the nonce. You should use
2199 * psa_aead_generate_nonce() unless the protocol you are implementing
2200 * requires a specific nonce value.
2201 * -# Call psa_aead_update_ad() zero, one or more times, passing a fragment
2202 * of the non-encrypted additional authenticated data each time.
2203 * -# Call psa_aead_update() zero, one or more times, passing a fragment
Gilles Peskinea05602d2019-01-17 15:25:52 +01002204 * of the message to encrypt each time.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002205 * -# Call psa_aead_finish().
2206 *
2207 * The application may call psa_aead_abort() at any time after the operation
2208 * has been initialized.
2209 *
2210 * After a successful call to psa_aead_encrypt_setup(), the application must
2211 * eventually terminate the operation. The following events terminate an
2212 * operation:
2213 * - A failed call to any of the \c psa_aead_xxx functions.
2214 * - A call to psa_aead_finish(), psa_aead_verify() or psa_aead_abort().
2215 *
2216 * \param[in,out] operation The operation object to set up. It must have
2217 * been initialized as per the documentation for
2218 * #psa_aead_operation_t and not yet in use.
2219 * \param handle Handle to the key to use for the operation.
2220 * It must remain valid until the operation
2221 * terminates.
2222 * \param alg The AEAD algorithm to compute
2223 * (\c PSA_ALG_XXX value such that
2224 * #PSA_ALG_IS_AEAD(\p alg) is true).
2225 *
2226 * \retval #PSA_SUCCESS
2227 * Success.
2228 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine30a9e412019-01-14 18:36:12 +01002229 * \retval #PSA_ERROR_NOT_PERMITTED
2230 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002231 * \p handle is not compatible with \p alg.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002232 * \retval #PSA_ERROR_NOT_SUPPORTED
2233 * \p alg is not supported or is not an AEAD algorithm.
2234 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2235 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2236 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002237 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine30a9e412019-01-14 18:36:12 +01002238 * \retval #PSA_ERROR_BAD_STATE
2239 * The library has not been previously initialized by psa_crypto_init().
2240 * It is implementation-dependent whether a failure to initialize
2241 * results in this error code.
2242 */
2243psa_status_t psa_aead_encrypt_setup(psa_aead_operation_t *operation,
2244 psa_key_handle_t handle,
2245 psa_algorithm_t alg);
2246
2247/** Set the key for a multipart authenticated decryption operation.
2248 *
2249 * The sequence of operations to decrypt a message with authentication
2250 * is as follows:
2251 * -# Allocate an operation object which will be passed to all the functions
2252 * listed here.
2253 * -# Initialize the operation object with one of the methods described in the
2254 * documentation for #psa_aead_operation_t, e.g.
2255 * PSA_AEAD_OPERATION_INIT.
2256 * -# Call psa_aead_decrypt_setup() to specify the algorithm and key.
Gilles Peskinebc59c852019-01-17 15:26:08 +01002257 * -# If needed, call psa_aead_set_lengths() to specify the length of the
2258 * inputs to the subsequent calls to psa_aead_update_ad() and
2259 * psa_aead_update(). See the documentation of psa_aead_set_lengths()
2260 * for details.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002261 * -# Call psa_aead_set_nonce() with the nonce for the decryption.
2262 * -# Call psa_aead_update_ad() zero, one or more times, passing a fragment
2263 * of the non-encrypted additional authenticated data each time.
2264 * -# Call psa_aead_update() zero, one or more times, passing a fragment
Gilles Peskinea05602d2019-01-17 15:25:52 +01002265 * of the ciphertext to decrypt each time.
2266 * -# Call psa_aead_verify().
Gilles Peskine30a9e412019-01-14 18:36:12 +01002267 *
2268 * The application may call psa_aead_abort() at any time after the operation
2269 * has been initialized.
2270 *
2271 * After a successful call to psa_aead_decrypt_setup(), the application must
2272 * eventually terminate the operation. The following events terminate an
2273 * operation:
2274 * - A failed call to any of the \c psa_aead_xxx functions.
2275 * - A call to psa_aead_finish(), psa_aead_verify() or psa_aead_abort().
2276 *
2277 * \param[in,out] operation The operation object to set up. It must have
2278 * been initialized as per the documentation for
2279 * #psa_aead_operation_t and not yet in use.
2280 * \param handle Handle to the key to use for the operation.
2281 * It must remain valid until the operation
2282 * terminates.
2283 * \param alg The AEAD algorithm to compute
2284 * (\c PSA_ALG_XXX value such that
2285 * #PSA_ALG_IS_AEAD(\p alg) is true).
2286 *
2287 * \retval #PSA_SUCCESS
2288 * Success.
2289 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine30a9e412019-01-14 18:36:12 +01002290 * \retval #PSA_ERROR_NOT_PERMITTED
2291 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002292 * \p handle is not compatible with \p alg.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002293 * \retval #PSA_ERROR_NOT_SUPPORTED
2294 * \p alg is not supported or is not an AEAD algorithm.
2295 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2296 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2297 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002298 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine30a9e412019-01-14 18:36:12 +01002299 * \retval #PSA_ERROR_BAD_STATE
2300 * The library has not been previously initialized by psa_crypto_init().
2301 * It is implementation-dependent whether a failure to initialize
2302 * results in this error code.
2303 */
2304psa_status_t psa_aead_decrypt_setup(psa_aead_operation_t *operation,
2305 psa_key_handle_t handle,
2306 psa_algorithm_t alg);
2307
2308/** Generate a random nonce for an authenticated encryption operation.
2309 *
2310 * This function generates a random nonce for the authenticated encryption
2311 * operation with an appropriate size for the chosen algorithm, key type
2312 * and key size.
2313 *
2314 * The application must call psa_aead_encrypt_setup() before
2315 * calling this function.
2316 *
2317 * If this function returns an error status, the operation becomes inactive.
2318 *
2319 * \param[in,out] operation Active AEAD operation.
2320 * \param[out] nonce Buffer where the generated nonce is to be
2321 * written.
2322 * \param nonce_size Size of the \p nonce buffer in bytes.
2323 * \param[out] nonce_length On success, the number of bytes of the
2324 * generated nonce.
2325 *
2326 * \retval #PSA_SUCCESS
2327 * Success.
2328 * \retval #PSA_ERROR_BAD_STATE
2329 * The operation state is not valid (not set up, or nonce already set).
2330 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
2331 * The size of the \p nonce buffer is too small.
2332 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2333 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2334 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002335 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01002336 * \retval #PSA_ERROR_BAD_STATE
2337 * The library has not been previously initialized by psa_crypto_init().
2338 * It is implementation-dependent whether a failure to initialize
2339 * results in this error code.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002340 */
2341psa_status_t psa_aead_generate_nonce(psa_aead_operation_t *operation,
Andrew Thoelked16bdac2019-05-15 12:34:01 +01002342 uint8_t *nonce,
Gilles Peskine30a9e412019-01-14 18:36:12 +01002343 size_t nonce_size,
2344 size_t *nonce_length);
2345
2346/** Set the nonce for an authenticated encryption or decryption operation.
2347 *
2348 * This function sets the nonce for the authenticated
2349 * encryption or decryption operation.
2350 *
2351 * The application must call psa_aead_encrypt_setup() before
2352 * calling this function.
2353 *
2354 * If this function returns an error status, the operation becomes inactive.
2355 *
Gilles Peskinea05602d2019-01-17 15:25:52 +01002356 * \note When encrypting, applications should use psa_aead_generate_nonce()
Gilles Peskine30a9e412019-01-14 18:36:12 +01002357 * instead of this function, unless implementing a protocol that requires
2358 * a non-random IV.
2359 *
2360 * \param[in,out] operation Active AEAD operation.
Gilles Peskinea05602d2019-01-17 15:25:52 +01002361 * \param[in] nonce Buffer containing the nonce to use.
2362 * \param nonce_length Size of the nonce in bytes.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002363 *
2364 * \retval #PSA_SUCCESS
2365 * Success.
2366 * \retval #PSA_ERROR_BAD_STATE
2367 * The operation state is not valid (not set up, or nonce already set).
2368 * \retval #PSA_ERROR_INVALID_ARGUMENT
2369 * The size of \p nonce is not acceptable for the chosen algorithm.
2370 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2371 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2372 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002373 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01002374 * \retval #PSA_ERROR_BAD_STATE
2375 * The library has not been previously initialized by psa_crypto_init().
2376 * It is implementation-dependent whether a failure to initialize
2377 * results in this error code.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002378 */
2379psa_status_t psa_aead_set_nonce(psa_aead_operation_t *operation,
Andrew Thoelked16bdac2019-05-15 12:34:01 +01002380 const uint8_t *nonce,
Gilles Peskine30a9e412019-01-14 18:36:12 +01002381 size_t nonce_length);
2382
Gilles Peskinebc59c852019-01-17 15:26:08 +01002383/** Declare the lengths of the message and additional data for AEAD.
2384 *
2385 * The application must call this function before calling
2386 * psa_aead_update_ad() or psa_aead_update() if the algorithm for
2387 * the operation requires it. If the algorithm does not require it,
2388 * calling this function is optional, but if this function is called
2389 * then the implementation must enforce the lengths.
2390 *
2391 * You may call this function before or after setting the nonce with
2392 * psa_aead_set_nonce() or psa_aead_generate_nonce().
2393 *
2394 * - For #PSA_ALG_CCM, calling this function is required.
2395 * - For the other AEAD algorithms defined in this specification, calling
2396 * this function is not required.
2397 * - For vendor-defined algorithm, refer to the vendor documentation.
2398 *
2399 * \param[in,out] operation Active AEAD operation.
2400 * \param ad_length Size of the non-encrypted additional
2401 * authenticated data in bytes.
2402 * \param plaintext_length Size of the plaintext to encrypt in bytes.
2403 *
2404 * \retval #PSA_SUCCESS
2405 * Success.
2406 * \retval #PSA_ERROR_BAD_STATE
2407 * The operation state is not valid (not set up, already completed,
2408 * or psa_aead_update_ad() or psa_aead_update() already called).
2409 * \retval #PSA_ERROR_INVALID_ARGUMENT
2410 * At least one of the lengths is not acceptable for the chosen
2411 * algorithm.
2412 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2413 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2414 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002415 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01002416 * \retval #PSA_ERROR_BAD_STATE
2417 * The library has not been previously initialized by psa_crypto_init().
2418 * It is implementation-dependent whether a failure to initialize
2419 * results in this error code.
Gilles Peskinebc59c852019-01-17 15:26:08 +01002420 */
2421psa_status_t psa_aead_set_lengths(psa_aead_operation_t *operation,
2422 size_t ad_length,
2423 size_t plaintext_length);
2424
Gilles Peskine30a9e412019-01-14 18:36:12 +01002425/** Pass additional data to an active AEAD operation.
2426 *
2427 * Additional data is authenticated, but not encrypted.
2428 *
2429 * You may call this function multiple times to pass successive fragments
2430 * of the additional data. You may not call this function after passing
2431 * data to encrypt or decrypt with psa_aead_update().
2432 *
2433 * Before calling this function, you must:
2434 * 1. Call either psa_aead_encrypt_setup() or psa_aead_decrypt_setup().
2435 * 2. Set the nonce with psa_aead_generate_nonce() or psa_aead_set_nonce().
2436 *
2437 * If this function returns an error status, the operation becomes inactive.
2438 *
2439 * \warning When decrypting, until psa_aead_verify() has returned #PSA_SUCCESS,
2440 * there is no guarantee that the input is valid. Therefore, until
2441 * you have called psa_aead_verify() and it has returned #PSA_SUCCESS,
2442 * treat the input as untrusted and prepare to undo any action that
2443 * depends on the input if psa_aead_verify() returns an error status.
2444 *
2445 * \param[in,out] operation Active AEAD operation.
2446 * \param[in] input Buffer containing the fragment of
2447 * additional data.
2448 * \param input_length Size of the \p input buffer in bytes.
2449 *
2450 * \retval #PSA_SUCCESS
2451 * Success.
2452 * \retval #PSA_ERROR_BAD_STATE
2453 * The operation state is not valid (not set up, nonce not set,
2454 * psa_aead_update() already called, or operation already completed).
Gilles Peskinebc59c852019-01-17 15:26:08 +01002455 * \retval #PSA_ERROR_INVALID_ARGUMENT
2456 * The total input length overflows the additional data length that
2457 * was previously specified with psa_aead_set_lengths().
Gilles Peskine30a9e412019-01-14 18:36:12 +01002458 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2459 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2460 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002461 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01002462 * \retval #PSA_ERROR_BAD_STATE
2463 * The library has not been previously initialized by psa_crypto_init().
2464 * It is implementation-dependent whether a failure to initialize
2465 * results in this error code.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002466 */
2467psa_status_t psa_aead_update_ad(psa_aead_operation_t *operation,
2468 const uint8_t *input,
2469 size_t input_length);
2470
2471/** Encrypt or decrypt a message fragment in an active AEAD operation.
2472 *
2473 * Before calling this function, you must:
2474 * 1. Call either psa_aead_encrypt_setup() or psa_aead_decrypt_setup().
2475 * The choice of setup function determines whether this function
2476 * encrypts or decrypts its input.
2477 * 2. Set the nonce with psa_aead_generate_nonce() or psa_aead_set_nonce().
2478 * 3. Call psa_aead_update_ad() to pass all the additional data.
2479 *
2480 * If this function returns an error status, the operation becomes inactive.
2481 *
2482 * \warning When decrypting, until psa_aead_verify() has returned #PSA_SUCCESS,
2483 * there is no guarantee that the input is valid. Therefore, until
2484 * you have called psa_aead_verify() and it has returned #PSA_SUCCESS:
2485 * - Do not use the output in any way other than storing it in a
2486 * confidential location. If you take any action that depends
2487 * on the tentative decrypted data, this action will need to be
2488 * undone if the input turns out not to be valid. Furthermore,
2489 * if an adversary can observe that this action took place
2490 * (for example through timing), they may be able to use this
2491 * fact as an oracle to decrypt any message encrypted with the
2492 * same key.
2493 * - In particular, do not copy the output anywhere but to a
2494 * memory or storage space that you have exclusive access to.
2495 *
Gilles Peskinef02aec92019-05-06 15:42:54 +02002496 * This function does not require the input to be aligned to any
2497 * particular block boundary. If the implementation can only process
Gilles Peskineac99e322019-05-14 16:10:53 +02002498 * a whole block at a time, it must consume all the input provided, but
2499 * it may delay the end of the corresponding output until a subsequent
2500 * call to psa_aead_update(), psa_aead_finish() or psa_aead_verify()
2501 * provides sufficient input. The amount of data that can be delayed
2502 * in this way is bounded by #PSA_AEAD_UPDATE_OUTPUT_SIZE.
Gilles Peskinef02aec92019-05-06 15:42:54 +02002503 *
Gilles Peskine30a9e412019-01-14 18:36:12 +01002504 * \param[in,out] operation Active AEAD operation.
2505 * \param[in] input Buffer containing the message fragment to
2506 * encrypt or decrypt.
2507 * \param input_length Size of the \p input buffer in bytes.
2508 * \param[out] output Buffer where the output is to be written.
2509 * \param output_size Size of the \p output buffer in bytes.
Gilles Peskine49dd8d82019-05-06 15:16:19 +02002510 * This must be at least
2511 * #PSA_AEAD_UPDATE_OUTPUT_SIZE(\c alg,
2512 * \p input_length) where \c alg is the
2513 * algorithm that is being calculated.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002514 * \param[out] output_length On success, the number of bytes
2515 * that make up the returned output.
2516 *
2517 * \retval #PSA_SUCCESS
2518 * Success.
2519 * \retval #PSA_ERROR_BAD_STATE
2520 * The operation state is not valid (not set up, nonce not set
2521 * or already completed).
2522 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
2523 * The size of the \p output buffer is too small.
Gilles Peskine49dd8d82019-05-06 15:16:19 +02002524 * You can determine a sufficient buffer size by calling
2525 * #PSA_AEAD_UPDATE_OUTPUT_SIZE(\c alg, \p input_length)
2526 * where \c alg is the algorithm that is being calculated.
Gilles Peskinebc59c852019-01-17 15:26:08 +01002527 * \retval #PSA_ERROR_INVALID_ARGUMENT
2528 * The total length of input to psa_aead_update_ad() so far is
2529 * less than the additional data length that was previously
2530 * specified with psa_aead_set_lengths().
2531 * \retval #PSA_ERROR_INVALID_ARGUMENT
2532 * The total input length overflows the plaintext length that
2533 * was previously specified with psa_aead_set_lengths().
Gilles Peskine30a9e412019-01-14 18:36:12 +01002534 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2535 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2536 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002537 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01002538 * \retval #PSA_ERROR_BAD_STATE
2539 * The library has not been previously initialized by psa_crypto_init().
2540 * It is implementation-dependent whether a failure to initialize
2541 * results in this error code.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002542 */
2543psa_status_t psa_aead_update(psa_aead_operation_t *operation,
2544 const uint8_t *input,
2545 size_t input_length,
Andrew Thoelked16bdac2019-05-15 12:34:01 +01002546 uint8_t *output,
Gilles Peskine30a9e412019-01-14 18:36:12 +01002547 size_t output_size,
2548 size_t *output_length);
2549
2550/** Finish encrypting a message in an AEAD operation.
2551 *
2552 * The operation must have been set up with psa_aead_encrypt_setup().
2553 *
2554 * This function finishes the authentication of the additional data
2555 * formed by concatenating the inputs passed to preceding calls to
2556 * psa_aead_update_ad() with the plaintext formed by concatenating the
2557 * inputs passed to preceding calls to psa_aead_update().
2558 *
2559 * This function has two output buffers:
2560 * - \p ciphertext contains trailing ciphertext that was buffered from
Gilles Peskinef02aec92019-05-06 15:42:54 +02002561 * preceding calls to psa_aead_update().
Gilles Peskine30a9e412019-01-14 18:36:12 +01002562 * - \p tag contains the authentication tag. Its length is always
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002563 * #PSA_AEAD_TAG_LENGTH(\c alg) where \c alg is the AEAD algorithm
Gilles Peskine30a9e412019-01-14 18:36:12 +01002564 * that the operation performs.
2565 *
2566 * When this function returns, the operation becomes inactive.
2567 *
2568 * \param[in,out] operation Active AEAD operation.
2569 * \param[out] ciphertext Buffer where the last part of the ciphertext
2570 * is to be written.
2571 * \param ciphertext_size Size of the \p ciphertext buffer in bytes.
Gilles Peskine49dd8d82019-05-06 15:16:19 +02002572 * This must be at least
2573 * #PSA_AEAD_FINISH_OUTPUT_SIZE(\c alg) where
2574 * \c alg is the algorithm that is being
2575 * calculated.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002576 * \param[out] ciphertext_length On success, the number of bytes of
2577 * returned ciphertext.
2578 * \param[out] tag Buffer where the authentication tag is
2579 * to be written.
2580 * \param tag_size Size of the \p tag buffer in bytes.
Gilles Peskine49dd8d82019-05-06 15:16:19 +02002581 * This must be at least
2582 * #PSA_AEAD_TAG_LENGTH(\c alg) where \c alg is
2583 * the algorithm that is being calculated.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002584 * \param[out] tag_length On success, the number of bytes
2585 * that make up the returned tag.
2586 *
2587 * \retval #PSA_SUCCESS
2588 * Success.
2589 * \retval #PSA_ERROR_BAD_STATE
2590 * The operation state is not valid (not set up, nonce not set,
2591 * decryption, or already completed).
2592 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002593 * The size of the \p ciphertext or \p tag buffer is too small.
Gilles Peskine49dd8d82019-05-06 15:16:19 +02002594 * You can determine a sufficient buffer size for \p ciphertext by
2595 * calling #PSA_AEAD_FINISH_OUTPUT_SIZE(\c alg)
2596 * where \c alg is the algorithm that is being calculated.
2597 * You can determine a sufficient buffer size for \p tag by
2598 * calling #PSA_AEAD_TAG_LENGTH(\c alg).
Gilles Peskinebc59c852019-01-17 15:26:08 +01002599 * \retval #PSA_ERROR_INVALID_ARGUMENT
2600 * The total length of input to psa_aead_update_ad() so far is
2601 * less than the additional data length that was previously
2602 * specified with psa_aead_set_lengths().
2603 * \retval #PSA_ERROR_INVALID_ARGUMENT
2604 * The total length of input to psa_aead_update() so far is
2605 * less than the plaintext length that was previously
2606 * specified with psa_aead_set_lengths().
Gilles Peskine30a9e412019-01-14 18:36:12 +01002607 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2608 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2609 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002610 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01002611 * \retval #PSA_ERROR_BAD_STATE
2612 * The library has not been previously initialized by psa_crypto_init().
2613 * It is implementation-dependent whether a failure to initialize
2614 * results in this error code.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002615 */
2616psa_status_t psa_aead_finish(psa_aead_operation_t *operation,
Gilles Peskinea05602d2019-01-17 15:25:52 +01002617 uint8_t *ciphertext,
2618 size_t ciphertext_size,
2619 size_t *ciphertext_length,
Gilles Peskine30a9e412019-01-14 18:36:12 +01002620 uint8_t *tag,
2621 size_t tag_size,
2622 size_t *tag_length);
2623
2624/** Finish authenticating and decrypting a message in an AEAD operation.
2625 *
2626 * The operation must have been set up with psa_aead_decrypt_setup().
2627 *
2628 * This function finishes the authentication of the additional data
2629 * formed by concatenating the inputs passed to preceding calls to
2630 * psa_aead_update_ad() with the ciphertext formed by concatenating the
2631 * inputs passed to preceding calls to psa_aead_update().
2632 *
2633 * When this function returns, the operation becomes inactive.
2634 *
2635 * \param[in,out] operation Active AEAD operation.
Gilles Peskine5211efb2019-05-06 15:56:05 +02002636 * \param[out] plaintext Buffer where the last part of the plaintext
Gilles Peskineac99e322019-05-14 16:10:53 +02002637 * is to be written. This is the remaining data
Gilles Peskine5211efb2019-05-06 15:56:05 +02002638 * from previous calls to psa_aead_update()
2639 * that could not be processed until the end
2640 * of the input.
2641 * \param plaintext_size Size of the \p plaintext buffer in bytes.
Gilles Peskine49dd8d82019-05-06 15:16:19 +02002642 * This must be at least
2643 * #PSA_AEAD_VERIFY_OUTPUT_SIZE(\c alg) where
2644 * \c alg is the algorithm that is being
2645 * calculated.
Gilles Peskine5211efb2019-05-06 15:56:05 +02002646 * \param[out] plaintext_length On success, the number of bytes of
2647 * returned plaintext.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002648 * \param[in] tag Buffer containing the authentication tag.
2649 * \param tag_length Size of the \p tag buffer in bytes.
2650 *
2651 * \retval #PSA_SUCCESS
2652 * Success.
2653 * \retval #PSA_ERROR_BAD_STATE
2654 * The operation state is not valid (not set up, nonce not set,
2655 * encryption, or already completed).
Gilles Peskine49dd8d82019-05-06 15:16:19 +02002656 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
2657 * The size of the \p plaintext buffer is too small.
2658 * You can determine a sufficient buffer size for \p plaintext by
2659 * calling #PSA_AEAD_VERIFY_OUTPUT_SIZE(\c alg)
2660 * where \c alg is the algorithm that is being calculated.
Gilles Peskinebc59c852019-01-17 15:26:08 +01002661 * \retval #PSA_ERROR_INVALID_ARGUMENT
2662 * The total length of input to psa_aead_update_ad() so far is
2663 * less than the additional data length that was previously
2664 * specified with psa_aead_set_lengths().
2665 * \retval #PSA_ERROR_INVALID_ARGUMENT
2666 * The total length of input to psa_aead_update() so far is
2667 * less than the plaintext length that was previously
2668 * specified with psa_aead_set_lengths().
Gilles Peskine30a9e412019-01-14 18:36:12 +01002669 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2670 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2671 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002672 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01002673 * \retval #PSA_ERROR_BAD_STATE
2674 * The library has not been previously initialized by psa_crypto_init().
2675 * It is implementation-dependent whether a failure to initialize
2676 * results in this error code.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002677 */
2678psa_status_t psa_aead_verify(psa_aead_operation_t *operation,
Gilles Peskine5211efb2019-05-06 15:56:05 +02002679 uint8_t *plaintext,
2680 size_t plaintext_size,
2681 size_t *plaintext_length,
Gilles Peskine30a9e412019-01-14 18:36:12 +01002682 const uint8_t *tag,
2683 size_t tag_length);
2684
2685/** Abort an AEAD operation.
2686 *
2687 * Aborting an operation frees all associated resources except for the
2688 * \p operation structure itself. Once aborted, the operation object
2689 * can be reused for another operation by calling
2690 * psa_aead_encrypt_setup() or psa_aead_decrypt_setup() again.
2691 *
2692 * You may call this function any time after the operation object has
2693 * been initialized by any of the following methods:
2694 * - A call to psa_aead_encrypt_setup() or psa_aead_decrypt_setup(),
2695 * whether it succeeds or not.
2696 * - Initializing the \c struct to all-bits-zero.
2697 * - Initializing the \c struct to logical zeros, e.g.
2698 * `psa_aead_operation_t operation = {0}`.
2699 *
2700 * In particular, calling psa_aead_abort() after the operation has been
2701 * terminated by a call to psa_aead_abort() or psa_aead_finish()
2702 * is safe and has no effect.
2703 *
2704 * \param[in,out] operation Initialized AEAD operation.
2705 *
2706 * \retval #PSA_SUCCESS
2707 * \retval #PSA_ERROR_BAD_STATE
2708 * \p operation is not an active AEAD operation.
2709 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2710 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002711 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01002712 * \retval #PSA_ERROR_BAD_STATE
2713 * The library has not been previously initialized by psa_crypto_init().
2714 * It is implementation-dependent whether a failure to initialize
2715 * results in this error code.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002716 */
2717psa_status_t psa_aead_abort(psa_aead_operation_t *operation);
2718
Gilles Peskine3b555712018-03-03 21:27:57 +01002719/**@}*/
2720
Gilles Peskine20035e32018-02-03 22:44:14 +01002721/** \defgroup asymmetric Asymmetric cryptography
2722 * @{
2723 */
2724
2725/**
2726 * \brief Sign a hash or short message with a private key.
2727 *
Gilles Peskine08bac712018-06-26 16:14:46 +02002728 * Note that to perform a hash-and-sign signature algorithm, you must
Gilles Peskineda8191d1c2018-07-08 19:46:38 +02002729 * first calculate the hash by calling psa_hash_setup(), psa_hash_update()
Gilles Peskine08bac712018-06-26 16:14:46 +02002730 * and psa_hash_finish(). Then pass the resulting hash as the \p hash
2731 * parameter to this function. You can use #PSA_ALG_SIGN_GET_HASH(\p alg)
2732 * to determine the hash algorithm to use.
2733 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01002734 * \param handle Handle to the key to use for the operation.
2735 * It must be an asymmetric key pair.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002736 * \param alg A signature algorithm that is compatible with
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002737 * the type of \p handle.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002738 * \param[in] hash The hash or message to sign.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002739 * \param hash_length Size of the \p hash buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002740 * \param[out] signature Buffer where the signature is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002741 * \param signature_size Size of the \p signature buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002742 * \param[out] signature_length On success, the number of bytes
2743 * that make up the returned signature value.
Gilles Peskine308b91d2018-02-08 09:47:44 +01002744 *
Gilles Peskine28538492018-07-11 17:34:00 +02002745 * \retval #PSA_SUCCESS
2746 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002747 * The size of the \p signature buffer is too small. You can
Gilles Peskine308b91d2018-02-08 09:47:44 +01002748 * determine a sufficient buffer size by calling
Gilles Peskine7256e6c2018-07-12 00:34:26 +02002749 * #PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
Gilles Peskine308b91d2018-02-08 09:47:44 +01002750 * where \c key_type and \c key_bits are the type and bit-size
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002751 * respectively of \p handle.
Gilles Peskine28538492018-07-11 17:34:00 +02002752 * \retval #PSA_ERROR_NOT_SUPPORTED
2753 * \retval #PSA_ERROR_INVALID_ARGUMENT
2754 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2755 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2756 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002757 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine28538492018-07-11 17:34:00 +02002758 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
itayzafrir90d8c7a2018-09-12 11:44:52 +03002759 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03002760 * The library has not been previously initialized by psa_crypto_init().
2761 * It is implementation-dependent whether a failure to initialize
2762 * results in this error code.
Gilles Peskine20035e32018-02-03 22:44:14 +01002763 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01002764psa_status_t psa_asymmetric_sign(psa_key_handle_t handle,
Gilles Peskine20035e32018-02-03 22:44:14 +01002765 psa_algorithm_t alg,
2766 const uint8_t *hash,
2767 size_t hash_length,
Gilles Peskine20035e32018-02-03 22:44:14 +01002768 uint8_t *signature,
2769 size_t signature_size,
2770 size_t *signature_length);
2771
2772/**
2773 * \brief Verify the signature a hash or short message using a public key.
2774 *
Gilles Peskine08bac712018-06-26 16:14:46 +02002775 * Note that to perform a hash-and-sign signature algorithm, you must
Gilles Peskineda8191d1c2018-07-08 19:46:38 +02002776 * first calculate the hash by calling psa_hash_setup(), psa_hash_update()
Gilles Peskine08bac712018-06-26 16:14:46 +02002777 * and psa_hash_finish(). Then pass the resulting hash as the \p hash
2778 * parameter to this function. You can use #PSA_ALG_SIGN_GET_HASH(\p alg)
2779 * to determine the hash algorithm to use.
2780 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01002781 * \param handle Handle to the key to use for the operation.
2782 * It must be a public key or an asymmetric key pair.
Gilles Peskine308b91d2018-02-08 09:47:44 +01002783 * \param alg A signature algorithm that is compatible with
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002784 * the type of \p handle.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002785 * \param[in] hash The hash or message whose signature is to be
Gilles Peskine08bac712018-06-26 16:14:46 +02002786 * verified.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002787 * \param hash_length Size of the \p hash buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002788 * \param[in] signature Buffer containing the signature to verify.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002789 * \param signature_length Size of the \p signature buffer in bytes.
Gilles Peskine308b91d2018-02-08 09:47:44 +01002790 *
Gilles Peskine28538492018-07-11 17:34:00 +02002791 * \retval #PSA_SUCCESS
Gilles Peskine308b91d2018-02-08 09:47:44 +01002792 * The signature is valid.
Gilles Peskine28538492018-07-11 17:34:00 +02002793 * \retval #PSA_ERROR_INVALID_SIGNATURE
Gilles Peskine308b91d2018-02-08 09:47:44 +01002794 * The calculation was perfomed successfully, but the passed
2795 * signature is not a valid signature.
Gilles Peskine28538492018-07-11 17:34:00 +02002796 * \retval #PSA_ERROR_NOT_SUPPORTED
2797 * \retval #PSA_ERROR_INVALID_ARGUMENT
2798 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2799 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2800 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002801 * \retval #PSA_ERROR_CORRUPTION_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03002802 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03002803 * The library has not been previously initialized by psa_crypto_init().
2804 * It is implementation-dependent whether a failure to initialize
2805 * results in this error code.
Gilles Peskine20035e32018-02-03 22:44:14 +01002806 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01002807psa_status_t psa_asymmetric_verify(psa_key_handle_t handle,
Gilles Peskine20035e32018-02-03 22:44:14 +01002808 psa_algorithm_t alg,
2809 const uint8_t *hash,
2810 size_t hash_length,
Gilles Peskinee9191ff2018-06-27 14:58:41 +02002811 const uint8_t *signature,
Gilles Peskine526fab02018-06-27 18:19:40 +02002812 size_t signature_length);
Gilles Peskine20035e32018-02-03 22:44:14 +01002813
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002814/**
2815 * \brief Encrypt a short message with a public key.
2816 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01002817 * \param handle Handle to the key to use for the operation.
2818 * It must be a public key or an asymmetric
2819 * key pair.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002820 * \param alg An asymmetric encryption algorithm that is
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002821 * compatible with the type of \p handle.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002822 * \param[in] input The message to encrypt.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002823 * \param input_length Size of the \p input buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002824 * \param[in] salt A salt or label, if supported by the
2825 * encryption algorithm.
2826 * If the algorithm does not support a
2827 * salt, pass \c NULL.
2828 * If the algorithm supports an optional
2829 * salt and you do not want to pass a salt,
2830 * pass \c NULL.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002831 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02002832 * - For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is
2833 * supported.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002834 * \param salt_length Size of the \p salt buffer in bytes.
2835 * If \p salt is \c NULL, pass 0.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002836 * \param[out] output Buffer where the encrypted message is to
2837 * be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002838 * \param output_size Size of the \p output buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002839 * \param[out] output_length On success, the number of bytes
2840 * that make up the returned output.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002841 *
Gilles Peskine28538492018-07-11 17:34:00 +02002842 * \retval #PSA_SUCCESS
2843 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002844 * The size of the \p output buffer is too small. You can
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002845 * determine a sufficient buffer size by calling
Gilles Peskine7256e6c2018-07-12 00:34:26 +02002846 * #PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002847 * where \c key_type and \c key_bits are the type and bit-size
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002848 * respectively of \p handle.
Gilles Peskine28538492018-07-11 17:34:00 +02002849 * \retval #PSA_ERROR_NOT_SUPPORTED
2850 * \retval #PSA_ERROR_INVALID_ARGUMENT
2851 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2852 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2853 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002854 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine28538492018-07-11 17:34:00 +02002855 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
itayzafrir90d8c7a2018-09-12 11:44:52 +03002856 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03002857 * The library has not been previously initialized by psa_crypto_init().
2858 * It is implementation-dependent whether a failure to initialize
2859 * results in this error code.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002860 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01002861psa_status_t psa_asymmetric_encrypt(psa_key_handle_t handle,
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002862 psa_algorithm_t alg,
2863 const uint8_t *input,
2864 size_t input_length,
2865 const uint8_t *salt,
2866 size_t salt_length,
2867 uint8_t *output,
2868 size_t output_size,
2869 size_t *output_length);
2870
2871/**
2872 * \brief Decrypt a short message with a private key.
2873 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01002874 * \param handle Handle to the key to use for the operation.
2875 * It must be an asymmetric key pair.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002876 * \param alg An asymmetric encryption algorithm that is
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002877 * compatible with the type of \p handle.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002878 * \param[in] input The message to decrypt.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002879 * \param input_length Size of the \p input buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002880 * \param[in] salt A salt or label, if supported by the
2881 * encryption algorithm.
2882 * If the algorithm does not support a
2883 * salt, pass \c NULL.
2884 * If the algorithm supports an optional
2885 * salt and you do not want to pass a salt,
2886 * pass \c NULL.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002887 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02002888 * - For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is
2889 * supported.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002890 * \param salt_length Size of the \p salt buffer in bytes.
2891 * If \p salt is \c NULL, pass 0.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002892 * \param[out] output Buffer where the decrypted message is to
2893 * be written.
2894 * \param output_size Size of the \c output buffer in bytes.
2895 * \param[out] output_length On success, the number of bytes
2896 * that make up the returned output.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002897 *
Gilles Peskine28538492018-07-11 17:34:00 +02002898 * \retval #PSA_SUCCESS
2899 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002900 * The size of the \p output buffer is too small. You can
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002901 * determine a sufficient buffer size by calling
Gilles Peskinedda3bd32018-07-12 19:40:46 +02002902 * #PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002903 * where \c key_type and \c key_bits are the type and bit-size
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002904 * respectively of \p handle.
Gilles Peskine28538492018-07-11 17:34:00 +02002905 * \retval #PSA_ERROR_NOT_SUPPORTED
2906 * \retval #PSA_ERROR_INVALID_ARGUMENT
2907 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2908 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2909 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002910 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine28538492018-07-11 17:34:00 +02002911 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
2912 * \retval #PSA_ERROR_INVALID_PADDING
itayzafrir90d8c7a2018-09-12 11:44:52 +03002913 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03002914 * The library has not been previously initialized by psa_crypto_init().
2915 * It is implementation-dependent whether a failure to initialize
2916 * results in this error code.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002917 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01002918psa_status_t psa_asymmetric_decrypt(psa_key_handle_t handle,
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002919 psa_algorithm_t alg,
2920 const uint8_t *input,
2921 size_t input_length,
2922 const uint8_t *salt,
2923 size_t salt_length,
2924 uint8_t *output,
2925 size_t output_size,
2926 size_t *output_length);
2927
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +01002928/**@}*/
2929
Gilles Peskine35675b62019-05-16 17:26:11 +02002930/** \defgroup key_derivation Key derivation and pseudorandom generation
Gilles Peskineeab56e42018-07-12 17:12:33 +02002931 * @{
2932 */
2933
Gilles Peskine35675b62019-05-16 17:26:11 +02002934/** The type of the state data structure for key derivation operations.
Gilles Peskineeab56e42018-07-12 17:12:33 +02002935 *
Gilles Peskine35675b62019-05-16 17:26:11 +02002936 * Before calling any function on a key derivation operation object, the
2937 * application must initialize it by any of the following means:
Gilles Peskineeab56e42018-07-12 17:12:33 +02002938 * - Set the structure to all-bits-zero, for example:
2939 * \code
Gilles Peskine35675b62019-05-16 17:26:11 +02002940 * psa_key_derivation_operation_t operation;
2941 * memset(&operation, 0, sizeof(operation));
Gilles Peskineeab56e42018-07-12 17:12:33 +02002942 * \endcode
2943 * - Initialize the structure to logical zero values, for example:
2944 * \code
Gilles Peskine35675b62019-05-16 17:26:11 +02002945 * psa_key_derivation_operation_t operation = {0};
Gilles Peskineeab56e42018-07-12 17:12:33 +02002946 * \endcode
Gilles Peskinea99d3fb2019-05-16 15:28:51 +02002947 * - Initialize the structure to the initializer #PSA_KEY_DERIVATION_OPERATION_INIT,
Gilles Peskineeab56e42018-07-12 17:12:33 +02002948 * for example:
2949 * \code
Gilles Peskine35675b62019-05-16 17:26:11 +02002950 * psa_key_derivation_operation_t operation = PSA_KEY_DERIVATION_OPERATION_INIT;
Gilles Peskineeab56e42018-07-12 17:12:33 +02002951 * \endcode
Gilles Peskinea99d3fb2019-05-16 15:28:51 +02002952 * - Assign the result of the function psa_key_derivation_operation_init()
Gilles Peskineeab56e42018-07-12 17:12:33 +02002953 * to the structure, for example:
2954 * \code
Gilles Peskine35675b62019-05-16 17:26:11 +02002955 * psa_key_derivation_operation_t operation;
2956 * operation = psa_key_derivation_operation_init();
Gilles Peskineeab56e42018-07-12 17:12:33 +02002957 * \endcode
2958 *
2959 * This is an implementation-defined \c struct. Applications should not
2960 * make any assumptions about the content of this structure except
2961 * as directed by the documentation of a specific implementation.
2962 */
Gilles Peskinecbe66502019-05-16 16:59:18 +02002963typedef struct psa_key_derivation_s psa_key_derivation_operation_t;
Gilles Peskineeab56e42018-07-12 17:12:33 +02002964
Gilles Peskinea99d3fb2019-05-16 15:28:51 +02002965/** \def PSA_KEY_DERIVATION_OPERATION_INIT
Gilles Peskineeab56e42018-07-12 17:12:33 +02002966 *
Gilles Peskine35675b62019-05-16 17:26:11 +02002967 * This macro returns a suitable initializer for a key derivation operation
2968 * object of type #psa_key_derivation_operation_t.
Gilles Peskineeab56e42018-07-12 17:12:33 +02002969 */
2970#ifdef __DOXYGEN_ONLY__
2971/* This is an example definition for documentation purposes.
2972 * Implementations should define a suitable value in `crypto_struct.h`.
2973 */
Gilles Peskinea99d3fb2019-05-16 15:28:51 +02002974#define PSA_KEY_DERIVATION_OPERATION_INIT {0}
Gilles Peskineeab56e42018-07-12 17:12:33 +02002975#endif
2976
Gilles Peskine35675b62019-05-16 17:26:11 +02002977/** Return an initial value for a key derivation operation object.
Gilles Peskineeab56e42018-07-12 17:12:33 +02002978 */
Gilles Peskinea99d3fb2019-05-16 15:28:51 +02002979static psa_key_derivation_operation_t psa_key_derivation_operation_init(void);
Gilles Peskineeab56e42018-07-12 17:12:33 +02002980
Gilles Peskine1cb9a082019-05-16 17:56:47 +02002981/** Set up a key derivation operation.
2982 *
2983 * A key derivation algorithm takes some inputs and uses them to generate
2984 * a byte stream in a deterministic way.
2985 * This byte stream can be used to produce keys and other
2986 * cryptographic material.
2987 *
2988 * To derive a key:
2989 * - Start with an initialized object of type #psa_key_derivation_operation_t.
2990 * - Call psa_key_derivation_setup() to select the algorithm.
2991 * - Provide the inputs for the key derivation by calling
2992 * psa_key_derivation_input_bytes() or psa_key_derivation_input_key()
2993 * as appropriate. Which inputs are needed, in what order, and whether
2994 * they may be keys and if so of what type depends on the algorithm.
2995 * - Optionally set the operation's maximum capacity with
2996 * psa_key_derivation_set_capacity(). You may do this before, in the middle
2997 * of or after providing inputs. For some algorithms, this step is mandatory
2998 * because the output depends on the maximum capacity.
2999 * - To derive a key, call psa_key_derivation_output_key().
3000 * To derive a byte string for a different purpose, call
3001 * - psa_key_derivation_output_bytes().
3002 * Successive calls to these functions use successive output bytes
3003 * calculated by the key derivation algorithm.
3004 * - Clean up the key derivation operation object with
3005 * psa_key_derivation_abort().
3006 *
3007 * \param[in,out] operation The key derivation operation object
3008 * to set up. It must
3009 * have been initialized but not set up yet.
3010 * \param alg The key derivation algorithm to compute
3011 * (\c PSA_ALG_XXX value such that
3012 * #PSA_ALG_IS_KEY_DERIVATION(\p alg) is true).
3013 *
3014 * \retval #PSA_SUCCESS
3015 * Success.
3016 * \retval #PSA_ERROR_INVALID_ARGUMENT
3017 * \c alg is not a key derivation algorithm.
3018 * \retval #PSA_ERROR_NOT_SUPPORTED
3019 * \c alg is not supported or is not a key derivation algorithm.
3020 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3021 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3022 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003023 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine1cb9a082019-05-16 17:56:47 +02003024 * \retval #PSA_ERROR_BAD_STATE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01003025 * The operation state is either not initialized or has been setup.
3026 * \retval #PSA_ERROR_BAD_STATE
3027 * The library has not been previously initialized by psa_crypto_init().
3028 * It is implementation-dependent whether a failure to initialize
3029 * results in this error code.
Gilles Peskine1cb9a082019-05-16 17:56:47 +02003030 */
3031psa_status_t psa_key_derivation_setup(
3032 psa_key_derivation_operation_t *operation,
3033 psa_algorithm_t alg);
3034
Gilles Peskine35675b62019-05-16 17:26:11 +02003035/** Retrieve the current capacity of a key derivation operation.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003036 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003037 * The capacity of a key derivation is the maximum number of bytes that it can
3038 * return. When you get *N* bytes of output from a key derivation operation,
3039 * this reduces its capacity by *N*.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003040 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003041 * \param[in] operation The operation to query.
3042 * \param[out] capacity On success, the capacity of the operation.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003043 *
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003044 * \retval #PSA_SUCCESS
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003045 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01003046 * \retval #PSA_ERROR_BAD_STATE
3047 * The operation state is not valid.
3048 * \retval #PSA_ERROR_BAD_STATE
3049 * The library has not been previously initialized by psa_crypto_init().
3050 * It is implementation-dependent whether a failure to initialize
3051 * results in this error code.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003052 */
Gilles Peskinecf7292e2019-05-16 17:53:40 +02003053psa_status_t psa_key_derivation_get_capacity(
3054 const psa_key_derivation_operation_t *operation,
3055 size_t *capacity);
Gilles Peskineeab56e42018-07-12 17:12:33 +02003056
Gilles Peskine35675b62019-05-16 17:26:11 +02003057/** Set the maximum capacity of a key derivation operation.
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01003058 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003059 * The capacity of a key derivation operation is the maximum number of bytes
3060 * that the key derivation operation can return from this point onwards.
3061 *
3062 * \param[in,out] operation The key derivation operation object to modify.
3063 * \param capacity The new capacity of the operation.
3064 * It must be less or equal to the operation's
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01003065 * current capacity.
3066 *
3067 * \retval #PSA_SUCCESS
3068 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine35675b62019-05-16 17:26:11 +02003069 * \p capacity is larger than the operation's current capacity.
3070 * In this case, the operation object remains valid and its capacity
3071 * remains unchanged.
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01003072 * \retval #PSA_ERROR_BAD_STATE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01003073 * The operation state is not valid.
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01003074 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01003075 * \retval #PSA_ERROR_BAD_STATE
3076 * The library has not been previously initialized by psa_crypto_init().
3077 * It is implementation-dependent whether a failure to initialize
3078 * results in this error code.
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01003079 */
Gilles Peskinecf7292e2019-05-16 17:53:40 +02003080psa_status_t psa_key_derivation_set_capacity(
3081 psa_key_derivation_operation_t *operation,
3082 size_t capacity);
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01003083
Gilles Peskine1cb9a082019-05-16 17:56:47 +02003084/** Use the maximum possible capacity for a key derivation operation.
3085 *
3086 * Use this value as the capacity argument when setting up a key derivation
3087 * to indicate that the operation should have the maximum possible capacity.
3088 * The value of the maximum possible capacity depends on the key derivation
3089 * algorithm.
3090 */
3091#define PSA_KEY_DERIVATION_UNLIMITED_CAPACITY ((size_t)(-1))
3092
3093/** Provide an input for key derivation or key agreement.
3094 *
3095 * Which inputs are required and in what order depends on the algorithm.
3096 * Refer to the documentation of each key derivation or key agreement
3097 * algorithm for information.
3098 *
3099 * This function passes direct inputs. Some inputs must be passed as keys
3100 * using psa_key_derivation_input_key() instead of this function. Refer to
3101 * the documentation of individual step types for information.
3102 *
3103 * \param[in,out] operation The key derivation operation object to use.
3104 * It must have been set up with
3105 * psa_key_derivation_setup() and must not
3106 * have produced any output yet.
3107 * \param step Which step the input data is for.
3108 * \param[in] data Input data to use.
3109 * \param data_length Size of the \p data buffer in bytes.
3110 *
3111 * \retval #PSA_SUCCESS
3112 * Success.
3113 * \retval #PSA_ERROR_INVALID_ARGUMENT
3114 * \c step is not compatible with the operation's algorithm.
3115 * \retval #PSA_ERROR_INVALID_ARGUMENT
3116 * \c step does not allow direct inputs.
3117 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3118 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3119 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003120 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine1cb9a082019-05-16 17:56:47 +02003121 * \retval #PSA_ERROR_BAD_STATE
3122 * The value of \p step is not valid given the state of \p operation.
3123 * \retval #PSA_ERROR_BAD_STATE
3124 * The library has not been previously initialized by psa_crypto_init().
3125 * It is implementation-dependent whether a failure to initialize
3126 * results in this error code.
3127 */
3128psa_status_t psa_key_derivation_input_bytes(
3129 psa_key_derivation_operation_t *operation,
3130 psa_key_derivation_step_t step,
3131 const uint8_t *data,
3132 size_t data_length);
3133
3134/** Provide an input for key derivation in the form of a key.
3135 *
3136 * Which inputs are required and in what order depends on the algorithm.
3137 * Refer to the documentation of each key derivation or key agreement
3138 * algorithm for information.
3139 *
3140 * This function passes key inputs. Some inputs must be passed as keys
3141 * of the appropriate type using this function, while others must be
3142 * passed as direct inputs using psa_key_derivation_input_bytes(). Refer to
3143 * the documentation of individual step types for information.
3144 *
3145 * \param[in,out] operation The key derivation operation object to use.
3146 * It must have been set up with
3147 * psa_key_derivation_setup() and must not
3148 * have produced any output yet.
3149 * \param step Which step the input data is for.
3150 * \param handle Handle to the key. It must have an
3151 * appropriate type for \p step and must
3152 * allow the usage #PSA_KEY_USAGE_DERIVE.
3153 *
3154 * \retval #PSA_SUCCESS
3155 * Success.
3156 * \retval #PSA_ERROR_INVALID_HANDLE
3157 * \retval #PSA_ERROR_DOES_NOT_EXIST
3158 * \retval #PSA_ERROR_NOT_PERMITTED
3159 * \retval #PSA_ERROR_INVALID_ARGUMENT
3160 * \c step is not compatible with the operation's algorithm.
3161 * \retval #PSA_ERROR_INVALID_ARGUMENT
3162 * \c step does not allow key inputs.
3163 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3164 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3165 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003166 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine1cb9a082019-05-16 17:56:47 +02003167 * \retval #PSA_ERROR_BAD_STATE
3168 * The value of \p step is not valid given the state of \p operation.
3169 * \retval #PSA_ERROR_BAD_STATE
3170 * The library has not been previously initialized by psa_crypto_init().
3171 * It is implementation-dependent whether a failure to initialize
3172 * results in this error code.
3173 */
3174psa_status_t psa_key_derivation_input_key(
3175 psa_key_derivation_operation_t *operation,
3176 psa_key_derivation_step_t step,
3177 psa_key_handle_t handle);
3178
3179/** Perform a key agreement and use the shared secret as input to a key
3180 * derivation.
3181 *
3182 * A key agreement algorithm takes two inputs: a private key \p private_key
3183 * a public key \p peer_key.
3184 * The result of this function is passed as input to a key derivation.
3185 * The output of this key derivation can be extracted by reading from the
3186 * resulting operation to produce keys and other cryptographic material.
3187 *
3188 * \param[in,out] operation The key derivation operation object to use.
3189 * It must have been set up with
3190 * psa_key_derivation_setup() with a
3191 * key agreement and derivation algorithm
3192 * \c alg (\c PSA_ALG_XXX value such that
3193 * #PSA_ALG_IS_KEY_AGREEMENT(\c alg) is true
3194 * and #PSA_ALG_IS_RAW_KEY_AGREEMENT(\c alg)
3195 * is false).
3196 * The operation must be ready for an
3197 * input of the type given by \p step.
3198 * \param step Which step the input data is for.
3199 * \param private_key Handle to the private key to use.
3200 * \param[in] peer_key Public key of the peer. The peer key must be in the
3201 * same format that psa_import_key() accepts for the
3202 * public key type corresponding to the type of
3203 * private_key. That is, this function performs the
3204 * equivalent of
3205 * #psa_import_key(...,
3206 * `peer_key`, `peer_key_length`) where
3207 * with key attributes indicating the public key
3208 * type corresponding to the type of `private_key`.
3209 * For example, for EC keys, this means that peer_key
3210 * is interpreted as a point on the curve that the
3211 * private key is on. The standard formats for public
3212 * keys are documented in the documentation of
3213 * psa_export_public_key().
3214 * \param peer_key_length Size of \p peer_key in bytes.
3215 *
3216 * \retval #PSA_SUCCESS
3217 * Success.
3218 * \retval #PSA_ERROR_INVALID_HANDLE
3219 * \retval #PSA_ERROR_DOES_NOT_EXIST
3220 * \retval #PSA_ERROR_NOT_PERMITTED
3221 * \retval #PSA_ERROR_INVALID_ARGUMENT
3222 * \c private_key is not compatible with \c alg,
3223 * or \p peer_key is not valid for \c alg or not compatible with
3224 * \c private_key.
3225 * \retval #PSA_ERROR_NOT_SUPPORTED
3226 * \c alg is not supported or is not a key derivation algorithm.
3227 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3228 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3229 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003230 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01003231 * \retval #PSA_ERROR_BAD_STATE
3232 * The library has not been previously initialized by psa_crypto_init().
3233 * It is implementation-dependent whether a failure to initialize
3234 * results in this error code.
Gilles Peskine1cb9a082019-05-16 17:56:47 +02003235 */
3236psa_status_t psa_key_derivation_key_agreement(
3237 psa_key_derivation_operation_t *operation,
3238 psa_key_derivation_step_t step,
3239 psa_key_handle_t private_key,
3240 const uint8_t *peer_key,
3241 size_t peer_key_length);
3242
Gilles Peskine35675b62019-05-16 17:26:11 +02003243/** Read some data from a key derivation operation.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003244 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003245 * This function calculates output bytes from a key derivation algorithm and
3246 * return those bytes.
3247 * If you view the key derivation's output as a stream of bytes, this
3248 * function destructively reads the requested number of bytes from the
3249 * stream.
3250 * The operation's capacity decreases by the number of bytes read.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003251 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003252 * \param[in,out] operation The key derivation operation object to read from.
3253 * \param[out] output Buffer where the output will be written.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003254 * \param output_length Number of bytes to output.
3255 *
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003256 * \retval #PSA_SUCCESS
David Saadab4ecc272019-02-14 13:48:10 +02003257 * \retval #PSA_ERROR_INSUFFICIENT_DATA
Gilles Peskine35675b62019-05-16 17:26:11 +02003258 * The operation's capacity was less than
3259 * \p output_length bytes. Note that in this case,
3260 * no output is written to the output buffer.
3261 * The operation's capacity is set to 0, thus
Gilles Peskineeab56e42018-07-12 17:12:33 +02003262 * subsequent calls to this function will not
3263 * succeed, even with a smaller output buffer.
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003264 * \retval #PSA_ERROR_BAD_STATE
3265 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3266 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3267 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003268 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01003269 * \retval #PSA_ERROR_BAD_STATE
3270 * The library has not been previously initialized by psa_crypto_init().
3271 * It is implementation-dependent whether a failure to initialize
3272 * results in this error code.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003273 */
Gilles Peskinecf7292e2019-05-16 17:53:40 +02003274psa_status_t psa_key_derivation_output_bytes(
3275 psa_key_derivation_operation_t *operation,
3276 uint8_t *output,
3277 size_t output_length);
Gilles Peskineeab56e42018-07-12 17:12:33 +02003278
Gilles Peskine35675b62019-05-16 17:26:11 +02003279/** Derive a key from an ongoing key derivation operation.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003280 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003281 * This function calculates output bytes from a key derivation algorithm
3282 * and uses those bytes to generate a key deterministically.
3283 * If you view the key derivation's output as a stream of bytes, this
3284 * function destructively reads as many bytes as required from the
3285 * stream.
3286 * The operation's capacity decreases by the number of bytes read.
3287 *
3288 * How much output is produced and consumed from the operation, and how
3289 * the key is derived, depends on the key type:
Gilles Peskineeab56e42018-07-12 17:12:33 +02003290 *
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003291 * - For key types for which the key is an arbitrary sequence of bytes
Gilles Peskinecf7292e2019-05-16 17:53:40 +02003292 * of a given size, this function is functionally equivalent to
3293 * calling #psa_key_derivation_output_bytes
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003294 * and passing the resulting output to #psa_import_key.
3295 * However, this function has a security benefit:
3296 * if the implementation provides an isolation boundary then
3297 * the key material is not exposed outside the isolation boundary.
3298 * As a consequence, for these key types, this function always consumes
Gilles Peskine35675b62019-05-16 17:26:11 +02003299 * exactly (\p bits / 8) bytes from the operation.
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003300 * The following key types defined in this specification follow this scheme:
3301 *
3302 * - #PSA_KEY_TYPE_AES;
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003303 * - #PSA_KEY_TYPE_ARC4;
3304 * - #PSA_KEY_TYPE_CAMELLIA;
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003305 * - #PSA_KEY_TYPE_DERIVE;
3306 * - #PSA_KEY_TYPE_HMAC.
3307 *
3308 * - For ECC keys on a Montgomery elliptic curve
Gilles Peskinec93b80c2019-05-16 19:39:54 +02003309 * (#PSA_KEY_TYPE_ECC_KEY_PAIR(\c curve) where \c curve designates a
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003310 * Montgomery curve), this function always draws a byte string whose
3311 * length is determined by the curve, and sets the mandatory bits
3312 * accordingly. That is:
3313 *
3314 * - #PSA_ECC_CURVE_CURVE25519: draw a 32-byte string
3315 * and process it as specified in RFC 7748 &sect;5.
3316 * - #PSA_ECC_CURVE_CURVE448: draw a 56-byte string
3317 * and process it as specified in RFC 7748 &sect;5.
3318 *
3319 * - For key types for which the key is represented by a single sequence of
3320 * \p bits bits with constraints as to which bit sequences are acceptable,
3321 * this function draws a byte string of length (\p bits / 8) bytes rounded
3322 * up to the nearest whole number of bytes. If the resulting byte string
3323 * is acceptable, it becomes the key, otherwise the drawn bytes are discarded.
3324 * This process is repeated until an acceptable byte string is drawn.
Gilles Peskine35675b62019-05-16 17:26:11 +02003325 * The byte string drawn from the operation is interpreted as specified
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003326 * for the output produced by psa_export_key().
3327 * The following key types defined in this specification follow this scheme:
3328 *
Gilles Peskine2de2c0d2019-03-11 17:59:16 +01003329 * - #PSA_KEY_TYPE_DES.
3330 * Force-set the parity bits, but discard forbidden weak keys.
3331 * For 2-key and 3-key triple-DES, the three keys are generated
3332 * successively (for example, for 3-key triple-DES,
3333 * if the first 8 bytes specify a weak key and the next 8 bytes do not,
3334 * discard the first 8 bytes, use the next 8 bytes as the first key,
Gilles Peskine35675b62019-05-16 17:26:11 +02003335 * and continue reading output from the operation to derive the other
Gilles Peskine2de2c0d2019-03-11 17:59:16 +01003336 * two keys).
Gilles Peskinec93b80c2019-05-16 19:39:54 +02003337 * - Finite-field Diffie-Hellman keys (#PSA_KEY_TYPE_DH_KEY_PAIR(\c group)
Gilles Peskinea1302192019-05-16 13:58:24 +02003338 * where \c group designates any Diffie-Hellman group) and
Gilles Peskine2de2c0d2019-03-11 17:59:16 +01003339 * ECC keys on a Weierstrass elliptic curve
Gilles Peskinec93b80c2019-05-16 19:39:54 +02003340 * (#PSA_KEY_TYPE_ECC_KEY_PAIR(\c curve) where \c curve designates a
Gilles Peskine2de2c0d2019-03-11 17:59:16 +01003341 * Weierstrass curve).
3342 * For these key types, interpret the byte string as integer
3343 * in big-endian order. Discard it if it is not in the range
3344 * [0, *N* - 2] where *N* is the boundary of the private key domain
3345 * (the prime *p* for Diffie-Hellman, the subprime *q* for DSA,
Gilles Peskine55799712019-03-12 11:50:26 +01003346 * or the order of the curve's base point for ECC).
Gilles Peskine2de2c0d2019-03-11 17:59:16 +01003347 * Add 1 to the resulting integer and use this as the private key *x*.
Gilles Peskine55799712019-03-12 11:50:26 +01003348 * This method allows compliance to NIST standards, specifically
3349 * the methods titled "key-pair generation by testing candidates"
Gilles Peskine2de2c0d2019-03-11 17:59:16 +01003350 * in NIST SP 800-56A &sect;5.6.1.1.4 for Diffie-Hellman,
3351 * in FIPS 186-4 &sect;B.1.2 for DSA, and
3352 * in NIST SP 800-56A &sect;5.6.1.2.2 or
3353 * FIPS 186-4 &sect;B.4.2 for elliptic curve keys.
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003354 *
Gilles Peskinec93b80c2019-05-16 19:39:54 +02003355 * - For other key types, including #PSA_KEY_TYPE_RSA_KEY_PAIR,
Gilles Peskine35675b62019-05-16 17:26:11 +02003356 * the way in which the operation output is consumed is
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003357 * implementation-defined.
3358 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003359 * In all cases, the data that is read is discarded from the operation.
3360 * The operation's capacity is decreased by the number of bytes read.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003361 *
Gilles Peskine20628592019-04-19 19:29:50 +02003362 * \param[in] attributes The attributes for the new key.
Gilles Peskine35675b62019-05-16 17:26:11 +02003363 * \param[in,out] operation The key derivation operation object to read from.
Gilles Peskine20628592019-04-19 19:29:50 +02003364 * \param[out] handle On success, a handle to the newly created key.
3365 * \c 0 on failure.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003366 *
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003367 * \retval #PSA_SUCCESS
Gilles Peskineeab56e42018-07-12 17:12:33 +02003368 * Success.
Gilles Peskine23fd2bd2018-12-11 15:51:32 +01003369 * If the key is persistent, the key material and the key's metadata
3370 * have been saved to persistent storage.
Gilles Peskine20628592019-04-19 19:29:50 +02003371 * \retval #PSA_ERROR_ALREADY_EXISTS
3372 * This is an attempt to create a persistent key, and there is
3373 * already a persistent key with the given identifier.
David Saadab4ecc272019-02-14 13:48:10 +02003374 * \retval #PSA_ERROR_INSUFFICIENT_DATA
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003375 * There was not enough data to create the desired key.
3376 * Note that in this case, no output is written to the output buffer.
Gilles Peskine35675b62019-05-16 17:26:11 +02003377 * The operation's capacity is set to 0, thus subsequent calls to
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003378 * this function will not succeed, even with a smaller output buffer.
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003379 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskineeab56e42018-07-12 17:12:33 +02003380 * The key type or key size is not supported, either by the
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +01003381 * implementation in general or in this particular location.
k-stachowiakb9b4f092019-08-15 19:01:59 +02003382 * \retval #PSA_ERROR_INVALID_ARGUMENT
3383 * The provided key attributes are not valid for the operation.
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003384 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003385 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3386 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
3387 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3388 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003389 * \retval #PSA_ERROR_CORRUPTION_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03003390 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03003391 * The library has not been previously initialized by psa_crypto_init().
3392 * It is implementation-dependent whether a failure to initialize
3393 * results in this error code.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003394 */
Gilles Peskinecf7292e2019-05-16 17:53:40 +02003395psa_status_t psa_key_derivation_output_key(
3396 const psa_key_attributes_t *attributes,
3397 psa_key_derivation_operation_t *operation,
3398 psa_key_handle_t *handle);
Gilles Peskineeab56e42018-07-12 17:12:33 +02003399
Gilles Peskine35675b62019-05-16 17:26:11 +02003400/** Abort a key derivation operation.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003401 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003402 * Once a key derivation operation has been aborted, its capacity is zero.
3403 * Aborting an operation frees all associated resources except for the
3404 * \c operation structure itself.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003405 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003406 * This function may be called at any time as long as the operation
Gilles Peskinea99d3fb2019-05-16 15:28:51 +02003407 * object has been initialized to #PSA_KEY_DERIVATION_OPERATION_INIT, to
Gilles Peskinecf7292e2019-05-16 17:53:40 +02003408 * psa_key_derivation_operation_init() or a zero value. In particular,
3409 * it is valid to call psa_key_derivation_abort() twice, or to call
3410 * psa_key_derivation_abort() on an operation that has not been set up.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003411 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003412 * Once aborted, the key derivation operation object may be called.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003413 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003414 * \param[in,out] operation The operation to abort.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003415 *
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003416 * \retval #PSA_SUCCESS
3417 * \retval #PSA_ERROR_BAD_STATE
3418 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3419 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003420 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01003421 * \retval #PSA_ERROR_BAD_STATE
3422 * The library has not been previously initialized by psa_crypto_init().
3423 * It is implementation-dependent whether a failure to initialize
3424 * results in this error code.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003425 */
Gilles Peskinecf7292e2019-05-16 17:53:40 +02003426psa_status_t psa_key_derivation_abort(
3427 psa_key_derivation_operation_t *operation);
Gilles Peskineeab56e42018-07-12 17:12:33 +02003428
Gilles Peskine58fe9e82019-05-16 18:01:45 +02003429/** Perform a key agreement and return the raw shared secret.
Gilles Peskine769c7a62019-01-18 16:42:29 +01003430 *
3431 * \warning The raw result of a key agreement algorithm such as finite-field
3432 * Diffie-Hellman or elliptic curve Diffie-Hellman has biases and should
3433 * not be used directly as key material. It should instead be passed as
3434 * input to a key derivation algorithm. To chain a key agreement with
Gilles Peskinecf7292e2019-05-16 17:53:40 +02003435 * a key derivation, use psa_key_derivation_key_agreement() and other
3436 * functions from the key derivation interface.
Gilles Peskine769c7a62019-01-18 16:42:29 +01003437 *
Gilles Peskine47e79fb2019-02-08 11:24:59 +01003438 * \param alg The key agreement algorithm to compute
3439 * (\c PSA_ALG_XXX value such that
3440 * #PSA_ALG_IS_RAW_KEY_AGREEMENT(\p alg)
3441 * is true).
Gilles Peskine769c7a62019-01-18 16:42:29 +01003442 * \param private_key Handle to the private key to use.
3443 * \param[in] peer_key Public key of the peer. It must be
3444 * in the same format that psa_import_key()
3445 * accepts. The standard formats for public
3446 * keys are documented in the documentation
3447 * of psa_export_public_key().
3448 * \param peer_key_length Size of \p peer_key in bytes.
3449 * \param[out] output Buffer where the decrypted message is to
3450 * be written.
3451 * \param output_size Size of the \c output buffer in bytes.
3452 * \param[out] output_length On success, the number of bytes
3453 * that make up the returned output.
3454 *
3455 * \retval #PSA_SUCCESS
3456 * Success.
3457 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine769c7a62019-01-18 16:42:29 +01003458 * \retval #PSA_ERROR_NOT_PERMITTED
3459 * \retval #PSA_ERROR_INVALID_ARGUMENT
3460 * \p alg is not a key agreement algorithm
3461 * \retval #PSA_ERROR_INVALID_ARGUMENT
3462 * \p private_key is not compatible with \p alg,
3463 * or \p peer_key is not valid for \p alg or not compatible with
3464 * \p private_key.
3465 * \retval #PSA_ERROR_NOT_SUPPORTED
3466 * \p alg is not a supported key agreement algorithm.
3467 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3468 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3469 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003470 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01003471 * \retval #PSA_ERROR_BAD_STATE
3472 * The library has not been previously initialized by psa_crypto_init().
3473 * It is implementation-dependent whether a failure to initialize
3474 * results in this error code.
Gilles Peskine769c7a62019-01-18 16:42:29 +01003475 */
Gilles Peskinebe697d82019-05-16 18:00:41 +02003476psa_status_t psa_raw_key_agreement(psa_algorithm_t alg,
3477 psa_key_handle_t private_key,
3478 const uint8_t *peer_key,
3479 size_t peer_key_length,
3480 uint8_t *output,
3481 size_t output_size,
3482 size_t *output_length);
Gilles Peskine01d718c2018-09-18 12:01:02 +02003483
Gilles Peskineea0fb492018-07-12 17:17:20 +02003484/**@}*/
3485
Gilles Peskineedd76872018-07-20 17:42:05 +02003486/** \defgroup random Random generation
Gilles Peskine9e7dc712018-03-28 14:18:50 +02003487 * @{
3488 */
3489
3490/**
3491 * \brief Generate random bytes.
3492 *
3493 * \warning This function **can** fail! Callers MUST check the return status
3494 * and MUST NOT use the content of the output buffer if the return
3495 * status is not #PSA_SUCCESS.
3496 *
Gilles Peskine35ef36b2019-05-16 19:42:05 +02003497 * \note To generate a key, use psa_generate_key() instead.
Gilles Peskine9e7dc712018-03-28 14:18:50 +02003498 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02003499 * \param[out] output Output buffer for the generated data.
Gilles Peskine9e7dc712018-03-28 14:18:50 +02003500 * \param output_size Number of bytes to generate and output.
3501 *
Gilles Peskine28538492018-07-11 17:34:00 +02003502 * \retval #PSA_SUCCESS
3503 * \retval #PSA_ERROR_NOT_SUPPORTED
3504 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
3505 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3506 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003507 * \retval #PSA_ERROR_CORRUPTION_DETECTED
itayzafrir0adf0fc2018-09-06 16:24:41 +03003508 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03003509 * The library has not been previously initialized by psa_crypto_init().
3510 * It is implementation-dependent whether a failure to initialize
3511 * results in this error code.
Gilles Peskine9e7dc712018-03-28 14:18:50 +02003512 */
3513psa_status_t psa_generate_random(uint8_t *output,
3514 size_t output_size);
3515
3516/**
3517 * \brief Generate a key or key pair.
3518 *
Gilles Peskinee56e8782019-04-26 17:34:02 +02003519 * The key is generated randomly.
3520 * Its location, policy, type and size are taken from \p attributes.
3521 *
Gilles Peskine20a77ae2019-05-16 14:05:56 +02003522 * The following type-specific considerations apply:
Gilles Peskinec93b80c2019-05-16 19:39:54 +02003523 * - For RSA keys (#PSA_KEY_TYPE_RSA_KEY_PAIR),
Gilles Peskine20a77ae2019-05-16 14:05:56 +02003524 * the public exponent is 65537.
3525 * The modulus is a product of two probabilistic primes
3526 * between 2^{n-1} and 2^n where n is the bit size specified in the
3527 * attributes.
3528 *
Gilles Peskine20628592019-04-19 19:29:50 +02003529 * \param[in] attributes The attributes for the new key.
Gilles Peskine20628592019-04-19 19:29:50 +02003530 * \param[out] handle On success, a handle to the newly created key.
3531 * \c 0 on failure.
Gilles Peskine9e7dc712018-03-28 14:18:50 +02003532 *
Gilles Peskine28538492018-07-11 17:34:00 +02003533 * \retval #PSA_SUCCESS
Gilles Peskine23fd2bd2018-12-11 15:51:32 +01003534 * Success.
3535 * If the key is persistent, the key material and the key's metadata
3536 * have been saved to persistent storage.
David Saadab4ecc272019-02-14 13:48:10 +02003537 * \retval #PSA_ERROR_ALREADY_EXISTS
Gilles Peskine20628592019-04-19 19:29:50 +02003538 * This is an attempt to create a persistent key, and there is
3539 * already a persistent key with the given identifier.
Gilles Peskine28538492018-07-11 17:34:00 +02003540 * \retval #PSA_ERROR_NOT_SUPPORTED
3541 * \retval #PSA_ERROR_INVALID_ARGUMENT
3542 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3543 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
3544 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3545 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003546 * \retval #PSA_ERROR_CORRUPTION_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03003547 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03003548 * The library has not been previously initialized by psa_crypto_init().
3549 * It is implementation-dependent whether a failure to initialize
3550 * results in this error code.
Gilles Peskine9e7dc712018-03-28 14:18:50 +02003551 */
Gilles Peskine35ef36b2019-05-16 19:42:05 +02003552psa_status_t psa_generate_key(const psa_key_attributes_t *attributes,
Gilles Peskinee56e8782019-04-26 17:34:02 +02003553 psa_key_handle_t *handle);
Gilles Peskine9e7dc712018-03-28 14:18:50 +02003554
3555/**@}*/
3556
Gilles Peskinee59236f2018-01-27 23:32:46 +01003557#ifdef __cplusplus
3558}
3559#endif
3560
Gilles Peskine0cad07c2018-06-27 19:49:02 +02003561/* The file "crypto_sizes.h" contains definitions for size calculation
3562 * macros whose definitions are implementation-specific. */
3563#include "crypto_sizes.h"
3564
Gilles Peskine9ef733f2018-02-07 21:05:37 +01003565/* The file "crypto_struct.h" contains definitions for
3566 * implementation-specific structs that are declared above. */
3567#include "crypto_struct.h"
3568
3569/* The file "crypto_extra.h" contains vendor-specific definitions. This
3570 * can include vendor-defined algorithms, extra functions, etc. */
Gilles Peskinee59236f2018-01-27 23:32:46 +01003571#include "crypto_extra.h"
3572
3573#endif /* PSA_CRYPTO_H */