blob: d570115305bd09ed83e570f3489f12f5cdaf0b3c [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
Adrian L. Shawd789dc12019-08-12 15:06:48 +0100401 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine225010f2019-05-06 18:44:55 +0200402 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +0100403 * \retval #PSA_ERROR_BAD_STATE
404 * The library has not been previously initialized by psa_crypto_init().
405 * It is implementation-dependent whether a failure to initialize
406 * results in this error code.
Gilles Peskinef535eb22018-11-30 14:08:36 +0100407 */
Gilles Peskine225010f2019-05-06 18:44:55 +0200408psa_status_t psa_open_key(psa_key_id_t id,
Gilles Peskinef535eb22018-11-30 14:08:36 +0100409 psa_key_handle_t *handle);
410
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +0100411
Gilles Peskinef535eb22018-11-30 14:08:36 +0100412/** Close a key handle.
413 *
Andrew Thoelke3daba812019-08-21 22:46:56 +0100414 * If the handle designates a volatile key, this will destroy the key material
415 * and free all associated resources, just like psa_destroy_key().
Gilles Peskinef535eb22018-11-30 14:08:36 +0100416 *
Andrew Thoelke3daba812019-08-21 22:46:56 +0100417 * If this is the last open handle to a persistent key, then closing the handle
418 * will free all resources associated with the key in volatile memory. The key
419 * data in persistent storage is not affected and can be opened again later
420 * with a call to psa_open_key().
Gilles Peskinef535eb22018-11-30 14:08:36 +0100421 *
Andrew Thoelke3daba812019-08-21 22:46:56 +0100422 * Closing the key handle makes the handle invalid, and the key handle
Andrew Thoelke8824dae2019-08-22 15:04:48 +0100423 * must not be used again by the application.
Andrew Thoelke3daba812019-08-21 22:46:56 +0100424 *
425 * If the key is currently in use in a multipart operation, then closing the
Andrew Thoelke8824dae2019-08-22 15:04:48 +0100426 * last remaining handle to the key will abort the multipart operation.
Gilles Peskine5f25dd02019-01-14 18:24:53 +0100427 *
Gilles Peskinef535eb22018-11-30 14:08:36 +0100428 * \param handle The key handle to close.
429 *
430 * \retval #PSA_SUCCESS
431 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskineae32aac2018-11-30 14:39:32 +0100432 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
Adrian L. Shawf97c8522019-08-15 13:27:12 +0100433 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +0100434 * \retval #PSA_ERROR_BAD_STATE
435 * The library has not been previously initialized by psa_crypto_init().
436 * It is implementation-dependent whether a failure to initialize
437 * results in this error code.
Gilles Peskinef535eb22018-11-30 14:08:36 +0100438 */
439psa_status_t psa_close_key(psa_key_handle_t handle);
440
Gilles Peskine3cac8c42018-11-30 14:07:45 +0100441/**@}*/
442
443/** \defgroup import_export Key import and export
444 * @{
445 */
446
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100447/**
448 * \brief Import a key in binary format.
449 *
Gilles Peskinef5b9fa12018-03-07 16:40:18 +0100450 * This function supports any output from psa_export_key(). Refer to the
Gilles Peskinef7933932018-10-31 14:07:52 +0100451 * documentation of psa_export_public_key() for the format of public keys
452 * and to the documentation of psa_export_key() for the format for
453 * other key types.
454 *
455 * This specification supports a single format for each key type.
456 * Implementations may support other formats as long as the standard
457 * format is supported. Implementations that support other formats
458 * should ensure that the formats are clearly unambiguous so as to
459 * minimize the risk that an invalid input is accidentally interpreted
460 * according to a different format.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100461 *
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +0100462
Gilles Peskine20628592019-04-19 19:29:50 +0200463 * \param[in] attributes The attributes for the new key.
Gilles Peskine4ce2a9d2019-05-03 16:57:15 +0200464 * The key size is always determined from the
465 * \p data buffer.
466 * If the key size in \p attributes is nonzero,
467 * it must be equal to the size from \p data.
Gilles Peskine20628592019-04-19 19:29:50 +0200468 * \param[out] handle On success, a handle to the newly created key.
469 * \c 0 on failure.
Gilles Peskinef7933932018-10-31 14:07:52 +0100470 * \param[in] data Buffer containing the key data. The content of this
Gilles Peskine24f10f82019-05-16 12:18:32 +0200471 * buffer is interpreted according to the type declared
472 * in \p attributes.
Gilles Peskine20628592019-04-19 19:29:50 +0200473 * All implementations must support at least the format
474 * described in the documentation
Gilles Peskinef7933932018-10-31 14:07:52 +0100475 * of psa_export_key() or psa_export_public_key() for
Gilles Peskine20628592019-04-19 19:29:50 +0200476 * the chosen type. Implementations may allow other
477 * formats, but should be conservative: implementations
478 * should err on the side of rejecting content if it
479 * may be erroneous (e.g. wrong type or truncated data).
Gilles Peskinefa4070c2018-07-12 19:23:03 +0200480 * \param data_length Size of the \p data buffer in bytes.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100481 *
Gilles Peskine28538492018-07-11 17:34:00 +0200482 * \retval #PSA_SUCCESS
Gilles Peskine308b91d2018-02-08 09:47:44 +0100483 * Success.
Gilles Peskine23fd2bd2018-12-11 15:51:32 +0100484 * If the key is persistent, the key material and the key's metadata
485 * have been saved to persistent storage.
Gilles Peskine20628592019-04-19 19:29:50 +0200486 * \retval #PSA_ERROR_ALREADY_EXISTS
487 * This is an attempt to create a persistent key, and there is
488 * already a persistent key with the given identifier.
Gilles Peskine28538492018-07-11 17:34:00 +0200489 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskine65eb8582018-04-19 08:28:58 +0200490 * The key type or key size is not supported, either by the
Gilles Peskine20628592019-04-19 19:29:50 +0200491 * implementation in general or in this particular persistent location.
Gilles Peskine28538492018-07-11 17:34:00 +0200492 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine4ce2a9d2019-05-03 16:57:15 +0200493 * The key attributes, as a whole, are invalid.
494 * \retval #PSA_ERROR_INVALID_ARGUMENT
495 * The key data is not correctly formatted.
496 * \retval #PSA_ERROR_INVALID_ARGUMENT
497 * The size in \p attributes is nonzero and does not match the size
498 * of the key data.
Gilles Peskine28538492018-07-11 17:34:00 +0200499 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
500 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
501 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
Darryl Greend49a4992018-06-18 17:27:26 +0100502 * \retval #PSA_ERROR_STORAGE_FAILURE
Gilles Peskine28538492018-07-11 17:34:00 +0200503 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +0200504 * \retval #PSA_ERROR_CORRUPTION_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +0300505 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +0300506 * The library has not been previously initialized by psa_crypto_init().
507 * It is implementation-dependent whether a failure to initialize
508 * results in this error code.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100509 */
Gilles Peskine87a5e562019-04-17 12:28:25 +0200510psa_status_t psa_import_key(const psa_key_attributes_t *attributes,
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100511 const uint8_t *data,
Gilles Peskine73676cb2019-05-15 20:15:10 +0200512 size_t data_length,
513 psa_key_handle_t *handle);
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100514
515/**
Gilles Peskineae32aac2018-11-30 14:39:32 +0100516 * \brief Destroy a key.
Gilles Peskine154bd952018-04-19 08:38:16 +0200517 *
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +0100518 * This function destroys a key from both volatile
Gilles Peskine154bd952018-04-19 08:38:16 +0200519 * memory and, if applicable, non-volatile storage. Implementations shall
Adrian L. Shawd56456c2019-05-15 11:36:13 +0100520 * make a best effort to ensure that that the key material cannot be recovered.
Gilles Peskine154bd952018-04-19 08:38:16 +0200521 *
Gilles Peskineae32aac2018-11-30 14:39:32 +0100522 * This function also erases any metadata such as policies and frees all
523 * resources associated with the key.
Gilles Peskine154bd952018-04-19 08:38:16 +0200524 *
Andrew Thoelke07f16b72019-08-21 22:48:47 +0100525 * Destroying a key will invalidate all existing handles to the key.
526 *
527 * If the key is currently in use in a multipart operation, then destroying the
528 * key will abort the multipart operation.
529 *
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +0100530 * \param handle Handle to the key to erase.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100531 *
Gilles Peskine28538492018-07-11 17:34:00 +0200532 * \retval #PSA_SUCCESS
Adrian L. Shawd56456c2019-05-15 11:36:13 +0100533 * The key material has been erased.
Gilles Peskine28538492018-07-11 17:34:00 +0200534 * \retval #PSA_ERROR_NOT_PERMITTED
Adrian L. Shaw0a695bd2019-05-15 13:28:41 +0100535 * The key cannot be erased because it is
Gilles Peskine65eb8582018-04-19 08:28:58 +0200536 * read-only, either due to a policy or due to physical restrictions.
Gilles Peskineae32aac2018-11-30 14:39:32 +0100537 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine28538492018-07-11 17:34:00 +0200538 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
Gilles Peskine65eb8582018-04-19 08:28:58 +0200539 * There was an failure in communication with the cryptoprocessor.
540 * The key material may still be present in the cryptoprocessor.
Gilles Peskine28538492018-07-11 17:34:00 +0200541 * \retval #PSA_ERROR_STORAGE_FAILURE
Gilles Peskine65eb8582018-04-19 08:28:58 +0200542 * The storage is corrupted. Implementations shall make a best effort
543 * to erase key material even in this stage, however applications
544 * should be aware that it may be impossible to guarantee that the
545 * key material is not recoverable in such cases.
Gilles Peskine4b3eb692019-05-16 21:35:18 +0200546 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine65eb8582018-04-19 08:28:58 +0200547 * An unexpected condition which is not a storage corruption or
548 * a communication failure occurred. The cryptoprocessor may have
549 * been compromised.
itayzafrir90d8c7a2018-09-12 11:44:52 +0300550 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +0300551 * The library has not been previously initialized by psa_crypto_init().
552 * It is implementation-dependent whether a failure to initialize
553 * results in this error code.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100554 */
Gilles Peskineae32aac2018-11-30 14:39:32 +0100555psa_status_t psa_destroy_key(psa_key_handle_t handle);
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100556
557/**
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100558 * \brief Export a key in binary format.
559 *
560 * The output of this function can be passed to psa_import_key() to
561 * create an equivalent object.
562 *
Gilles Peskinef7933932018-10-31 14:07:52 +0100563 * If the implementation of psa_import_key() supports other formats
564 * beyond the format specified here, the output from psa_export_key()
565 * must use the representation specified here, not the original
566 * representation.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100567 *
Gilles Peskine308b91d2018-02-08 09:47:44 +0100568 * For standard key types, the output format is as follows:
569 *
570 * - For symmetric keys (including MAC keys), the format is the
571 * raw bytes of the key.
572 * - For DES, the key data consists of 8 bytes. The parity bits must be
573 * correct.
574 * - For Triple-DES, the format is the concatenation of the
575 * two or three DES keys.
Gilles Peskinec93b80c2019-05-16 19:39:54 +0200576 * - For RSA key pairs (#PSA_KEY_TYPE_RSA_KEY_PAIR), the format
Gilles Peskine4e1e9be2018-08-10 18:57:40 +0200577 * is the non-encrypted DER encoding of the representation defined by
578 * PKCS\#1 (RFC 8017) as `RSAPrivateKey`, version 0.
579 * ```
580 * RSAPrivateKey ::= SEQUENCE {
Gilles Peskine4f6c77b2018-08-11 01:17:53 +0200581 * version INTEGER, -- must be 0
Gilles Peskine4e1e9be2018-08-10 18:57:40 +0200582 * modulus INTEGER, -- n
583 * publicExponent INTEGER, -- e
584 * privateExponent INTEGER, -- d
585 * prime1 INTEGER, -- p
586 * prime2 INTEGER, -- q
587 * exponent1 INTEGER, -- d mod (p-1)
588 * exponent2 INTEGER, -- d mod (q-1)
589 * coefficient INTEGER, -- (inverse of q) mod p
590 * }
591 * ```
Gilles Peskine4e1e9be2018-08-10 18:57:40 +0200592 * - For elliptic curve key pairs (key types for which
Gilles Peskinec93b80c2019-05-16 19:39:54 +0200593 * #PSA_KEY_TYPE_IS_ECC_KEY_PAIR is true), the format is
Gilles Peskine6c6a0232018-11-15 17:44:43 +0100594 * a representation of the private value as a `ceiling(m/8)`-byte string
595 * where `m` is the bit size associated with the curve, i.e. the bit size
596 * of the order of the curve's coordinate field. This byte string is
597 * in little-endian order for Montgomery curves (curve types
598 * `PSA_ECC_CURVE_CURVEXXX`), and in big-endian order for Weierstrass
599 * curves (curve types `PSA_ECC_CURVE_SECTXXX`, `PSA_ECC_CURVE_SECPXXX`
600 * and `PSA_ECC_CURVE_BRAINPOOL_PXXX`).
Gilles Peskinef76aa772018-10-29 19:24:33 +0100601 * This is the content of the `privateKey` field of the `ECPrivateKey`
602 * format defined by RFC 5915.
Gilles Peskinedcaefae2019-05-16 12:55:35 +0200603 * - For Diffie-Hellman key exchange key pairs (key types for which
Gilles Peskinec93b80c2019-05-16 19:39:54 +0200604 * #PSA_KEY_TYPE_IS_DH_KEY_PAIR is true), the
Jaeden Amero8851c402019-01-11 14:20:03 +0000605 * format is the representation of the private key `x` as a big-endian byte
606 * string. The length of the byte string is the private key size in bytes
607 * (leading zeroes are not stripped).
Gilles Peskine4e1e9be2018-08-10 18:57:40 +0200608 * - For public keys (key types for which #PSA_KEY_TYPE_IS_PUBLIC_KEY is
609 * true), the format is the same as for psa_export_public_key().
Gilles Peskine308b91d2018-02-08 09:47:44 +0100610 *
Gilles Peskine4318dfc2019-05-14 14:23:32 +0200611 * The policy on the key must have the usage flag #PSA_KEY_USAGE_EXPORT set.
612 *
Gilles Peskineae32aac2018-11-30 14:39:32 +0100613 * \param handle Handle to the key to export.
Gilles Peskineedd11a12018-07-12 01:08:58 +0200614 * \param[out] data Buffer where the key data is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +0200615 * \param data_size Size of the \p data buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +0200616 * \param[out] data_length On success, the number of bytes
617 * that make up the key data.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100618 *
Gilles Peskine28538492018-07-11 17:34:00 +0200619 * \retval #PSA_SUCCESS
Gilles Peskineae32aac2018-11-30 14:39:32 +0100620 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine28538492018-07-11 17:34:00 +0200621 * \retval #PSA_ERROR_NOT_PERMITTED
Gilles Peskine4318dfc2019-05-14 14:23:32 +0200622 * The key does not have the #PSA_KEY_USAGE_EXPORT flag.
Darryl Green9e2d7a02018-07-24 16:33:30 +0100623 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskine1be949b2018-08-10 19:06:59 +0200624 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
625 * The size of the \p data buffer is too small. You can determine a
626 * sufficient buffer size by calling
627 * #PSA_KEY_EXPORT_MAX_SIZE(\c type, \c bits)
628 * where \c type is the key type
629 * and \c bits is the key size in bits.
Gilles Peskine28538492018-07-11 17:34:00 +0200630 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
631 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +0200632 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw89b71522019-08-06 16:21:00 +0100633 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shaw0542d592019-08-06 16:34:44 +0100634 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
itayzafrir90d8c7a2018-09-12 11:44:52 +0300635 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +0300636 * The library has not been previously initialized by psa_crypto_init().
637 * It is implementation-dependent whether a failure to initialize
638 * results in this error code.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100639 */
Gilles Peskineae32aac2018-11-30 14:39:32 +0100640psa_status_t psa_export_key(psa_key_handle_t handle,
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100641 uint8_t *data,
642 size_t data_size,
643 size_t *data_length);
644
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100645/**
646 * \brief Export a public key or the public part of a key pair in binary format.
647 *
648 * The output of this function can be passed to psa_import_key() to
649 * create an object that is equivalent to the public key.
650 *
Jaeden Amerod3a0c2c2019-01-11 17:15:56 +0000651 * This specification supports a single format for each key type.
652 * Implementations may support other formats as long as the standard
653 * format is supported. Implementations that support other formats
654 * should ensure that the formats are clearly unambiguous so as to
655 * minimize the risk that an invalid input is accidentally interpreted
656 * according to a different format.
657 *
Jaeden Amero6b196002019-01-10 10:23:21 +0000658 * For standard key types, the output format is as follows:
659 * - For RSA public keys (#PSA_KEY_TYPE_RSA_PUBLIC_KEY), the DER encoding of
660 * the representation defined by RFC 3279 &sect;2.3.1 as `RSAPublicKey`.
661 * ```
662 * RSAPublicKey ::= SEQUENCE {
663 * modulus INTEGER, -- n
664 * publicExponent INTEGER } -- e
665 * ```
Jaeden Amero0ae445f2019-01-10 11:42:27 +0000666 * - For elliptic curve public keys (key types for which
667 * #PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY is true), the format is the uncompressed
668 * representation defined by SEC1 &sect;2.3.3 as the content of an ECPoint.
669 * Let `m` be the bit size associated with the curve, i.e. the bit size of
670 * `q` for a curve over `F_q`. The representation consists of:
671 * - The byte 0x04;
672 * - `x_P` as a `ceiling(m/8)`-byte string, big-endian;
673 * - `y_P` as a `ceiling(m/8)`-byte string, big-endian.
Gilles Peskinedcaefae2019-05-16 12:55:35 +0200674 * - For Diffie-Hellman key exchange public keys (key types for which
675 * #PSA_KEY_TYPE_IS_DH_PUBLIC_KEY is true),
Jaeden Amero8851c402019-01-11 14:20:03 +0000676 * the format is the representation of the public key `y = g^x mod p` as a
677 * big-endian byte string. The length of the byte string is the length of the
678 * base prime `p` in bytes.
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100679 *
Gilles Peskine4318dfc2019-05-14 14:23:32 +0200680 * Exporting a public key object or the public part of a key pair is
681 * always permitted, regardless of the key's usage flags.
682 *
Gilles Peskineae32aac2018-11-30 14:39:32 +0100683 * \param handle Handle to the key to export.
Gilles Peskineedd11a12018-07-12 01:08:58 +0200684 * \param[out] data Buffer where the key data is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +0200685 * \param data_size Size of the \p data buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +0200686 * \param[out] data_length On success, the number of bytes
687 * that make up the key data.
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100688 *
Gilles Peskine28538492018-07-11 17:34:00 +0200689 * \retval #PSA_SUCCESS
Gilles Peskineae32aac2018-11-30 14:39:32 +0100690 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine28538492018-07-11 17:34:00 +0200691 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine1be949b2018-08-10 19:06:59 +0200692 * The key is neither a public key nor a key pair.
693 * \retval #PSA_ERROR_NOT_SUPPORTED
694 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
695 * The size of the \p data buffer is too small. You can determine a
696 * sufficient buffer size by calling
Gilles Peskinec93b80c2019-05-16 19:39:54 +0200697 * #PSA_KEY_EXPORT_MAX_SIZE(#PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(\c type), \c bits)
Gilles Peskine1be949b2018-08-10 19:06:59 +0200698 * where \c type is the key type
699 * and \c bits is the key size in bits.
Gilles Peskine28538492018-07-11 17:34:00 +0200700 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
701 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +0200702 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw398b3c22019-08-06 17:22:41 +0100703 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shaw88c51ad2019-08-06 17:09:33 +0100704 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
itayzafrir90d8c7a2018-09-12 11:44:52 +0300705 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +0300706 * The library has not been previously initialized by psa_crypto_init().
707 * It is implementation-dependent whether a failure to initialize
708 * results in this error code.
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100709 */
Gilles Peskineae32aac2018-11-30 14:39:32 +0100710psa_status_t psa_export_public_key(psa_key_handle_t handle,
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100711 uint8_t *data,
712 size_t data_size,
713 size_t *data_length);
714
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100715/** Make a copy of a key.
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100716 *
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100717 * Copy key material from one location to another.
Jaeden Amero70261c52019-01-04 11:47:20 +0000718 *
Gilles Peskineaec5a7f2019-02-05 20:26:09 +0100719 * This function is primarily useful to copy a key from one location
720 * to another, since it populates a key using the material from
721 * another key which may have a different lifetime.
Gilles Peskine6ac73a92018-07-12 19:47:19 +0200722 *
Adrian L. Shaw0a695bd2019-05-15 13:28:41 +0100723 * This function may be used to share a key with a different party,
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100724 * subject to implementation-defined restrictions on key sharing.
Gilles Peskine7e198532018-03-08 07:50:30 +0100725 *
Gilles Peskine8e0206a2019-05-14 14:24:28 +0200726 * The policy on the source key must have the usage flag
727 * #PSA_KEY_USAGE_COPY set.
Gilles Peskined6a8f5f2019-05-14 16:25:50 +0200728 * This flag is sufficient to permit the copy if the key has the lifetime
729 * #PSA_KEY_LIFETIME_VOLATILE or #PSA_KEY_LIFETIME_PERSISTENT.
730 * Some secure elements do not provide a way to copy a key without
731 * making it extractable from the secure element. If a key is located
732 * in such a secure element, then the key must have both usage flags
733 * #PSA_KEY_USAGE_COPY and #PSA_KEY_USAGE_EXPORT in order to make
734 * a copy of the key outside the secure element.
Gilles Peskine8e0206a2019-05-14 14:24:28 +0200735 *
Gilles Peskine20628592019-04-19 19:29:50 +0200736 * The resulting key may only be used in a way that conforms to
737 * both the policy of the original key and the policy specified in
738 * the \p attributes parameter:
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100739 * - The usage flags on the resulting key are the bitwise-and of the
Gilles Peskine20628592019-04-19 19:29:50 +0200740 * usage flags on the source policy and the usage flags in \p attributes.
741 * - If both allow the same algorithm or wildcard-based
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100742 * algorithm policy, the resulting key has the same algorithm policy.
Gilles Peskine20628592019-04-19 19:29:50 +0200743 * - If either of the policies allows an algorithm and the other policy
744 * allows a wildcard-based algorithm policy that includes this algorithm,
745 * the resulting key allows the same algorithm.
746 * - If the policies do not allow any algorithm in common, this function
747 * fails with the status #PSA_ERROR_INVALID_ARGUMENT.
Gilles Peskine6ac73a92018-07-12 19:47:19 +0200748 *
Gilles Peskine20628592019-04-19 19:29:50 +0200749 * The effect of this function on implementation-defined attributes is
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100750 * implementation-defined.
Gilles Peskine6ac73a92018-07-12 19:47:19 +0200751 *
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +0100752 * \param source_handle The key to copy. It must be a valid key handle.
Gilles Peskine20628592019-04-19 19:29:50 +0200753 * \param[in] attributes The attributes for the new key.
754 * They are used as follows:
Gilles Peskine4ce2a9d2019-05-03 16:57:15 +0200755 * - The key type and size may be 0. If either is
756 * nonzero, it must match the corresponding
757 * attribute of the source key.
Gilles Peskine20628592019-04-19 19:29:50 +0200758 * - The key location (the lifetime and, for
759 * persistent keys, the key identifier) is
760 * used directly.
761 * - The policy constraints (usage flags and
762 * algorithm policy) are combined from
763 * the source key and \p attributes so that
764 * both sets of restrictions apply, as
765 * described in the documentation of this function.
766 * \param[out] target_handle On success, a handle to the newly created key.
767 * \c 0 on failure.
Gilles Peskine6ac73a92018-07-12 19:47:19 +0200768 *
769 * \retval #PSA_SUCCESS
Gilles Peskineae32aac2018-11-30 14:39:32 +0100770 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine20628592019-04-19 19:29:50 +0200771 * \p source_handle is invalid.
David Saadab4ecc272019-02-14 13:48:10 +0200772 * \retval #PSA_ERROR_ALREADY_EXISTS
Gilles Peskine20628592019-04-19 19:29:50 +0200773 * This is an attempt to create a persistent key, and there is
774 * already a persistent key with the given identifier.
Gilles Peskine6ac73a92018-07-12 19:47:19 +0200775 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine20628592019-04-19 19:29:50 +0200776 * The lifetime or identifier in \p attributes are invalid.
777 * \retval #PSA_ERROR_INVALID_ARGUMENT
778 * The policy constraints on the source and specified in
779 * \p attributes are incompatible.
Gilles Peskine4ce2a9d2019-05-03 16:57:15 +0200780 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine24f10f82019-05-16 12:18:32 +0200781 * \p attributes specifies a key type or key size
Gilles Peskine4ce2a9d2019-05-03 16:57:15 +0200782 * which does not match the attributes of the source key.
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100783 * \retval #PSA_ERROR_NOT_PERMITTED
Gilles Peskine8e0206a2019-05-14 14:24:28 +0200784 * The source key does not have the #PSA_KEY_USAGE_COPY usage flag.
785 * \retval #PSA_ERROR_NOT_PERMITTED
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100786 * The source key is not exportable and its lifetime does not
787 * allow copying it to the target's lifetime.
788 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
789 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
Gilles Peskine6ac73a92018-07-12 19:47:19 +0200790 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
791 * \retval #PSA_ERROR_HARDWARE_FAILURE
Adrian L. Shaw60b03202019-08-06 17:26:16 +0100792 * \retval #PSA_ERROR_STORAGE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +0200793 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +0100794 * \retval #PSA_ERROR_BAD_STATE
795 * The library has not been previously initialized by psa_crypto_init().
796 * It is implementation-dependent whether a failure to initialize
797 * results in this error code.
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100798 */
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100799psa_status_t psa_copy_key(psa_key_handle_t source_handle,
Gilles Peskine87a5e562019-04-17 12:28:25 +0200800 const psa_key_attributes_t *attributes,
801 psa_key_handle_t *target_handle);
Gilles Peskine20035e32018-02-03 22:44:14 +0100802
803/**@}*/
804
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100805/** \defgroup hash Message digests
806 * @{
807 */
808
Gilles Peskine69647a42019-01-14 20:18:12 +0100809/** Calculate the hash (digest) of a message.
810 *
811 * \note To verify the hash of a message against an
812 * expected value, use psa_hash_compare() instead.
813 *
814 * \param alg The hash algorithm to compute (\c PSA_ALG_XXX value
815 * such that #PSA_ALG_IS_HASH(\p alg) is true).
816 * \param[in] input Buffer containing the message to hash.
817 * \param input_length Size of the \p input buffer in bytes.
818 * \param[out] hash Buffer where the hash is to be written.
819 * \param hash_size Size of the \p hash buffer in bytes.
820 * \param[out] hash_length On success, the number of bytes
821 * that make up the hash value. This is always
Gilles Peskined338b912019-02-15 13:01:41 +0100822 * #PSA_HASH_SIZE(\p alg).
Gilles Peskine69647a42019-01-14 20:18:12 +0100823 *
824 * \retval #PSA_SUCCESS
825 * Success.
826 * \retval #PSA_ERROR_NOT_SUPPORTED
827 * \p alg is not supported or is not a hash algorithm.
Adrian L. Shawf7d852a2019-08-06 17:50:26 +0100828 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
829 * \p hash_size is too small
Gilles Peskine69647a42019-01-14 20:18:12 +0100830 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
831 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
832 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +0200833 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw15731c12019-08-06 16:21:00 +0100834 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shaw7f1863c2019-08-06 16:34:44 +0100835 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
Adrian L. Shawdec47b62019-08-07 14:25:38 +0100836 * \retval #PSA_ERROR_BAD_STATE
837 * The library has not been previously initialized by psa_crypto_init().
838 * It is implementation-dependent whether a failure to initialize
839 * results in this error code.
Gilles Peskine69647a42019-01-14 20:18:12 +0100840 */
841psa_status_t psa_hash_compute(psa_algorithm_t alg,
842 const uint8_t *input,
843 size_t input_length,
844 uint8_t *hash,
845 size_t hash_size,
846 size_t *hash_length);
847
848/** Calculate the hash (digest) of a message and compare it with a
849 * reference value.
850 *
851 * \param alg The hash algorithm to compute (\c PSA_ALG_XXX value
852 * such that #PSA_ALG_IS_HASH(\p alg) is true).
853 * \param[in] input Buffer containing the message to hash.
854 * \param input_length Size of the \p input buffer in bytes.
855 * \param[out] hash Buffer containing the expected hash value.
Gilles Peskinea05602d2019-01-17 15:25:52 +0100856 * \param hash_length Size of the \p hash buffer in bytes.
Gilles Peskine69647a42019-01-14 20:18:12 +0100857 *
858 * \retval #PSA_SUCCESS
859 * The expected hash is identical to the actual hash of the input.
860 * \retval #PSA_ERROR_INVALID_SIGNATURE
861 * The hash of the message was calculated successfully, but it
862 * differs from the expected hash.
863 * \retval #PSA_ERROR_NOT_SUPPORTED
864 * \p alg is not supported or is not a hash algorithm.
Adrian L. Shaw8d0bcf22019-08-13 11:36:29 +0100865 * \retval #PSA_ERROR_INVALID_ARGUMENT
866 * \p input_length or \p hash_length do not match the hash size for \p alg
Gilles Peskine69647a42019-01-14 20:18:12 +0100867 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
868 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
869 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +0200870 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw11638b92019-08-06 17:09:33 +0100871 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
Adrian L. Shawdec47b62019-08-07 14:25:38 +0100872 * \retval #PSA_ERROR_BAD_STATE
873 * The library has not been previously initialized by psa_crypto_init().
874 * It is implementation-dependent whether a failure to initialize
875 * results in this error code.
Gilles Peskine69647a42019-01-14 20:18:12 +0100876 */
877psa_status_t psa_hash_compare(psa_algorithm_t alg,
878 const uint8_t *input,
879 size_t input_length,
880 const uint8_t *hash,
881 const size_t hash_length);
882
Gilles Peskine308b91d2018-02-08 09:47:44 +0100883/** The type of the state data structure for multipart hash operations.
884 *
Jaeden Amero6a25b412019-01-04 11:47:44 +0000885 * Before calling any function on a hash operation object, the application must
886 * initialize it by any of the following means:
887 * - Set the structure to all-bits-zero, for example:
888 * \code
889 * psa_hash_operation_t operation;
890 * memset(&operation, 0, sizeof(operation));
891 * \endcode
892 * - Initialize the structure to logical zero values, for example:
893 * \code
894 * psa_hash_operation_t operation = {0};
895 * \endcode
896 * - Initialize the structure to the initializer #PSA_HASH_OPERATION_INIT,
897 * for example:
898 * \code
899 * psa_hash_operation_t operation = PSA_HASH_OPERATION_INIT;
900 * \endcode
901 * - Assign the result of the function psa_hash_operation_init()
902 * to the structure, for example:
903 * \code
904 * psa_hash_operation_t operation;
905 * operation = psa_hash_operation_init();
906 * \endcode
907 *
Gilles Peskine92b30732018-03-03 21:29:30 +0100908 * This is an implementation-defined \c struct. Applications should not
Gilles Peskine308b91d2018-02-08 09:47:44 +0100909 * make any assumptions about the content of this structure except
910 * as directed by the documentation of a specific implementation. */
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100911typedef struct psa_hash_operation_s psa_hash_operation_t;
912
Jaeden Amero6a25b412019-01-04 11:47:44 +0000913/** \def PSA_HASH_OPERATION_INIT
914 *
915 * This macro returns a suitable initializer for a hash operation object
916 * of type #psa_hash_operation_t.
917 */
918#ifdef __DOXYGEN_ONLY__
919/* This is an example definition for documentation purposes.
920 * Implementations should define a suitable value in `crypto_struct.h`.
921 */
922#define PSA_HASH_OPERATION_INIT {0}
923#endif
924
925/** Return an initial value for a hash operation object.
926 */
927static psa_hash_operation_t psa_hash_operation_init(void);
928
Gilles Peskinef45adda2019-01-14 18:29:18 +0100929/** Set up a multipart hash operation.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100930 *
931 * The sequence of operations to calculate a hash (message digest)
932 * is as follows:
933 * -# Allocate an operation object which will be passed to all the functions
934 * listed here.
Jaeden Amero6a25b412019-01-04 11:47:44 +0000935 * -# Initialize the operation object with one of the methods described in the
936 * documentation for #psa_hash_operation_t, e.g. PSA_HASH_OPERATION_INIT.
Gilles Peskineda8191d1c2018-07-08 19:46:38 +0200937 * -# Call psa_hash_setup() to specify the algorithm.
Gilles Peskine7e4acc52018-02-16 21:24:11 +0100938 * -# Call psa_hash_update() zero, one or more times, passing a fragment
Gilles Peskine308b91d2018-02-08 09:47:44 +0100939 * of the message each time. The hash that is calculated is the hash
940 * of the concatenation of these messages in order.
941 * -# To calculate the hash, call psa_hash_finish().
942 * To compare the hash with an expected value, call psa_hash_verify().
943 *
944 * The application may call psa_hash_abort() at any time after the operation
Jaeden Amero6a25b412019-01-04 11:47:44 +0000945 * has been initialized.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100946 *
Gilles Peskineda8191d1c2018-07-08 19:46:38 +0200947 * After a successful call to psa_hash_setup(), the application must
Gilles Peskineed522972018-03-20 17:54:15 +0100948 * eventually terminate the operation. The following events terminate an
949 * operation:
Gilles Peskine308b91d2018-02-08 09:47:44 +0100950 * - A failed call to psa_hash_update().
Gilles Peskine19067982018-03-20 17:54:53 +0100951 * - A call to psa_hash_finish(), psa_hash_verify() or psa_hash_abort().
Gilles Peskine308b91d2018-02-08 09:47:44 +0100952 *
Jaeden Amero6a25b412019-01-04 11:47:44 +0000953 * \param[in,out] operation The operation object to set up. It must have
954 * been initialized as per the documentation for
955 * #psa_hash_operation_t and not yet in use.
Gilles Peskineedd11a12018-07-12 01:08:58 +0200956 * \param alg The hash algorithm to compute (\c PSA_ALG_XXX value
957 * such that #PSA_ALG_IS_HASH(\p alg) is true).
Gilles Peskine308b91d2018-02-08 09:47:44 +0100958 *
Gilles Peskine28538492018-07-11 17:34:00 +0200959 * \retval #PSA_SUCCESS
Gilles Peskine308b91d2018-02-08 09:47:44 +0100960 * Success.
Gilles Peskine28538492018-07-11 17:34:00 +0200961 * \retval #PSA_ERROR_NOT_SUPPORTED
Adrian L. Shawfbf7f122019-08-15 13:34:51 +0100962 * \p alg is not a supported hash algorithm.
963 * \retval #PSA_ERROR_INVALID_ARGUMENT
964 * \p alg is not a hash algorithm.
Gilles Peskine8e1addc2019-01-10 11:51:17 +0100965 * \retval #PSA_ERROR_BAD_STATE
966 * The operation state is not valid (already set up and not
967 * subsequently completed).
Gilles Peskine28538492018-07-11 17:34:00 +0200968 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
969 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
970 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +0200971 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +0100972 * \retval #PSA_ERROR_BAD_STATE
Adrian L. Shawe970d652019-08-08 14:40:04 +0100973 * \p operation is either not initialized or is in use
974 * \retval #PSA_ERROR_BAD_STATE
Adrian L. Shawdec47b62019-08-07 14:25:38 +0100975 * The library has not been previously initialized by psa_crypto_init().
976 * It is implementation-dependent whether a failure to initialize
977 * results in this error code.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100978 */
Gilles Peskineda8191d1c2018-07-08 19:46:38 +0200979psa_status_t psa_hash_setup(psa_hash_operation_t *operation,
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100980 psa_algorithm_t alg);
981
Gilles Peskine308b91d2018-02-08 09:47:44 +0100982/** Add a message fragment to a multipart hash operation.
983 *
Gilles Peskineda8191d1c2018-07-08 19:46:38 +0200984 * The application must call psa_hash_setup() before calling this function.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100985 *
986 * If this function returns an error status, the operation becomes inactive.
987 *
Gilles Peskineedd11a12018-07-12 01:08:58 +0200988 * \param[in,out] operation Active hash operation.
989 * \param[in] input Buffer containing the message fragment to hash.
Gilles Peskinefa4070c2018-07-12 19:23:03 +0200990 * \param input_length Size of the \p input buffer in bytes.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100991 *
Gilles Peskine28538492018-07-11 17:34:00 +0200992 * \retval #PSA_SUCCESS
Gilles Peskine308b91d2018-02-08 09:47:44 +0100993 * Success.
Gilles Peskine28538492018-07-11 17:34:00 +0200994 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +0100995 * The operation state is not valid (not set up, or already completed).
Gilles Peskine28538492018-07-11 17:34:00 +0200996 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
997 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
998 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +0200999 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001000 * \retval #PSA_ERROR_BAD_STATE
Adrian L. Shaw320659b2019-08-08 14:49:01 +01001001 * The operation state is not valid.
1002 * \retval #PSA_ERROR_BAD_STATE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001003 * The library has not been previously initialized by psa_crypto_init().
1004 * It is implementation-dependent whether a failure to initialize
1005 * results in this error code.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001006 */
Gilles Peskine9ef733f2018-02-07 21:05:37 +01001007psa_status_t psa_hash_update(psa_hash_operation_t *operation,
1008 const uint8_t *input,
1009 size_t input_length);
1010
Gilles Peskine308b91d2018-02-08 09:47:44 +01001011/** Finish the calculation of the hash of a message.
1012 *
Gilles Peskineda8191d1c2018-07-08 19:46:38 +02001013 * The application must call psa_hash_setup() before calling this function.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001014 * This function calculates the hash of the message formed by concatenating
1015 * the inputs passed to preceding calls to psa_hash_update().
1016 *
1017 * When this function returns, the operation becomes inactive.
1018 *
1019 * \warning Applications should not call this function if they expect
1020 * a specific value for the hash. Call psa_hash_verify() instead.
1021 * Beware that comparing integrity or authenticity data such as
1022 * hash values with a function such as \c memcmp is risky
1023 * because the time taken by the comparison may leak information
1024 * about the hashed data which could allow an attacker to guess
1025 * a valid hash and thereby bypass security controls.
1026 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001027 * \param[in,out] operation Active hash operation.
1028 * \param[out] hash Buffer where the hash is to be written.
1029 * \param hash_size Size of the \p hash buffer in bytes.
1030 * \param[out] hash_length On success, the number of bytes
1031 * that make up the hash value. This is always
Gilles Peskinebe42f312018-07-13 14:38:15 +02001032 * #PSA_HASH_SIZE(\c alg) where \c alg is the
Gilles Peskineedd11a12018-07-12 01:08:58 +02001033 * hash algorithm that is calculated.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001034 *
Gilles Peskine28538492018-07-11 17:34:00 +02001035 * \retval #PSA_SUCCESS
Gilles Peskine308b91d2018-02-08 09:47:44 +01001036 * Success.
Gilles Peskine28538492018-07-11 17:34:00 +02001037 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001038 * The operation state is not valid (not set up, or already completed).
Gilles Peskine28538492018-07-11 17:34:00 +02001039 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001040 * The size of the \p hash buffer is too small. You can determine a
Gilles Peskine7256e6c2018-07-12 00:34:26 +02001041 * sufficient buffer size by calling #PSA_HASH_SIZE(\c alg)
Gilles Peskine308b91d2018-02-08 09:47:44 +01001042 * where \c alg is the hash algorithm that is calculated.
Gilles Peskine28538492018-07-11 17:34:00 +02001043 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1044 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1045 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001046 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001047 * \retval #PSA_ERROR_BAD_STATE
Adrian L. Shaw320659b2019-08-08 14:49:01 +01001048 * The operation state is not valid.
1049 * \retval #PSA_ERROR_BAD_STATE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001050 * The library has not been previously initialized by psa_crypto_init().
1051 * It is implementation-dependent whether a failure to initialize
1052 * results in this error code.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001053 */
Gilles Peskine9ef733f2018-02-07 21:05:37 +01001054psa_status_t psa_hash_finish(psa_hash_operation_t *operation,
1055 uint8_t *hash,
1056 size_t hash_size,
1057 size_t *hash_length);
1058
Gilles Peskine308b91d2018-02-08 09:47:44 +01001059/** Finish the calculation of the hash of a message and compare it with
1060 * an expected value.
1061 *
Gilles Peskineda8191d1c2018-07-08 19:46:38 +02001062 * The application must call psa_hash_setup() before calling this function.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001063 * This function calculates the hash of the message formed by concatenating
1064 * the inputs passed to preceding calls to psa_hash_update(). It then
1065 * compares the calculated hash with the expected hash passed as a
1066 * parameter to this function.
1067 *
1068 * When this function returns, the operation becomes inactive.
1069 *
Gilles Peskine19067982018-03-20 17:54:53 +01001070 * \note Implementations shall make the best effort to ensure that the
Gilles Peskine308b91d2018-02-08 09:47:44 +01001071 * comparison between the actual hash and the expected hash is performed
1072 * in constant time.
1073 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001074 * \param[in,out] operation Active hash operation.
1075 * \param[in] hash Buffer containing the expected hash value.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001076 * \param hash_length Size of the \p hash buffer in bytes.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001077 *
Gilles Peskine28538492018-07-11 17:34:00 +02001078 * \retval #PSA_SUCCESS
Gilles Peskine308b91d2018-02-08 09:47:44 +01001079 * The expected hash is identical to the actual hash of the message.
Gilles Peskine28538492018-07-11 17:34:00 +02001080 * \retval #PSA_ERROR_INVALID_SIGNATURE
Gilles Peskine308b91d2018-02-08 09:47:44 +01001081 * The hash of the message was calculated successfully, but it
1082 * differs from the expected hash.
Gilles Peskine28538492018-07-11 17:34:00 +02001083 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001084 * The operation state is not valid (not set up, or already completed).
Gilles Peskine28538492018-07-11 17:34:00 +02001085 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1086 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1087 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001088 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001089 * \retval #PSA_ERROR_BAD_STATE
Adrian L. Shaw320659b2019-08-08 14:49:01 +01001090 * The operation state is not valid.
1091 * \retval #PSA_ERROR_BAD_STATE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001092 * The library has not been previously initialized by psa_crypto_init().
1093 * It is implementation-dependent whether a failure to initialize
1094 * results in this error code.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001095 */
Gilles Peskine9ef733f2018-02-07 21:05:37 +01001096psa_status_t psa_hash_verify(psa_hash_operation_t *operation,
1097 const uint8_t *hash,
1098 size_t hash_length);
1099
Gilles Peskine308b91d2018-02-08 09:47:44 +01001100/** Abort a hash operation.
1101 *
Gilles Peskine308b91d2018-02-08 09:47:44 +01001102 * Aborting an operation frees all associated resources except for the
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001103 * \p operation structure itself. Once aborted, the operation object
1104 * can be reused for another operation by calling
1105 * psa_hash_setup() again.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001106 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001107 * You may call this function any time after the operation object has
1108 * been initialized by any of the following methods:
1109 * - A call to psa_hash_setup(), whether it succeeds or not.
1110 * - Initializing the \c struct to all-bits-zero.
1111 * - Initializing the \c struct to logical zeros, e.g.
1112 * `psa_hash_operation_t operation = {0}`.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001113 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001114 * In particular, calling psa_hash_abort() after the operation has been
1115 * terminated by a call to psa_hash_abort(), psa_hash_finish() or
1116 * psa_hash_verify() is safe and has no effect.
1117 *
1118 * \param[in,out] operation Initialized hash operation.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001119 *
Gilles Peskine28538492018-07-11 17:34:00 +02001120 * \retval #PSA_SUCCESS
1121 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001122 * \p operation is not an active hash operation.
Gilles Peskine28538492018-07-11 17:34:00 +02001123 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1124 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001125 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001126 * \retval #PSA_ERROR_BAD_STATE
Adrian L. Shaw320659b2019-08-08 14:49:01 +01001127 * The operation state is not valid.
1128 * \retval #PSA_ERROR_BAD_STATE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001129 * The library has not been previously initialized by psa_crypto_init().
1130 * It is implementation-dependent whether a failure to initialize
1131 * results in this error code.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001132 */
1133psa_status_t psa_hash_abort(psa_hash_operation_t *operation);
Gilles Peskine9ef733f2018-02-07 21:05:37 +01001134
Gilles Peskineebb2c3e2019-01-19 12:03:41 +01001135/** Clone a hash operation.
1136 *
Gilles Peskinee43aa392019-01-21 14:50:37 +01001137 * This function copies the state of an ongoing hash operation to
1138 * a new operation object. In other words, this function is equivalent
1139 * to calling psa_hash_setup() on \p target_operation with the same
1140 * algorithm that \p source_operation was set up for, then
1141 * psa_hash_update() on \p target_operation with the same input that
1142 * that was passed to \p source_operation. After this function returns, the
1143 * two objects are independent, i.e. subsequent calls involving one of
1144 * the objects do not affect the other object.
1145 *
Gilles Peskineebb2c3e2019-01-19 12:03:41 +01001146 * \param[in] source_operation The active hash operation to clone.
1147 * \param[in,out] target_operation The operation object to set up.
1148 * It must be initialized but not active.
1149 *
1150 * \retval #PSA_SUCCESS
1151 * \retval #PSA_ERROR_BAD_STATE
1152 * \p source_operation is not an active hash operation.
1153 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinee43aa392019-01-21 14:50:37 +01001154 * \p target_operation is active.
Gilles Peskineebb2c3e2019-01-19 12:03:41 +01001155 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1156 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001157 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawd789dc12019-08-12 15:06:48 +01001158 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001159 * \retval #PSA_ERROR_BAD_STATE
Adrian L. Shaw320659b2019-08-08 14:49:01 +01001160 * The operation state is either not initialized or has already been setup.
1161 * \retval #PSA_ERROR_BAD_STATE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001162 * The library has not been previously initialized by psa_crypto_init().
1163 * It is implementation-dependent whether a failure to initialize
1164 * results in this error code.
Gilles Peskineebb2c3e2019-01-19 12:03:41 +01001165 */
1166psa_status_t psa_hash_clone(const psa_hash_operation_t *source_operation,
1167 psa_hash_operation_t *target_operation);
1168
Gilles Peskine9ef733f2018-02-07 21:05:37 +01001169/**@}*/
1170
Gilles Peskine8c9def32018-02-08 10:02:12 +01001171/** \defgroup MAC Message authentication codes
1172 * @{
1173 */
1174
Gilles Peskine69647a42019-01-14 20:18:12 +01001175/** Calculate the MAC (message authentication code) of a message.
1176 *
1177 * \note To verify the MAC of a message against an
1178 * expected value, use psa_mac_verify() instead.
1179 * Beware that comparing integrity or authenticity data such as
1180 * MAC values with a function such as \c memcmp is risky
1181 * because the time taken by the comparison may leak information
1182 * about the MAC value which could allow an attacker to guess
1183 * a valid MAC and thereby bypass security controls.
1184 *
1185 * \param handle Handle to the key to use for the operation.
1186 * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
Gilles Peskine63f79302019-02-15 13:01:17 +01001187 * such that #PSA_ALG_IS_MAC(\p alg) is true).
Gilles Peskine69647a42019-01-14 20:18:12 +01001188 * \param[in] input Buffer containing the input message.
1189 * \param input_length Size of the \p input buffer in bytes.
1190 * \param[out] mac Buffer where the MAC value is to be written.
1191 * \param mac_size Size of the \p mac buffer in bytes.
1192 * \param[out] mac_length On success, the number of bytes
Gilles Peskined338b912019-02-15 13:01:41 +01001193 * that make up the MAC value.
Gilles Peskine69647a42019-01-14 20:18:12 +01001194 *
1195 * \retval #PSA_SUCCESS
1196 * Success.
1197 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine69647a42019-01-14 20:18:12 +01001198 * \retval #PSA_ERROR_NOT_PERMITTED
1199 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001200 * \p handle is not compatible with \p alg.
Gilles Peskine69647a42019-01-14 20:18:12 +01001201 * \retval #PSA_ERROR_NOT_SUPPORTED
1202 * \p alg is not supported or is not a MAC algorithm.
Adrian L. Shawd5ae06b2019-08-07 15:59:33 +01001203 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
1204 * \p mac_size is too small
Gilles Peskine69647a42019-01-14 20:18:12 +01001205 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1206 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1207 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001208 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawfa591c42019-08-07 10:47:47 +01001209 * \retval #PSA_ERROR_STORAGE_FAILURE
1210 * The key could not be retrieved from storage.
Gilles Peskine69647a42019-01-14 20:18:12 +01001211 * \retval #PSA_ERROR_BAD_STATE
1212 * The library has not been previously initialized by psa_crypto_init().
1213 * It is implementation-dependent whether a failure to initialize
1214 * results in this error code.
1215 */
1216psa_status_t psa_mac_compute(psa_key_handle_t handle,
1217 psa_algorithm_t alg,
1218 const uint8_t *input,
1219 size_t input_length,
1220 uint8_t *mac,
1221 size_t mac_size,
1222 size_t *mac_length);
1223
1224/** Calculate the MAC of a message and compare it with a reference value.
1225 *
1226 * \param handle Handle to the key to use for the operation.
1227 * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
Gilles Peskine63f79302019-02-15 13:01:17 +01001228 * such that #PSA_ALG_IS_MAC(\p alg) is true).
Gilles Peskine69647a42019-01-14 20:18:12 +01001229 * \param[in] input Buffer containing the input message.
1230 * \param input_length Size of the \p input buffer in bytes.
1231 * \param[out] mac Buffer containing the expected MAC value.
1232 * \param mac_length Size of the \p mac buffer in bytes.
1233 *
1234 * \retval #PSA_SUCCESS
1235 * The expected MAC is identical to the actual MAC of the input.
1236 * \retval #PSA_ERROR_INVALID_SIGNATURE
1237 * The MAC of the message was calculated successfully, but it
1238 * differs from the expected value.
1239 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine69647a42019-01-14 20:18:12 +01001240 * \retval #PSA_ERROR_NOT_PERMITTED
1241 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001242 * \p handle is not compatible with \p alg.
Gilles Peskine69647a42019-01-14 20:18:12 +01001243 * \retval #PSA_ERROR_NOT_SUPPORTED
1244 * \p alg is not supported or is not a MAC algorithm.
1245 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1246 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1247 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001248 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001249 * \retval #PSA_ERROR_STORAGE_FAILURE
1250 * The key could not be retrieved from storage.
1251 * \retval #PSA_ERROR_BAD_STATE
1252 * The library has not been previously initialized by psa_crypto_init().
1253 * It is implementation-dependent whether a failure to initialize
1254 * results in this error code.
Gilles Peskine69647a42019-01-14 20:18:12 +01001255 */
Gilles Peskinea05602d2019-01-17 15:25:52 +01001256psa_status_t psa_mac_verify(psa_key_handle_t handle,
1257 psa_algorithm_t alg,
Gilles Peskine69647a42019-01-14 20:18:12 +01001258 const uint8_t *input,
1259 size_t input_length,
1260 const uint8_t *mac,
1261 const size_t mac_length);
1262
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001263/** The type of the state data structure for multipart MAC operations.
1264 *
Jaeden Amero769ce272019-01-04 11:48:03 +00001265 * Before calling any function on a MAC operation object, the application must
1266 * initialize it by any of the following means:
1267 * - Set the structure to all-bits-zero, for example:
1268 * \code
1269 * psa_mac_operation_t operation;
1270 * memset(&operation, 0, sizeof(operation));
1271 * \endcode
1272 * - Initialize the structure to logical zero values, for example:
1273 * \code
1274 * psa_mac_operation_t operation = {0};
1275 * \endcode
1276 * - Initialize the structure to the initializer #PSA_MAC_OPERATION_INIT,
1277 * for example:
1278 * \code
1279 * psa_mac_operation_t operation = PSA_MAC_OPERATION_INIT;
1280 * \endcode
1281 * - Assign the result of the function psa_mac_operation_init()
1282 * to the structure, for example:
1283 * \code
1284 * psa_mac_operation_t operation;
1285 * operation = psa_mac_operation_init();
1286 * \endcode
1287 *
Gilles Peskine92b30732018-03-03 21:29:30 +01001288 * This is an implementation-defined \c struct. Applications should not
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001289 * make any assumptions about the content of this structure except
1290 * as directed by the documentation of a specific implementation. */
Gilles Peskine8c9def32018-02-08 10:02:12 +01001291typedef struct psa_mac_operation_s psa_mac_operation_t;
1292
Jaeden Amero769ce272019-01-04 11:48:03 +00001293/** \def PSA_MAC_OPERATION_INIT
1294 *
1295 * This macro returns a suitable initializer for a MAC operation object of type
1296 * #psa_mac_operation_t.
1297 */
1298#ifdef __DOXYGEN_ONLY__
1299/* This is an example definition for documentation purposes.
1300 * Implementations should define a suitable value in `crypto_struct.h`.
1301 */
1302#define PSA_MAC_OPERATION_INIT {0}
1303#endif
1304
1305/** Return an initial value for a MAC operation object.
1306 */
1307static psa_mac_operation_t psa_mac_operation_init(void);
1308
Gilles Peskinef45adda2019-01-14 18:29:18 +01001309/** Set up a multipart MAC calculation operation.
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001310 *
Gilles Peskine89167cb2018-07-08 20:12:23 +02001311 * This function sets up the calculation of the MAC
1312 * (message authentication code) of a byte string.
1313 * To verify the MAC of a message against an
1314 * expected value, use psa_mac_verify_setup() instead.
1315 *
1316 * The sequence of operations to calculate a MAC is as follows:
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001317 * -# Allocate an operation object which will be passed to all the functions
1318 * listed here.
Jaeden Amero769ce272019-01-04 11:48:03 +00001319 * -# Initialize the operation object with one of the methods described in the
1320 * documentation for #psa_mac_operation_t, e.g. PSA_MAC_OPERATION_INIT.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001321 * -# Call psa_mac_sign_setup() to specify the algorithm and key.
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001322 * -# Call psa_mac_update() zero, one or more times, passing a fragment
1323 * of the message each time. The MAC that is calculated is the MAC
1324 * of the concatenation of these messages in order.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001325 * -# At the end of the message, call psa_mac_sign_finish() to finish
1326 * calculating the MAC value and retrieve it.
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001327 *
1328 * The application may call psa_mac_abort() at any time after the operation
Jaeden Amero769ce272019-01-04 11:48:03 +00001329 * has been initialized.
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001330 *
Gilles Peskine89167cb2018-07-08 20:12:23 +02001331 * After a successful call to psa_mac_sign_setup(), the application must
1332 * eventually terminate the operation through one of the following methods:
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001333 * - A failed call to psa_mac_update().
Gilles Peskine89167cb2018-07-08 20:12:23 +02001334 * - A call to psa_mac_sign_finish() or psa_mac_abort().
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001335 *
Jaeden Amero769ce272019-01-04 11:48:03 +00001336 * \param[in,out] operation The operation object to set up. It must have
1337 * been initialized as per the documentation for
1338 * #psa_mac_operation_t and not yet in use.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001339 * \param handle Handle to the key to use for the operation.
Gilles Peskine5f25dd02019-01-14 18:24:53 +01001340 * It must remain valid until the operation
1341 * terminates.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001342 * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
Gilles Peskine63f79302019-02-15 13:01:17 +01001343 * such that #PSA_ALG_IS_MAC(\p alg) is true).
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001344 *
Gilles Peskine28538492018-07-11 17:34:00 +02001345 * \retval #PSA_SUCCESS
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001346 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001347 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine28538492018-07-11 17:34:00 +02001348 * \retval #PSA_ERROR_NOT_PERMITTED
1349 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001350 * \p handle is not compatible with \p alg.
Gilles Peskine28538492018-07-11 17:34:00 +02001351 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001352 * \p alg is not supported or is not a MAC algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02001353 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1354 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1355 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001356 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw2409ba02019-08-07 16:05:06 +01001357 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdf3c7ac2019-08-12 16:43:30 +01001358 * The key could not be retrieved from storage.
itayzafrir90d8c7a2018-09-12 11:44:52 +03001359 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskine8e1addc2019-01-10 11:51:17 +01001360 * The operation state is not valid (already set up and not
1361 * subsequently completed).
1362 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03001363 * The library has not been previously initialized by psa_crypto_init().
1364 * It is implementation-dependent whether a failure to initialize
1365 * results in this error code.
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001366 */
Gilles Peskine89167cb2018-07-08 20:12:23 +02001367psa_status_t psa_mac_sign_setup(psa_mac_operation_t *operation,
Gilles Peskineae32aac2018-11-30 14:39:32 +01001368 psa_key_handle_t handle,
Gilles Peskine89167cb2018-07-08 20:12:23 +02001369 psa_algorithm_t alg);
1370
Gilles Peskinef45adda2019-01-14 18:29:18 +01001371/** Set up a multipart MAC verification operation.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001372 *
1373 * This function sets up the verification of the MAC
1374 * (message authentication code) of a byte string against an expected value.
1375 *
1376 * The sequence of operations to verify a MAC is as follows:
1377 * -# Allocate an operation object which will be passed to all the functions
1378 * listed here.
Jaeden Amero769ce272019-01-04 11:48:03 +00001379 * -# Initialize the operation object with one of the methods described in the
1380 * documentation for #psa_mac_operation_t, e.g. PSA_MAC_OPERATION_INIT.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001381 * -# Call psa_mac_verify_setup() to specify the algorithm and key.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001382 * -# Call psa_mac_update() zero, one or more times, passing a fragment
1383 * of the message each time. The MAC that is calculated is the MAC
1384 * of the concatenation of these messages in order.
1385 * -# At the end of the message, call psa_mac_verify_finish() to finish
1386 * calculating the actual MAC of the message and verify it against
1387 * the expected value.
1388 *
1389 * The application may call psa_mac_abort() at any time after the operation
Jaeden Amero769ce272019-01-04 11:48:03 +00001390 * has been initialized.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001391 *
1392 * After a successful call to psa_mac_verify_setup(), the application must
1393 * eventually terminate the operation through one of the following methods:
1394 * - A failed call to psa_mac_update().
1395 * - A call to psa_mac_verify_finish() or psa_mac_abort().
1396 *
Jaeden Amero769ce272019-01-04 11:48:03 +00001397 * \param[in,out] operation The operation object to set up. It must have
1398 * been initialized as per the documentation for
1399 * #psa_mac_operation_t and not yet in use.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001400 * \param handle Handle to the key to use for the operation.
Gilles Peskine5f25dd02019-01-14 18:24:53 +01001401 * It must remain valid until the operation
1402 * terminates.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001403 * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
1404 * such that #PSA_ALG_IS_MAC(\p alg) is true).
Gilles Peskine89167cb2018-07-08 20:12:23 +02001405 *
Gilles Peskine28538492018-07-11 17:34:00 +02001406 * \retval #PSA_SUCCESS
Gilles Peskine89167cb2018-07-08 20:12:23 +02001407 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001408 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine28538492018-07-11 17:34:00 +02001409 * \retval #PSA_ERROR_NOT_PERMITTED
1410 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine89167cb2018-07-08 20:12:23 +02001411 * \c key is not compatible with \c alg.
Gilles Peskine28538492018-07-11 17:34:00 +02001412 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskine89167cb2018-07-08 20:12:23 +02001413 * \c alg is not supported or is not a MAC algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02001414 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1415 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1416 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001417 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw9770d0e2019-08-07 16:18:18 +01001418 * \retval #PSA_ERROR_STORAGE_FAILURE
1419 * The key could not be retrieved from storage
itayzafrir90d8c7a2018-09-12 11:44:52 +03001420 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskine8e1addc2019-01-10 11:51:17 +01001421 * The operation state is not valid (already set up and not
1422 * subsequently completed).
1423 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03001424 * The library has not been previously initialized by psa_crypto_init().
1425 * It is implementation-dependent whether a failure to initialize
1426 * results in this error code.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001427 */
1428psa_status_t psa_mac_verify_setup(psa_mac_operation_t *operation,
Gilles Peskineae32aac2018-11-30 14:39:32 +01001429 psa_key_handle_t handle,
Gilles Peskine89167cb2018-07-08 20:12:23 +02001430 psa_algorithm_t alg);
Gilles Peskine8c9def32018-02-08 10:02:12 +01001431
Gilles Peskinedcd14942018-07-12 00:30:52 +02001432/** Add a message fragment to a multipart MAC operation.
1433 *
1434 * The application must call psa_mac_sign_setup() or psa_mac_verify_setup()
1435 * before calling this function.
1436 *
1437 * If this function returns an error status, the operation becomes inactive.
1438 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001439 * \param[in,out] operation Active MAC operation.
1440 * \param[in] input Buffer containing the message fragment to add to
1441 * the MAC calculation.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001442 * \param input_length Size of the \p input buffer in bytes.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001443 *
1444 * \retval #PSA_SUCCESS
1445 * Success.
1446 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001447 * The operation state is not valid (not set up, or already completed).
Gilles Peskinedcd14942018-07-12 00:30:52 +02001448 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1449 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1450 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001451 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawd789dc12019-08-12 15:06:48 +01001452 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001453 * \retval #PSA_ERROR_BAD_STATE
1454 * The library has not been previously initialized by psa_crypto_init().
1455 * It is implementation-dependent whether a failure to initialize
1456 * results in this error code.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001457 */
Gilles Peskine8c9def32018-02-08 10:02:12 +01001458psa_status_t psa_mac_update(psa_mac_operation_t *operation,
1459 const uint8_t *input,
1460 size_t input_length);
1461
Gilles Peskinedcd14942018-07-12 00:30:52 +02001462/** Finish the calculation of the MAC of a message.
1463 *
1464 * The application must call psa_mac_sign_setup() before calling this function.
1465 * This function calculates the MAC of the message formed by concatenating
1466 * the inputs passed to preceding calls to psa_mac_update().
1467 *
1468 * When this function returns, the operation becomes inactive.
1469 *
1470 * \warning Applications should not call this function if they expect
1471 * a specific value for the MAC. Call psa_mac_verify_finish() instead.
1472 * Beware that comparing integrity or authenticity data such as
1473 * MAC values with a function such as \c memcmp is risky
1474 * because the time taken by the comparison may leak information
1475 * about the MAC value which could allow an attacker to guess
1476 * a valid MAC and thereby bypass security controls.
1477 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001478 * \param[in,out] operation Active MAC operation.
1479 * \param[out] mac Buffer where the MAC value is to be written.
1480 * \param mac_size Size of the \p mac buffer in bytes.
1481 * \param[out] mac_length On success, the number of bytes
1482 * that make up the MAC value. This is always
Gilles Peskinedda3bd32018-07-12 19:40:46 +02001483 * #PSA_MAC_FINAL_SIZE(\c key_type, \c key_bits, \c alg)
Gilles Peskineedd11a12018-07-12 01:08:58 +02001484 * where \c key_type and \c key_bits are the type and
Gilles Peskinedda3bd32018-07-12 19:40:46 +02001485 * bit-size respectively of the key and \c alg is the
Gilles Peskineedd11a12018-07-12 01:08:58 +02001486 * MAC algorithm that is calculated.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001487 *
1488 * \retval #PSA_SUCCESS
1489 * Success.
1490 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001491 * The operation state is not valid (not set up, or already completed).
Gilles Peskinedcd14942018-07-12 00:30:52 +02001492 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001493 * The size of the \p mac buffer is too small. You can determine a
Gilles Peskinedcd14942018-07-12 00:30:52 +02001494 * sufficient buffer size by calling PSA_MAC_FINAL_SIZE().
1495 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1496 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1497 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001498 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw26322362019-08-13 11:43:40 +01001499 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001500 * \retval #PSA_ERROR_BAD_STATE
1501 * The library has not been previously initialized by psa_crypto_init().
1502 * It is implementation-dependent whether a failure to initialize
1503 * results in this error code.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001504 */
Gilles Peskineacd4be32018-07-08 19:56:25 +02001505psa_status_t psa_mac_sign_finish(psa_mac_operation_t *operation,
1506 uint8_t *mac,
1507 size_t mac_size,
1508 size_t *mac_length);
Gilles Peskine8c9def32018-02-08 10:02:12 +01001509
Gilles Peskinedcd14942018-07-12 00:30:52 +02001510/** Finish the calculation of the MAC of a message and compare it with
1511 * an expected value.
1512 *
1513 * The application must call psa_mac_verify_setup() before calling this function.
1514 * This function calculates the MAC of the message formed by concatenating
1515 * the inputs passed to preceding calls to psa_mac_update(). It then
1516 * compares the calculated MAC with the expected MAC passed as a
1517 * parameter to this function.
1518 *
1519 * When this function returns, the operation becomes inactive.
1520 *
1521 * \note Implementations shall make the best effort to ensure that the
1522 * comparison between the actual MAC and the expected MAC is performed
1523 * in constant time.
1524 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001525 * \param[in,out] operation Active MAC operation.
1526 * \param[in] mac Buffer containing the expected MAC value.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001527 * \param mac_length Size of the \p mac buffer in bytes.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001528 *
1529 * \retval #PSA_SUCCESS
1530 * The expected MAC is identical to the actual MAC of the message.
1531 * \retval #PSA_ERROR_INVALID_SIGNATURE
1532 * The MAC of the message was calculated successfully, but it
1533 * differs from the expected MAC.
1534 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001535 * The operation state is not valid (not set up, or already completed).
Gilles Peskinedcd14942018-07-12 00:30:52 +02001536 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1537 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1538 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001539 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawd9e90242019-08-13 11:44:30 +01001540 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001541 * \retval #PSA_ERROR_BAD_STATE
1542 * The library has not been previously initialized by psa_crypto_init().
1543 * It is implementation-dependent whether a failure to initialize
1544 * results in this error code.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001545 */
Gilles Peskineacd4be32018-07-08 19:56:25 +02001546psa_status_t psa_mac_verify_finish(psa_mac_operation_t *operation,
1547 const uint8_t *mac,
1548 size_t mac_length);
Gilles Peskine8c9def32018-02-08 10:02:12 +01001549
Gilles Peskinedcd14942018-07-12 00:30:52 +02001550/** Abort a MAC operation.
1551 *
Gilles Peskinedcd14942018-07-12 00:30:52 +02001552 * Aborting an operation frees all associated resources except for the
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001553 * \p operation structure itself. Once aborted, the operation object
1554 * can be reused for another operation by calling
1555 * psa_mac_sign_setup() or psa_mac_verify_setup() again.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001556 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001557 * You may call this function any time after the operation object has
1558 * been initialized by any of the following methods:
1559 * - A call to psa_mac_sign_setup() or psa_mac_verify_setup(), whether
1560 * it succeeds or not.
1561 * - Initializing the \c struct to all-bits-zero.
1562 * - Initializing the \c struct to logical zeros, e.g.
1563 * `psa_mac_operation_t operation = {0}`.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001564 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001565 * In particular, calling psa_mac_abort() after the operation has been
1566 * terminated by a call to psa_mac_abort(), psa_mac_sign_finish() or
1567 * psa_mac_verify_finish() is safe and has no effect.
1568 *
1569 * \param[in,out] operation Initialized MAC operation.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001570 *
1571 * \retval #PSA_SUCCESS
1572 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001573 * \p operation is not an active MAC operation.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001574 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1575 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001576 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001577 * \retval #PSA_ERROR_BAD_STATE
1578 * The library has not been previously initialized by psa_crypto_init().
1579 * It is implementation-dependent whether a failure to initialize
1580 * results in this error code.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001581 */
Gilles Peskine8c9def32018-02-08 10:02:12 +01001582psa_status_t psa_mac_abort(psa_mac_operation_t *operation);
1583
1584/**@}*/
1585
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001586/** \defgroup cipher Symmetric ciphers
1587 * @{
1588 */
1589
Gilles Peskine69647a42019-01-14 20:18:12 +01001590/** Encrypt a message using a symmetric cipher.
1591 *
1592 * This function encrypts a message with a random IV (initialization
1593 * vector).
1594 *
1595 * \param handle Handle to the key to use for the operation.
1596 * It must remain valid until the operation
1597 * terminates.
1598 * \param alg The cipher algorithm to compute
1599 * (\c PSA_ALG_XXX value such that
1600 * #PSA_ALG_IS_CIPHER(\p alg) is true).
1601 * \param[in] input Buffer containing the message to encrypt.
1602 * \param input_length Size of the \p input buffer in bytes.
1603 * \param[out] output Buffer where the output is to be written.
1604 * The output contains the IV followed by
1605 * the ciphertext proper.
1606 * \param output_size Size of the \p output buffer in bytes.
1607 * \param[out] output_length On success, the number of bytes
1608 * that make up the output.
1609 *
1610 * \retval #PSA_SUCCESS
1611 * Success.
1612 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine69647a42019-01-14 20:18:12 +01001613 * \retval #PSA_ERROR_NOT_PERMITTED
1614 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001615 * \p handle is not compatible with \p alg.
Gilles Peskine69647a42019-01-14 20:18:12 +01001616 * \retval #PSA_ERROR_NOT_SUPPORTED
1617 * \p alg is not supported or is not a cipher algorithm.
1618 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
1619 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1620 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1621 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001622 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawa3f6ba52019-08-08 14:51:49 +01001623 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001624 * \retval #PSA_ERROR_BAD_STATE
1625 * The library has not been previously initialized by psa_crypto_init().
1626 * It is implementation-dependent whether a failure to initialize
1627 * results in this error code.
Gilles Peskine69647a42019-01-14 20:18:12 +01001628 */
1629psa_status_t psa_cipher_encrypt(psa_key_handle_t handle,
1630 psa_algorithm_t alg,
1631 const uint8_t *input,
1632 size_t input_length,
1633 uint8_t *output,
1634 size_t output_size,
1635 size_t *output_length);
1636
1637/** Decrypt a message using a symmetric cipher.
1638 *
1639 * This function decrypts a message encrypted with a symmetric cipher.
1640 *
1641 * \param handle Handle to the key to use for the operation.
1642 * It must remain valid until the operation
1643 * terminates.
1644 * \param alg The cipher algorithm to compute
1645 * (\c PSA_ALG_XXX value such that
1646 * #PSA_ALG_IS_CIPHER(\p alg) is true).
1647 * \param[in] input Buffer containing the message to decrypt.
1648 * This consists of the IV followed by the
1649 * ciphertext proper.
1650 * \param input_length Size of the \p input buffer in bytes.
1651 * \param[out] output Buffer where the plaintext is to be written.
1652 * \param output_size Size of the \p output buffer in bytes.
1653 * \param[out] output_length On success, the number of bytes
1654 * that make up the output.
1655 *
1656 * \retval #PSA_SUCCESS
1657 * Success.
1658 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine69647a42019-01-14 20:18:12 +01001659 * \retval #PSA_ERROR_NOT_PERMITTED
1660 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001661 * \p handle is not compatible with \p alg.
Gilles Peskine69647a42019-01-14 20:18:12 +01001662 * \retval #PSA_ERROR_NOT_SUPPORTED
1663 * \p alg is not supported or is not a cipher algorithm.
1664 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
1665 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1666 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1667 * \retval #PSA_ERROR_HARDWARE_FAILURE
Adrian L. Shawa3f6ba52019-08-08 14:51:49 +01001668 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shaw39797aa2019-08-23 16:17:43 +01001669 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001670 * \retval #PSA_ERROR_BAD_STATE
1671 * The library has not been previously initialized by psa_crypto_init().
1672 * It is implementation-dependent whether a failure to initialize
Adrian L. Shaw23c006f2019-08-06 16:02:12 +01001673 * results in this error code.
Gilles Peskine69647a42019-01-14 20:18:12 +01001674 */
1675psa_status_t psa_cipher_decrypt(psa_key_handle_t handle,
1676 psa_algorithm_t alg,
1677 const uint8_t *input,
1678 size_t input_length,
1679 uint8_t *output,
1680 size_t output_size,
1681 size_t *output_length);
1682
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001683/** The type of the state data structure for multipart cipher operations.
1684 *
Jaeden Amero5bae2272019-01-04 11:48:27 +00001685 * Before calling any function on a cipher operation object, the application
1686 * must initialize it by any of the following means:
1687 * - Set the structure to all-bits-zero, for example:
1688 * \code
1689 * psa_cipher_operation_t operation;
1690 * memset(&operation, 0, sizeof(operation));
1691 * \endcode
1692 * - Initialize the structure to logical zero values, for example:
1693 * \code
1694 * psa_cipher_operation_t operation = {0};
1695 * \endcode
1696 * - Initialize the structure to the initializer #PSA_CIPHER_OPERATION_INIT,
1697 * for example:
1698 * \code
1699 * psa_cipher_operation_t operation = PSA_CIPHER_OPERATION_INIT;
1700 * \endcode
1701 * - Assign the result of the function psa_cipher_operation_init()
1702 * to the structure, for example:
1703 * \code
1704 * psa_cipher_operation_t operation;
1705 * operation = psa_cipher_operation_init();
1706 * \endcode
1707 *
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001708 * This is an implementation-defined \c struct. Applications should not
1709 * make any assumptions about the content of this structure except
1710 * as directed by the documentation of a specific implementation. */
1711typedef struct psa_cipher_operation_s psa_cipher_operation_t;
1712
Jaeden Amero5bae2272019-01-04 11:48:27 +00001713/** \def PSA_CIPHER_OPERATION_INIT
1714 *
1715 * This macro returns a suitable initializer for a cipher operation object of
1716 * type #psa_cipher_operation_t.
1717 */
1718#ifdef __DOXYGEN_ONLY__
1719/* This is an example definition for documentation purposes.
1720 * Implementations should define a suitable value in `crypto_struct.h`.
1721 */
1722#define PSA_CIPHER_OPERATION_INIT {0}
1723#endif
1724
1725/** Return an initial value for a cipher operation object.
1726 */
1727static psa_cipher_operation_t psa_cipher_operation_init(void);
1728
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001729/** Set the key for a multipart symmetric encryption operation.
1730 *
1731 * The sequence of operations to encrypt a message with a symmetric cipher
1732 * is as follows:
1733 * -# Allocate an operation object which will be passed to all the functions
1734 * listed here.
Jaeden Amero5bae2272019-01-04 11:48:27 +00001735 * -# Initialize the operation object with one of the methods described in the
1736 * documentation for #psa_cipher_operation_t, e.g.
1737 * PSA_CIPHER_OPERATION_INIT.
Gilles Peskinefe119512018-07-08 21:39:34 +02001738 * -# Call psa_cipher_encrypt_setup() to specify the algorithm and key.
itayzafrired7382f2018-08-02 14:19:33 +03001739 * -# Call either psa_cipher_generate_iv() or psa_cipher_set_iv() to
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001740 * generate or set the IV (initialization vector). You should use
itayzafrired7382f2018-08-02 14:19:33 +03001741 * psa_cipher_generate_iv() unless the protocol you are implementing
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001742 * requires a specific IV value.
1743 * -# Call psa_cipher_update() zero, one or more times, passing a fragment
1744 * of the message each time.
1745 * -# Call psa_cipher_finish().
1746 *
1747 * The application may call psa_cipher_abort() at any time after the operation
Jaeden Amero5bae2272019-01-04 11:48:27 +00001748 * has been initialized.
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001749 *
Gilles Peskinefe119512018-07-08 21:39:34 +02001750 * After a successful call to psa_cipher_encrypt_setup(), the application must
Gilles Peskineed522972018-03-20 17:54:15 +01001751 * eventually terminate the operation. The following events terminate an
1752 * operation:
Gilles Peskinef45adda2019-01-14 18:29:18 +01001753 * - A failed call to any of the \c psa_cipher_xxx functions.
Gilles Peskine19067982018-03-20 17:54:53 +01001754 * - A call to psa_cipher_finish() or psa_cipher_abort().
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001755 *
Jaeden Amero5bae2272019-01-04 11:48:27 +00001756 * \param[in,out] operation The operation object to set up. It must have
1757 * been initialized as per the documentation for
1758 * #psa_cipher_operation_t and not yet in use.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001759 * \param handle Handle to the key to use for the operation.
Gilles Peskine5f25dd02019-01-14 18:24:53 +01001760 * It must remain valid until the operation
1761 * terminates.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001762 * \param alg The cipher algorithm to compute
1763 * (\c PSA_ALG_XXX value such that
1764 * #PSA_ALG_IS_CIPHER(\p alg) is true).
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001765 *
Gilles Peskine28538492018-07-11 17:34:00 +02001766 * \retval #PSA_SUCCESS
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001767 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001768 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine28538492018-07-11 17:34:00 +02001769 * \retval #PSA_ERROR_NOT_PERMITTED
1770 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001771 * \p handle is not compatible with \p alg.
Gilles Peskine28538492018-07-11 17:34:00 +02001772 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001773 * \p alg is not supported or is not a cipher algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02001774 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1775 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1776 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001777 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdc5bf5c2019-08-13 11:46:09 +01001778 * \retval #PSA_ERROR_STORAGE_FAILURE
itayzafrir90d8c7a2018-09-12 11:44:52 +03001779 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskine8e1addc2019-01-10 11:51:17 +01001780 * The operation state is not valid (already set up and not
1781 * subsequently completed).
1782 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03001783 * The library has not been previously initialized by psa_crypto_init().
1784 * It is implementation-dependent whether a failure to initialize
1785 * results in this error code.
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001786 */
Gilles Peskinefe119512018-07-08 21:39:34 +02001787psa_status_t psa_cipher_encrypt_setup(psa_cipher_operation_t *operation,
Gilles Peskineae32aac2018-11-30 14:39:32 +01001788 psa_key_handle_t handle,
Gilles Peskinefe119512018-07-08 21:39:34 +02001789 psa_algorithm_t alg);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001790
1791/** Set the key for a multipart symmetric decryption operation.
1792 *
1793 * The sequence of operations to decrypt a message with a symmetric cipher
1794 * is as follows:
1795 * -# Allocate an operation object which will be passed to all the functions
1796 * listed here.
Jaeden Amero5bae2272019-01-04 11:48:27 +00001797 * -# Initialize the operation object with one of the methods described in the
1798 * documentation for #psa_cipher_operation_t, e.g.
1799 * PSA_CIPHER_OPERATION_INIT.
Gilles Peskinefe119512018-07-08 21:39:34 +02001800 * -# Call psa_cipher_decrypt_setup() to specify the algorithm and key.
Gilles Peskinef45adda2019-01-14 18:29:18 +01001801 * -# Call psa_cipher_set_iv() with the IV (initialization vector) for the
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001802 * decryption. If the IV is prepended to the ciphertext, you can call
1803 * psa_cipher_update() on a buffer containing the IV followed by the
1804 * beginning of the message.
1805 * -# Call psa_cipher_update() zero, one or more times, passing a fragment
1806 * of the message each time.
1807 * -# Call psa_cipher_finish().
1808 *
1809 * The application may call psa_cipher_abort() at any time after the operation
Jaeden Amero5bae2272019-01-04 11:48:27 +00001810 * has been initialized.
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001811 *
Gilles Peskinefe119512018-07-08 21:39:34 +02001812 * After a successful call to psa_cipher_decrypt_setup(), the application must
Gilles Peskineed522972018-03-20 17:54:15 +01001813 * eventually terminate the operation. The following events terminate an
1814 * operation:
Gilles Peskinef45adda2019-01-14 18:29:18 +01001815 * - A failed call to any of the \c psa_cipher_xxx functions.
Gilles Peskine19067982018-03-20 17:54:53 +01001816 * - A call to psa_cipher_finish() or psa_cipher_abort().
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001817 *
Jaeden Amero5bae2272019-01-04 11:48:27 +00001818 * \param[in,out] operation The operation object to set up. It must have
1819 * been initialized as per the documentation for
1820 * #psa_cipher_operation_t and not yet in use.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001821 * \param handle Handle to the key to use for the operation.
Gilles Peskine5f25dd02019-01-14 18:24:53 +01001822 * It must remain valid until the operation
1823 * terminates.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001824 * \param alg The cipher algorithm to compute
1825 * (\c PSA_ALG_XXX value such that
1826 * #PSA_ALG_IS_CIPHER(\p alg) is true).
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001827 *
Gilles Peskine28538492018-07-11 17:34:00 +02001828 * \retval #PSA_SUCCESS
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001829 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001830 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine28538492018-07-11 17:34:00 +02001831 * \retval #PSA_ERROR_NOT_PERMITTED
1832 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001833 * \p handle is not compatible with \p alg.
Gilles Peskine28538492018-07-11 17:34:00 +02001834 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001835 * \p alg is not supported or is not a cipher algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02001836 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1837 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1838 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001839 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdc5bf5c2019-08-13 11:46:09 +01001840 * \retval #PSA_ERROR_STORAGE_FAILURE
itayzafrir90d8c7a2018-09-12 11:44:52 +03001841 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskine8e1addc2019-01-10 11:51:17 +01001842 * The operation state is not valid (already set up and not
1843 * subsequently completed).
1844 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03001845 * The library has not been previously initialized by psa_crypto_init().
1846 * It is implementation-dependent whether a failure to initialize
1847 * results in this error code.
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001848 */
Gilles Peskinefe119512018-07-08 21:39:34 +02001849psa_status_t psa_cipher_decrypt_setup(psa_cipher_operation_t *operation,
Gilles Peskineae32aac2018-11-30 14:39:32 +01001850 psa_key_handle_t handle,
Gilles Peskinefe119512018-07-08 21:39:34 +02001851 psa_algorithm_t alg);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001852
Gilles Peskinedcd14942018-07-12 00:30:52 +02001853/** Generate an IV for a symmetric encryption operation.
1854 *
1855 * This function generates a random IV (initialization vector), nonce
1856 * or initial counter value for the encryption operation as appropriate
1857 * for the chosen algorithm, key type and key size.
1858 *
1859 * The application must call psa_cipher_encrypt_setup() before
1860 * calling this function.
1861 *
1862 * If this function returns an error status, the operation becomes inactive.
1863 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001864 * \param[in,out] operation Active cipher operation.
1865 * \param[out] iv Buffer where the generated IV is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001866 * \param iv_size Size of the \p iv buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001867 * \param[out] iv_length On success, the number of bytes of the
1868 * generated IV.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001869 *
1870 * \retval #PSA_SUCCESS
1871 * Success.
1872 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001873 * The operation state is not valid (not set up, or IV already set).
Gilles Peskinedcd14942018-07-12 00:30:52 +02001874 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinedda3bd32018-07-12 19:40:46 +02001875 * The size of the \p iv buffer is too small.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001876 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1877 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1878 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001879 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw66200c42019-08-15 13:30:57 +01001880 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001881 * \retval #PSA_ERROR_BAD_STATE
1882 * The library has not been previously initialized by psa_crypto_init().
1883 * It is implementation-dependent whether a failure to initialize
1884 * results in this error code.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001885 */
Gilles Peskinefe119512018-07-08 21:39:34 +02001886psa_status_t psa_cipher_generate_iv(psa_cipher_operation_t *operation,
Andrew Thoelke47629d02019-03-22 11:24:17 +00001887 uint8_t *iv,
Gilles Peskinefe119512018-07-08 21:39:34 +02001888 size_t iv_size,
1889 size_t *iv_length);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001890
Gilles Peskinedcd14942018-07-12 00:30:52 +02001891/** Set the IV for a symmetric encryption or decryption operation.
1892 *
Gilles Peskinef45adda2019-01-14 18:29:18 +01001893 * This function sets the IV (initialization vector), nonce
Gilles Peskinedcd14942018-07-12 00:30:52 +02001894 * or initial counter value for the encryption or decryption operation.
1895 *
1896 * The application must call psa_cipher_encrypt_setup() before
1897 * calling this function.
1898 *
1899 * If this function returns an error status, the operation becomes inactive.
1900 *
1901 * \note When encrypting, applications should use psa_cipher_generate_iv()
1902 * instead of this function, unless implementing a protocol that requires
1903 * a non-random IV.
1904 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001905 * \param[in,out] operation Active cipher operation.
1906 * \param[in] iv Buffer containing the IV to use.
1907 * \param iv_length Size of the IV in bytes.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001908 *
1909 * \retval #PSA_SUCCESS
1910 * Success.
1911 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001912 * The operation state is not valid (not set up, or IV already set).
Gilles Peskinedcd14942018-07-12 00:30:52 +02001913 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001914 * The size of \p iv is not acceptable for the chosen algorithm,
Gilles Peskinedcd14942018-07-12 00:30:52 +02001915 * or the chosen algorithm does not use an IV.
1916 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1917 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1918 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001919 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001920 * \retval #PSA_ERROR_BAD_STATE
1921 * The library has not been previously initialized by psa_crypto_init().
1922 * It is implementation-dependent whether a failure to initialize
1923 * results in this error code.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001924 */
Gilles Peskinefe119512018-07-08 21:39:34 +02001925psa_status_t psa_cipher_set_iv(psa_cipher_operation_t *operation,
Andrew Thoelke47629d02019-03-22 11:24:17 +00001926 const uint8_t *iv,
Gilles Peskinefe119512018-07-08 21:39:34 +02001927 size_t iv_length);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001928
Gilles Peskinedcd14942018-07-12 00:30:52 +02001929/** Encrypt or decrypt a message fragment in an active cipher operation.
1930 *
Gilles Peskine9ac94262018-07-12 20:15:32 +02001931 * Before calling this function, you must:
1932 * 1. Call either psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup().
1933 * The choice of setup function determines whether this function
1934 * encrypts or decrypts its input.
1935 * 2. If the algorithm requires an IV, call psa_cipher_generate_iv()
1936 * (recommended when encrypting) or psa_cipher_set_iv().
Gilles Peskinedcd14942018-07-12 00:30:52 +02001937 *
1938 * If this function returns an error status, the operation becomes inactive.
1939 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001940 * \param[in,out] operation Active cipher operation.
1941 * \param[in] input Buffer containing the message fragment to
1942 * encrypt or decrypt.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001943 * \param input_length Size of the \p input buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001944 * \param[out] output Buffer where the output is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001945 * \param output_size Size of the \p output buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001946 * \param[out] output_length On success, the number of bytes
1947 * that make up the returned output.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001948 *
1949 * \retval #PSA_SUCCESS
1950 * Success.
1951 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001952 * The operation state is not valid (not set up, IV required but
Gilles Peskinedcd14942018-07-12 00:30:52 +02001953 * not set, or already completed).
1954 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
1955 * The size of the \p output buffer is too small.
1956 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1957 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1958 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001959 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw484ba882019-08-13 14:41:52 +01001960 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001961 * \retval #PSA_ERROR_BAD_STATE
1962 * The library has not been previously initialized by psa_crypto_init().
1963 * It is implementation-dependent whether a failure to initialize
1964 * results in this error code.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001965 */
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001966psa_status_t psa_cipher_update(psa_cipher_operation_t *operation,
1967 const uint8_t *input,
mohammad1603503973b2018-03-12 15:59:30 +02001968 size_t input_length,
Andrew Thoelke47629d02019-03-22 11:24:17 +00001969 uint8_t *output,
Gilles Peskine2d277862018-06-18 15:41:12 +02001970 size_t output_size,
mohammad1603503973b2018-03-12 15:59:30 +02001971 size_t *output_length);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001972
Gilles Peskinedcd14942018-07-12 00:30:52 +02001973/** Finish encrypting or decrypting a message in a cipher operation.
1974 *
1975 * The application must call psa_cipher_encrypt_setup() or
1976 * psa_cipher_decrypt_setup() before calling this function. The choice
1977 * of setup function determines whether this function encrypts or
1978 * decrypts its input.
1979 *
1980 * This function finishes the encryption or decryption of the message
1981 * formed by concatenating the inputs passed to preceding calls to
1982 * psa_cipher_update().
1983 *
1984 * When this function returns, the operation becomes inactive.
1985 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001986 * \param[in,out] operation Active cipher operation.
1987 * \param[out] output Buffer where the output is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001988 * \param output_size Size of the \p output buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001989 * \param[out] output_length On success, the number of bytes
1990 * that make up the returned output.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001991 *
1992 * \retval #PSA_SUCCESS
1993 * Success.
1994 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001995 * The operation state is not valid (not set up, IV required but
Gilles Peskinedcd14942018-07-12 00:30:52 +02001996 * not set, or already completed).
1997 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
1998 * The size of the \p output buffer is too small.
1999 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2000 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2001 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002002 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01002003 * \retval #PSA_ERROR_BAD_STATE
2004 * The library has not been previously initialized by psa_crypto_init().
2005 * It is implementation-dependent whether a failure to initialize
2006 * results in this error code.
Gilles Peskinedcd14942018-07-12 00:30:52 +02002007 */
Gilles Peskine428dc5a2018-03-03 21:27:18 +01002008psa_status_t psa_cipher_finish(psa_cipher_operation_t *operation,
mohammad1603503973b2018-03-12 15:59:30 +02002009 uint8_t *output,
Moran Peker0071b872018-04-22 20:16:58 +03002010 size_t output_size,
mohammad1603503973b2018-03-12 15:59:30 +02002011 size_t *output_length);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01002012
Gilles Peskinedcd14942018-07-12 00:30:52 +02002013/** Abort a cipher operation.
2014 *
Gilles Peskinedcd14942018-07-12 00:30:52 +02002015 * Aborting an operation frees all associated resources except for the
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02002016 * \p operation structure itself. Once aborted, the operation object
2017 * can be reused for another operation by calling
2018 * psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup() again.
Gilles Peskinedcd14942018-07-12 00:30:52 +02002019 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02002020 * You may call this function any time after the operation object has
2021 * been initialized by any of the following methods:
2022 * - A call to psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup(),
2023 * whether it succeeds or not.
2024 * - Initializing the \c struct to all-bits-zero.
2025 * - Initializing the \c struct to logical zeros, e.g.
2026 * `psa_cipher_operation_t operation = {0}`.
Gilles Peskinedcd14942018-07-12 00:30:52 +02002027 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02002028 * In particular, calling psa_cipher_abort() after the operation has been
2029 * terminated by a call to psa_cipher_abort() or psa_cipher_finish()
2030 * is safe and has no effect.
2031 *
2032 * \param[in,out] operation Initialized cipher operation.
Gilles Peskinedcd14942018-07-12 00:30:52 +02002033 *
2034 * \retval #PSA_SUCCESS
2035 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002036 * \p operation is not an active cipher operation.
Gilles Peskinedcd14942018-07-12 00:30:52 +02002037 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2038 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002039 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01002040 * \retval #PSA_ERROR_BAD_STATE
2041 * The library has not been previously initialized by psa_crypto_init().
2042 * It is implementation-dependent whether a failure to initialize
2043 * results in this error code.
Gilles Peskinedcd14942018-07-12 00:30:52 +02002044 */
Gilles Peskine428dc5a2018-03-03 21:27:18 +01002045psa_status_t psa_cipher_abort(psa_cipher_operation_t *operation);
2046
2047/**@}*/
2048
Gilles Peskine3b555712018-03-03 21:27:57 +01002049/** \defgroup aead Authenticated encryption with associated data (AEAD)
2050 * @{
2051 */
2052
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002053/** Process an authenticated encryption operation.
Gilles Peskine3b555712018-03-03 21:27:57 +01002054 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01002055 * \param handle Handle to the key to use for the operation.
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002056 * \param alg The AEAD algorithm to compute
2057 * (\c PSA_ALG_XXX value such that
Gilles Peskine7256e6c2018-07-12 00:34:26 +02002058 * #PSA_ALG_IS_AEAD(\p alg) is true).
Gilles Peskineedd11a12018-07-12 01:08:58 +02002059 * \param[in] nonce Nonce or IV to use.
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002060 * \param nonce_length Size of the \p nonce buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002061 * \param[in] additional_data Additional data that will be authenticated
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002062 * but not encrypted.
2063 * \param additional_data_length Size of \p additional_data in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002064 * \param[in] plaintext Data that will be authenticated and
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002065 * encrypted.
2066 * \param plaintext_length Size of \p plaintext in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002067 * \param[out] ciphertext Output buffer for the authenticated and
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002068 * encrypted data. The additional data is not
2069 * part of this output. For algorithms where the
2070 * encrypted data and the authentication tag
2071 * are defined as separate outputs, the
2072 * authentication tag is appended to the
2073 * encrypted data.
2074 * \param ciphertext_size Size of the \p ciphertext buffer in bytes.
2075 * This must be at least
2076 * #PSA_AEAD_ENCRYPT_OUTPUT_SIZE(\p alg,
2077 * \p plaintext_length).
Gilles Peskineedd11a12018-07-12 01:08:58 +02002078 * \param[out] ciphertext_length On success, the size of the output
Gilles Peskine4c6fdbb2019-02-08 11:22:39 +01002079 * in the \p ciphertext buffer.
Gilles Peskine3b555712018-03-03 21:27:57 +01002080 *
Gilles Peskine28538492018-07-11 17:34:00 +02002081 * \retval #PSA_SUCCESS
Gilles Peskine3b555712018-03-03 21:27:57 +01002082 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01002083 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine28538492018-07-11 17:34:00 +02002084 * \retval #PSA_ERROR_NOT_PERMITTED
2085 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002086 * \p handle is not compatible with \p alg.
Gilles Peskine28538492018-07-11 17:34:00 +02002087 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002088 * \p alg is not supported or is not an AEAD algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02002089 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
Adrian L. Shaw484ba882019-08-13 14:41:52 +01002090 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
2091 * \p ciphertext_size is too small
Gilles Peskine28538492018-07-11 17:34:00 +02002092 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2093 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002094 * \retval #PSA_ERROR_CORRUPTION_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03002095 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03002096 * The library has not been previously initialized by psa_crypto_init().
2097 * It is implementation-dependent whether a failure to initialize
2098 * results in this error code.
Gilles Peskine3b555712018-03-03 21:27:57 +01002099 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01002100psa_status_t psa_aead_encrypt(psa_key_handle_t handle,
Gilles Peskine9fb0e012018-07-19 15:51:49 +02002101 psa_algorithm_t alg,
2102 const uint8_t *nonce,
2103 size_t nonce_length,
2104 const uint8_t *additional_data,
2105 size_t additional_data_length,
2106 const uint8_t *plaintext,
2107 size_t plaintext_length,
2108 uint8_t *ciphertext,
2109 size_t ciphertext_size,
2110 size_t *ciphertext_length);
Gilles Peskine3b555712018-03-03 21:27:57 +01002111
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002112/** Process an authenticated decryption operation.
Gilles Peskine3b555712018-03-03 21:27:57 +01002113 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01002114 * \param handle Handle to the key to use for the operation.
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002115 * \param alg The AEAD algorithm to compute
2116 * (\c PSA_ALG_XXX value such that
Gilles Peskine7256e6c2018-07-12 00:34:26 +02002117 * #PSA_ALG_IS_AEAD(\p alg) is true).
Gilles Peskineedd11a12018-07-12 01:08:58 +02002118 * \param[in] nonce Nonce or IV to use.
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002119 * \param nonce_length Size of the \p nonce buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002120 * \param[in] additional_data Additional data that has been authenticated
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002121 * but not encrypted.
2122 * \param additional_data_length Size of \p additional_data in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002123 * \param[in] ciphertext Data that has been authenticated and
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002124 * encrypted. For algorithms where the
2125 * encrypted data and the authentication tag
2126 * are defined as separate inputs, the buffer
2127 * must contain the encrypted data followed
2128 * by the authentication tag.
2129 * \param ciphertext_length Size of \p ciphertext in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002130 * \param[out] plaintext Output buffer for the decrypted data.
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002131 * \param plaintext_size Size of the \p plaintext buffer in bytes.
2132 * This must be at least
2133 * #PSA_AEAD_DECRYPT_OUTPUT_SIZE(\p alg,
2134 * \p ciphertext_length).
Gilles Peskineedd11a12018-07-12 01:08:58 +02002135 * \param[out] plaintext_length On success, the size of the output
Gilles Peskine4c6fdbb2019-02-08 11:22:39 +01002136 * in the \p plaintext buffer.
Gilles Peskine3b555712018-03-03 21:27:57 +01002137 *
Gilles Peskine28538492018-07-11 17:34:00 +02002138 * \retval #PSA_SUCCESS
Gilles Peskine3b555712018-03-03 21:27:57 +01002139 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01002140 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine28538492018-07-11 17:34:00 +02002141 * \retval #PSA_ERROR_INVALID_SIGNATURE
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002142 * The ciphertext is not authentic.
Gilles Peskine28538492018-07-11 17:34:00 +02002143 * \retval #PSA_ERROR_NOT_PERMITTED
2144 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002145 * \p handle is not compatible with \p alg.
Gilles Peskine28538492018-07-11 17:34:00 +02002146 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002147 * \p alg is not supported or is not an AEAD algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02002148 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
Adrian L. Shawc207ba32019-08-08 10:55:38 +01002149 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
2150 * \p plaintext_size or \p nonce_length is too small
Gilles Peskine28538492018-07-11 17:34:00 +02002151 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2152 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002153 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawc207ba32019-08-08 10:55:38 +01002154 * \retval #PSA_ERROR_STORAGE_FAILURE
itayzafrir90d8c7a2018-09-12 11:44:52 +03002155 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03002156 * The library has not been previously initialized by psa_crypto_init().
2157 * It is implementation-dependent whether a failure to initialize
2158 * results in this error code.
Gilles Peskine3b555712018-03-03 21:27:57 +01002159 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01002160psa_status_t psa_aead_decrypt(psa_key_handle_t handle,
Gilles Peskine9fb0e012018-07-19 15:51:49 +02002161 psa_algorithm_t alg,
2162 const uint8_t *nonce,
2163 size_t nonce_length,
2164 const uint8_t *additional_data,
2165 size_t additional_data_length,
2166 const uint8_t *ciphertext,
2167 size_t ciphertext_length,
2168 uint8_t *plaintext,
2169 size_t plaintext_size,
2170 size_t *plaintext_length);
Gilles Peskine3b555712018-03-03 21:27:57 +01002171
Gilles Peskine30a9e412019-01-14 18:36:12 +01002172/** The type of the state data structure for multipart AEAD operations.
2173 *
2174 * Before calling any function on an AEAD operation object, the application
2175 * must initialize it by any of the following means:
2176 * - Set the structure to all-bits-zero, for example:
2177 * \code
2178 * psa_aead_operation_t operation;
2179 * memset(&operation, 0, sizeof(operation));
2180 * \endcode
2181 * - Initialize the structure to logical zero values, for example:
2182 * \code
2183 * psa_aead_operation_t operation = {0};
2184 * \endcode
2185 * - Initialize the structure to the initializer #PSA_AEAD_OPERATION_INIT,
2186 * for example:
2187 * \code
2188 * psa_aead_operation_t operation = PSA_AEAD_OPERATION_INIT;
2189 * \endcode
2190 * - Assign the result of the function psa_aead_operation_init()
2191 * to the structure, for example:
2192 * \code
2193 * psa_aead_operation_t operation;
2194 * operation = psa_aead_operation_init();
2195 * \endcode
2196 *
2197 * This is an implementation-defined \c struct. Applications should not
2198 * make any assumptions about the content of this structure except
2199 * as directed by the documentation of a specific implementation. */
2200typedef struct psa_aead_operation_s psa_aead_operation_t;
2201
2202/** \def PSA_AEAD_OPERATION_INIT
2203 *
2204 * This macro returns a suitable initializer for an AEAD operation object of
2205 * type #psa_aead_operation_t.
2206 */
2207#ifdef __DOXYGEN_ONLY__
2208/* This is an example definition for documentation purposes.
2209 * Implementations should define a suitable value in `crypto_struct.h`.
2210 */
2211#define PSA_AEAD_OPERATION_INIT {0}
2212#endif
2213
2214/** Return an initial value for an AEAD operation object.
2215 */
2216static psa_aead_operation_t psa_aead_operation_init(void);
2217
2218/** Set the key for a multipart authenticated encryption operation.
2219 *
2220 * The sequence of operations to encrypt a message with authentication
2221 * is as follows:
2222 * -# Allocate an operation object which will be passed to all the functions
2223 * listed here.
2224 * -# Initialize the operation object with one of the methods described in the
2225 * documentation for #psa_aead_operation_t, e.g.
2226 * PSA_AEAD_OPERATION_INIT.
2227 * -# Call psa_aead_encrypt_setup() to specify the algorithm and key.
Gilles Peskinebc59c852019-01-17 15:26:08 +01002228 * -# If needed, call psa_aead_set_lengths() to specify the length of the
2229 * inputs to the subsequent calls to psa_aead_update_ad() and
2230 * psa_aead_update(). See the documentation of psa_aead_set_lengths()
2231 * for details.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002232 * -# Call either psa_aead_generate_nonce() or psa_aead_set_nonce() to
2233 * generate or set the nonce. You should use
2234 * psa_aead_generate_nonce() unless the protocol you are implementing
2235 * requires a specific nonce value.
2236 * -# Call psa_aead_update_ad() zero, one or more times, passing a fragment
2237 * of the non-encrypted additional authenticated data each time.
2238 * -# Call psa_aead_update() zero, one or more times, passing a fragment
Gilles Peskinea05602d2019-01-17 15:25:52 +01002239 * of the message to encrypt each time.
Adrian L. Shaw67257572019-08-15 10:53:47 +01002240 * -# Call psa_aead_finish().
Gilles Peskine30a9e412019-01-14 18:36:12 +01002241 *
2242 * The application may call psa_aead_abort() at any time after the operation
2243 * has been initialized.
2244 *
2245 * After a successful call to psa_aead_encrypt_setup(), the application must
2246 * eventually terminate the operation. The following events terminate an
2247 * operation:
2248 * - A failed call to any of the \c psa_aead_xxx functions.
2249 * - A call to psa_aead_finish(), psa_aead_verify() or psa_aead_abort().
2250 *
2251 * \param[in,out] operation The operation object to set up. It must have
2252 * been initialized as per the documentation for
2253 * #psa_aead_operation_t and not yet in use.
2254 * \param handle Handle to the key to use for the operation.
2255 * It must remain valid until the operation
2256 * terminates.
2257 * \param alg The AEAD algorithm to compute
2258 * (\c PSA_ALG_XXX value such that
2259 * #PSA_ALG_IS_AEAD(\p alg) is true).
2260 *
2261 * \retval #PSA_SUCCESS
2262 * Success.
2263 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine30a9e412019-01-14 18:36:12 +01002264 * \retval #PSA_ERROR_NOT_PERMITTED
2265 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002266 * \p handle is not compatible with \p alg.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002267 * \retval #PSA_ERROR_NOT_SUPPORTED
2268 * \p alg is not supported or is not an AEAD algorithm.
2269 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2270 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2271 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002272 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw3e412492019-08-08 15:10:33 +01002273 * \retval #PSA_ERROR_STORAGE_FAILURE
Gilles Peskine30a9e412019-01-14 18:36:12 +01002274 * \retval #PSA_ERROR_BAD_STATE
2275 * The library has not been previously initialized by psa_crypto_init().
2276 * It is implementation-dependent whether a failure to initialize
2277 * results in this error code.
2278 */
2279psa_status_t psa_aead_encrypt_setup(psa_aead_operation_t *operation,
2280 psa_key_handle_t handle,
2281 psa_algorithm_t alg);
2282
2283/** Set the key for a multipart authenticated decryption operation.
2284 *
2285 * The sequence of operations to decrypt a message with authentication
2286 * is as follows:
2287 * -# Allocate an operation object which will be passed to all the functions
2288 * listed here.
2289 * -# Initialize the operation object with one of the methods described in the
2290 * documentation for #psa_aead_operation_t, e.g.
2291 * PSA_AEAD_OPERATION_INIT.
2292 * -# Call psa_aead_decrypt_setup() to specify the algorithm and key.
Gilles Peskinebc59c852019-01-17 15:26:08 +01002293 * -# If needed, call psa_aead_set_lengths() to specify the length of the
2294 * inputs to the subsequent calls to psa_aead_update_ad() and
2295 * psa_aead_update(). See the documentation of psa_aead_set_lengths()
2296 * for details.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002297 * -# Call psa_aead_set_nonce() with the nonce for the decryption.
2298 * -# Call psa_aead_update_ad() zero, one or more times, passing a fragment
2299 * of the non-encrypted additional authenticated data each time.
2300 * -# Call psa_aead_update() zero, one or more times, passing a fragment
Gilles Peskinea05602d2019-01-17 15:25:52 +01002301 * of the ciphertext to decrypt each time.
2302 * -# Call psa_aead_verify().
Gilles Peskine30a9e412019-01-14 18:36:12 +01002303 *
2304 * The application may call psa_aead_abort() at any time after the operation
2305 * has been initialized.
2306 *
2307 * After a successful call to psa_aead_decrypt_setup(), the application must
2308 * eventually terminate the operation. The following events terminate an
2309 * operation:
2310 * - A failed call to any of the \c psa_aead_xxx functions.
2311 * - A call to psa_aead_finish(), psa_aead_verify() or psa_aead_abort().
2312 *
2313 * \param[in,out] operation The operation object to set up. It must have
2314 * been initialized as per the documentation for
2315 * #psa_aead_operation_t and not yet in use.
2316 * \param handle Handle to the key to use for the operation.
2317 * It must remain valid until the operation
2318 * terminates.
2319 * \param alg The AEAD algorithm to compute
2320 * (\c PSA_ALG_XXX value such that
2321 * #PSA_ALG_IS_AEAD(\p alg) is true).
2322 *
2323 * \retval #PSA_SUCCESS
2324 * Success.
2325 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine30a9e412019-01-14 18:36:12 +01002326 * \retval #PSA_ERROR_NOT_PERMITTED
2327 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002328 * \p handle is not compatible with \p alg.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002329 * \retval #PSA_ERROR_NOT_SUPPORTED
2330 * \p alg is not supported or is not an AEAD algorithm.
2331 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2332 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2333 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002334 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw3e412492019-08-08 15:10:33 +01002335 * \retval #PSA_ERROR_STORAGE_FAILURE
Gilles Peskine30a9e412019-01-14 18:36:12 +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.
2340 */
2341psa_status_t psa_aead_decrypt_setup(psa_aead_operation_t *operation,
2342 psa_key_handle_t handle,
2343 psa_algorithm_t alg);
2344
2345/** Generate a random nonce for an authenticated encryption operation.
2346 *
2347 * This function generates a random nonce for the authenticated encryption
2348 * operation with an appropriate size for the chosen algorithm, key type
2349 * and key size.
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 *
2356 * \param[in,out] operation Active AEAD operation.
2357 * \param[out] nonce Buffer where the generated nonce is to be
2358 * written.
2359 * \param nonce_size Size of the \p nonce buffer in bytes.
2360 * \param[out] nonce_length On success, the number of bytes of the
2361 * generated nonce.
2362 *
2363 * \retval #PSA_SUCCESS
2364 * Success.
2365 * \retval #PSA_ERROR_BAD_STATE
2366 * The operation state is not valid (not set up, or nonce already set).
2367 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
2368 * The size of the \p nonce buffer is too small.
2369 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2370 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2371 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002372 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw484ba882019-08-13 14:41:52 +01002373 * \retval #PSA_ERROR_STORAGE_FAILURE
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_generate_nonce(psa_aead_operation_t *operation,
Andrew Thoelked16bdac2019-05-15 12:34:01 +01002380 uint8_t *nonce,
Gilles Peskine30a9e412019-01-14 18:36:12 +01002381 size_t nonce_size,
2382 size_t *nonce_length);
2383
2384/** Set the nonce for an authenticated encryption or decryption operation.
2385 *
2386 * This function sets the nonce for the authenticated
2387 * encryption or decryption operation.
2388 *
2389 * The application must call psa_aead_encrypt_setup() before
2390 * calling this function.
2391 *
2392 * If this function returns an error status, the operation becomes inactive.
2393 *
Gilles Peskinea05602d2019-01-17 15:25:52 +01002394 * \note When encrypting, applications should use psa_aead_generate_nonce()
Gilles Peskine30a9e412019-01-14 18:36:12 +01002395 * instead of this function, unless implementing a protocol that requires
2396 * a non-random IV.
2397 *
2398 * \param[in,out] operation Active AEAD operation.
Gilles Peskinea05602d2019-01-17 15:25:52 +01002399 * \param[in] nonce Buffer containing the nonce to use.
2400 * \param nonce_length Size of the nonce in bytes.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002401 *
2402 * \retval #PSA_SUCCESS
2403 * Success.
2404 * \retval #PSA_ERROR_BAD_STATE
2405 * The operation state is not valid (not set up, or nonce already set).
2406 * \retval #PSA_ERROR_INVALID_ARGUMENT
2407 * The size of \p nonce is not acceptable for the chosen algorithm.
2408 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2409 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2410 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002411 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw484ba882019-08-13 14:41:52 +01002412 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01002413 * \retval #PSA_ERROR_BAD_STATE
2414 * The library has not been previously initialized by psa_crypto_init().
2415 * It is implementation-dependent whether a failure to initialize
2416 * results in this error code.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002417 */
2418psa_status_t psa_aead_set_nonce(psa_aead_operation_t *operation,
Andrew Thoelked16bdac2019-05-15 12:34:01 +01002419 const uint8_t *nonce,
Gilles Peskine30a9e412019-01-14 18:36:12 +01002420 size_t nonce_length);
2421
Gilles Peskinebc59c852019-01-17 15:26:08 +01002422/** Declare the lengths of the message and additional data for AEAD.
2423 *
2424 * The application must call this function before calling
2425 * psa_aead_update_ad() or psa_aead_update() if the algorithm for
2426 * the operation requires it. If the algorithm does not require it,
2427 * calling this function is optional, but if this function is called
2428 * then the implementation must enforce the lengths.
2429 *
2430 * You may call this function before or after setting the nonce with
2431 * psa_aead_set_nonce() or psa_aead_generate_nonce().
2432 *
2433 * - For #PSA_ALG_CCM, calling this function is required.
2434 * - For the other AEAD algorithms defined in this specification, calling
2435 * this function is not required.
2436 * - For vendor-defined algorithm, refer to the vendor documentation.
2437 *
2438 * \param[in,out] operation Active AEAD operation.
2439 * \param ad_length Size of the non-encrypted additional
2440 * authenticated data in bytes.
2441 * \param plaintext_length Size of the plaintext to encrypt in bytes.
2442 *
2443 * \retval #PSA_SUCCESS
2444 * Success.
2445 * \retval #PSA_ERROR_BAD_STATE
2446 * The operation state is not valid (not set up, already completed,
2447 * or psa_aead_update_ad() or psa_aead_update() already called).
2448 * \retval #PSA_ERROR_INVALID_ARGUMENT
2449 * At least one of the lengths is not acceptable for the chosen
2450 * algorithm.
2451 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2452 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2453 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002454 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw484ba882019-08-13 14:41:52 +01002455 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01002456 * \retval #PSA_ERROR_BAD_STATE
2457 * The library has not been previously initialized by psa_crypto_init().
2458 * It is implementation-dependent whether a failure to initialize
2459 * results in this error code.
Gilles Peskinebc59c852019-01-17 15:26:08 +01002460 */
2461psa_status_t psa_aead_set_lengths(psa_aead_operation_t *operation,
2462 size_t ad_length,
2463 size_t plaintext_length);
2464
Gilles Peskine30a9e412019-01-14 18:36:12 +01002465/** Pass additional data to an active AEAD operation.
2466 *
2467 * Additional data is authenticated, but not encrypted.
2468 *
2469 * You may call this function multiple times to pass successive fragments
2470 * of the additional data. You may not call this function after passing
2471 * data to encrypt or decrypt with psa_aead_update().
2472 *
2473 * Before calling this function, you must:
2474 * 1. Call either psa_aead_encrypt_setup() or psa_aead_decrypt_setup().
2475 * 2. Set the nonce with psa_aead_generate_nonce() or psa_aead_set_nonce().
2476 *
2477 * If this function returns an error status, the operation becomes inactive.
2478 *
2479 * \warning When decrypting, until psa_aead_verify() has returned #PSA_SUCCESS,
2480 * there is no guarantee that the input is valid. Therefore, until
2481 * you have called psa_aead_verify() and it has returned #PSA_SUCCESS,
2482 * treat the input as untrusted and prepare to undo any action that
2483 * depends on the input if psa_aead_verify() returns an error status.
2484 *
2485 * \param[in,out] operation Active AEAD operation.
2486 * \param[in] input Buffer containing the fragment of
2487 * additional data.
2488 * \param input_length Size of the \p input buffer in bytes.
2489 *
2490 * \retval #PSA_SUCCESS
2491 * Success.
2492 * \retval #PSA_ERROR_BAD_STATE
2493 * The operation state is not valid (not set up, nonce not set,
2494 * psa_aead_update() already called, or operation already completed).
Gilles Peskinebc59c852019-01-17 15:26:08 +01002495 * \retval #PSA_ERROR_INVALID_ARGUMENT
2496 * The total input length overflows the additional data length that
2497 * was previously specified with psa_aead_set_lengths().
Gilles Peskine30a9e412019-01-14 18:36:12 +01002498 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2499 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2500 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002501 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw484ba882019-08-13 14:41:52 +01002502 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01002503 * \retval #PSA_ERROR_BAD_STATE
2504 * The library has not been previously initialized by psa_crypto_init().
2505 * It is implementation-dependent whether a failure to initialize
2506 * results in this error code.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002507 */
2508psa_status_t psa_aead_update_ad(psa_aead_operation_t *operation,
2509 const uint8_t *input,
2510 size_t input_length);
2511
2512/** Encrypt or decrypt a message fragment in an active AEAD operation.
2513 *
2514 * Before calling this function, you must:
2515 * 1. Call either psa_aead_encrypt_setup() or psa_aead_decrypt_setup().
2516 * The choice of setup function determines whether this function
2517 * encrypts or decrypts its input.
2518 * 2. Set the nonce with psa_aead_generate_nonce() or psa_aead_set_nonce().
2519 * 3. Call psa_aead_update_ad() to pass all the additional data.
2520 *
2521 * If this function returns an error status, the operation becomes inactive.
2522 *
2523 * \warning When decrypting, until psa_aead_verify() has returned #PSA_SUCCESS,
2524 * there is no guarantee that the input is valid. Therefore, until
2525 * you have called psa_aead_verify() and it has returned #PSA_SUCCESS:
2526 * - Do not use the output in any way other than storing it in a
2527 * confidential location. If you take any action that depends
2528 * on the tentative decrypted data, this action will need to be
2529 * undone if the input turns out not to be valid. Furthermore,
2530 * if an adversary can observe that this action took place
2531 * (for example through timing), they may be able to use this
2532 * fact as an oracle to decrypt any message encrypted with the
2533 * same key.
2534 * - In particular, do not copy the output anywhere but to a
2535 * memory or storage space that you have exclusive access to.
2536 *
Gilles Peskinef02aec92019-05-06 15:42:54 +02002537 * This function does not require the input to be aligned to any
2538 * particular block boundary. If the implementation can only process
Gilles Peskineac99e322019-05-14 16:10:53 +02002539 * a whole block at a time, it must consume all the input provided, but
2540 * it may delay the end of the corresponding output until a subsequent
2541 * call to psa_aead_update(), psa_aead_finish() or psa_aead_verify()
2542 * provides sufficient input. The amount of data that can be delayed
2543 * in this way is bounded by #PSA_AEAD_UPDATE_OUTPUT_SIZE.
Gilles Peskinef02aec92019-05-06 15:42:54 +02002544 *
Gilles Peskine30a9e412019-01-14 18:36:12 +01002545 * \param[in,out] operation Active AEAD operation.
2546 * \param[in] input Buffer containing the message fragment to
2547 * encrypt or decrypt.
2548 * \param input_length Size of the \p input buffer in bytes.
2549 * \param[out] output Buffer where the output is to be written.
2550 * \param output_size Size of the \p output buffer in bytes.
Gilles Peskine49dd8d82019-05-06 15:16:19 +02002551 * This must be at least
2552 * #PSA_AEAD_UPDATE_OUTPUT_SIZE(\c alg,
2553 * \p input_length) where \c alg is the
2554 * algorithm that is being calculated.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002555 * \param[out] output_length On success, the number of bytes
2556 * that make up the returned output.
2557 *
2558 * \retval #PSA_SUCCESS
2559 * Success.
2560 * \retval #PSA_ERROR_BAD_STATE
2561 * The operation state is not valid (not set up, nonce not set
2562 * or already completed).
2563 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
2564 * The size of the \p output buffer is too small.
Gilles Peskine49dd8d82019-05-06 15:16:19 +02002565 * You can determine a sufficient buffer size by calling
2566 * #PSA_AEAD_UPDATE_OUTPUT_SIZE(\c alg, \p input_length)
2567 * where \c alg is the algorithm that is being calculated.
Gilles Peskinebc59c852019-01-17 15:26:08 +01002568 * \retval #PSA_ERROR_INVALID_ARGUMENT
2569 * The total length of input to psa_aead_update_ad() so far is
2570 * less than the additional data length that was previously
2571 * specified with psa_aead_set_lengths().
2572 * \retval #PSA_ERROR_INVALID_ARGUMENT
2573 * The total input length overflows the plaintext length that
2574 * was previously specified with psa_aead_set_lengths().
Gilles Peskine30a9e412019-01-14 18:36:12 +01002575 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2576 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2577 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002578 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw484ba882019-08-13 14:41:52 +01002579 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01002580 * \retval #PSA_ERROR_BAD_STATE
2581 * The library has not been previously initialized by psa_crypto_init().
2582 * It is implementation-dependent whether a failure to initialize
2583 * results in this error code.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002584 */
2585psa_status_t psa_aead_update(psa_aead_operation_t *operation,
2586 const uint8_t *input,
2587 size_t input_length,
Andrew Thoelked16bdac2019-05-15 12:34:01 +01002588 uint8_t *output,
Gilles Peskine30a9e412019-01-14 18:36:12 +01002589 size_t output_size,
2590 size_t *output_length);
2591
2592/** Finish encrypting a message in an AEAD operation.
2593 *
2594 * The operation must have been set up with psa_aead_encrypt_setup().
2595 *
2596 * This function finishes the authentication of the additional data
2597 * formed by concatenating the inputs passed to preceding calls to
2598 * psa_aead_update_ad() with the plaintext formed by concatenating the
2599 * inputs passed to preceding calls to psa_aead_update().
2600 *
2601 * This function has two output buffers:
2602 * - \p ciphertext contains trailing ciphertext that was buffered from
Gilles Peskinef02aec92019-05-06 15:42:54 +02002603 * preceding calls to psa_aead_update().
Gilles Peskine30a9e412019-01-14 18:36:12 +01002604 * - \p tag contains the authentication tag. Its length is always
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002605 * #PSA_AEAD_TAG_LENGTH(\c alg) where \c alg is the AEAD algorithm
Gilles Peskine30a9e412019-01-14 18:36:12 +01002606 * that the operation performs.
2607 *
2608 * When this function returns, the operation becomes inactive.
2609 *
2610 * \param[in,out] operation Active AEAD operation.
2611 * \param[out] ciphertext Buffer where the last part of the ciphertext
2612 * is to be written.
2613 * \param ciphertext_size Size of the \p ciphertext buffer in bytes.
Gilles Peskine49dd8d82019-05-06 15:16:19 +02002614 * This must be at least
2615 * #PSA_AEAD_FINISH_OUTPUT_SIZE(\c alg) where
2616 * \c alg is the algorithm that is being
2617 * calculated.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002618 * \param[out] ciphertext_length On success, the number of bytes of
2619 * returned ciphertext.
2620 * \param[out] tag Buffer where the authentication tag is
2621 * to be written.
2622 * \param tag_size Size of the \p tag buffer in bytes.
Gilles Peskine49dd8d82019-05-06 15:16:19 +02002623 * This must be at least
2624 * #PSA_AEAD_TAG_LENGTH(\c alg) where \c alg is
2625 * the algorithm that is being calculated.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002626 * \param[out] tag_length On success, the number of bytes
2627 * that make up the returned tag.
2628 *
2629 * \retval #PSA_SUCCESS
2630 * Success.
2631 * \retval #PSA_ERROR_BAD_STATE
2632 * The operation state is not valid (not set up, nonce not set,
2633 * decryption, or already completed).
2634 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002635 * The size of the \p ciphertext or \p tag buffer is too small.
Gilles Peskine49dd8d82019-05-06 15:16:19 +02002636 * You can determine a sufficient buffer size for \p ciphertext by
2637 * calling #PSA_AEAD_FINISH_OUTPUT_SIZE(\c alg)
2638 * where \c alg is the algorithm that is being calculated.
2639 * You can determine a sufficient buffer size for \p tag by
2640 * calling #PSA_AEAD_TAG_LENGTH(\c alg).
Gilles Peskinebc59c852019-01-17 15:26:08 +01002641 * \retval #PSA_ERROR_INVALID_ARGUMENT
2642 * The total length of input to psa_aead_update_ad() so far is
2643 * less than the additional data length that was previously
2644 * specified with psa_aead_set_lengths().
2645 * \retval #PSA_ERROR_INVALID_ARGUMENT
2646 * The total length of input to psa_aead_update() so far is
2647 * less than the plaintext length that was previously
2648 * specified with psa_aead_set_lengths().
Gilles Peskine30a9e412019-01-14 18:36:12 +01002649 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2650 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2651 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002652 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw484ba882019-08-13 14:41:52 +01002653 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01002654 * \retval #PSA_ERROR_BAD_STATE
2655 * The library has not been previously initialized by psa_crypto_init().
2656 * It is implementation-dependent whether a failure to initialize
2657 * results in this error code.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002658 */
2659psa_status_t psa_aead_finish(psa_aead_operation_t *operation,
Gilles Peskinea05602d2019-01-17 15:25:52 +01002660 uint8_t *ciphertext,
2661 size_t ciphertext_size,
2662 size_t *ciphertext_length,
Gilles Peskine30a9e412019-01-14 18:36:12 +01002663 uint8_t *tag,
2664 size_t tag_size,
2665 size_t *tag_length);
2666
2667/** Finish authenticating and decrypting a message in an AEAD operation.
2668 *
2669 * The operation must have been set up with psa_aead_decrypt_setup().
2670 *
2671 * This function finishes the authentication of the additional data
2672 * formed by concatenating the inputs passed to preceding calls to
2673 * psa_aead_update_ad() with the ciphertext formed by concatenating the
2674 * inputs passed to preceding calls to psa_aead_update().
2675 *
2676 * When this function returns, the operation becomes inactive.
2677 *
2678 * \param[in,out] operation Active AEAD operation.
Gilles Peskine5211efb2019-05-06 15:56:05 +02002679 * \param[out] plaintext Buffer where the last part of the plaintext
Gilles Peskineac99e322019-05-14 16:10:53 +02002680 * is to be written. This is the remaining data
Gilles Peskine5211efb2019-05-06 15:56:05 +02002681 * from previous calls to psa_aead_update()
2682 * that could not be processed until the end
2683 * of the input.
2684 * \param plaintext_size Size of the \p plaintext buffer in bytes.
Gilles Peskine49dd8d82019-05-06 15:16:19 +02002685 * This must be at least
2686 * #PSA_AEAD_VERIFY_OUTPUT_SIZE(\c alg) where
2687 * \c alg is the algorithm that is being
2688 * calculated.
Gilles Peskine5211efb2019-05-06 15:56:05 +02002689 * \param[out] plaintext_length On success, the number of bytes of
2690 * returned plaintext.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002691 * \param[in] tag Buffer containing the authentication tag.
2692 * \param tag_length Size of the \p tag buffer in bytes.
2693 *
2694 * \retval #PSA_SUCCESS
2695 * Success.
2696 * \retval #PSA_ERROR_BAD_STATE
2697 * The operation state is not valid (not set up, nonce not set,
2698 * encryption, or already completed).
Gilles Peskine49dd8d82019-05-06 15:16:19 +02002699 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
2700 * The size of the \p plaintext buffer is too small.
2701 * You can determine a sufficient buffer size for \p plaintext by
2702 * calling #PSA_AEAD_VERIFY_OUTPUT_SIZE(\c alg)
2703 * where \c alg is the algorithm that is being calculated.
Gilles Peskinebc59c852019-01-17 15:26:08 +01002704 * \retval #PSA_ERROR_INVALID_ARGUMENT
2705 * The total length of input to psa_aead_update_ad() so far is
2706 * less than the additional data length that was previously
2707 * specified with psa_aead_set_lengths().
2708 * \retval #PSA_ERROR_INVALID_ARGUMENT
2709 * The total length of input to psa_aead_update() so far is
2710 * less than the plaintext length that was previously
2711 * specified with psa_aead_set_lengths().
Gilles Peskine30a9e412019-01-14 18:36:12 +01002712 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2713 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2714 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002715 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw484ba882019-08-13 14:41:52 +01002716 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01002717 * \retval #PSA_ERROR_BAD_STATE
2718 * The library has not been previously initialized by psa_crypto_init().
2719 * It is implementation-dependent whether a failure to initialize
2720 * results in this error code.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002721 */
2722psa_status_t psa_aead_verify(psa_aead_operation_t *operation,
Gilles Peskine5211efb2019-05-06 15:56:05 +02002723 uint8_t *plaintext,
2724 size_t plaintext_size,
2725 size_t *plaintext_length,
Gilles Peskine30a9e412019-01-14 18:36:12 +01002726 const uint8_t *tag,
2727 size_t tag_length);
2728
2729/** Abort an AEAD operation.
2730 *
2731 * Aborting an operation frees all associated resources except for the
2732 * \p operation structure itself. Once aborted, the operation object
2733 * can be reused for another operation by calling
2734 * psa_aead_encrypt_setup() or psa_aead_decrypt_setup() again.
2735 *
2736 * You may call this function any time after the operation object has
2737 * been initialized by any of the following methods:
2738 * - A call to psa_aead_encrypt_setup() or psa_aead_decrypt_setup(),
2739 * whether it succeeds or not.
2740 * - Initializing the \c struct to all-bits-zero.
2741 * - Initializing the \c struct to logical zeros, e.g.
2742 * `psa_aead_operation_t operation = {0}`.
2743 *
2744 * In particular, calling psa_aead_abort() after the operation has been
2745 * terminated by a call to psa_aead_abort() or psa_aead_finish()
2746 * is safe and has no effect.
2747 *
2748 * \param[in,out] operation Initialized AEAD operation.
2749 *
2750 * \retval #PSA_SUCCESS
2751 * \retval #PSA_ERROR_BAD_STATE
2752 * \p operation is not an active AEAD operation.
2753 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2754 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002755 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01002756 * \retval #PSA_ERROR_BAD_STATE
2757 * The library has not been previously initialized by psa_crypto_init().
2758 * It is implementation-dependent whether a failure to initialize
2759 * results in this error code.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002760 */
2761psa_status_t psa_aead_abort(psa_aead_operation_t *operation);
2762
Gilles Peskine3b555712018-03-03 21:27:57 +01002763/**@}*/
2764
Gilles Peskine20035e32018-02-03 22:44:14 +01002765/** \defgroup asymmetric Asymmetric cryptography
2766 * @{
2767 */
2768
2769/**
2770 * \brief Sign a hash or short message with a private key.
2771 *
Gilles Peskine08bac712018-06-26 16:14:46 +02002772 * Note that to perform a hash-and-sign signature algorithm, you must
Gilles Peskineda8191d1c2018-07-08 19:46:38 +02002773 * first calculate the hash by calling psa_hash_setup(), psa_hash_update()
Gilles Peskine08bac712018-06-26 16:14:46 +02002774 * and psa_hash_finish(). Then pass the resulting hash as the \p hash
2775 * parameter to this function. You can use #PSA_ALG_SIGN_GET_HASH(\p alg)
2776 * to determine the hash algorithm to use.
2777 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01002778 * \param handle Handle to the key to use for the operation.
2779 * It must be an asymmetric key pair.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002780 * \param alg A signature algorithm that is compatible with
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002781 * the type of \p handle.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002782 * \param[in] hash The hash or message to sign.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002783 * \param hash_length Size of the \p hash buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002784 * \param[out] signature Buffer where the signature is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002785 * \param signature_size Size of the \p signature buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002786 * \param[out] signature_length On success, the number of bytes
2787 * that make up the returned signature value.
Gilles Peskine308b91d2018-02-08 09:47:44 +01002788 *
Gilles Peskine28538492018-07-11 17:34:00 +02002789 * \retval #PSA_SUCCESS
Adrian L. Shaw27c12152019-08-08 11:10:32 +01002790 * \retval #PSA_ERROR_INVALID_HANDLE
2791 * \retval #PSA_ERROR_NOT_PERMITTED
Gilles Peskine28538492018-07-11 17:34:00 +02002792 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002793 * The size of the \p signature buffer is too small. You can
Gilles Peskine308b91d2018-02-08 09:47:44 +01002794 * determine a sufficient buffer size by calling
Gilles Peskine7256e6c2018-07-12 00:34:26 +02002795 * #PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
Gilles Peskine308b91d2018-02-08 09:47:44 +01002796 * where \c key_type and \c key_bits are the type and bit-size
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002797 * respectively of \p handle.
Gilles Peskine28538492018-07-11 17:34:00 +02002798 * \retval #PSA_ERROR_NOT_SUPPORTED
2799 * \retval #PSA_ERROR_INVALID_ARGUMENT
2800 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2801 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2802 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002803 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw27c12152019-08-08 11:10:32 +01002804 * \retval #PSA_ERROR_STORAGE_FAILURE
Gilles Peskine28538492018-07-11 17:34:00 +02002805 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
itayzafrir90d8c7a2018-09-12 11:44:52 +03002806 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03002807 * The library has not been previously initialized by psa_crypto_init().
2808 * It is implementation-dependent whether a failure to initialize
2809 * results in this error code.
Gilles Peskine20035e32018-02-03 22:44:14 +01002810 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01002811psa_status_t psa_asymmetric_sign(psa_key_handle_t handle,
Gilles Peskine20035e32018-02-03 22:44:14 +01002812 psa_algorithm_t alg,
2813 const uint8_t *hash,
2814 size_t hash_length,
Gilles Peskine20035e32018-02-03 22:44:14 +01002815 uint8_t *signature,
2816 size_t signature_size,
2817 size_t *signature_length);
2818
2819/**
2820 * \brief Verify the signature a hash or short message using a public key.
2821 *
Gilles Peskine08bac712018-06-26 16:14:46 +02002822 * Note that to perform a hash-and-sign signature algorithm, you must
Gilles Peskineda8191d1c2018-07-08 19:46:38 +02002823 * first calculate the hash by calling psa_hash_setup(), psa_hash_update()
Gilles Peskine08bac712018-06-26 16:14:46 +02002824 * and psa_hash_finish(). Then pass the resulting hash as the \p hash
2825 * parameter to this function. You can use #PSA_ALG_SIGN_GET_HASH(\p alg)
2826 * to determine the hash algorithm to use.
2827 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01002828 * \param handle Handle to the key to use for the operation.
2829 * It must be a public key or an asymmetric key pair.
Gilles Peskine308b91d2018-02-08 09:47:44 +01002830 * \param alg A signature algorithm that is compatible with
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002831 * the type of \p handle.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002832 * \param[in] hash The hash or message whose signature is to be
Gilles Peskine08bac712018-06-26 16:14:46 +02002833 * verified.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002834 * \param hash_length Size of the \p hash buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002835 * \param[in] signature Buffer containing the signature to verify.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002836 * \param signature_length Size of the \p signature buffer in bytes.
Gilles Peskine308b91d2018-02-08 09:47:44 +01002837 *
Gilles Peskine28538492018-07-11 17:34:00 +02002838 * \retval #PSA_SUCCESS
Gilles Peskine308b91d2018-02-08 09:47:44 +01002839 * The signature is valid.
Adrian L. Shaw6e758c92019-08-08 11:11:43 +01002840 * \retval #PSA_ERROR_INVALID_HANDLE
2841 * \retval #PSA_ERROR_NOT_PERMITTED
Gilles Peskine28538492018-07-11 17:34:00 +02002842 * \retval #PSA_ERROR_INVALID_SIGNATURE
Gilles Peskine308b91d2018-02-08 09:47:44 +01002843 * The calculation was perfomed successfully, but the passed
2844 * signature is not a valid signature.
Gilles Peskine28538492018-07-11 17:34:00 +02002845 * \retval #PSA_ERROR_NOT_SUPPORTED
2846 * \retval #PSA_ERROR_INVALID_ARGUMENT
2847 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2848 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2849 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002850 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw6e758c92019-08-08 11:11:43 +01002851 * \retval #PSA_ERROR_STORAGE_FAILURE
itayzafrir90d8c7a2018-09-12 11:44:52 +03002852 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03002853 * The library has not been previously initialized by psa_crypto_init().
2854 * It is implementation-dependent whether a failure to initialize
2855 * results in this error code.
Gilles Peskine20035e32018-02-03 22:44:14 +01002856 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01002857psa_status_t psa_asymmetric_verify(psa_key_handle_t handle,
Gilles Peskine20035e32018-02-03 22:44:14 +01002858 psa_algorithm_t alg,
2859 const uint8_t *hash,
2860 size_t hash_length,
Gilles Peskinee9191ff2018-06-27 14:58:41 +02002861 const uint8_t *signature,
Gilles Peskine526fab02018-06-27 18:19:40 +02002862 size_t signature_length);
Gilles Peskine20035e32018-02-03 22:44:14 +01002863
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002864/**
2865 * \brief Encrypt a short message with a public key.
2866 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01002867 * \param handle Handle to the key to use for the operation.
2868 * It must be a public key or an asymmetric
2869 * key pair.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002870 * \param alg An asymmetric encryption algorithm that is
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002871 * compatible with the type of \p handle.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002872 * \param[in] input The message to encrypt.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002873 * \param input_length Size of the \p input buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002874 * \param[in] salt A salt or label, if supported by the
2875 * encryption algorithm.
2876 * If the algorithm does not support a
2877 * salt, pass \c NULL.
2878 * If the algorithm supports an optional
2879 * salt and you do not want to pass a salt,
2880 * pass \c NULL.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002881 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02002882 * - For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is
2883 * supported.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002884 * \param salt_length Size of the \p salt buffer in bytes.
2885 * If \p salt is \c NULL, pass 0.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002886 * \param[out] output Buffer where the encrypted message is to
2887 * be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002888 * \param output_size Size of the \p output buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002889 * \param[out] output_length On success, the number of bytes
2890 * that make up the returned output.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002891 *
Gilles Peskine28538492018-07-11 17:34:00 +02002892 * \retval #PSA_SUCCESS
Adrian L. Shawf961d5c2019-08-08 10:27:50 +01002893 * \retval #PSA_ERROR_INVALID_HANDLE
2894 * \retval #PSA_ERROR_NOT_PERMITTED
Gilles Peskine28538492018-07-11 17:34:00 +02002895 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002896 * The size of the \p output buffer is too small. You can
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002897 * determine a sufficient buffer size by calling
Gilles Peskine7256e6c2018-07-12 00:34:26 +02002898 * #PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002899 * where \c key_type and \c key_bits are the type and bit-size
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002900 * respectively of \p handle.
Gilles Peskine28538492018-07-11 17:34:00 +02002901 * \retval #PSA_ERROR_NOT_SUPPORTED
2902 * \retval #PSA_ERROR_INVALID_ARGUMENT
2903 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2904 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2905 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002906 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawf961d5c2019-08-08 10:27:50 +01002907 * \retval #PSA_ERROR_STORAGE_FAILURE
Gilles Peskine28538492018-07-11 17:34:00 +02002908 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
itayzafrir90d8c7a2018-09-12 11:44:52 +03002909 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03002910 * The library has not been previously initialized by psa_crypto_init().
2911 * It is implementation-dependent whether a failure to initialize
2912 * results in this error code.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002913 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01002914psa_status_t psa_asymmetric_encrypt(psa_key_handle_t handle,
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002915 psa_algorithm_t alg,
2916 const uint8_t *input,
2917 size_t input_length,
2918 const uint8_t *salt,
2919 size_t salt_length,
2920 uint8_t *output,
2921 size_t output_size,
2922 size_t *output_length);
2923
2924/**
2925 * \brief Decrypt a short message with a private key.
2926 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01002927 * \param handle Handle to the key to use for the operation.
2928 * It must be an asymmetric key pair.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002929 * \param alg An asymmetric encryption algorithm that is
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002930 * compatible with the type of \p handle.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002931 * \param[in] input The message to decrypt.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002932 * \param input_length Size of the \p input buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002933 * \param[in] salt A salt or label, if supported by the
2934 * encryption algorithm.
2935 * If the algorithm does not support a
2936 * salt, pass \c NULL.
2937 * If the algorithm supports an optional
2938 * salt and you do not want to pass a salt,
2939 * pass \c NULL.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002940 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02002941 * - For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is
2942 * supported.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002943 * \param salt_length Size of the \p salt buffer in bytes.
2944 * If \p salt is \c NULL, pass 0.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002945 * \param[out] output Buffer where the decrypted message is to
2946 * be written.
2947 * \param output_size Size of the \c output buffer in bytes.
2948 * \param[out] output_length On success, the number of bytes
2949 * that make up the returned output.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002950 *
Gilles Peskine28538492018-07-11 17:34:00 +02002951 * \retval #PSA_SUCCESS
Adrian L. Shaw96f31ad2019-08-08 10:30:58 +01002952 * \retval #PSA_ERROR_INVALID_HANDLE
2953 * \retval #PSA_ERROR_NOT_PERMITTED
Gilles Peskine28538492018-07-11 17:34:00 +02002954 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002955 * The size of the \p output buffer is too small. You can
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002956 * determine a sufficient buffer size by calling
Gilles Peskinedda3bd32018-07-12 19:40:46 +02002957 * #PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002958 * where \c key_type and \c key_bits are the type and bit-size
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002959 * respectively of \p handle.
Gilles Peskine28538492018-07-11 17:34:00 +02002960 * \retval #PSA_ERROR_NOT_SUPPORTED
2961 * \retval #PSA_ERROR_INVALID_ARGUMENT
2962 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2963 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2964 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002965 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw96f31ad2019-08-08 10:30:58 +01002966 * \retval #PSA_ERROR_STORAGE_FAILURE
Gilles Peskine28538492018-07-11 17:34:00 +02002967 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
2968 * \retval #PSA_ERROR_INVALID_PADDING
itayzafrir90d8c7a2018-09-12 11:44:52 +03002969 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03002970 * The library has not been previously initialized by psa_crypto_init().
2971 * It is implementation-dependent whether a failure to initialize
2972 * results in this error code.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002973 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01002974psa_status_t psa_asymmetric_decrypt(psa_key_handle_t handle,
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002975 psa_algorithm_t alg,
2976 const uint8_t *input,
2977 size_t input_length,
2978 const uint8_t *salt,
2979 size_t salt_length,
2980 uint8_t *output,
2981 size_t output_size,
2982 size_t *output_length);
2983
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +01002984/**@}*/
2985
Gilles Peskine35675b62019-05-16 17:26:11 +02002986/** \defgroup key_derivation Key derivation and pseudorandom generation
Gilles Peskineeab56e42018-07-12 17:12:33 +02002987 * @{
2988 */
2989
Gilles Peskine35675b62019-05-16 17:26:11 +02002990/** The type of the state data structure for key derivation operations.
Gilles Peskineeab56e42018-07-12 17:12:33 +02002991 *
Gilles Peskine35675b62019-05-16 17:26:11 +02002992 * Before calling any function on a key derivation operation object, the
2993 * application must initialize it by any of the following means:
Gilles Peskineeab56e42018-07-12 17:12:33 +02002994 * - Set the structure to all-bits-zero, for example:
2995 * \code
Gilles Peskine35675b62019-05-16 17:26:11 +02002996 * psa_key_derivation_operation_t operation;
2997 * memset(&operation, 0, sizeof(operation));
Gilles Peskineeab56e42018-07-12 17:12:33 +02002998 * \endcode
2999 * - Initialize the structure to logical zero values, for example:
3000 * \code
Gilles Peskine35675b62019-05-16 17:26:11 +02003001 * psa_key_derivation_operation_t operation = {0};
Gilles Peskineeab56e42018-07-12 17:12:33 +02003002 * \endcode
Gilles Peskinea99d3fb2019-05-16 15:28:51 +02003003 * - Initialize the structure to the initializer #PSA_KEY_DERIVATION_OPERATION_INIT,
Gilles Peskineeab56e42018-07-12 17:12:33 +02003004 * for example:
3005 * \code
Gilles Peskine35675b62019-05-16 17:26:11 +02003006 * psa_key_derivation_operation_t operation = PSA_KEY_DERIVATION_OPERATION_INIT;
Gilles Peskineeab56e42018-07-12 17:12:33 +02003007 * \endcode
Gilles Peskinea99d3fb2019-05-16 15:28:51 +02003008 * - Assign the result of the function psa_key_derivation_operation_init()
Gilles Peskineeab56e42018-07-12 17:12:33 +02003009 * to the structure, for example:
3010 * \code
Gilles Peskine35675b62019-05-16 17:26:11 +02003011 * psa_key_derivation_operation_t operation;
3012 * operation = psa_key_derivation_operation_init();
Gilles Peskineeab56e42018-07-12 17:12:33 +02003013 * \endcode
3014 *
3015 * This is an implementation-defined \c struct. Applications should not
3016 * make any assumptions about the content of this structure except
3017 * as directed by the documentation of a specific implementation.
3018 */
Gilles Peskinecbe66502019-05-16 16:59:18 +02003019typedef struct psa_key_derivation_s psa_key_derivation_operation_t;
Gilles Peskineeab56e42018-07-12 17:12:33 +02003020
Gilles Peskinea99d3fb2019-05-16 15:28:51 +02003021/** \def PSA_KEY_DERIVATION_OPERATION_INIT
Gilles Peskineeab56e42018-07-12 17:12:33 +02003022 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003023 * This macro returns a suitable initializer for a key derivation operation
3024 * object of type #psa_key_derivation_operation_t.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003025 */
3026#ifdef __DOXYGEN_ONLY__
3027/* This is an example definition for documentation purposes.
3028 * Implementations should define a suitable value in `crypto_struct.h`.
3029 */
Gilles Peskinea99d3fb2019-05-16 15:28:51 +02003030#define PSA_KEY_DERIVATION_OPERATION_INIT {0}
Gilles Peskineeab56e42018-07-12 17:12:33 +02003031#endif
3032
Gilles Peskine35675b62019-05-16 17:26:11 +02003033/** Return an initial value for a key derivation operation object.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003034 */
Gilles Peskinea99d3fb2019-05-16 15:28:51 +02003035static psa_key_derivation_operation_t psa_key_derivation_operation_init(void);
Gilles Peskineeab56e42018-07-12 17:12:33 +02003036
Gilles Peskine1cb9a082019-05-16 17:56:47 +02003037/** Set up a key derivation operation.
3038 *
3039 * A key derivation algorithm takes some inputs and uses them to generate
3040 * a byte stream in a deterministic way.
3041 * This byte stream can be used to produce keys and other
3042 * cryptographic material.
3043 *
3044 * To derive a key:
3045 * - Start with an initialized object of type #psa_key_derivation_operation_t.
3046 * - Call psa_key_derivation_setup() to select the algorithm.
3047 * - Provide the inputs for the key derivation by calling
3048 * psa_key_derivation_input_bytes() or psa_key_derivation_input_key()
3049 * as appropriate. Which inputs are needed, in what order, and whether
3050 * they may be keys and if so of what type depends on the algorithm.
3051 * - Optionally set the operation's maximum capacity with
3052 * psa_key_derivation_set_capacity(). You may do this before, in the middle
3053 * of or after providing inputs. For some algorithms, this step is mandatory
3054 * because the output depends on the maximum capacity.
3055 * - To derive a key, call psa_key_derivation_output_key().
3056 * To derive a byte string for a different purpose, call
3057 * - psa_key_derivation_output_bytes().
3058 * Successive calls to these functions use successive output bytes
3059 * calculated by the key derivation algorithm.
3060 * - Clean up the key derivation operation object with
3061 * psa_key_derivation_abort().
3062 *
3063 * \param[in,out] operation The key derivation operation object
3064 * to set up. It must
3065 * have been initialized but not set up yet.
3066 * \param alg The key derivation algorithm to compute
3067 * (\c PSA_ALG_XXX value such that
3068 * #PSA_ALG_IS_KEY_DERIVATION(\p alg) is true).
3069 *
3070 * \retval #PSA_SUCCESS
3071 * Success.
3072 * \retval #PSA_ERROR_INVALID_ARGUMENT
3073 * \c alg is not a key derivation algorithm.
3074 * \retval #PSA_ERROR_NOT_SUPPORTED
3075 * \c alg is not supported or is not a key derivation algorithm.
3076 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3077 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3078 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003079 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine1cb9a082019-05-16 17:56:47 +02003080 * \retval #PSA_ERROR_BAD_STATE
Adrian L. Shaw320659b2019-08-08 14:49:01 +01003081 * The operation state is either not initialized or has already been setup.
Adrian L. Shawdec47b62019-08-07 14:25:38 +01003082 * \retval #PSA_ERROR_BAD_STATE
3083 * The library has not been previously initialized by psa_crypto_init().
3084 * It is implementation-dependent whether a failure to initialize
3085 * results in this error code.
Gilles Peskine1cb9a082019-05-16 17:56:47 +02003086 */
3087psa_status_t psa_key_derivation_setup(
3088 psa_key_derivation_operation_t *operation,
3089 psa_algorithm_t alg);
3090
Gilles Peskine35675b62019-05-16 17:26:11 +02003091/** Retrieve the current capacity of a key derivation operation.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003092 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003093 * The capacity of a key derivation is the maximum number of bytes that it can
3094 * return. When you get *N* bytes of output from a key derivation operation,
3095 * this reduces its capacity by *N*.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003096 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003097 * \param[in] operation The operation to query.
3098 * \param[out] capacity On success, the capacity of the operation.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003099 *
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003100 * \retval #PSA_SUCCESS
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003101 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01003102 * \retval #PSA_ERROR_BAD_STATE
3103 * The operation state is not valid.
Adrian L. Shaw484ba882019-08-13 14:41:52 +01003104 * \retval #PSA_ERROR_HARDWARE_FAILURE
3105 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01003106 * \retval #PSA_ERROR_BAD_STATE
3107 * The library has not been previously initialized by psa_crypto_init().
3108 * It is implementation-dependent whether a failure to initialize
3109 * results in this error code.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003110 */
Gilles Peskinecf7292e2019-05-16 17:53:40 +02003111psa_status_t psa_key_derivation_get_capacity(
3112 const psa_key_derivation_operation_t *operation,
3113 size_t *capacity);
Gilles Peskineeab56e42018-07-12 17:12:33 +02003114
Gilles Peskine35675b62019-05-16 17:26:11 +02003115/** Set the maximum capacity of a key derivation operation.
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01003116 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003117 * The capacity of a key derivation operation is the maximum number of bytes
3118 * that the key derivation operation can return from this point onwards.
3119 *
3120 * \param[in,out] operation The key derivation operation object to modify.
3121 * \param capacity The new capacity of the operation.
3122 * It must be less or equal to the operation's
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01003123 * current capacity.
3124 *
3125 * \retval #PSA_SUCCESS
3126 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine35675b62019-05-16 17:26:11 +02003127 * \p capacity is larger than the operation's current capacity.
3128 * In this case, the operation object remains valid and its capacity
3129 * remains unchanged.
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01003130 * \retval #PSA_ERROR_BAD_STATE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01003131 * The operation state is not valid.
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01003132 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
Adrian L. Shaw484ba882019-08-13 14:41:52 +01003133 * \retval #PSA_ERROR_HARDWARE_FAILURE
3134 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01003135 * \retval #PSA_ERROR_BAD_STATE
3136 * The library has not been previously initialized by psa_crypto_init().
3137 * It is implementation-dependent whether a failure to initialize
3138 * results in this error code.
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01003139 */
Gilles Peskinecf7292e2019-05-16 17:53:40 +02003140psa_status_t psa_key_derivation_set_capacity(
3141 psa_key_derivation_operation_t *operation,
3142 size_t capacity);
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01003143
Gilles Peskine1cb9a082019-05-16 17:56:47 +02003144/** Use the maximum possible capacity for a key derivation operation.
3145 *
3146 * Use this value as the capacity argument when setting up a key derivation
3147 * to indicate that the operation should have the maximum possible capacity.
3148 * The value of the maximum possible capacity depends on the key derivation
3149 * algorithm.
3150 */
3151#define PSA_KEY_DERIVATION_UNLIMITED_CAPACITY ((size_t)(-1))
3152
3153/** Provide an input for key derivation or key agreement.
3154 *
3155 * Which inputs are required and in what order depends on the algorithm.
3156 * Refer to the documentation of each key derivation or key agreement
3157 * algorithm for information.
3158 *
3159 * This function passes direct inputs. Some inputs must be passed as keys
3160 * using psa_key_derivation_input_key() instead of this function. Refer to
3161 * the documentation of individual step types for information.
3162 *
3163 * \param[in,out] operation The key derivation operation object to use.
3164 * It must have been set up with
3165 * psa_key_derivation_setup() and must not
3166 * have produced any output yet.
3167 * \param step Which step the input data is for.
3168 * \param[in] data Input data to use.
3169 * \param data_length Size of the \p data buffer in bytes.
3170 *
3171 * \retval #PSA_SUCCESS
3172 * Success.
3173 * \retval #PSA_ERROR_INVALID_ARGUMENT
3174 * \c step is not compatible with the operation's algorithm.
3175 * \retval #PSA_ERROR_INVALID_ARGUMENT
3176 * \c step does not allow direct inputs.
3177 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3178 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3179 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003180 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw484ba882019-08-13 14:41:52 +01003181 * \retval #PSA_ERROR_STORAGE_FAILURE
Gilles Peskine1cb9a082019-05-16 17:56:47 +02003182 * \retval #PSA_ERROR_BAD_STATE
3183 * The value of \p step is not valid given the state of \p operation.
3184 * \retval #PSA_ERROR_BAD_STATE
3185 * The library has not been previously initialized by psa_crypto_init().
3186 * It is implementation-dependent whether a failure to initialize
3187 * results in this error code.
3188 */
3189psa_status_t psa_key_derivation_input_bytes(
3190 psa_key_derivation_operation_t *operation,
3191 psa_key_derivation_step_t step,
3192 const uint8_t *data,
3193 size_t data_length);
3194
3195/** Provide an input for key derivation in the form of a key.
3196 *
3197 * Which inputs are required and in what order depends on the algorithm.
3198 * Refer to the documentation of each key derivation or key agreement
3199 * algorithm for information.
3200 *
3201 * This function passes key inputs. Some inputs must be passed as keys
3202 * of the appropriate type using this function, while others must be
3203 * passed as direct inputs using psa_key_derivation_input_bytes(). Refer to
3204 * the documentation of individual step types for information.
3205 *
3206 * \param[in,out] operation The key derivation operation object to use.
3207 * It must have been set up with
3208 * psa_key_derivation_setup() and must not
3209 * have produced any output yet.
3210 * \param step Which step the input data is for.
3211 * \param handle Handle to the key. It must have an
3212 * appropriate type for \p step and must
3213 * allow the usage #PSA_KEY_USAGE_DERIVE.
3214 *
3215 * \retval #PSA_SUCCESS
3216 * Success.
3217 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine1cb9a082019-05-16 17:56:47 +02003218 * \retval #PSA_ERROR_NOT_PERMITTED
3219 * \retval #PSA_ERROR_INVALID_ARGUMENT
3220 * \c step is not compatible with the operation's algorithm.
3221 * \retval #PSA_ERROR_INVALID_ARGUMENT
3222 * \c step does not allow key inputs.
3223 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3224 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3225 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003226 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw484ba882019-08-13 14:41:52 +01003227 * \retval #PSA_ERROR_STORAGE_FAILURE
Gilles Peskine1cb9a082019-05-16 17:56:47 +02003228 * \retval #PSA_ERROR_BAD_STATE
3229 * The value of \p step is not valid given the state of \p operation.
3230 * \retval #PSA_ERROR_BAD_STATE
3231 * The library has not been previously initialized by psa_crypto_init().
3232 * It is implementation-dependent whether a failure to initialize
3233 * results in this error code.
3234 */
3235psa_status_t psa_key_derivation_input_key(
3236 psa_key_derivation_operation_t *operation,
3237 psa_key_derivation_step_t step,
3238 psa_key_handle_t handle);
3239
3240/** Perform a key agreement and use the shared secret as input to a key
3241 * derivation.
3242 *
3243 * A key agreement algorithm takes two inputs: a private key \p private_key
3244 * a public key \p peer_key.
3245 * The result of this function is passed as input to a key derivation.
3246 * The output of this key derivation can be extracted by reading from the
3247 * resulting operation to produce keys and other cryptographic material.
3248 *
3249 * \param[in,out] operation The key derivation operation object to use.
3250 * It must have been set up with
3251 * psa_key_derivation_setup() with a
3252 * key agreement and derivation algorithm
3253 * \c alg (\c PSA_ALG_XXX value such that
3254 * #PSA_ALG_IS_KEY_AGREEMENT(\c alg) is true
3255 * and #PSA_ALG_IS_RAW_KEY_AGREEMENT(\c alg)
3256 * is false).
3257 * The operation must be ready for an
3258 * input of the type given by \p step.
3259 * \param step Which step the input data is for.
3260 * \param private_key Handle to the private key to use.
3261 * \param[in] peer_key Public key of the peer. The peer key must be in the
3262 * same format that psa_import_key() accepts for the
3263 * public key type corresponding to the type of
3264 * private_key. That is, this function performs the
3265 * equivalent of
3266 * #psa_import_key(...,
3267 * `peer_key`, `peer_key_length`) where
3268 * with key attributes indicating the public key
3269 * type corresponding to the type of `private_key`.
3270 * For example, for EC keys, this means that peer_key
3271 * is interpreted as a point on the curve that the
3272 * private key is on. The standard formats for public
3273 * keys are documented in the documentation of
3274 * psa_export_public_key().
3275 * \param peer_key_length Size of \p peer_key in bytes.
3276 *
3277 * \retval #PSA_SUCCESS
3278 * Success.
3279 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine1cb9a082019-05-16 17:56:47 +02003280 * \retval #PSA_ERROR_NOT_PERMITTED
3281 * \retval #PSA_ERROR_INVALID_ARGUMENT
3282 * \c private_key is not compatible with \c alg,
3283 * or \p peer_key is not valid for \c alg or not compatible with
3284 * \c private_key.
3285 * \retval #PSA_ERROR_NOT_SUPPORTED
3286 * \c alg is not supported or is not a key derivation algorithm.
3287 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3288 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3289 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003290 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw484ba882019-08-13 14:41:52 +01003291 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01003292 * \retval #PSA_ERROR_BAD_STATE
3293 * The library has not been previously initialized by psa_crypto_init().
3294 * It is implementation-dependent whether a failure to initialize
3295 * results in this error code.
Gilles Peskine1cb9a082019-05-16 17:56:47 +02003296 */
3297psa_status_t psa_key_derivation_key_agreement(
3298 psa_key_derivation_operation_t *operation,
3299 psa_key_derivation_step_t step,
3300 psa_key_handle_t private_key,
3301 const uint8_t *peer_key,
3302 size_t peer_key_length);
3303
Gilles Peskine35675b62019-05-16 17:26:11 +02003304/** Read some data from a key derivation operation.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003305 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003306 * This function calculates output bytes from a key derivation algorithm and
3307 * return those bytes.
3308 * If you view the key derivation's output as a stream of bytes, this
3309 * function destructively reads the requested number of bytes from the
3310 * stream.
3311 * The operation's capacity decreases by the number of bytes read.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003312 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003313 * \param[in,out] operation The key derivation operation object to read from.
3314 * \param[out] output Buffer where the output will be written.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003315 * \param output_length Number of bytes to output.
3316 *
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003317 * \retval #PSA_SUCCESS
David Saadab4ecc272019-02-14 13:48:10 +02003318 * \retval #PSA_ERROR_INSUFFICIENT_DATA
Gilles Peskine35675b62019-05-16 17:26:11 +02003319 * The operation's capacity was less than
3320 * \p output_length bytes. Note that in this case,
3321 * no output is written to the output buffer.
3322 * The operation's capacity is set to 0, thus
Gilles Peskineeab56e42018-07-12 17:12:33 +02003323 * subsequent calls to this function will not
3324 * succeed, even with a smaller output buffer.
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003325 * \retval #PSA_ERROR_BAD_STATE
3326 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3327 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3328 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003329 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw484ba882019-08-13 14:41:52 +01003330 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01003331 * \retval #PSA_ERROR_BAD_STATE
3332 * The library has not been previously initialized by psa_crypto_init().
3333 * It is implementation-dependent whether a failure to initialize
3334 * results in this error code.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003335 */
Gilles Peskinecf7292e2019-05-16 17:53:40 +02003336psa_status_t psa_key_derivation_output_bytes(
3337 psa_key_derivation_operation_t *operation,
3338 uint8_t *output,
3339 size_t output_length);
Gilles Peskineeab56e42018-07-12 17:12:33 +02003340
Gilles Peskine35675b62019-05-16 17:26:11 +02003341/** Derive a key from an ongoing key derivation operation.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003342 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003343 * This function calculates output bytes from a key derivation algorithm
3344 * and uses those bytes to generate a key deterministically.
3345 * If you view the key derivation's output as a stream of bytes, this
3346 * function destructively reads as many bytes as required from the
3347 * stream.
3348 * The operation's capacity decreases by the number of bytes read.
3349 *
3350 * How much output is produced and consumed from the operation, and how
3351 * the key is derived, depends on the key type:
Gilles Peskineeab56e42018-07-12 17:12:33 +02003352 *
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003353 * - For key types for which the key is an arbitrary sequence of bytes
Gilles Peskinecf7292e2019-05-16 17:53:40 +02003354 * of a given size, this function is functionally equivalent to
3355 * calling #psa_key_derivation_output_bytes
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003356 * and passing the resulting output to #psa_import_key.
3357 * However, this function has a security benefit:
3358 * if the implementation provides an isolation boundary then
3359 * the key material is not exposed outside the isolation boundary.
3360 * As a consequence, for these key types, this function always consumes
Gilles Peskine35675b62019-05-16 17:26:11 +02003361 * exactly (\p bits / 8) bytes from the operation.
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003362 * The following key types defined in this specification follow this scheme:
3363 *
3364 * - #PSA_KEY_TYPE_AES;
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003365 * - #PSA_KEY_TYPE_ARC4;
3366 * - #PSA_KEY_TYPE_CAMELLIA;
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003367 * - #PSA_KEY_TYPE_DERIVE;
3368 * - #PSA_KEY_TYPE_HMAC.
3369 *
3370 * - For ECC keys on a Montgomery elliptic curve
Gilles Peskinec93b80c2019-05-16 19:39:54 +02003371 * (#PSA_KEY_TYPE_ECC_KEY_PAIR(\c curve) where \c curve designates a
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003372 * Montgomery curve), this function always draws a byte string whose
3373 * length is determined by the curve, and sets the mandatory bits
3374 * accordingly. That is:
3375 *
3376 * - #PSA_ECC_CURVE_CURVE25519: draw a 32-byte string
3377 * and process it as specified in RFC 7748 &sect;5.
3378 * - #PSA_ECC_CURVE_CURVE448: draw a 56-byte string
3379 * and process it as specified in RFC 7748 &sect;5.
3380 *
3381 * - For key types for which the key is represented by a single sequence of
3382 * \p bits bits with constraints as to which bit sequences are acceptable,
3383 * this function draws a byte string of length (\p bits / 8) bytes rounded
3384 * up to the nearest whole number of bytes. If the resulting byte string
3385 * is acceptable, it becomes the key, otherwise the drawn bytes are discarded.
3386 * This process is repeated until an acceptable byte string is drawn.
Gilles Peskine35675b62019-05-16 17:26:11 +02003387 * The byte string drawn from the operation is interpreted as specified
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003388 * for the output produced by psa_export_key().
3389 * The following key types defined in this specification follow this scheme:
3390 *
Gilles Peskine2de2c0d2019-03-11 17:59:16 +01003391 * - #PSA_KEY_TYPE_DES.
3392 * Force-set the parity bits, but discard forbidden weak keys.
3393 * For 2-key and 3-key triple-DES, the three keys are generated
3394 * successively (for example, for 3-key triple-DES,
3395 * if the first 8 bytes specify a weak key and the next 8 bytes do not,
3396 * discard the first 8 bytes, use the next 8 bytes as the first key,
Gilles Peskine35675b62019-05-16 17:26:11 +02003397 * and continue reading output from the operation to derive the other
Gilles Peskine2de2c0d2019-03-11 17:59:16 +01003398 * two keys).
Gilles Peskinec93b80c2019-05-16 19:39:54 +02003399 * - Finite-field Diffie-Hellman keys (#PSA_KEY_TYPE_DH_KEY_PAIR(\c group)
Gilles Peskinea1302192019-05-16 13:58:24 +02003400 * where \c group designates any Diffie-Hellman group) and
Gilles Peskine2de2c0d2019-03-11 17:59:16 +01003401 * ECC keys on a Weierstrass elliptic curve
Gilles Peskinec93b80c2019-05-16 19:39:54 +02003402 * (#PSA_KEY_TYPE_ECC_KEY_PAIR(\c curve) where \c curve designates a
Gilles Peskine2de2c0d2019-03-11 17:59:16 +01003403 * Weierstrass curve).
3404 * For these key types, interpret the byte string as integer
3405 * in big-endian order. Discard it if it is not in the range
3406 * [0, *N* - 2] where *N* is the boundary of the private key domain
3407 * (the prime *p* for Diffie-Hellman, the subprime *q* for DSA,
Gilles Peskine55799712019-03-12 11:50:26 +01003408 * or the order of the curve's base point for ECC).
Gilles Peskine2de2c0d2019-03-11 17:59:16 +01003409 * Add 1 to the resulting integer and use this as the private key *x*.
Gilles Peskine55799712019-03-12 11:50:26 +01003410 * This method allows compliance to NIST standards, specifically
3411 * the methods titled "key-pair generation by testing candidates"
Gilles Peskine2de2c0d2019-03-11 17:59:16 +01003412 * in NIST SP 800-56A &sect;5.6.1.1.4 for Diffie-Hellman,
3413 * in FIPS 186-4 &sect;B.1.2 for DSA, and
3414 * in NIST SP 800-56A &sect;5.6.1.2.2 or
3415 * FIPS 186-4 &sect;B.4.2 for elliptic curve keys.
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003416 *
Gilles Peskinec93b80c2019-05-16 19:39:54 +02003417 * - For other key types, including #PSA_KEY_TYPE_RSA_KEY_PAIR,
Gilles Peskine35675b62019-05-16 17:26:11 +02003418 * the way in which the operation output is consumed is
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003419 * implementation-defined.
3420 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003421 * In all cases, the data that is read is discarded from the operation.
3422 * The operation's capacity is decreased by the number of bytes read.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003423 *
Gilles Peskine20628592019-04-19 19:29:50 +02003424 * \param[in] attributes The attributes for the new key.
Gilles Peskine35675b62019-05-16 17:26:11 +02003425 * \param[in,out] operation The key derivation operation object to read from.
Gilles Peskine20628592019-04-19 19:29:50 +02003426 * \param[out] handle On success, a handle to the newly created key.
3427 * \c 0 on failure.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003428 *
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003429 * \retval #PSA_SUCCESS
Gilles Peskineeab56e42018-07-12 17:12:33 +02003430 * Success.
Gilles Peskine23fd2bd2018-12-11 15:51:32 +01003431 * If the key is persistent, the key material and the key's metadata
3432 * have been saved to persistent storage.
Gilles Peskine20628592019-04-19 19:29:50 +02003433 * \retval #PSA_ERROR_ALREADY_EXISTS
3434 * This is an attempt to create a persistent key, and there is
3435 * already a persistent key with the given identifier.
David Saadab4ecc272019-02-14 13:48:10 +02003436 * \retval #PSA_ERROR_INSUFFICIENT_DATA
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003437 * There was not enough data to create the desired key.
3438 * Note that in this case, no output is written to the output buffer.
Gilles Peskine35675b62019-05-16 17:26:11 +02003439 * The operation's capacity is set to 0, thus subsequent calls to
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003440 * this function will not succeed, even with a smaller output buffer.
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003441 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskineeab56e42018-07-12 17:12:33 +02003442 * The key type or key size is not supported, either by the
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +01003443 * implementation in general or in this particular location.
k-stachowiakb9b4f092019-08-15 19:01:59 +02003444 * \retval #PSA_ERROR_INVALID_ARGUMENT
3445 * The provided key attributes are not valid for the operation.
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003446 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003447 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3448 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
3449 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3450 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003451 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw484ba882019-08-13 14:41:52 +01003452 * \retval #PSA_ERROR_STORAGE_FAILURE
itayzafrir90d8c7a2018-09-12 11:44:52 +03003453 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03003454 * The library has not been previously initialized by psa_crypto_init().
3455 * It is implementation-dependent whether a failure to initialize
3456 * results in this error code.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003457 */
Gilles Peskinecf7292e2019-05-16 17:53:40 +02003458psa_status_t psa_key_derivation_output_key(
3459 const psa_key_attributes_t *attributes,
3460 psa_key_derivation_operation_t *operation,
3461 psa_key_handle_t *handle);
Gilles Peskineeab56e42018-07-12 17:12:33 +02003462
Gilles Peskine35675b62019-05-16 17:26:11 +02003463/** Abort a key derivation operation.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003464 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003465 * Once a key derivation operation has been aborted, its capacity is zero.
3466 * Aborting an operation frees all associated resources except for the
3467 * \c operation structure itself.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003468 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003469 * This function may be called at any time as long as the operation
Gilles Peskinea99d3fb2019-05-16 15:28:51 +02003470 * object has been initialized to #PSA_KEY_DERIVATION_OPERATION_INIT, to
Gilles Peskinecf7292e2019-05-16 17:53:40 +02003471 * psa_key_derivation_operation_init() or a zero value. In particular,
3472 * it is valid to call psa_key_derivation_abort() twice, or to call
3473 * psa_key_derivation_abort() on an operation that has not been set up.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003474 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003475 * Once aborted, the key derivation operation object may be called.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003476 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003477 * \param[in,out] operation The operation to abort.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003478 *
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003479 * \retval #PSA_SUCCESS
3480 * \retval #PSA_ERROR_BAD_STATE
3481 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3482 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003483 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01003484 * \retval #PSA_ERROR_BAD_STATE
3485 * The library has not been previously initialized by psa_crypto_init().
3486 * It is implementation-dependent whether a failure to initialize
3487 * results in this error code.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003488 */
Gilles Peskinecf7292e2019-05-16 17:53:40 +02003489psa_status_t psa_key_derivation_abort(
3490 psa_key_derivation_operation_t *operation);
Gilles Peskineeab56e42018-07-12 17:12:33 +02003491
Gilles Peskine58fe9e82019-05-16 18:01:45 +02003492/** Perform a key agreement and return the raw shared secret.
Gilles Peskine769c7a62019-01-18 16:42:29 +01003493 *
3494 * \warning The raw result of a key agreement algorithm such as finite-field
3495 * Diffie-Hellman or elliptic curve Diffie-Hellman has biases and should
3496 * not be used directly as key material. It should instead be passed as
3497 * input to a key derivation algorithm. To chain a key agreement with
Gilles Peskinecf7292e2019-05-16 17:53:40 +02003498 * a key derivation, use psa_key_derivation_key_agreement() and other
3499 * functions from the key derivation interface.
Gilles Peskine769c7a62019-01-18 16:42:29 +01003500 *
Gilles Peskine47e79fb2019-02-08 11:24:59 +01003501 * \param alg The key agreement algorithm to compute
3502 * (\c PSA_ALG_XXX value such that
3503 * #PSA_ALG_IS_RAW_KEY_AGREEMENT(\p alg)
3504 * is true).
Gilles Peskine769c7a62019-01-18 16:42:29 +01003505 * \param private_key Handle to the private key to use.
3506 * \param[in] peer_key Public key of the peer. It must be
3507 * in the same format that psa_import_key()
3508 * accepts. The standard formats for public
3509 * keys are documented in the documentation
3510 * of psa_export_public_key().
3511 * \param peer_key_length Size of \p peer_key in bytes.
3512 * \param[out] output Buffer where the decrypted message is to
3513 * be written.
3514 * \param output_size Size of the \c output buffer in bytes.
3515 * \param[out] output_length On success, the number of bytes
3516 * that make up the returned output.
3517 *
3518 * \retval #PSA_SUCCESS
3519 * Success.
3520 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine769c7a62019-01-18 16:42:29 +01003521 * \retval #PSA_ERROR_NOT_PERMITTED
3522 * \retval #PSA_ERROR_INVALID_ARGUMENT
3523 * \p alg is not a key agreement algorithm
3524 * \retval #PSA_ERROR_INVALID_ARGUMENT
3525 * \p private_key is not compatible with \p alg,
3526 * or \p peer_key is not valid for \p alg or not compatible with
3527 * \p private_key.
Adrian L. Shaw0d280b92019-08-08 15:07:07 +01003528 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
3529 * \p output_size is too small
Gilles Peskine769c7a62019-01-18 16:42:29 +01003530 * \retval #PSA_ERROR_NOT_SUPPORTED
3531 * \p alg is not a supported key agreement algorithm.
3532 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3533 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3534 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003535 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw0d280b92019-08-08 15:07:07 +01003536 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01003537 * \retval #PSA_ERROR_BAD_STATE
3538 * The library has not been previously initialized by psa_crypto_init().
3539 * It is implementation-dependent whether a failure to initialize
3540 * results in this error code.
Gilles Peskine769c7a62019-01-18 16:42:29 +01003541 */
Gilles Peskinebe697d82019-05-16 18:00:41 +02003542psa_status_t psa_raw_key_agreement(psa_algorithm_t alg,
3543 psa_key_handle_t private_key,
3544 const uint8_t *peer_key,
3545 size_t peer_key_length,
3546 uint8_t *output,
3547 size_t output_size,
3548 size_t *output_length);
Gilles Peskine01d718c2018-09-18 12:01:02 +02003549
Gilles Peskineea0fb492018-07-12 17:17:20 +02003550/**@}*/
3551
Gilles Peskineedd76872018-07-20 17:42:05 +02003552/** \defgroup random Random generation
Gilles Peskine9e7dc712018-03-28 14:18:50 +02003553 * @{
3554 */
3555
3556/**
3557 * \brief Generate random bytes.
3558 *
3559 * \warning This function **can** fail! Callers MUST check the return status
3560 * and MUST NOT use the content of the output buffer if the return
3561 * status is not #PSA_SUCCESS.
3562 *
Gilles Peskine35ef36b2019-05-16 19:42:05 +02003563 * \note To generate a key, use psa_generate_key() instead.
Gilles Peskine9e7dc712018-03-28 14:18:50 +02003564 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02003565 * \param[out] output Output buffer for the generated data.
Gilles Peskine9e7dc712018-03-28 14:18:50 +02003566 * \param output_size Number of bytes to generate and output.
3567 *
Gilles Peskine28538492018-07-11 17:34:00 +02003568 * \retval #PSA_SUCCESS
3569 * \retval #PSA_ERROR_NOT_SUPPORTED
3570 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
Adrian L. Shaw71b33ff2019-08-08 15:07:57 +01003571 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
Gilles Peskine28538492018-07-11 17:34:00 +02003572 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3573 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003574 * \retval #PSA_ERROR_CORRUPTION_DETECTED
itayzafrir0adf0fc2018-09-06 16:24:41 +03003575 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03003576 * The library has not been previously initialized by psa_crypto_init().
3577 * It is implementation-dependent whether a failure to initialize
3578 * results in this error code.
Gilles Peskine9e7dc712018-03-28 14:18:50 +02003579 */
3580psa_status_t psa_generate_random(uint8_t *output,
3581 size_t output_size);
3582
3583/**
3584 * \brief Generate a key or key pair.
3585 *
Gilles Peskinee56e8782019-04-26 17:34:02 +02003586 * The key is generated randomly.
3587 * Its location, policy, type and size are taken from \p attributes.
3588 *
Gilles Peskine20a77ae2019-05-16 14:05:56 +02003589 * The following type-specific considerations apply:
Gilles Peskinec93b80c2019-05-16 19:39:54 +02003590 * - For RSA keys (#PSA_KEY_TYPE_RSA_KEY_PAIR),
Gilles Peskine20a77ae2019-05-16 14:05:56 +02003591 * the public exponent is 65537.
3592 * The modulus is a product of two probabilistic primes
3593 * between 2^{n-1} and 2^n where n is the bit size specified in the
3594 * attributes.
3595 *
Gilles Peskine20628592019-04-19 19:29:50 +02003596 * \param[in] attributes The attributes for the new key.
Gilles Peskine20628592019-04-19 19:29:50 +02003597 * \param[out] handle On success, a handle to the newly created key.
3598 * \c 0 on failure.
Gilles Peskine9e7dc712018-03-28 14:18:50 +02003599 *
Gilles Peskine28538492018-07-11 17:34:00 +02003600 * \retval #PSA_SUCCESS
Gilles Peskine23fd2bd2018-12-11 15:51:32 +01003601 * Success.
3602 * If the key is persistent, the key material and the key's metadata
3603 * have been saved to persistent storage.
David Saadab4ecc272019-02-14 13:48:10 +02003604 * \retval #PSA_ERROR_ALREADY_EXISTS
Gilles Peskine20628592019-04-19 19:29:50 +02003605 * This is an attempt to create a persistent key, and there is
3606 * already a persistent key with the given identifier.
Gilles Peskine28538492018-07-11 17:34:00 +02003607 * \retval #PSA_ERROR_NOT_SUPPORTED
3608 * \retval #PSA_ERROR_INVALID_ARGUMENT
3609 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3610 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
3611 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3612 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003613 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawd21c6e62019-08-08 10:58:08 +01003614 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
3615 * \retval #PSA_ERROR_STORAGE_FAILURE
itayzafrir90d8c7a2018-09-12 11:44:52 +03003616 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03003617 * The library has not been previously initialized by psa_crypto_init().
3618 * It is implementation-dependent whether a failure to initialize
3619 * results in this error code.
Gilles Peskine9e7dc712018-03-28 14:18:50 +02003620 */
Gilles Peskine35ef36b2019-05-16 19:42:05 +02003621psa_status_t psa_generate_key(const psa_key_attributes_t *attributes,
Gilles Peskinee56e8782019-04-26 17:34:02 +02003622 psa_key_handle_t *handle);
Gilles Peskine9e7dc712018-03-28 14:18:50 +02003623
3624/**@}*/
3625
Gilles Peskinee59236f2018-01-27 23:32:46 +01003626#ifdef __cplusplus
3627}
3628#endif
3629
Gilles Peskine0cad07c2018-06-27 19:49:02 +02003630/* The file "crypto_sizes.h" contains definitions for size calculation
3631 * macros whose definitions are implementation-specific. */
3632#include "crypto_sizes.h"
3633
Gilles Peskine9ef733f2018-02-07 21:05:37 +01003634/* The file "crypto_struct.h" contains definitions for
3635 * implementation-specific structs that are declared above. */
3636#include "crypto_struct.h"
3637
3638/* The file "crypto_extra.h" contains vendor-specific definitions. This
3639 * can include vendor-defined algorithms, extra functions, etc. */
Gilles Peskinee59236f2018-01-27 23:32:46 +01003640#include "crypto_extra.h"
3641
3642#endif /* PSA_CRYPTO_H */