blob: 89392da67cebc3c195766094996ef486809a3111 [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
Gilles Peskinea170d922019-09-12 16:59:37 +0200229 * algorithms are permitted to be used with this key. The following
230 * algorithm policies are supported:
231 * - 0 does not allow any cryptographic operation with the key. The key
232 * may be used for non-cryptographic actions such as exporting (if
233 * permitted by the usage flags).
234 * - An algorithm value permits this particular algorithm.
235 * - An algorithm wildcard built from #PSA_ALG_ANY_HASH allows the specified
236 * signature scheme with any hash algorithm.
Gilles Peskine20628592019-04-19 19:29:50 +0200237 *
238 * This function overwrites any algorithm policy
239 * previously set in \p attributes.
240 *
241 * This function may be declared as `static` (i.e. without external
242 * linkage). This function may be provided as a function-like macro,
243 * but in this case it must evaluate each of its arguments exactly once.
244 *
245 * \param[out] attributes The attribute structure to write to.
246 * \param alg The permitted algorithm policy to write.
247 */
Gilles Peskine4747d192019-04-17 15:05:45 +0200248static void psa_set_key_algorithm(psa_key_attributes_t *attributes,
249 psa_algorithm_t alg);
250
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +0100251
Gilles Peskine20628592019-04-19 19:29:50 +0200252/** Retrieve the algorithm policy from key attributes.
253 *
254 * This function may be declared as `static` (i.e. without external
255 * linkage). This function may be provided as a function-like macro,
256 * but in this case it must evaluate its argument exactly once.
257 *
258 * \param[in] attributes The key attribute structure to query.
259 *
260 * \return The algorithm stored in the attribute structure.
261 */
Gilles Peskine4747d192019-04-17 15:05:45 +0200262static psa_algorithm_t psa_get_key_algorithm(
263 const psa_key_attributes_t *attributes);
264
Gilles Peskine20628592019-04-19 19:29:50 +0200265/** Declare the type of a key.
266 *
Gilles Peskine24f10f82019-05-16 12:18:32 +0200267 * This function overwrites any key type
Gilles Peskine20628592019-04-19 19:29:50 +0200268 * previously set in \p attributes.
269 *
270 * This function may be declared as `static` (i.e. without external
271 * linkage). This function may be provided as a function-like macro,
272 * but in this case it must evaluate each of its arguments exactly once.
273 *
274 * \param[out] attributes The attribute structure to write to.
275 * \param type The key type to write.
Gilles Peskinea170d922019-09-12 16:59:37 +0200276 * If this is 0, the key type in \p attributes
277 * becomes unspecified.
Gilles Peskine20628592019-04-19 19:29:50 +0200278 */
Gilles Peskine4747d192019-04-17 15:05:45 +0200279static void psa_set_key_type(psa_key_attributes_t *attributes,
280 psa_key_type_t type);
281
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +0100282
Gilles Peskine3a4f1f82019-04-26 13:49:28 +0200283/** Declare the size of a key.
284 *
285 * This function overwrites any key size previously set in \p attributes.
286 *
287 * This function may be declared as `static` (i.e. without external
288 * linkage). This function may be provided as a function-like macro,
289 * but in this case it must evaluate each of its arguments exactly once.
290 *
291 * \param[out] attributes The attribute structure to write to.
292 * \param bits The key size in bits.
Gilles Peskinea170d922019-09-12 16:59:37 +0200293 * If this is 0, the key size in \p attributes
Gilles Peskine05c900b2019-09-12 18:29:43 +0200294 * becomes unspecified. Keys of size 0 are
295 * not supported.
Gilles Peskine3a4f1f82019-04-26 13:49:28 +0200296 */
297static void psa_set_key_bits(psa_key_attributes_t *attributes,
298 size_t bits);
299
Gilles Peskine20628592019-04-19 19:29:50 +0200300/** Retrieve the key type 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 type stored in the attribute structure.
309 */
Gilles Peskine4747d192019-04-17 15:05:45 +0200310static psa_key_type_t psa_get_key_type(const psa_key_attributes_t *attributes);
311
Gilles Peskine20628592019-04-19 19:29:50 +0200312/** Retrieve the key size from key attributes.
313 *
314 * This function may be declared as `static` (i.e. without external
315 * linkage). This function may be provided as a function-like macro,
316 * but in this case it must evaluate its argument exactly once.
317 *
318 * \param[in] attributes The key attribute structure to query.
319 *
320 * \return The key size stored in the attribute structure, in bits.
321 */
Gilles Peskine4747d192019-04-17 15:05:45 +0200322static size_t psa_get_key_bits(const psa_key_attributes_t *attributes);
323
Gilles Peskine20628592019-04-19 19:29:50 +0200324/** Retrieve the attributes of a key.
325 *
326 * This function first resets the attribute structure as with
Gilles Peskine9c640f92019-04-28 11:36:21 +0200327 * psa_reset_key_attributes(). It then copies the attributes of
328 * the given key into the given attribute structure.
Gilles Peskine20628592019-04-19 19:29:50 +0200329 *
Gilles Peskine9c640f92019-04-28 11:36:21 +0200330 * \note This function may allocate memory or other resources.
331 * Once you have called this function on an attribute structure,
332 * you must call psa_reset_key_attributes() to free these resources.
Gilles Peskine20628592019-04-19 19:29:50 +0200333 *
Gilles Peskine20628592019-04-19 19:29:50 +0200334 * \param[in] handle Handle to the key to query.
335 * \param[in,out] attributes On success, the attributes of the key.
336 * On failure, equivalent to a
337 * freshly-initialized structure.
338 *
339 * \retval #PSA_SUCCESS
340 * \retval #PSA_ERROR_INVALID_HANDLE
341 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
342 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
Adrian L. Shaw29b64072019-08-06 16:02:12 +0100343 * \retval #PSA_ERROR_CORRUPTION_DETECTED
344 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +0100345 * \retval #PSA_ERROR_BAD_STATE
346 * The library has not been previously initialized by psa_crypto_init().
347 * It is implementation-dependent whether a failure to initialize
348 * results in this error code.
Gilles Peskine20628592019-04-19 19:29:50 +0200349 */
Gilles Peskine4747d192019-04-17 15:05:45 +0200350psa_status_t psa_get_key_attributes(psa_key_handle_t handle,
351 psa_key_attributes_t *attributes);
352
Gilles Peskine20628592019-04-19 19:29:50 +0200353/** Reset a key attribute structure to a freshly initialized state.
354 *
355 * You must initialize the attribute structure as described in the
356 * documentation of the type #psa_key_attributes_t before calling this
357 * function. Once the structure has been initialized, you may call this
358 * function at any time.
359 *
360 * This function frees any auxiliary resources that the structure
361 * may contain.
362 *
363 * \param[in,out] attributes The attribute structure to reset.
364 */
Gilles Peskine8c8f2ab2019-04-18 21:44:46 +0200365void psa_reset_key_attributes(psa_key_attributes_t *attributes);
Gilles Peskine4747d192019-04-17 15:05:45 +0200366
Gilles Peskine87a5e562019-04-17 12:28:25 +0200367/**@}*/
368
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100369/** \defgroup key_management Key management
370 * @{
371 */
372
Gilles Peskinef535eb22018-11-30 14:08:36 +0100373/** Open a handle to an existing persistent key.
374 *
Gilles Peskine4754cde2019-05-21 15:56:29 +0200375 * Open a handle to a persistent key. A key is persistent if it was created
376 * with a lifetime other than #PSA_KEY_LIFETIME_VOLATILE. A persistent key
377 * always has a nonzero key identifier, set with psa_set_key_id() when
378 * creating the key. Implementations may provide additional pre-provisioned
Andrew Thoelke203491c2019-08-21 17:55:30 +0100379 * keys that can be opened with psa_open_key(). Such keys have a key identifier
380 * in the vendor range, as documented in the description of #psa_key_id_t.
Gilles Peskine4754cde2019-05-21 15:56:29 +0200381 *
Andrew Thoelkede183412019-09-05 09:38:06 +0100382 * The application must eventually close the handle with psa_close_key() or
383 * psa_destroy_key() to release associated resources. If the application dies
384 * without calling one of these functions, the implementation should perform
385 * the equivalent of a call to psa_close_key().
Gilles Peskinef535eb22018-11-30 14:08:36 +0100386 *
Andrew Thoelke9741b112019-08-21 18:20:41 +0100387 * Some implementations permit an application to open the same key multiple
Andrew Thoelkede183412019-09-05 09:38:06 +0100388 * times. If this is successful, each call to psa_open_key() will return a
389 * different key handle.
390 *
391 * \note Applications that rely on opening a key multiple times will not be
392 * portable to implementations that only permit a single key handle to be
393 * opened. See also :ref:\`key-handles\`.
Andrew Thoelke9741b112019-08-21 18:20:41 +0100394 *
Gilles Peskinef535eb22018-11-30 14:08:36 +0100395 * \param id The persistent identifier of the key.
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +0100396 * \param[out] handle On success, a handle to the key.
Gilles Peskinef535eb22018-11-30 14:08:36 +0100397 *
398 * \retval #PSA_SUCCESS
399 * Success. The application can now use the value of `*handle`
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +0100400 * to access the key.
Gilles Peskinef535eb22018-11-30 14:08:36 +0100401 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
Andrew Thoelke9741b112019-08-21 18:20:41 +0100402 * The implementation does not have sufficient resources to open the
403 * key. This can be due to reaching an implementation limit on the
404 * number of open keys, the number of open key handles, or available
405 * memory.
David Saadab4ecc272019-02-14 13:48:10 +0200406 * \retval #PSA_ERROR_DOES_NOT_EXIST
Andrew Thoelke9741b112019-08-21 18:20:41 +0100407 * There is no persistent key with key identifier \p id.
Gilles Peskinef535eb22018-11-30 14:08:36 +0100408 * \retval #PSA_ERROR_INVALID_ARGUMENT
Andrew Thoelke9741b112019-08-21 18:20:41 +0100409 * \p id is not a valid persistent key identifier.
Gilles Peskinef535eb22018-11-30 14:08:36 +0100410 * \retval #PSA_ERROR_NOT_PERMITTED
411 * The specified key exists, but the application does not have the
412 * permission to access it. Note that this specification does not
413 * define any way to create such a key, but it may be possible
414 * through implementation-specific means.
Gilles Peskine225010f2019-05-06 18:44:55 +0200415 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
Adrian L. Shawd789dc12019-08-12 15:06:48 +0100416 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine225010f2019-05-06 18:44:55 +0200417 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +0100418 * \retval #PSA_ERROR_BAD_STATE
419 * The library has not been previously initialized by psa_crypto_init().
420 * It is implementation-dependent whether a failure to initialize
421 * results in this error code.
Gilles Peskinef535eb22018-11-30 14:08:36 +0100422 */
Gilles Peskine225010f2019-05-06 18:44:55 +0200423psa_status_t psa_open_key(psa_key_id_t id,
Gilles Peskinef535eb22018-11-30 14:08:36 +0100424 psa_key_handle_t *handle);
425
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +0100426
Gilles Peskinef535eb22018-11-30 14:08:36 +0100427/** Close a key handle.
428 *
Andrew Thoelke3daba812019-08-21 22:46:56 +0100429 * If the handle designates a volatile key, this will destroy the key material
430 * and free all associated resources, just like psa_destroy_key().
Gilles Peskinef535eb22018-11-30 14:08:36 +0100431 *
Andrew Thoelke3daba812019-08-21 22:46:56 +0100432 * If this is the last open handle to a persistent key, then closing the handle
433 * will free all resources associated with the key in volatile memory. The key
434 * data in persistent storage is not affected and can be opened again later
435 * with a call to psa_open_key().
Gilles Peskinef535eb22018-11-30 14:08:36 +0100436 *
Andrew Thoelke3daba812019-08-21 22:46:56 +0100437 * Closing the key handle makes the handle invalid, and the key handle
Andrew Thoelke8824dae2019-08-22 15:04:48 +0100438 * must not be used again by the application.
Andrew Thoelke3daba812019-08-21 22:46:56 +0100439 *
Andrew Thoelke970629f2019-09-09 09:56:34 +0100440 * \note If the key handle was used to set up an active
Andrew Thoelkede183412019-09-05 09:38:06 +0100441 * :ref:\`multipart operation <multipart-operations>\`, then closing the
442 * key handle can cause the multipart operation to fail. Applications should
443 * maintain the key handle until after the multipart operation has finished.
Gilles Peskine5f25dd02019-01-14 18:24:53 +0100444 *
Gilles Peskinef535eb22018-11-30 14:08:36 +0100445 * \param handle The key handle to close.
446 *
447 * \retval #PSA_SUCCESS
448 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskineae32aac2018-11-30 14:39:32 +0100449 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
Adrian L. Shawf97c8522019-08-15 13:27:12 +0100450 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +0100451 * \retval #PSA_ERROR_BAD_STATE
452 * The library has not been previously initialized by psa_crypto_init().
453 * It is implementation-dependent whether a failure to initialize
454 * results in this error code.
Gilles Peskinef535eb22018-11-30 14:08:36 +0100455 */
456psa_status_t psa_close_key(psa_key_handle_t handle);
457
Adrian L. Shaw4c61c1a2019-09-11 14:40:51 +0100458/** Make a copy of a key.
459 *
460 * Copy key material from one location to another.
461 *
462 * This function is primarily useful to copy a key from one location
463 * to another, since it populates a key using the material from
464 * another key which may have a different lifetime.
465 *
466 * This function may be used to share a key with a different party,
467 * subject to implementation-defined restrictions on key sharing.
468 *
469 * The policy on the source key must have the usage flag
470 * #PSA_KEY_USAGE_COPY set.
471 * This flag is sufficient to permit the copy if the key has the lifetime
472 * #PSA_KEY_LIFETIME_VOLATILE or #PSA_KEY_LIFETIME_PERSISTENT.
473 * Some secure elements do not provide a way to copy a key without
474 * making it extractable from the secure element. If a key is located
475 * in such a secure element, then the key must have both usage flags
476 * #PSA_KEY_USAGE_COPY and #PSA_KEY_USAGE_EXPORT in order to make
477 * a copy of the key outside the secure element.
478 *
479 * The resulting key may only be used in a way that conforms to
480 * both the policy of the original key and the policy specified in
481 * the \p attributes parameter:
482 * - The usage flags on the resulting key are the bitwise-and of the
483 * usage flags on the source policy and the usage flags in \p attributes.
484 * - If both allow the same algorithm or wildcard-based
485 * algorithm policy, the resulting key has the same algorithm policy.
486 * - If either of the policies allows an algorithm and the other policy
487 * allows a wildcard-based algorithm policy that includes this algorithm,
488 * the resulting key allows the same algorithm.
489 * - If the policies do not allow any algorithm in common, this function
490 * fails with the status #PSA_ERROR_INVALID_ARGUMENT.
491 *
492 * The effect of this function on implementation-defined attributes is
493 * implementation-defined.
494 *
495 * \param source_handle The key to copy. It must be a valid key handle.
496 * \param[in] attributes The attributes for the new key.
497 * They are used as follows:
498 * - The key type and size may be 0. If either is
499 * nonzero, it must match the corresponding
500 * attribute of the source key.
501 * - The key location (the lifetime and, for
502 * persistent keys, the key identifier) is
503 * used directly.
504 * - The policy constraints (usage flags and
505 * algorithm policy) are combined from
506 * the source key and \p attributes so that
507 * both sets of restrictions apply, as
508 * described in the documentation of this function.
509 * \param[out] target_handle On success, a handle to the newly created key.
510 * \c 0 on failure.
511 *
512 * \retval #PSA_SUCCESS
513 * \retval #PSA_ERROR_INVALID_HANDLE
514 * \p source_handle is invalid.
515 * \retval #PSA_ERROR_ALREADY_EXISTS
516 * This is an attempt to create a persistent key, and there is
517 * already a persistent key with the given identifier.
518 * \retval #PSA_ERROR_INVALID_ARGUMENT
519 * The lifetime or identifier in \p attributes are invalid.
520 * \retval #PSA_ERROR_INVALID_ARGUMENT
521 * The policy constraints on the source and specified in
522 * \p attributes are incompatible.
523 * \retval #PSA_ERROR_INVALID_ARGUMENT
524 * \p attributes specifies a key type or key size
525 * which does not match the attributes of the source key.
526 * \retval #PSA_ERROR_NOT_PERMITTED
527 * The source key does not have the #PSA_KEY_USAGE_COPY usage flag.
528 * \retval #PSA_ERROR_NOT_PERMITTED
529 * The source key is not exportable and its lifetime does not
530 * allow copying it to the target's lifetime.
531 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
532 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
533 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
534 * \retval #PSA_ERROR_HARDWARE_FAILURE
535 * \retval #PSA_ERROR_STORAGE_FAILURE
536 * \retval #PSA_ERROR_CORRUPTION_DETECTED
537 * \retval #PSA_ERROR_BAD_STATE
538 * The library has not been previously initialized by psa_crypto_init().
539 * It is implementation-dependent whether a failure to initialize
540 * results in this error code.
541 */
542psa_status_t psa_copy_key(psa_key_handle_t source_handle,
543 const psa_key_attributes_t *attributes,
544 psa_key_handle_t *target_handle);
545
546
547/**
548 * \brief Destroy a key.
549 *
550 * This function destroys a key from both volatile
551 * memory and, if applicable, non-volatile storage. Implementations shall
552 * make a best effort to ensure that that the key material cannot be recovered.
553 *
554 * This function also erases any metadata such as policies and frees
555 * resources associated with the key. To free all resources associated with
556 * the key, all handles to the key must be closed or destroyed.
557 *
558 * Destroying the key makes the handle invalid, and the key handle
559 * must not be used again by the application. Using other open handles to the
560 * destroyed key in a cryptographic operation will result in an error.
561 *
562 * If a key is currently in use in a multipart operation, then destroying the
563 * key will cause the multipart operation to fail.
564 *
565 * \param handle Handle to the key to erase.
566 *
567 * \retval #PSA_SUCCESS
568 * The key material has been erased.
569 * \retval #PSA_ERROR_NOT_PERMITTED
570 * The key cannot be erased because it is
571 * read-only, either due to a policy or due to physical restrictions.
572 * \retval #PSA_ERROR_INVALID_HANDLE
573 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
574 * There was an failure in communication with the cryptoprocessor.
575 * The key material may still be present in the cryptoprocessor.
576 * \retval #PSA_ERROR_STORAGE_FAILURE
577 * The storage is corrupted. Implementations shall make a best effort
578 * to erase key material even in this stage, however applications
579 * should be aware that it may be impossible to guarantee that the
580 * key material is not recoverable in such cases.
581 * \retval #PSA_ERROR_CORRUPTION_DETECTED
582 * An unexpected condition which is not a storage corruption or
583 * a communication failure occurred. The cryptoprocessor may have
584 * been compromised.
585 * \retval #PSA_ERROR_BAD_STATE
586 * The library has not been previously initialized by psa_crypto_init().
587 * It is implementation-dependent whether a failure to initialize
588 * results in this error code.
589 */
590psa_status_t psa_destroy_key(psa_key_handle_t handle);
591
Gilles Peskine3cac8c42018-11-30 14:07:45 +0100592/**@}*/
593
594/** \defgroup import_export Key import and export
595 * @{
596 */
597
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100598/**
599 * \brief Import a key in binary format.
600 *
Gilles Peskinef5b9fa12018-03-07 16:40:18 +0100601 * This function supports any output from psa_export_key(). Refer to the
Gilles Peskinef7933932018-10-31 14:07:52 +0100602 * documentation of psa_export_public_key() for the format of public keys
603 * and to the documentation of psa_export_key() for the format for
604 * other key types.
605 *
Gilles Peskine05c900b2019-09-12 18:29:43 +0200606 * The key data determines the key size. The attributes may optionally
607 * specify a key size; in this case it must match the size determined
608 * from the key data. A key size of 0 in \p attributes indicates that
609 * the key size is solely determined by the key data.
610 *
611 * Implementations must reject an attempt to import a key of size 0.
612 *
Gilles Peskinef7933932018-10-31 14:07:52 +0100613 * This specification supports a single format for each key type.
614 * Implementations may support other formats as long as the standard
615 * format is supported. Implementations that support other formats
616 * should ensure that the formats are clearly unambiguous so as to
617 * minimize the risk that an invalid input is accidentally interpreted
618 * according to a different format.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100619 *
Gilles Peskine20628592019-04-19 19:29:50 +0200620 * \param[in] attributes The attributes for the new key.
Gilles Peskine4ce2a9d2019-05-03 16:57:15 +0200621 * The key size is always determined from the
622 * \p data buffer.
623 * If the key size in \p attributes is nonzero,
624 * it must be equal to the size from \p data.
Gilles Peskine20628592019-04-19 19:29:50 +0200625 * \param[out] handle On success, a handle to the newly created key.
626 * \c 0 on failure.
Gilles Peskinef7933932018-10-31 14:07:52 +0100627 * \param[in] data Buffer containing the key data. The content of this
Gilles Peskine24f10f82019-05-16 12:18:32 +0200628 * buffer is interpreted according to the type declared
629 * in \p attributes.
Gilles Peskine20628592019-04-19 19:29:50 +0200630 * All implementations must support at least the format
631 * described in the documentation
Gilles Peskinef7933932018-10-31 14:07:52 +0100632 * of psa_export_key() or psa_export_public_key() for
Gilles Peskine20628592019-04-19 19:29:50 +0200633 * the chosen type. Implementations may allow other
634 * formats, but should be conservative: implementations
635 * should err on the side of rejecting content if it
636 * may be erroneous (e.g. wrong type or truncated data).
Gilles Peskinefa4070c2018-07-12 19:23:03 +0200637 * \param data_length Size of the \p data buffer in bytes.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100638 *
Gilles Peskine28538492018-07-11 17:34:00 +0200639 * \retval #PSA_SUCCESS
Gilles Peskine308b91d2018-02-08 09:47:44 +0100640 * Success.
Gilles Peskine23fd2bd2018-12-11 15:51:32 +0100641 * If the key is persistent, the key material and the key's metadata
642 * have been saved to persistent storage.
Gilles Peskine20628592019-04-19 19:29:50 +0200643 * \retval #PSA_ERROR_ALREADY_EXISTS
644 * This is an attempt to create a persistent key, and there is
645 * already a persistent key with the given identifier.
Gilles Peskine28538492018-07-11 17:34:00 +0200646 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskine65eb8582018-04-19 08:28:58 +0200647 * The key type or key size is not supported, either by the
Gilles Peskine20628592019-04-19 19:29:50 +0200648 * implementation in general or in this particular persistent location.
Gilles Peskine28538492018-07-11 17:34:00 +0200649 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine4ce2a9d2019-05-03 16:57:15 +0200650 * The key attributes, as a whole, are invalid.
651 * \retval #PSA_ERROR_INVALID_ARGUMENT
652 * The key data is not correctly formatted.
653 * \retval #PSA_ERROR_INVALID_ARGUMENT
654 * The size in \p attributes is nonzero and does not match the size
655 * of the key data.
Gilles Peskine28538492018-07-11 17:34:00 +0200656 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
657 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
658 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
Darryl Greend49a4992018-06-18 17:27:26 +0100659 * \retval #PSA_ERROR_STORAGE_FAILURE
Gilles Peskine28538492018-07-11 17:34:00 +0200660 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +0200661 * \retval #PSA_ERROR_CORRUPTION_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +0300662 * \retval #PSA_ERROR_BAD_STATE
Adrian L. Shaw97d3bc32019-08-08 14:40:04 +0100663 * \p operation is either not initialized or is in use
664 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +0300665 * The library has not been previously initialized by psa_crypto_init().
666 * It is implementation-dependent whether a failure to initialize
667 * results in this error code.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100668 */
Gilles Peskine87a5e562019-04-17 12:28:25 +0200669psa_status_t psa_import_key(const psa_key_attributes_t *attributes,
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100670 const uint8_t *data,
Gilles Peskine73676cb2019-05-15 20:15:10 +0200671 size_t data_length,
672 psa_key_handle_t *handle);
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100673
Adrian L. Shaw4c61c1a2019-09-11 14:40:51 +0100674
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100675
676/**
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100677 * \brief Export a key in binary format.
678 *
679 * The output of this function can be passed to psa_import_key() to
680 * create an equivalent object.
681 *
Gilles Peskinef7933932018-10-31 14:07:52 +0100682 * If the implementation of psa_import_key() supports other formats
683 * beyond the format specified here, the output from psa_export_key()
684 * must use the representation specified here, not the original
685 * representation.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100686 *
Gilles Peskine308b91d2018-02-08 09:47:44 +0100687 * For standard key types, the output format is as follows:
688 *
689 * - For symmetric keys (including MAC keys), the format is the
690 * raw bytes of the key.
691 * - For DES, the key data consists of 8 bytes. The parity bits must be
692 * correct.
693 * - For Triple-DES, the format is the concatenation of the
694 * two or three DES keys.
Gilles Peskinec93b80c2019-05-16 19:39:54 +0200695 * - For RSA key pairs (#PSA_KEY_TYPE_RSA_KEY_PAIR), the format
Gilles Peskine4e1e9be2018-08-10 18:57:40 +0200696 * is the non-encrypted DER encoding of the representation defined by
697 * PKCS\#1 (RFC 8017) as `RSAPrivateKey`, version 0.
698 * ```
699 * RSAPrivateKey ::= SEQUENCE {
Gilles Peskine4f6c77b2018-08-11 01:17:53 +0200700 * version INTEGER, -- must be 0
Gilles Peskine4e1e9be2018-08-10 18:57:40 +0200701 * modulus INTEGER, -- n
702 * publicExponent INTEGER, -- e
703 * privateExponent INTEGER, -- d
704 * prime1 INTEGER, -- p
705 * prime2 INTEGER, -- q
706 * exponent1 INTEGER, -- d mod (p-1)
707 * exponent2 INTEGER, -- d mod (q-1)
708 * coefficient INTEGER, -- (inverse of q) mod p
709 * }
710 * ```
Gilles Peskine4e1e9be2018-08-10 18:57:40 +0200711 * - For elliptic curve key pairs (key types for which
Gilles Peskinec93b80c2019-05-16 19:39:54 +0200712 * #PSA_KEY_TYPE_IS_ECC_KEY_PAIR is true), the format is
Gilles Peskine6c6a0232018-11-15 17:44:43 +0100713 * a representation of the private value as a `ceiling(m/8)`-byte string
714 * where `m` is the bit size associated with the curve, i.e. the bit size
715 * of the order of the curve's coordinate field. This byte string is
716 * in little-endian order for Montgomery curves (curve types
717 * `PSA_ECC_CURVE_CURVEXXX`), and in big-endian order for Weierstrass
718 * curves (curve types `PSA_ECC_CURVE_SECTXXX`, `PSA_ECC_CURVE_SECPXXX`
719 * and `PSA_ECC_CURVE_BRAINPOOL_PXXX`).
Gilles Peskinef76aa772018-10-29 19:24:33 +0100720 * This is the content of the `privateKey` field of the `ECPrivateKey`
721 * format defined by RFC 5915.
Gilles Peskinedcaefae2019-05-16 12:55:35 +0200722 * - For Diffie-Hellman key exchange key pairs (key types for which
Gilles Peskinec93b80c2019-05-16 19:39:54 +0200723 * #PSA_KEY_TYPE_IS_DH_KEY_PAIR is true), the
Jaeden Amero8851c402019-01-11 14:20:03 +0000724 * format is the representation of the private key `x` as a big-endian byte
725 * string. The length of the byte string is the private key size in bytes
726 * (leading zeroes are not stripped).
Gilles Peskine4e1e9be2018-08-10 18:57:40 +0200727 * - For public keys (key types for which #PSA_KEY_TYPE_IS_PUBLIC_KEY is
728 * true), the format is the same as for psa_export_public_key().
Gilles Peskine308b91d2018-02-08 09:47:44 +0100729 *
Gilles Peskine4318dfc2019-05-14 14:23:32 +0200730 * The policy on the key must have the usage flag #PSA_KEY_USAGE_EXPORT set.
731 *
Gilles Peskineae32aac2018-11-30 14:39:32 +0100732 * \param handle Handle to the key to export.
Gilles Peskineedd11a12018-07-12 01:08:58 +0200733 * \param[out] data Buffer where the key data is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +0200734 * \param data_size Size of the \p data buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +0200735 * \param[out] data_length On success, the number of bytes
736 * that make up the key data.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100737 *
Gilles Peskine28538492018-07-11 17:34:00 +0200738 * \retval #PSA_SUCCESS
Gilles Peskineae32aac2018-11-30 14:39:32 +0100739 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine28538492018-07-11 17:34:00 +0200740 * \retval #PSA_ERROR_NOT_PERMITTED
Gilles Peskine4318dfc2019-05-14 14:23:32 +0200741 * The key does not have the #PSA_KEY_USAGE_EXPORT flag.
Darryl Green9e2d7a02018-07-24 16:33:30 +0100742 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskine1be949b2018-08-10 19:06:59 +0200743 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
744 * The size of the \p data buffer is too small. You can determine a
745 * sufficient buffer size by calling
746 * #PSA_KEY_EXPORT_MAX_SIZE(\c type, \c bits)
747 * where \c type is the key type
748 * and \c bits is the key size in bits.
Gilles Peskine28538492018-07-11 17:34:00 +0200749 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
750 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +0200751 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw89b71522019-08-06 16:21:00 +0100752 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shaw0542d592019-08-06 16:34:44 +0100753 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
itayzafrir90d8c7a2018-09-12 11:44:52 +0300754 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +0300755 * The library has not been previously initialized by psa_crypto_init().
756 * It is implementation-dependent whether a failure to initialize
757 * results in this error code.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100758 */
Gilles Peskineae32aac2018-11-30 14:39:32 +0100759psa_status_t psa_export_key(psa_key_handle_t handle,
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100760 uint8_t *data,
761 size_t data_size,
762 size_t *data_length);
763
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100764/**
765 * \brief Export a public key or the public part of a key pair in binary format.
766 *
767 * The output of this function can be passed to psa_import_key() to
768 * create an object that is equivalent to the public key.
769 *
Jaeden Amerod3a0c2c2019-01-11 17:15:56 +0000770 * This specification supports a single format for each key type.
771 * Implementations may support other formats as long as the standard
772 * format is supported. Implementations that support other formats
773 * should ensure that the formats are clearly unambiguous so as to
774 * minimize the risk that an invalid input is accidentally interpreted
775 * according to a different format.
776 *
Jaeden Amero6b196002019-01-10 10:23:21 +0000777 * For standard key types, the output format is as follows:
778 * - For RSA public keys (#PSA_KEY_TYPE_RSA_PUBLIC_KEY), the DER encoding of
779 * the representation defined by RFC 3279 &sect;2.3.1 as `RSAPublicKey`.
780 * ```
781 * RSAPublicKey ::= SEQUENCE {
782 * modulus INTEGER, -- n
783 * publicExponent INTEGER } -- e
784 * ```
Jaeden Amero0ae445f2019-01-10 11:42:27 +0000785 * - For elliptic curve public keys (key types for which
786 * #PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY is true), the format is the uncompressed
787 * representation defined by SEC1 &sect;2.3.3 as the content of an ECPoint.
788 * Let `m` be the bit size associated with the curve, i.e. the bit size of
789 * `q` for a curve over `F_q`. The representation consists of:
790 * - The byte 0x04;
791 * - `x_P` as a `ceiling(m/8)`-byte string, big-endian;
792 * - `y_P` as a `ceiling(m/8)`-byte string, big-endian.
Gilles Peskinedcaefae2019-05-16 12:55:35 +0200793 * - For Diffie-Hellman key exchange public keys (key types for which
794 * #PSA_KEY_TYPE_IS_DH_PUBLIC_KEY is true),
Jaeden Amero8851c402019-01-11 14:20:03 +0000795 * the format is the representation of the public key `y = g^x mod p` as a
796 * big-endian byte string. The length of the byte string is the length of the
797 * base prime `p` in bytes.
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100798 *
Gilles Peskine4318dfc2019-05-14 14:23:32 +0200799 * Exporting a public key object or the public part of a key pair is
800 * always permitted, regardless of the key's usage flags.
801 *
Gilles Peskineae32aac2018-11-30 14:39:32 +0100802 * \param handle Handle to the key to export.
Gilles Peskineedd11a12018-07-12 01:08:58 +0200803 * \param[out] data Buffer where the key data is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +0200804 * \param data_size Size of the \p data buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +0200805 * \param[out] data_length On success, the number of bytes
806 * that make up the key data.
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100807 *
Gilles Peskine28538492018-07-11 17:34:00 +0200808 * \retval #PSA_SUCCESS
Gilles Peskineae32aac2018-11-30 14:39:32 +0100809 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine28538492018-07-11 17:34:00 +0200810 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine1be949b2018-08-10 19:06:59 +0200811 * The key is neither a public key nor a key pair.
812 * \retval #PSA_ERROR_NOT_SUPPORTED
813 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
814 * The size of the \p data buffer is too small. You can determine a
815 * sufficient buffer size by calling
Gilles Peskinec93b80c2019-05-16 19:39:54 +0200816 * #PSA_KEY_EXPORT_MAX_SIZE(#PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(\c type), \c bits)
Gilles Peskine1be949b2018-08-10 19:06:59 +0200817 * where \c type is the key type
818 * and \c bits is the key size in bits.
Gilles Peskine28538492018-07-11 17:34:00 +0200819 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
820 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +0200821 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw398b3c22019-08-06 17:22:41 +0100822 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shaw88c51ad2019-08-06 17:09:33 +0100823 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
itayzafrir90d8c7a2018-09-12 11:44:52 +0300824 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +0300825 * The library has not been previously initialized by psa_crypto_init().
826 * It is implementation-dependent whether a failure to initialize
827 * results in this error code.
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100828 */
Gilles Peskineae32aac2018-11-30 14:39:32 +0100829psa_status_t psa_export_public_key(psa_key_handle_t handle,
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100830 uint8_t *data,
831 size_t data_size,
832 size_t *data_length);
833
Adrian L. Shaw4c61c1a2019-09-11 14:40:51 +0100834
Gilles Peskine20035e32018-02-03 22:44:14 +0100835
836/**@}*/
837
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100838/** \defgroup hash Message digests
839 * @{
840 */
841
Gilles Peskine69647a42019-01-14 20:18:12 +0100842/** Calculate the hash (digest) of a message.
843 *
844 * \note To verify the hash of a message against an
845 * expected value, use psa_hash_compare() instead.
846 *
847 * \param alg The hash algorithm to compute (\c PSA_ALG_XXX value
848 * such that #PSA_ALG_IS_HASH(\p alg) is true).
849 * \param[in] input Buffer containing the message to hash.
850 * \param input_length Size of the \p input buffer in bytes.
851 * \param[out] hash Buffer where the hash is to be written.
852 * \param hash_size Size of the \p hash buffer in bytes.
853 * \param[out] hash_length On success, the number of bytes
854 * that make up the hash value. This is always
Gilles Peskined338b912019-02-15 13:01:41 +0100855 * #PSA_HASH_SIZE(\p alg).
Gilles Peskine69647a42019-01-14 20:18:12 +0100856 *
857 * \retval #PSA_SUCCESS
858 * Success.
859 * \retval #PSA_ERROR_NOT_SUPPORTED
860 * \p alg is not supported or is not a hash algorithm.
Adrian L. Shawfa2cefa2019-09-03 16:51:19 +0100861 * \retval #PSA_ERROR_INVALID_ARGUMENT
Adrian L. Shawf7d852a2019-08-06 17:50:26 +0100862 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
863 * \p hash_size is too small
Gilles Peskine69647a42019-01-14 20:18:12 +0100864 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
865 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
866 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +0200867 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw7f1863c2019-08-06 16:34:44 +0100868 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
Adrian L. Shawdec47b62019-08-07 14:25:38 +0100869 * \retval #PSA_ERROR_BAD_STATE
870 * The library has not been previously initialized by psa_crypto_init().
871 * It is implementation-dependent whether a failure to initialize
872 * results in this error code.
Gilles Peskine69647a42019-01-14 20:18:12 +0100873 */
874psa_status_t psa_hash_compute(psa_algorithm_t alg,
875 const uint8_t *input,
876 size_t input_length,
877 uint8_t *hash,
878 size_t hash_size,
879 size_t *hash_length);
880
881/** Calculate the hash (digest) of a message and compare it with a
882 * reference value.
883 *
884 * \param alg The hash algorithm to compute (\c PSA_ALG_XXX value
885 * such that #PSA_ALG_IS_HASH(\p alg) is true).
886 * \param[in] input Buffer containing the message to hash.
887 * \param input_length Size of the \p input buffer in bytes.
888 * \param[out] hash Buffer containing the expected hash value.
Gilles Peskinea05602d2019-01-17 15:25:52 +0100889 * \param hash_length Size of the \p hash buffer in bytes.
Gilles Peskine69647a42019-01-14 20:18:12 +0100890 *
891 * \retval #PSA_SUCCESS
892 * The expected hash is identical to the actual hash of the input.
893 * \retval #PSA_ERROR_INVALID_SIGNATURE
894 * The hash of the message was calculated successfully, but it
895 * differs from the expected hash.
896 * \retval #PSA_ERROR_NOT_SUPPORTED
897 * \p alg is not supported or is not a hash algorithm.
Adrian L. Shaw8d0bcf22019-08-13 11:36:29 +0100898 * \retval #PSA_ERROR_INVALID_ARGUMENT
899 * \p input_length or \p hash_length do not match the hash size for \p alg
Gilles Peskine69647a42019-01-14 20:18:12 +0100900 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
901 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
902 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +0200903 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw11638b92019-08-06 17:09:33 +0100904 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
Adrian L. Shawdec47b62019-08-07 14:25:38 +0100905 * \retval #PSA_ERROR_BAD_STATE
906 * The library has not been previously initialized by psa_crypto_init().
907 * It is implementation-dependent whether a failure to initialize
908 * results in this error code.
Gilles Peskine69647a42019-01-14 20:18:12 +0100909 */
910psa_status_t psa_hash_compare(psa_algorithm_t alg,
911 const uint8_t *input,
912 size_t input_length,
913 const uint8_t *hash,
914 const size_t hash_length);
915
Gilles Peskine308b91d2018-02-08 09:47:44 +0100916/** The type of the state data structure for multipart hash operations.
917 *
Jaeden Amero6a25b412019-01-04 11:47:44 +0000918 * Before calling any function on a hash operation object, the application must
919 * initialize it by any of the following means:
920 * - Set the structure to all-bits-zero, for example:
921 * \code
922 * psa_hash_operation_t operation;
923 * memset(&operation, 0, sizeof(operation));
924 * \endcode
925 * - Initialize the structure to logical zero values, for example:
926 * \code
927 * psa_hash_operation_t operation = {0};
928 * \endcode
929 * - Initialize the structure to the initializer #PSA_HASH_OPERATION_INIT,
930 * for example:
931 * \code
932 * psa_hash_operation_t operation = PSA_HASH_OPERATION_INIT;
933 * \endcode
934 * - Assign the result of the function psa_hash_operation_init()
935 * to the structure, for example:
936 * \code
937 * psa_hash_operation_t operation;
938 * operation = psa_hash_operation_init();
939 * \endcode
940 *
Gilles Peskine92b30732018-03-03 21:29:30 +0100941 * This is an implementation-defined \c struct. Applications should not
Gilles Peskine308b91d2018-02-08 09:47:44 +0100942 * make any assumptions about the content of this structure except
943 * as directed by the documentation of a specific implementation. */
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100944typedef struct psa_hash_operation_s psa_hash_operation_t;
945
Jaeden Amero6a25b412019-01-04 11:47:44 +0000946/** \def PSA_HASH_OPERATION_INIT
947 *
948 * This macro returns a suitable initializer for a hash operation object
949 * of type #psa_hash_operation_t.
950 */
951#ifdef __DOXYGEN_ONLY__
952/* This is an example definition for documentation purposes.
953 * Implementations should define a suitable value in `crypto_struct.h`.
954 */
955#define PSA_HASH_OPERATION_INIT {0}
956#endif
957
958/** Return an initial value for a hash operation object.
959 */
960static psa_hash_operation_t psa_hash_operation_init(void);
961
Gilles Peskinef45adda2019-01-14 18:29:18 +0100962/** Set up a multipart hash operation.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100963 *
964 * The sequence of operations to calculate a hash (message digest)
965 * is as follows:
966 * -# Allocate an operation object which will be passed to all the functions
967 * listed here.
Jaeden Amero6a25b412019-01-04 11:47:44 +0000968 * -# Initialize the operation object with one of the methods described in the
969 * documentation for #psa_hash_operation_t, e.g. PSA_HASH_OPERATION_INIT.
Gilles Peskineda8191d1c2018-07-08 19:46:38 +0200970 * -# Call psa_hash_setup() to specify the algorithm.
Gilles Peskine7e4acc52018-02-16 21:24:11 +0100971 * -# Call psa_hash_update() zero, one or more times, passing a fragment
Gilles Peskine308b91d2018-02-08 09:47:44 +0100972 * of the message each time. The hash that is calculated is the hash
973 * of the concatenation of these messages in order.
974 * -# To calculate the hash, call psa_hash_finish().
975 * To compare the hash with an expected value, call psa_hash_verify().
976 *
977 * The application may call psa_hash_abort() at any time after the operation
Jaeden Amero6a25b412019-01-04 11:47:44 +0000978 * has been initialized.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100979 *
Gilles Peskineda8191d1c2018-07-08 19:46:38 +0200980 * After a successful call to psa_hash_setup(), the application must
Gilles Peskineed522972018-03-20 17:54:15 +0100981 * eventually terminate the operation. The following events terminate an
982 * operation:
Gilles Peskine308b91d2018-02-08 09:47:44 +0100983 * - A failed call to psa_hash_update().
Gilles Peskine19067982018-03-20 17:54:53 +0100984 * - A call to psa_hash_finish(), psa_hash_verify() or psa_hash_abort().
Gilles Peskine308b91d2018-02-08 09:47:44 +0100985 *
Jaeden Amero6a25b412019-01-04 11:47:44 +0000986 * \param[in,out] operation The operation object to set up. It must have
987 * been initialized as per the documentation for
988 * #psa_hash_operation_t and not yet in use.
Gilles Peskineedd11a12018-07-12 01:08:58 +0200989 * \param alg The hash algorithm to compute (\c PSA_ALG_XXX value
990 * such that #PSA_ALG_IS_HASH(\p alg) is true).
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_NOT_SUPPORTED
Adrian L. Shawfbf7f122019-08-15 13:34:51 +0100995 * \p alg is not a supported hash algorithm.
996 * \retval #PSA_ERROR_INVALID_ARGUMENT
997 * \p alg is not a hash algorithm.
Gilles Peskine8e1addc2019-01-10 11:51:17 +0100998 * \retval #PSA_ERROR_BAD_STATE
999 * The operation state is not valid (already set up and not
1000 * subsequently completed).
Gilles Peskine28538492018-07-11 17:34:00 +02001001 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1002 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1003 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001004 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001005 * \retval #PSA_ERROR_BAD_STATE
Adrian L. Shawe970d652019-08-08 14:40:04 +01001006 * \p operation is either not initialized or is in use
1007 * \retval #PSA_ERROR_BAD_STATE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001008 * The library has not been previously initialized by psa_crypto_init().
1009 * It is implementation-dependent whether a failure to initialize
1010 * results in this error code.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001011 */
Gilles Peskineda8191d1c2018-07-08 19:46:38 +02001012psa_status_t psa_hash_setup(psa_hash_operation_t *operation,
Gilles Peskine9ef733f2018-02-07 21:05:37 +01001013 psa_algorithm_t alg);
1014
Gilles Peskine308b91d2018-02-08 09:47:44 +01001015/** Add a message fragment to a multipart hash operation.
1016 *
Gilles Peskineda8191d1c2018-07-08 19:46:38 +02001017 * The application must call psa_hash_setup() before calling this function.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001018 *
1019 * If this function returns an error status, the operation becomes inactive.
1020 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001021 * \param[in,out] operation Active hash operation.
1022 * \param[in] input Buffer containing the message fragment to hash.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001023 * \param input_length Size of the \p input buffer in bytes.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001024 *
Gilles Peskine28538492018-07-11 17:34:00 +02001025 * \retval #PSA_SUCCESS
Gilles Peskine308b91d2018-02-08 09:47:44 +01001026 * Success.
Gilles Peskine28538492018-07-11 17:34:00 +02001027 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001028 * The operation state is not valid (not set up, or already completed).
Gilles Peskine28538492018-07-11 17:34:00 +02001029 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1030 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1031 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001032 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001033 * \retval #PSA_ERROR_BAD_STATE
Adrian L. Shaw320659b2019-08-08 14:49:01 +01001034 * The operation state is not valid.
1035 * \retval #PSA_ERROR_BAD_STATE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001036 * The library has not been previously initialized by psa_crypto_init().
1037 * It is implementation-dependent whether a failure to initialize
1038 * results in this error code.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001039 */
Gilles Peskine9ef733f2018-02-07 21:05:37 +01001040psa_status_t psa_hash_update(psa_hash_operation_t *operation,
1041 const uint8_t *input,
1042 size_t input_length);
1043
Gilles Peskine308b91d2018-02-08 09:47:44 +01001044/** Finish the calculation of the hash of a message.
1045 *
Gilles Peskineda8191d1c2018-07-08 19:46:38 +02001046 * The application must call psa_hash_setup() before calling this function.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001047 * This function calculates the hash of the message formed by concatenating
1048 * the inputs passed to preceding calls to psa_hash_update().
1049 *
1050 * When this function returns, the operation becomes inactive.
1051 *
1052 * \warning Applications should not call this function if they expect
1053 * a specific value for the hash. Call psa_hash_verify() instead.
1054 * Beware that comparing integrity or authenticity data such as
1055 * hash values with a function such as \c memcmp is risky
1056 * because the time taken by the comparison may leak information
1057 * about the hashed data which could allow an attacker to guess
1058 * a valid hash and thereby bypass security controls.
1059 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001060 * \param[in,out] operation Active hash operation.
1061 * \param[out] hash Buffer where the hash is to be written.
1062 * \param hash_size Size of the \p hash buffer in bytes.
1063 * \param[out] hash_length On success, the number of bytes
1064 * that make up the hash value. This is always
Gilles Peskinebe42f312018-07-13 14:38:15 +02001065 * #PSA_HASH_SIZE(\c alg) where \c alg is the
Gilles Peskineedd11a12018-07-12 01:08:58 +02001066 * hash algorithm that is calculated.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001067 *
Gilles Peskine28538492018-07-11 17:34:00 +02001068 * \retval #PSA_SUCCESS
Gilles Peskine308b91d2018-02-08 09:47:44 +01001069 * Success.
Gilles Peskine28538492018-07-11 17:34:00 +02001070 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001071 * The operation state is not valid (not set up, or already completed).
Gilles Peskine28538492018-07-11 17:34:00 +02001072 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001073 * The size of the \p hash buffer is too small. You can determine a
Gilles Peskine7256e6c2018-07-12 00:34:26 +02001074 * sufficient buffer size by calling #PSA_HASH_SIZE(\c alg)
Gilles Peskine308b91d2018-02-08 09:47:44 +01001075 * where \c alg is the hash algorithm that is calculated.
Gilles Peskine28538492018-07-11 17:34:00 +02001076 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1077 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1078 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001079 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001080 * \retval #PSA_ERROR_BAD_STATE
Adrian L. Shaw320659b2019-08-08 14:49:01 +01001081 * The operation state is not valid.
1082 * \retval #PSA_ERROR_BAD_STATE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001083 * The library has not been previously initialized by psa_crypto_init().
1084 * It is implementation-dependent whether a failure to initialize
1085 * results in this error code.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001086 */
Gilles Peskine9ef733f2018-02-07 21:05:37 +01001087psa_status_t psa_hash_finish(psa_hash_operation_t *operation,
1088 uint8_t *hash,
1089 size_t hash_size,
1090 size_t *hash_length);
1091
Gilles Peskine308b91d2018-02-08 09:47:44 +01001092/** Finish the calculation of the hash of a message and compare it with
1093 * an expected value.
1094 *
Gilles Peskineda8191d1c2018-07-08 19:46:38 +02001095 * The application must call psa_hash_setup() before calling this function.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001096 * This function calculates the hash of the message formed by concatenating
1097 * the inputs passed to preceding calls to psa_hash_update(). It then
1098 * compares the calculated hash with the expected hash passed as a
1099 * parameter to this function.
1100 *
1101 * When this function returns, the operation becomes inactive.
1102 *
Gilles Peskine19067982018-03-20 17:54:53 +01001103 * \note Implementations shall make the best effort to ensure that the
Gilles Peskine308b91d2018-02-08 09:47:44 +01001104 * comparison between the actual hash and the expected hash is performed
1105 * in constant time.
1106 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001107 * \param[in,out] operation Active hash operation.
1108 * \param[in] hash Buffer containing the expected hash value.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001109 * \param hash_length Size of the \p hash buffer in bytes.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001110 *
Gilles Peskine28538492018-07-11 17:34:00 +02001111 * \retval #PSA_SUCCESS
Gilles Peskine308b91d2018-02-08 09:47:44 +01001112 * The expected hash is identical to the actual hash of the message.
Gilles Peskine28538492018-07-11 17:34:00 +02001113 * \retval #PSA_ERROR_INVALID_SIGNATURE
Gilles Peskine308b91d2018-02-08 09:47:44 +01001114 * The hash of the message was calculated successfully, but it
1115 * differs from the expected hash.
Gilles Peskine28538492018-07-11 17:34:00 +02001116 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001117 * The operation state is not valid (not set up, or already completed).
Gilles Peskine28538492018-07-11 17:34:00 +02001118 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1119 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1120 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001121 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001122 * \retval #PSA_ERROR_BAD_STATE
Adrian L. Shaw320659b2019-08-08 14:49:01 +01001123 * The operation state is not valid.
1124 * \retval #PSA_ERROR_BAD_STATE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001125 * The library has not been previously initialized by psa_crypto_init().
1126 * It is implementation-dependent whether a failure to initialize
1127 * results in this error code.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001128 */
Gilles Peskine9ef733f2018-02-07 21:05:37 +01001129psa_status_t psa_hash_verify(psa_hash_operation_t *operation,
1130 const uint8_t *hash,
1131 size_t hash_length);
1132
Gilles Peskine308b91d2018-02-08 09:47:44 +01001133/** Abort a hash operation.
1134 *
Gilles Peskine308b91d2018-02-08 09:47:44 +01001135 * Aborting an operation frees all associated resources except for the
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001136 * \p operation structure itself. Once aborted, the operation object
1137 * can be reused for another operation by calling
1138 * psa_hash_setup() again.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001139 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001140 * You may call this function any time after the operation object has
1141 * been initialized by any of the following methods:
1142 * - A call to psa_hash_setup(), whether it succeeds or not.
1143 * - Initializing the \c struct to all-bits-zero.
1144 * - Initializing the \c struct to logical zeros, e.g.
1145 * `psa_hash_operation_t operation = {0}`.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001146 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001147 * In particular, calling psa_hash_abort() after the operation has been
1148 * terminated by a call to psa_hash_abort(), psa_hash_finish() or
1149 * psa_hash_verify() is safe and has no effect.
1150 *
1151 * \param[in,out] operation Initialized hash operation.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001152 *
Gilles Peskine28538492018-07-11 17:34:00 +02001153 * \retval #PSA_SUCCESS
1154 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001155 * \p operation is not an active hash operation.
Gilles Peskine28538492018-07-11 17:34:00 +02001156 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1157 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001158 * \retval #PSA_ERROR_CORRUPTION_DETECTED
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 not valid.
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 Peskine308b91d2018-02-08 09:47:44 +01001165 */
1166psa_status_t psa_hash_abort(psa_hash_operation_t *operation);
Gilles Peskine9ef733f2018-02-07 21:05:37 +01001167
Gilles Peskineebb2c3e2019-01-19 12:03:41 +01001168/** Clone a hash operation.
1169 *
Gilles Peskinee43aa392019-01-21 14:50:37 +01001170 * This function copies the state of an ongoing hash operation to
1171 * a new operation object. In other words, this function is equivalent
1172 * to calling psa_hash_setup() on \p target_operation with the same
1173 * algorithm that \p source_operation was set up for, then
1174 * psa_hash_update() on \p target_operation with the same input that
1175 * that was passed to \p source_operation. After this function returns, the
1176 * two objects are independent, i.e. subsequent calls involving one of
1177 * the objects do not affect the other object.
1178 *
Gilles Peskineebb2c3e2019-01-19 12:03:41 +01001179 * \param[in] source_operation The active hash operation to clone.
1180 * \param[in,out] target_operation The operation object to set up.
1181 * It must be initialized but not active.
1182 *
1183 * \retval #PSA_SUCCESS
1184 * \retval #PSA_ERROR_BAD_STATE
1185 * \p source_operation is not an active hash operation.
1186 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinee43aa392019-01-21 14:50:37 +01001187 * \p target_operation is active.
Gilles Peskineebb2c3e2019-01-19 12:03:41 +01001188 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1189 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001190 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawd789dc12019-08-12 15:06:48 +01001191 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001192 * \retval #PSA_ERROR_BAD_STATE
Adrian L. Shaw320659b2019-08-08 14:49:01 +01001193 * The operation state is either not initialized or has already been setup.
1194 * \retval #PSA_ERROR_BAD_STATE
Adrian L. Shaw8f7cd1e2019-08-08 14:49:01 +01001195 * The operation state is either not initialized or has already been setup.
1196 * \retval #PSA_ERROR_BAD_STATE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001197 * The library has not been previously initialized by psa_crypto_init().
1198 * It is implementation-dependent whether a failure to initialize
1199 * results in this error code.
Gilles Peskineebb2c3e2019-01-19 12:03:41 +01001200 */
1201psa_status_t psa_hash_clone(const psa_hash_operation_t *source_operation,
1202 psa_hash_operation_t *target_operation);
1203
Gilles Peskine9ef733f2018-02-07 21:05:37 +01001204/**@}*/
1205
Gilles Peskine8c9def32018-02-08 10:02:12 +01001206/** \defgroup MAC Message authentication codes
1207 * @{
1208 */
1209
Gilles Peskine69647a42019-01-14 20:18:12 +01001210/** Calculate the MAC (message authentication code) of a message.
1211 *
1212 * \note To verify the MAC of a message against an
1213 * expected value, use psa_mac_verify() instead.
1214 * Beware that comparing integrity or authenticity data such as
1215 * MAC values with a function such as \c memcmp is risky
1216 * because the time taken by the comparison may leak information
1217 * about the MAC value which could allow an attacker to guess
1218 * a valid MAC and thereby bypass security controls.
1219 *
1220 * \param handle Handle to the key to use for the operation.
1221 * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
Gilles Peskine63f79302019-02-15 13:01:17 +01001222 * such that #PSA_ALG_IS_MAC(\p alg) is true).
Gilles Peskine69647a42019-01-14 20:18:12 +01001223 * \param[in] input Buffer containing the input message.
1224 * \param input_length Size of the \p input buffer in bytes.
1225 * \param[out] mac Buffer where the MAC value is to be written.
1226 * \param mac_size Size of the \p mac buffer in bytes.
1227 * \param[out] mac_length On success, the number of bytes
Gilles Peskined338b912019-02-15 13:01:41 +01001228 * that make up the MAC value.
Gilles Peskine69647a42019-01-14 20:18:12 +01001229 *
1230 * \retval #PSA_SUCCESS
1231 * Success.
1232 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine69647a42019-01-14 20:18:12 +01001233 * \retval #PSA_ERROR_NOT_PERMITTED
1234 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001235 * \p handle is not compatible with \p alg.
Gilles Peskine69647a42019-01-14 20:18:12 +01001236 * \retval #PSA_ERROR_NOT_SUPPORTED
1237 * \p alg is not supported or is not a MAC algorithm.
Adrian L. Shawd5ae06b2019-08-07 15:59:33 +01001238 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
1239 * \p mac_size is too small
Gilles Peskine69647a42019-01-14 20:18:12 +01001240 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1241 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1242 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001243 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawfa591c42019-08-07 10:47:47 +01001244 * \retval #PSA_ERROR_STORAGE_FAILURE
1245 * The key could not be retrieved from storage.
Gilles Peskine69647a42019-01-14 20:18:12 +01001246 * \retval #PSA_ERROR_BAD_STATE
1247 * The library has not been previously initialized by psa_crypto_init().
1248 * It is implementation-dependent whether a failure to initialize
1249 * results in this error code.
1250 */
1251psa_status_t psa_mac_compute(psa_key_handle_t handle,
1252 psa_algorithm_t alg,
1253 const uint8_t *input,
1254 size_t input_length,
1255 uint8_t *mac,
1256 size_t mac_size,
1257 size_t *mac_length);
1258
1259/** Calculate the MAC of a message and compare it with a reference value.
1260 *
1261 * \param handle Handle to the key to use for the operation.
1262 * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
Gilles Peskine63f79302019-02-15 13:01:17 +01001263 * such that #PSA_ALG_IS_MAC(\p alg) is true).
Gilles Peskine69647a42019-01-14 20:18:12 +01001264 * \param[in] input Buffer containing the input message.
1265 * \param input_length Size of the \p input buffer in bytes.
1266 * \param[out] mac Buffer containing the expected MAC value.
1267 * \param mac_length Size of the \p mac buffer in bytes.
1268 *
1269 * \retval #PSA_SUCCESS
1270 * The expected MAC is identical to the actual MAC of the input.
1271 * \retval #PSA_ERROR_INVALID_SIGNATURE
1272 * The MAC of the message was calculated successfully, but it
1273 * differs from the expected value.
1274 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine69647a42019-01-14 20:18:12 +01001275 * \retval #PSA_ERROR_NOT_PERMITTED
1276 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001277 * \p handle is not compatible with \p alg.
Gilles Peskine69647a42019-01-14 20:18:12 +01001278 * \retval #PSA_ERROR_NOT_SUPPORTED
1279 * \p alg is not supported or is not a MAC algorithm.
1280 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1281 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1282 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001283 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001284 * \retval #PSA_ERROR_STORAGE_FAILURE
1285 * The key could not be retrieved from storage.
1286 * \retval #PSA_ERROR_BAD_STATE
1287 * The library has not been previously initialized by psa_crypto_init().
1288 * It is implementation-dependent whether a failure to initialize
1289 * results in this error code.
Gilles Peskine69647a42019-01-14 20:18:12 +01001290 */
Gilles Peskinea05602d2019-01-17 15:25:52 +01001291psa_status_t psa_mac_verify(psa_key_handle_t handle,
1292 psa_algorithm_t alg,
Gilles Peskine69647a42019-01-14 20:18:12 +01001293 const uint8_t *input,
1294 size_t input_length,
1295 const uint8_t *mac,
1296 const size_t mac_length);
1297
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001298/** The type of the state data structure for multipart MAC operations.
1299 *
Jaeden Amero769ce272019-01-04 11:48:03 +00001300 * Before calling any function on a MAC operation object, the application must
1301 * initialize it by any of the following means:
1302 * - Set the structure to all-bits-zero, for example:
1303 * \code
1304 * psa_mac_operation_t operation;
1305 * memset(&operation, 0, sizeof(operation));
1306 * \endcode
1307 * - Initialize the structure to logical zero values, for example:
1308 * \code
1309 * psa_mac_operation_t operation = {0};
1310 * \endcode
1311 * - Initialize the structure to the initializer #PSA_MAC_OPERATION_INIT,
1312 * for example:
1313 * \code
1314 * psa_mac_operation_t operation = PSA_MAC_OPERATION_INIT;
1315 * \endcode
1316 * - Assign the result of the function psa_mac_operation_init()
1317 * to the structure, for example:
1318 * \code
1319 * psa_mac_operation_t operation;
1320 * operation = psa_mac_operation_init();
1321 * \endcode
1322 *
Gilles Peskine92b30732018-03-03 21:29:30 +01001323 * This is an implementation-defined \c struct. Applications should not
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001324 * make any assumptions about the content of this structure except
1325 * as directed by the documentation of a specific implementation. */
Gilles Peskine8c9def32018-02-08 10:02:12 +01001326typedef struct psa_mac_operation_s psa_mac_operation_t;
1327
Jaeden Amero769ce272019-01-04 11:48:03 +00001328/** \def PSA_MAC_OPERATION_INIT
1329 *
1330 * This macro returns a suitable initializer for a MAC operation object of type
1331 * #psa_mac_operation_t.
1332 */
1333#ifdef __DOXYGEN_ONLY__
1334/* This is an example definition for documentation purposes.
1335 * Implementations should define a suitable value in `crypto_struct.h`.
1336 */
1337#define PSA_MAC_OPERATION_INIT {0}
1338#endif
1339
1340/** Return an initial value for a MAC operation object.
1341 */
1342static psa_mac_operation_t psa_mac_operation_init(void);
1343
Gilles Peskinef45adda2019-01-14 18:29:18 +01001344/** Set up a multipart MAC calculation operation.
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001345 *
Gilles Peskine89167cb2018-07-08 20:12:23 +02001346 * This function sets up the calculation of the MAC
1347 * (message authentication code) of a byte string.
1348 * To verify the MAC of a message against an
1349 * expected value, use psa_mac_verify_setup() instead.
1350 *
1351 * The sequence of operations to calculate a MAC is as follows:
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001352 * -# Allocate an operation object which will be passed to all the functions
1353 * listed here.
Jaeden Amero769ce272019-01-04 11:48:03 +00001354 * -# Initialize the operation object with one of the methods described in the
1355 * documentation for #psa_mac_operation_t, e.g. PSA_MAC_OPERATION_INIT.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001356 * -# Call psa_mac_sign_setup() to specify the algorithm and key.
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001357 * -# Call psa_mac_update() zero, one or more times, passing a fragment
1358 * of the message each time. The MAC that is calculated is the MAC
1359 * of the concatenation of these messages in order.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001360 * -# At the end of the message, call psa_mac_sign_finish() to finish
1361 * calculating the MAC value and retrieve it.
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001362 *
1363 * The application may call psa_mac_abort() at any time after the operation
Jaeden Amero769ce272019-01-04 11:48:03 +00001364 * has been initialized.
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001365 *
Gilles Peskine89167cb2018-07-08 20:12:23 +02001366 * After a successful call to psa_mac_sign_setup(), the application must
1367 * eventually terminate the operation through one of the following methods:
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001368 * - A failed call to psa_mac_update().
Gilles Peskine89167cb2018-07-08 20:12:23 +02001369 * - A call to psa_mac_sign_finish() or psa_mac_abort().
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001370 *
Jaeden Amero769ce272019-01-04 11:48:03 +00001371 * \param[in,out] operation The operation object to set up. It must have
1372 * been initialized as per the documentation for
1373 * #psa_mac_operation_t and not yet in use.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001374 * \param handle Handle to the key to use for the operation.
Gilles Peskine5f25dd02019-01-14 18:24:53 +01001375 * It must remain valid until the operation
1376 * terminates.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001377 * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
Gilles Peskine63f79302019-02-15 13:01:17 +01001378 * such that #PSA_ALG_IS_MAC(\p alg) is true).
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001379 *
Gilles Peskine28538492018-07-11 17:34:00 +02001380 * \retval #PSA_SUCCESS
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001381 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001382 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine28538492018-07-11 17:34:00 +02001383 * \retval #PSA_ERROR_NOT_PERMITTED
1384 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001385 * \p handle is not compatible with \p alg.
Gilles Peskine28538492018-07-11 17:34:00 +02001386 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001387 * \p alg is not supported or is not a MAC algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02001388 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1389 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1390 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001391 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw2409ba02019-08-07 16:05:06 +01001392 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdf3c7ac2019-08-12 16:43:30 +01001393 * The key could not be retrieved from storage.
itayzafrir90d8c7a2018-09-12 11:44:52 +03001394 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskine8e1addc2019-01-10 11:51:17 +01001395 * The operation state is not valid (already set up and not
1396 * subsequently completed).
1397 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03001398 * The library has not been previously initialized by psa_crypto_init().
1399 * It is implementation-dependent whether a failure to initialize
1400 * results in this error code.
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001401 */
Gilles Peskine89167cb2018-07-08 20:12:23 +02001402psa_status_t psa_mac_sign_setup(psa_mac_operation_t *operation,
Gilles Peskineae32aac2018-11-30 14:39:32 +01001403 psa_key_handle_t handle,
Gilles Peskine89167cb2018-07-08 20:12:23 +02001404 psa_algorithm_t alg);
1405
Gilles Peskinef45adda2019-01-14 18:29:18 +01001406/** Set up a multipart MAC verification operation.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001407 *
1408 * This function sets up the verification of the MAC
1409 * (message authentication code) of a byte string against an expected value.
1410 *
1411 * The sequence of operations to verify a MAC is as follows:
1412 * -# Allocate an operation object which will be passed to all the functions
1413 * listed here.
Jaeden Amero769ce272019-01-04 11:48:03 +00001414 * -# Initialize the operation object with one of the methods described in the
1415 * documentation for #psa_mac_operation_t, e.g. PSA_MAC_OPERATION_INIT.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001416 * -# Call psa_mac_verify_setup() to specify the algorithm and key.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001417 * -# Call psa_mac_update() zero, one or more times, passing a fragment
1418 * of the message each time. The MAC that is calculated is the MAC
1419 * of the concatenation of these messages in order.
1420 * -# At the end of the message, call psa_mac_verify_finish() to finish
1421 * calculating the actual MAC of the message and verify it against
1422 * the expected value.
1423 *
1424 * The application may call psa_mac_abort() at any time after the operation
Jaeden Amero769ce272019-01-04 11:48:03 +00001425 * has been initialized.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001426 *
1427 * After a successful call to psa_mac_verify_setup(), the application must
1428 * eventually terminate the operation through one of the following methods:
1429 * - A failed call to psa_mac_update().
1430 * - A call to psa_mac_verify_finish() or psa_mac_abort().
1431 *
Jaeden Amero769ce272019-01-04 11:48:03 +00001432 * \param[in,out] operation The operation object to set up. It must have
1433 * been initialized as per the documentation for
1434 * #psa_mac_operation_t and not yet in use.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001435 * \param handle Handle to the key to use for the operation.
Gilles Peskine5f25dd02019-01-14 18:24:53 +01001436 * It must remain valid until the operation
1437 * terminates.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001438 * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
1439 * such that #PSA_ALG_IS_MAC(\p alg) is true).
Gilles Peskine89167cb2018-07-08 20:12:23 +02001440 *
Gilles Peskine28538492018-07-11 17:34:00 +02001441 * \retval #PSA_SUCCESS
Gilles Peskine89167cb2018-07-08 20:12:23 +02001442 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001443 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine28538492018-07-11 17:34:00 +02001444 * \retval #PSA_ERROR_NOT_PERMITTED
1445 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine89167cb2018-07-08 20:12:23 +02001446 * \c key is not compatible with \c alg.
Gilles Peskine28538492018-07-11 17:34:00 +02001447 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskine89167cb2018-07-08 20:12:23 +02001448 * \c alg is not supported or is not a MAC algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02001449 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1450 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1451 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001452 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw9770d0e2019-08-07 16:18:18 +01001453 * \retval #PSA_ERROR_STORAGE_FAILURE
1454 * The key could not be retrieved from storage
itayzafrir90d8c7a2018-09-12 11:44:52 +03001455 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskine8e1addc2019-01-10 11:51:17 +01001456 * The operation state is not valid (already set up and not
1457 * subsequently completed).
1458 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03001459 * The library has not been previously initialized by psa_crypto_init().
1460 * It is implementation-dependent whether a failure to initialize
1461 * results in this error code.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001462 */
1463psa_status_t psa_mac_verify_setup(psa_mac_operation_t *operation,
Gilles Peskineae32aac2018-11-30 14:39:32 +01001464 psa_key_handle_t handle,
Gilles Peskine89167cb2018-07-08 20:12:23 +02001465 psa_algorithm_t alg);
Gilles Peskine8c9def32018-02-08 10:02:12 +01001466
Gilles Peskinedcd14942018-07-12 00:30:52 +02001467/** Add a message fragment to a multipart MAC operation.
1468 *
1469 * The application must call psa_mac_sign_setup() or psa_mac_verify_setup()
1470 * before calling this function.
1471 *
1472 * If this function returns an error status, the operation becomes inactive.
1473 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001474 * \param[in,out] operation Active MAC operation.
1475 * \param[in] input Buffer containing the message fragment to add to
1476 * the MAC calculation.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001477 * \param input_length Size of the \p input buffer in bytes.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001478 *
1479 * \retval #PSA_SUCCESS
1480 * Success.
1481 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001482 * The operation state is not valid (not set up, or already completed).
Gilles Peskinedcd14942018-07-12 00:30:52 +02001483 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1484 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1485 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001486 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawd789dc12019-08-12 15:06:48 +01001487 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001488 * \retval #PSA_ERROR_BAD_STATE
1489 * The library has not been previously initialized by psa_crypto_init().
1490 * It is implementation-dependent whether a failure to initialize
1491 * results in this error code.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001492 */
Gilles Peskine8c9def32018-02-08 10:02:12 +01001493psa_status_t psa_mac_update(psa_mac_operation_t *operation,
1494 const uint8_t *input,
1495 size_t input_length);
1496
Gilles Peskinedcd14942018-07-12 00:30:52 +02001497/** Finish the calculation of the MAC of a message.
1498 *
1499 * The application must call psa_mac_sign_setup() before calling this function.
1500 * This function calculates the MAC of the message formed by concatenating
1501 * the inputs passed to preceding calls to psa_mac_update().
1502 *
1503 * When this function returns, the operation becomes inactive.
1504 *
1505 * \warning Applications should not call this function if they expect
1506 * a specific value for the MAC. Call psa_mac_verify_finish() instead.
1507 * Beware that comparing integrity or authenticity data such as
1508 * MAC values with a function such as \c memcmp is risky
1509 * because the time taken by the comparison may leak information
1510 * about the MAC value which could allow an attacker to guess
1511 * a valid MAC and thereby bypass security controls.
1512 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001513 * \param[in,out] operation Active MAC operation.
1514 * \param[out] mac Buffer where the MAC value is to be written.
1515 * \param mac_size Size of the \p mac buffer in bytes.
1516 * \param[out] mac_length On success, the number of bytes
1517 * that make up the MAC value. This is always
Gilles Peskinedda3bd32018-07-12 19:40:46 +02001518 * #PSA_MAC_FINAL_SIZE(\c key_type, \c key_bits, \c alg)
Gilles Peskineedd11a12018-07-12 01:08:58 +02001519 * where \c key_type and \c key_bits are the type and
Gilles Peskinedda3bd32018-07-12 19:40:46 +02001520 * bit-size respectively of the key and \c alg is the
Gilles Peskineedd11a12018-07-12 01:08:58 +02001521 * MAC algorithm that is calculated.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001522 *
1523 * \retval #PSA_SUCCESS
1524 * Success.
1525 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001526 * The operation state is not valid (not set up, or already completed).
Gilles Peskinedcd14942018-07-12 00:30:52 +02001527 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001528 * The size of the \p mac buffer is too small. You can determine a
Gilles Peskinedcd14942018-07-12 00:30:52 +02001529 * sufficient buffer size by calling PSA_MAC_FINAL_SIZE().
1530 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1531 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1532 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001533 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw26322362019-08-13 11:43:40 +01001534 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001535 * \retval #PSA_ERROR_BAD_STATE
1536 * The library has not been previously initialized by psa_crypto_init().
1537 * It is implementation-dependent whether a failure to initialize
1538 * results in this error code.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001539 */
Gilles Peskineacd4be32018-07-08 19:56:25 +02001540psa_status_t psa_mac_sign_finish(psa_mac_operation_t *operation,
1541 uint8_t *mac,
1542 size_t mac_size,
1543 size_t *mac_length);
Gilles Peskine8c9def32018-02-08 10:02:12 +01001544
Gilles Peskinedcd14942018-07-12 00:30:52 +02001545/** Finish the calculation of the MAC of a message and compare it with
1546 * an expected value.
1547 *
1548 * The application must call psa_mac_verify_setup() before calling this function.
1549 * This function calculates the MAC of the message formed by concatenating
1550 * the inputs passed to preceding calls to psa_mac_update(). It then
1551 * compares the calculated MAC with the expected MAC passed as a
1552 * parameter to this function.
1553 *
1554 * When this function returns, the operation becomes inactive.
1555 *
1556 * \note Implementations shall make the best effort to ensure that the
1557 * comparison between the actual MAC and the expected MAC is performed
1558 * in constant time.
1559 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001560 * \param[in,out] operation Active MAC operation.
1561 * \param[in] mac Buffer containing the expected MAC value.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001562 * \param mac_length Size of the \p mac buffer in bytes.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001563 *
1564 * \retval #PSA_SUCCESS
1565 * The expected MAC is identical to the actual MAC of the message.
1566 * \retval #PSA_ERROR_INVALID_SIGNATURE
1567 * The MAC of the message was calculated successfully, but it
1568 * differs from the expected MAC.
1569 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001570 * The operation state is not valid (not set up, or already completed).
Gilles Peskinedcd14942018-07-12 00:30:52 +02001571 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1572 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1573 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001574 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawd9e90242019-08-13 11:44:30 +01001575 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001576 * \retval #PSA_ERROR_BAD_STATE
1577 * The library has not been previously initialized by psa_crypto_init().
1578 * It is implementation-dependent whether a failure to initialize
1579 * results in this error code.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001580 */
Gilles Peskineacd4be32018-07-08 19:56:25 +02001581psa_status_t psa_mac_verify_finish(psa_mac_operation_t *operation,
1582 const uint8_t *mac,
1583 size_t mac_length);
Gilles Peskine8c9def32018-02-08 10:02:12 +01001584
Gilles Peskinedcd14942018-07-12 00:30:52 +02001585/** Abort a MAC operation.
1586 *
Gilles Peskinedcd14942018-07-12 00:30:52 +02001587 * Aborting an operation frees all associated resources except for the
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001588 * \p operation structure itself. Once aborted, the operation object
1589 * can be reused for another operation by calling
1590 * psa_mac_sign_setup() or psa_mac_verify_setup() again.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001591 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001592 * You may call this function any time after the operation object has
1593 * been initialized by any of the following methods:
1594 * - A call to psa_mac_sign_setup() or psa_mac_verify_setup(), whether
1595 * it succeeds or not.
1596 * - Initializing the \c struct to all-bits-zero.
1597 * - Initializing the \c struct to logical zeros, e.g.
1598 * `psa_mac_operation_t operation = {0}`.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001599 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001600 * In particular, calling psa_mac_abort() after the operation has been
1601 * terminated by a call to psa_mac_abort(), psa_mac_sign_finish() or
1602 * psa_mac_verify_finish() is safe and has no effect.
1603 *
1604 * \param[in,out] operation Initialized MAC operation.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001605 *
1606 * \retval #PSA_SUCCESS
1607 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001608 * \p operation is not an active MAC operation.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001609 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1610 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001611 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001612 * \retval #PSA_ERROR_BAD_STATE
1613 * The library has not been previously initialized by psa_crypto_init().
1614 * It is implementation-dependent whether a failure to initialize
1615 * results in this error code.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001616 */
Gilles Peskine8c9def32018-02-08 10:02:12 +01001617psa_status_t psa_mac_abort(psa_mac_operation_t *operation);
1618
1619/**@}*/
1620
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001621/** \defgroup cipher Symmetric ciphers
1622 * @{
1623 */
1624
Gilles Peskine69647a42019-01-14 20:18:12 +01001625/** Encrypt a message using a symmetric cipher.
1626 *
1627 * This function encrypts a message with a random IV (initialization
1628 * vector).
1629 *
1630 * \param handle Handle to the key to use for the operation.
1631 * It must remain valid until the operation
1632 * terminates.
1633 * \param alg The cipher algorithm to compute
1634 * (\c PSA_ALG_XXX value such that
1635 * #PSA_ALG_IS_CIPHER(\p alg) is true).
1636 * \param[in] input Buffer containing the message to encrypt.
1637 * \param input_length Size of the \p input buffer in bytes.
1638 * \param[out] output Buffer where the output is to be written.
1639 * The output contains the IV followed by
1640 * the ciphertext proper.
1641 * \param output_size Size of the \p output buffer in bytes.
1642 * \param[out] output_length On success, the number of bytes
1643 * that make up the output.
1644 *
1645 * \retval #PSA_SUCCESS
1646 * Success.
1647 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine69647a42019-01-14 20:18:12 +01001648 * \retval #PSA_ERROR_NOT_PERMITTED
1649 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001650 * \p handle is not compatible with \p alg.
Gilles Peskine69647a42019-01-14 20:18:12 +01001651 * \retval #PSA_ERROR_NOT_SUPPORTED
1652 * \p alg is not supported or is not a cipher algorithm.
1653 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
1654 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1655 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1656 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001657 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawa3f6ba52019-08-08 14:51:49 +01001658 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001659 * \retval #PSA_ERROR_BAD_STATE
1660 * The library has not been previously initialized by psa_crypto_init().
1661 * It is implementation-dependent whether a failure to initialize
1662 * results in this error code.
Gilles Peskine69647a42019-01-14 20:18:12 +01001663 */
1664psa_status_t psa_cipher_encrypt(psa_key_handle_t handle,
1665 psa_algorithm_t alg,
1666 const uint8_t *input,
1667 size_t input_length,
1668 uint8_t *output,
1669 size_t output_size,
1670 size_t *output_length);
1671
1672/** Decrypt a message using a symmetric cipher.
1673 *
1674 * This function decrypts a message encrypted with a symmetric cipher.
1675 *
1676 * \param handle Handle to the key to use for the operation.
1677 * It must remain valid until the operation
1678 * terminates.
1679 * \param alg The cipher algorithm to compute
1680 * (\c PSA_ALG_XXX value such that
1681 * #PSA_ALG_IS_CIPHER(\p alg) is true).
1682 * \param[in] input Buffer containing the message to decrypt.
1683 * This consists of the IV followed by the
1684 * ciphertext proper.
1685 * \param input_length Size of the \p input buffer in bytes.
1686 * \param[out] output Buffer where the plaintext is to be written.
1687 * \param output_size Size of the \p output buffer in bytes.
1688 * \param[out] output_length On success, the number of bytes
1689 * that make up the output.
1690 *
1691 * \retval #PSA_SUCCESS
1692 * Success.
1693 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine69647a42019-01-14 20:18:12 +01001694 * \retval #PSA_ERROR_NOT_PERMITTED
1695 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001696 * \p handle is not compatible with \p alg.
Gilles Peskine69647a42019-01-14 20:18:12 +01001697 * \retval #PSA_ERROR_NOT_SUPPORTED
1698 * \p alg is not supported or is not a cipher algorithm.
1699 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
1700 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1701 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1702 * \retval #PSA_ERROR_HARDWARE_FAILURE
Adrian L. Shawa3f6ba52019-08-08 14:51:49 +01001703 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shaw39797aa2019-08-23 16:17:43 +01001704 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001705 * \retval #PSA_ERROR_BAD_STATE
1706 * The library has not been previously initialized by psa_crypto_init().
1707 * It is implementation-dependent whether a failure to initialize
Adrian L. Shaw23c006f2019-08-06 16:02:12 +01001708 * results in this error code.
Gilles Peskine69647a42019-01-14 20:18:12 +01001709 */
1710psa_status_t psa_cipher_decrypt(psa_key_handle_t handle,
1711 psa_algorithm_t alg,
1712 const uint8_t *input,
1713 size_t input_length,
1714 uint8_t *output,
1715 size_t output_size,
1716 size_t *output_length);
1717
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001718/** The type of the state data structure for multipart cipher operations.
1719 *
Jaeden Amero5bae2272019-01-04 11:48:27 +00001720 * Before calling any function on a cipher operation object, the application
1721 * must initialize it by any of the following means:
1722 * - Set the structure to all-bits-zero, for example:
1723 * \code
1724 * psa_cipher_operation_t operation;
1725 * memset(&operation, 0, sizeof(operation));
1726 * \endcode
1727 * - Initialize the structure to logical zero values, for example:
1728 * \code
1729 * psa_cipher_operation_t operation = {0};
1730 * \endcode
1731 * - Initialize the structure to the initializer #PSA_CIPHER_OPERATION_INIT,
1732 * for example:
1733 * \code
1734 * psa_cipher_operation_t operation = PSA_CIPHER_OPERATION_INIT;
1735 * \endcode
1736 * - Assign the result of the function psa_cipher_operation_init()
1737 * to the structure, for example:
1738 * \code
1739 * psa_cipher_operation_t operation;
1740 * operation = psa_cipher_operation_init();
1741 * \endcode
1742 *
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001743 * This is an implementation-defined \c struct. Applications should not
1744 * make any assumptions about the content of this structure except
1745 * as directed by the documentation of a specific implementation. */
1746typedef struct psa_cipher_operation_s psa_cipher_operation_t;
1747
Jaeden Amero5bae2272019-01-04 11:48:27 +00001748/** \def PSA_CIPHER_OPERATION_INIT
1749 *
1750 * This macro returns a suitable initializer for a cipher operation object of
1751 * type #psa_cipher_operation_t.
1752 */
1753#ifdef __DOXYGEN_ONLY__
1754/* This is an example definition for documentation purposes.
1755 * Implementations should define a suitable value in `crypto_struct.h`.
1756 */
1757#define PSA_CIPHER_OPERATION_INIT {0}
1758#endif
1759
1760/** Return an initial value for a cipher operation object.
1761 */
1762static psa_cipher_operation_t psa_cipher_operation_init(void);
1763
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001764/** Set the key for a multipart symmetric encryption operation.
1765 *
1766 * The sequence of operations to encrypt a message with a symmetric cipher
1767 * is as follows:
1768 * -# Allocate an operation object which will be passed to all the functions
1769 * listed here.
Jaeden Amero5bae2272019-01-04 11:48:27 +00001770 * -# Initialize the operation object with one of the methods described in the
1771 * documentation for #psa_cipher_operation_t, e.g.
1772 * PSA_CIPHER_OPERATION_INIT.
Gilles Peskinefe119512018-07-08 21:39:34 +02001773 * -# Call psa_cipher_encrypt_setup() to specify the algorithm and key.
itayzafrired7382f2018-08-02 14:19:33 +03001774 * -# Call either psa_cipher_generate_iv() or psa_cipher_set_iv() to
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001775 * generate or set the IV (initialization vector). You should use
itayzafrired7382f2018-08-02 14:19:33 +03001776 * psa_cipher_generate_iv() unless the protocol you are implementing
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001777 * requires a specific IV value.
1778 * -# Call psa_cipher_update() zero, one or more times, passing a fragment
1779 * of the message each time.
1780 * -# Call psa_cipher_finish().
1781 *
1782 * The application may call psa_cipher_abort() at any time after the operation
Jaeden Amero5bae2272019-01-04 11:48:27 +00001783 * has been initialized.
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001784 *
Gilles Peskinefe119512018-07-08 21:39:34 +02001785 * After a successful call to psa_cipher_encrypt_setup(), the application must
Gilles Peskineed522972018-03-20 17:54:15 +01001786 * eventually terminate the operation. The following events terminate an
1787 * operation:
Gilles Peskinef45adda2019-01-14 18:29:18 +01001788 * - A failed call to any of the \c psa_cipher_xxx functions.
Gilles Peskine19067982018-03-20 17:54:53 +01001789 * - A call to psa_cipher_finish() or psa_cipher_abort().
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001790 *
Jaeden Amero5bae2272019-01-04 11:48:27 +00001791 * \param[in,out] operation The operation object to set up. It must have
1792 * been initialized as per the documentation for
1793 * #psa_cipher_operation_t and not yet in use.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001794 * \param handle Handle to the key to use for the operation.
Gilles Peskine5f25dd02019-01-14 18:24:53 +01001795 * It must remain valid until the operation
1796 * terminates.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001797 * \param alg The cipher algorithm to compute
1798 * (\c PSA_ALG_XXX value such that
1799 * #PSA_ALG_IS_CIPHER(\p alg) is true).
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001800 *
Gilles Peskine28538492018-07-11 17:34:00 +02001801 * \retval #PSA_SUCCESS
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001802 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001803 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine28538492018-07-11 17:34:00 +02001804 * \retval #PSA_ERROR_NOT_PERMITTED
1805 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001806 * \p handle is not compatible with \p alg.
Gilles Peskine28538492018-07-11 17:34:00 +02001807 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001808 * \p alg is not supported or is not a cipher algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02001809 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1810 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1811 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001812 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdc5bf5c2019-08-13 11:46:09 +01001813 * \retval #PSA_ERROR_STORAGE_FAILURE
itayzafrir90d8c7a2018-09-12 11:44:52 +03001814 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskine8e1addc2019-01-10 11:51:17 +01001815 * The operation state is not valid (already set up and not
1816 * subsequently completed).
1817 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03001818 * The library has not been previously initialized by psa_crypto_init().
1819 * It is implementation-dependent whether a failure to initialize
1820 * results in this error code.
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001821 */
Gilles Peskinefe119512018-07-08 21:39:34 +02001822psa_status_t psa_cipher_encrypt_setup(psa_cipher_operation_t *operation,
Gilles Peskineae32aac2018-11-30 14:39:32 +01001823 psa_key_handle_t handle,
Gilles Peskinefe119512018-07-08 21:39:34 +02001824 psa_algorithm_t alg);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001825
1826/** Set the key for a multipart symmetric decryption operation.
1827 *
1828 * The sequence of operations to decrypt a message with a symmetric cipher
1829 * is as follows:
1830 * -# Allocate an operation object which will be passed to all the functions
1831 * listed here.
Jaeden Amero5bae2272019-01-04 11:48:27 +00001832 * -# Initialize the operation object with one of the methods described in the
1833 * documentation for #psa_cipher_operation_t, e.g.
1834 * PSA_CIPHER_OPERATION_INIT.
Gilles Peskinefe119512018-07-08 21:39:34 +02001835 * -# Call psa_cipher_decrypt_setup() to specify the algorithm and key.
Gilles Peskinef45adda2019-01-14 18:29:18 +01001836 * -# Call psa_cipher_set_iv() with the IV (initialization vector) for the
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001837 * decryption. If the IV is prepended to the ciphertext, you can call
1838 * psa_cipher_update() on a buffer containing the IV followed by the
1839 * beginning of the message.
1840 * -# Call psa_cipher_update() zero, one or more times, passing a fragment
1841 * of the message each time.
1842 * -# Call psa_cipher_finish().
1843 *
1844 * The application may call psa_cipher_abort() at any time after the operation
Jaeden Amero5bae2272019-01-04 11:48:27 +00001845 * has been initialized.
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001846 *
Gilles Peskinefe119512018-07-08 21:39:34 +02001847 * After a successful call to psa_cipher_decrypt_setup(), the application must
Gilles Peskineed522972018-03-20 17:54:15 +01001848 * eventually terminate the operation. The following events terminate an
1849 * operation:
Gilles Peskinef45adda2019-01-14 18:29:18 +01001850 * - A failed call to any of the \c psa_cipher_xxx functions.
Gilles Peskine19067982018-03-20 17:54:53 +01001851 * - A call to psa_cipher_finish() or psa_cipher_abort().
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001852 *
Jaeden Amero5bae2272019-01-04 11:48:27 +00001853 * \param[in,out] operation The operation object to set up. It must have
1854 * been initialized as per the documentation for
1855 * #psa_cipher_operation_t and not yet in use.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001856 * \param handle Handle to the key to use for the operation.
Gilles Peskine5f25dd02019-01-14 18:24:53 +01001857 * It must remain valid until the operation
1858 * terminates.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001859 * \param alg The cipher algorithm to compute
1860 * (\c PSA_ALG_XXX value such that
1861 * #PSA_ALG_IS_CIPHER(\p alg) is true).
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001862 *
Gilles Peskine28538492018-07-11 17:34:00 +02001863 * \retval #PSA_SUCCESS
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001864 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001865 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine28538492018-07-11 17:34:00 +02001866 * \retval #PSA_ERROR_NOT_PERMITTED
1867 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001868 * \p handle is not compatible with \p alg.
Gilles Peskine28538492018-07-11 17:34:00 +02001869 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001870 * \p alg is not supported or is not a cipher algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02001871 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1872 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1873 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001874 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdc5bf5c2019-08-13 11:46:09 +01001875 * \retval #PSA_ERROR_STORAGE_FAILURE
itayzafrir90d8c7a2018-09-12 11:44:52 +03001876 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskine8e1addc2019-01-10 11:51:17 +01001877 * The operation state is not valid (already set up and not
1878 * subsequently completed).
1879 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03001880 * The library has not been previously initialized by psa_crypto_init().
1881 * It is implementation-dependent whether a failure to initialize
1882 * results in this error code.
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001883 */
Gilles Peskinefe119512018-07-08 21:39:34 +02001884psa_status_t psa_cipher_decrypt_setup(psa_cipher_operation_t *operation,
Gilles Peskineae32aac2018-11-30 14:39:32 +01001885 psa_key_handle_t handle,
Gilles Peskinefe119512018-07-08 21:39:34 +02001886 psa_algorithm_t alg);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001887
Gilles Peskinedcd14942018-07-12 00:30:52 +02001888/** Generate an IV for a symmetric encryption operation.
1889 *
1890 * This function generates a random IV (initialization vector), nonce
1891 * or initial counter value for the encryption operation as appropriate
1892 * for the chosen algorithm, key type and key size.
1893 *
1894 * The application must call psa_cipher_encrypt_setup() before
1895 * calling this function.
1896 *
1897 * If this function returns an error status, the operation becomes inactive.
1898 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001899 * \param[in,out] operation Active cipher operation.
1900 * \param[out] iv Buffer where the generated IV is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001901 * \param iv_size Size of the \p iv buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001902 * \param[out] iv_length On success, the number of bytes of the
1903 * generated IV.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001904 *
1905 * \retval #PSA_SUCCESS
1906 * Success.
1907 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001908 * The operation state is not valid (not set up, or IV already set).
Gilles Peskinedcd14942018-07-12 00:30:52 +02001909 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinedda3bd32018-07-12 19:40:46 +02001910 * The size of the \p iv buffer is too small.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001911 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1912 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1913 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001914 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw66200c42019-08-15 13:30:57 +01001915 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001916 * \retval #PSA_ERROR_BAD_STATE
1917 * The library has not been previously initialized by psa_crypto_init().
1918 * It is implementation-dependent whether a failure to initialize
1919 * results in this error code.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001920 */
Gilles Peskinefe119512018-07-08 21:39:34 +02001921psa_status_t psa_cipher_generate_iv(psa_cipher_operation_t *operation,
Andrew Thoelke47629d02019-03-22 11:24:17 +00001922 uint8_t *iv,
Gilles Peskinefe119512018-07-08 21:39:34 +02001923 size_t iv_size,
1924 size_t *iv_length);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001925
Gilles Peskinedcd14942018-07-12 00:30:52 +02001926/** Set the IV for a symmetric encryption or decryption operation.
1927 *
Gilles Peskinef45adda2019-01-14 18:29:18 +01001928 * This function sets the IV (initialization vector), nonce
Gilles Peskinedcd14942018-07-12 00:30:52 +02001929 * or initial counter value for the encryption or decryption operation.
1930 *
1931 * The application must call psa_cipher_encrypt_setup() before
1932 * calling this function.
1933 *
1934 * If this function returns an error status, the operation becomes inactive.
1935 *
1936 * \note When encrypting, applications should use psa_cipher_generate_iv()
1937 * instead of this function, unless implementing a protocol that requires
1938 * a non-random IV.
1939 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001940 * \param[in,out] operation Active cipher operation.
1941 * \param[in] iv Buffer containing the IV to use.
1942 * \param iv_length Size of the IV in bytes.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001943 *
1944 * \retval #PSA_SUCCESS
1945 * Success.
1946 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001947 * The operation state is not valid (not set up, or IV already set).
Gilles Peskinedcd14942018-07-12 00:30:52 +02001948 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001949 * The size of \p iv is not acceptable for the chosen algorithm,
Gilles Peskinedcd14942018-07-12 00:30:52 +02001950 * or the chosen algorithm does not use an IV.
1951 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1952 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1953 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001954 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw56b32b12019-08-13 11:43:40 +01001955 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001956 * \retval #PSA_ERROR_BAD_STATE
1957 * The library has not been previously initialized by psa_crypto_init().
1958 * It is implementation-dependent whether a failure to initialize
1959 * results in this error code.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001960 */
Gilles Peskinefe119512018-07-08 21:39:34 +02001961psa_status_t psa_cipher_set_iv(psa_cipher_operation_t *operation,
Andrew Thoelke47629d02019-03-22 11:24:17 +00001962 const uint8_t *iv,
Gilles Peskinefe119512018-07-08 21:39:34 +02001963 size_t iv_length);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001964
Gilles Peskinedcd14942018-07-12 00:30:52 +02001965/** Encrypt or decrypt a message fragment in an active cipher operation.
1966 *
Gilles Peskine9ac94262018-07-12 20:15:32 +02001967 * Before calling this function, you must:
1968 * 1. Call either psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup().
1969 * The choice of setup function determines whether this function
1970 * encrypts or decrypts its input.
1971 * 2. If the algorithm requires an IV, call psa_cipher_generate_iv()
1972 * (recommended when encrypting) or psa_cipher_set_iv().
Gilles Peskinedcd14942018-07-12 00:30:52 +02001973 *
1974 * If this function returns an error status, the operation becomes inactive.
1975 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001976 * \param[in,out] operation Active cipher operation.
1977 * \param[in] input Buffer containing the message fragment to
1978 * encrypt or decrypt.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001979 * \param input_length Size of the \p input buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001980 * \param[out] output Buffer where the output is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001981 * \param output_size Size of the \p output buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001982 * \param[out] output_length On success, the number of bytes
1983 * that make up the returned output.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001984 *
1985 * \retval #PSA_SUCCESS
1986 * Success.
1987 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001988 * The operation state is not valid (not set up, IV required but
Gilles Peskinedcd14942018-07-12 00:30:52 +02001989 * not set, or already completed).
1990 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
1991 * The size of the \p output buffer is too small.
1992 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1993 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1994 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001995 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw484ba882019-08-13 14:41:52 +01001996 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01001997 * \retval #PSA_ERROR_BAD_STATE
1998 * The library has not been previously initialized by psa_crypto_init().
1999 * It is implementation-dependent whether a failure to initialize
2000 * results in this error code.
Gilles Peskinedcd14942018-07-12 00:30:52 +02002001 */
Gilles Peskine428dc5a2018-03-03 21:27:18 +01002002psa_status_t psa_cipher_update(psa_cipher_operation_t *operation,
2003 const uint8_t *input,
mohammad1603503973b2018-03-12 15:59:30 +02002004 size_t input_length,
Andrew Thoelke47629d02019-03-22 11:24:17 +00002005 uint8_t *output,
Gilles Peskine2d277862018-06-18 15:41:12 +02002006 size_t output_size,
mohammad1603503973b2018-03-12 15:59:30 +02002007 size_t *output_length);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01002008
Gilles Peskinedcd14942018-07-12 00:30:52 +02002009/** Finish encrypting or decrypting a message in a cipher operation.
2010 *
2011 * The application must call psa_cipher_encrypt_setup() or
2012 * psa_cipher_decrypt_setup() before calling this function. The choice
2013 * of setup function determines whether this function encrypts or
2014 * decrypts its input.
2015 *
2016 * This function finishes the encryption or decryption of the message
2017 * formed by concatenating the inputs passed to preceding calls to
2018 * psa_cipher_update().
2019 *
2020 * When this function returns, the operation becomes inactive.
2021 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02002022 * \param[in,out] operation Active cipher operation.
2023 * \param[out] output Buffer where the output is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002024 * \param output_size Size of the \p output buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002025 * \param[out] output_length On success, the number of bytes
2026 * that make up the returned output.
Gilles Peskinedcd14942018-07-12 00:30:52 +02002027 *
2028 * \retval #PSA_SUCCESS
2029 * Success.
Gilles Peskinebe061332019-07-18 13:52:30 +02002030 * \retval #PSA_ERROR_INVALID_ARGUMENT
2031 * The total input size passed to this operation is not valid for
2032 * this particular algorithm. For example, the algorithm is a based
2033 * on block cipher and requires a whole number of blocks, but the
2034 * total input size is not a multiple of the block size.
2035 * \retval #PSA_ERROR_INVALID_PADDING
2036 * This is a decryption operation for an algorithm that includes
2037 * padding, and the ciphertext does not contain valid padding.
Gilles Peskinedcd14942018-07-12 00:30:52 +02002038 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01002039 * The operation state is not valid (not set up, IV required but
Gilles Peskinedcd14942018-07-12 00:30:52 +02002040 * not set, or already completed).
2041 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
2042 * The size of the \p output buffer is too small.
2043 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2044 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2045 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002046 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw1f1e1a52019-08-13 11:44:30 +01002047 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01002048 * \retval #PSA_ERROR_BAD_STATE
2049 * The library has not been previously initialized by psa_crypto_init().
2050 * It is implementation-dependent whether a failure to initialize
2051 * results in this error code.
Gilles Peskinedcd14942018-07-12 00:30:52 +02002052 */
Gilles Peskine428dc5a2018-03-03 21:27:18 +01002053psa_status_t psa_cipher_finish(psa_cipher_operation_t *operation,
mohammad1603503973b2018-03-12 15:59:30 +02002054 uint8_t *output,
Moran Peker0071b872018-04-22 20:16:58 +03002055 size_t output_size,
mohammad1603503973b2018-03-12 15:59:30 +02002056 size_t *output_length);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01002057
Gilles Peskinedcd14942018-07-12 00:30:52 +02002058/** Abort a cipher operation.
2059 *
Gilles Peskinedcd14942018-07-12 00:30:52 +02002060 * Aborting an operation frees all associated resources except for the
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02002061 * \p operation structure itself. Once aborted, the operation object
2062 * can be reused for another operation by calling
2063 * psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup() again.
Gilles Peskinedcd14942018-07-12 00:30:52 +02002064 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02002065 * You may call this function any time after the operation object has
2066 * been initialized by any of the following methods:
2067 * - A call to psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup(),
2068 * whether it succeeds or not.
2069 * - Initializing the \c struct to all-bits-zero.
2070 * - Initializing the \c struct to logical zeros, e.g.
2071 * `psa_cipher_operation_t operation = {0}`.
Gilles Peskinedcd14942018-07-12 00:30:52 +02002072 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02002073 * In particular, calling psa_cipher_abort() after the operation has been
2074 * terminated by a call to psa_cipher_abort() or psa_cipher_finish()
2075 * is safe and has no effect.
2076 *
2077 * \param[in,out] operation Initialized cipher operation.
Gilles Peskinedcd14942018-07-12 00:30:52 +02002078 *
2079 * \retval #PSA_SUCCESS
2080 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002081 * \p operation is not an active cipher operation.
Gilles Peskinedcd14942018-07-12 00:30:52 +02002082 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2083 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002084 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01002085 * \retval #PSA_ERROR_BAD_STATE
2086 * The library has not been previously initialized by psa_crypto_init().
2087 * It is implementation-dependent whether a failure to initialize
2088 * results in this error code.
Gilles Peskinedcd14942018-07-12 00:30:52 +02002089 */
Gilles Peskine428dc5a2018-03-03 21:27:18 +01002090psa_status_t psa_cipher_abort(psa_cipher_operation_t *operation);
2091
2092/**@}*/
2093
Gilles Peskine3b555712018-03-03 21:27:57 +01002094/** \defgroup aead Authenticated encryption with associated data (AEAD)
2095 * @{
2096 */
2097
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002098/** Process an authenticated encryption operation.
Gilles Peskine3b555712018-03-03 21:27:57 +01002099 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01002100 * \param handle Handle to the key to use for the operation.
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002101 * \param alg The AEAD algorithm to compute
2102 * (\c PSA_ALG_XXX value such that
Gilles Peskine7256e6c2018-07-12 00:34:26 +02002103 * #PSA_ALG_IS_AEAD(\p alg) is true).
Gilles Peskineedd11a12018-07-12 01:08:58 +02002104 * \param[in] nonce Nonce or IV to use.
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002105 * \param nonce_length Size of the \p nonce buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002106 * \param[in] additional_data Additional data that will be authenticated
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002107 * but not encrypted.
2108 * \param additional_data_length Size of \p additional_data in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002109 * \param[in] plaintext Data that will be authenticated and
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002110 * encrypted.
2111 * \param plaintext_length Size of \p plaintext in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002112 * \param[out] ciphertext Output buffer for the authenticated and
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002113 * encrypted data. The additional data is not
2114 * part of this output. For algorithms where the
2115 * encrypted data and the authentication tag
2116 * are defined as separate outputs, the
2117 * authentication tag is appended to the
2118 * encrypted data.
2119 * \param ciphertext_size Size of the \p ciphertext buffer in bytes.
2120 * This must be at least
2121 * #PSA_AEAD_ENCRYPT_OUTPUT_SIZE(\p alg,
2122 * \p plaintext_length).
Gilles Peskineedd11a12018-07-12 01:08:58 +02002123 * \param[out] ciphertext_length On success, the size of the output
Gilles Peskine4c6fdbb2019-02-08 11:22:39 +01002124 * in the \p ciphertext buffer.
Gilles Peskine3b555712018-03-03 21:27:57 +01002125 *
Gilles Peskine28538492018-07-11 17:34:00 +02002126 * \retval #PSA_SUCCESS
Gilles Peskine3b555712018-03-03 21:27:57 +01002127 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01002128 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine28538492018-07-11 17:34:00 +02002129 * \retval #PSA_ERROR_NOT_PERMITTED
2130 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002131 * \p handle is not compatible with \p alg.
Gilles Peskine28538492018-07-11 17:34:00 +02002132 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002133 * \p alg is not supported or is not an AEAD algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02002134 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
Adrian L. Shaw484ba882019-08-13 14:41:52 +01002135 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
2136 * \p ciphertext_size is too small
Gilles Peskine28538492018-07-11 17:34:00 +02002137 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2138 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002139 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw22bc8ff2019-08-08 15:10:33 +01002140 * \retval #PSA_ERROR_STORAGE_FAILURE
itayzafrir90d8c7a2018-09-12 11:44:52 +03002141 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03002142 * The library has not been previously initialized by psa_crypto_init().
2143 * It is implementation-dependent whether a failure to initialize
2144 * results in this error code.
Gilles Peskine3b555712018-03-03 21:27:57 +01002145 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01002146psa_status_t psa_aead_encrypt(psa_key_handle_t handle,
Gilles Peskine9fb0e012018-07-19 15:51:49 +02002147 psa_algorithm_t alg,
2148 const uint8_t *nonce,
2149 size_t nonce_length,
2150 const uint8_t *additional_data,
2151 size_t additional_data_length,
2152 const uint8_t *plaintext,
2153 size_t plaintext_length,
2154 uint8_t *ciphertext,
2155 size_t ciphertext_size,
2156 size_t *ciphertext_length);
Gilles Peskine3b555712018-03-03 21:27:57 +01002157
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002158/** Process an authenticated decryption operation.
Gilles Peskine3b555712018-03-03 21:27:57 +01002159 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01002160 * \param handle Handle to the key to use for the operation.
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002161 * \param alg The AEAD algorithm to compute
2162 * (\c PSA_ALG_XXX value such that
Gilles Peskine7256e6c2018-07-12 00:34:26 +02002163 * #PSA_ALG_IS_AEAD(\p alg) is true).
Gilles Peskineedd11a12018-07-12 01:08:58 +02002164 * \param[in] nonce Nonce or IV to use.
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002165 * \param nonce_length Size of the \p nonce buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002166 * \param[in] additional_data Additional data that has been authenticated
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002167 * but not encrypted.
2168 * \param additional_data_length Size of \p additional_data in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002169 * \param[in] ciphertext Data that has been authenticated and
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002170 * encrypted. For algorithms where the
2171 * encrypted data and the authentication tag
2172 * are defined as separate inputs, the buffer
2173 * must contain the encrypted data followed
2174 * by the authentication tag.
2175 * \param ciphertext_length Size of \p ciphertext in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002176 * \param[out] plaintext Output buffer for the decrypted data.
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002177 * \param plaintext_size Size of the \p plaintext buffer in bytes.
2178 * This must be at least
2179 * #PSA_AEAD_DECRYPT_OUTPUT_SIZE(\p alg,
2180 * \p ciphertext_length).
Gilles Peskineedd11a12018-07-12 01:08:58 +02002181 * \param[out] plaintext_length On success, the size of the output
Gilles Peskine4c6fdbb2019-02-08 11:22:39 +01002182 * in the \p plaintext buffer.
Gilles Peskine3b555712018-03-03 21:27:57 +01002183 *
Gilles Peskine28538492018-07-11 17:34:00 +02002184 * \retval #PSA_SUCCESS
Gilles Peskine3b555712018-03-03 21:27:57 +01002185 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01002186 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine28538492018-07-11 17:34:00 +02002187 * \retval #PSA_ERROR_INVALID_SIGNATURE
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002188 * The ciphertext is not authentic.
Gilles Peskine28538492018-07-11 17:34:00 +02002189 * \retval #PSA_ERROR_NOT_PERMITTED
2190 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002191 * \p handle is not compatible with \p alg.
Gilles Peskine28538492018-07-11 17:34:00 +02002192 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002193 * \p alg is not supported or is not an AEAD algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02002194 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
Adrian L. Shawc207ba32019-08-08 10:55:38 +01002195 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
2196 * \p plaintext_size or \p nonce_length is too small
Gilles Peskine28538492018-07-11 17:34:00 +02002197 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2198 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002199 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawc207ba32019-08-08 10:55:38 +01002200 * \retval #PSA_ERROR_STORAGE_FAILURE
itayzafrir90d8c7a2018-09-12 11:44:52 +03002201 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03002202 * The library has not been previously initialized by psa_crypto_init().
2203 * It is implementation-dependent whether a failure to initialize
2204 * results in this error code.
Gilles Peskine3b555712018-03-03 21:27:57 +01002205 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01002206psa_status_t psa_aead_decrypt(psa_key_handle_t handle,
Gilles Peskine9fb0e012018-07-19 15:51:49 +02002207 psa_algorithm_t alg,
2208 const uint8_t *nonce,
2209 size_t nonce_length,
2210 const uint8_t *additional_data,
2211 size_t additional_data_length,
2212 const uint8_t *ciphertext,
2213 size_t ciphertext_length,
2214 uint8_t *plaintext,
2215 size_t plaintext_size,
2216 size_t *plaintext_length);
Gilles Peskine3b555712018-03-03 21:27:57 +01002217
Gilles Peskine30a9e412019-01-14 18:36:12 +01002218/** The type of the state data structure for multipart AEAD operations.
2219 *
2220 * Before calling any function on an AEAD operation object, the application
2221 * must initialize it by any of the following means:
2222 * - Set the structure to all-bits-zero, for example:
2223 * \code
2224 * psa_aead_operation_t operation;
2225 * memset(&operation, 0, sizeof(operation));
2226 * \endcode
2227 * - Initialize the structure to logical zero values, for example:
2228 * \code
2229 * psa_aead_operation_t operation = {0};
2230 * \endcode
2231 * - Initialize the structure to the initializer #PSA_AEAD_OPERATION_INIT,
2232 * for example:
2233 * \code
2234 * psa_aead_operation_t operation = PSA_AEAD_OPERATION_INIT;
2235 * \endcode
2236 * - Assign the result of the function psa_aead_operation_init()
2237 * to the structure, for example:
2238 * \code
2239 * psa_aead_operation_t operation;
2240 * operation = psa_aead_operation_init();
2241 * \endcode
2242 *
2243 * This is an implementation-defined \c struct. Applications should not
2244 * make any assumptions about the content of this structure except
2245 * as directed by the documentation of a specific implementation. */
2246typedef struct psa_aead_operation_s psa_aead_operation_t;
2247
2248/** \def PSA_AEAD_OPERATION_INIT
2249 *
2250 * This macro returns a suitable initializer for an AEAD operation object of
2251 * type #psa_aead_operation_t.
2252 */
2253#ifdef __DOXYGEN_ONLY__
2254/* This is an example definition for documentation purposes.
2255 * Implementations should define a suitable value in `crypto_struct.h`.
2256 */
2257#define PSA_AEAD_OPERATION_INIT {0}
2258#endif
2259
2260/** Return an initial value for an AEAD operation object.
2261 */
2262static psa_aead_operation_t psa_aead_operation_init(void);
2263
2264/** Set the key for a multipart authenticated encryption operation.
2265 *
2266 * The sequence of operations to encrypt a message with authentication
2267 * is as follows:
2268 * -# Allocate an operation object which will be passed to all the functions
2269 * listed here.
2270 * -# Initialize the operation object with one of the methods described in the
2271 * documentation for #psa_aead_operation_t, e.g.
2272 * PSA_AEAD_OPERATION_INIT.
2273 * -# Call psa_aead_encrypt_setup() to specify the algorithm and key.
Gilles Peskinebc59c852019-01-17 15:26:08 +01002274 * -# If needed, call psa_aead_set_lengths() to specify the length of the
2275 * inputs to the subsequent calls to psa_aead_update_ad() and
2276 * psa_aead_update(). See the documentation of psa_aead_set_lengths()
2277 * for details.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002278 * -# Call either psa_aead_generate_nonce() or psa_aead_set_nonce() to
2279 * generate or set the nonce. You should use
2280 * psa_aead_generate_nonce() unless the protocol you are implementing
2281 * requires a specific nonce value.
2282 * -# Call psa_aead_update_ad() zero, one or more times, passing a fragment
2283 * of the non-encrypted additional authenticated data each time.
2284 * -# Call psa_aead_update() zero, one or more times, passing a fragment
Gilles Peskinea05602d2019-01-17 15:25:52 +01002285 * of the message to encrypt each time.
Adrian L. Shaw599c7122019-08-15 10:53:47 +01002286 * -# Call psa_aead_finish().
Gilles Peskine30a9e412019-01-14 18:36:12 +01002287 *
2288 * The application may call psa_aead_abort() at any time after the operation
2289 * has been initialized.
2290 *
2291 * After a successful call to psa_aead_encrypt_setup(), the application must
2292 * eventually terminate the operation. The following events terminate an
2293 * operation:
2294 * - A failed call to any of the \c psa_aead_xxx functions.
2295 * - A call to psa_aead_finish(), psa_aead_verify() or psa_aead_abort().
2296 *
2297 * \param[in,out] operation The operation object to set up. It must have
2298 * been initialized as per the documentation for
2299 * #psa_aead_operation_t and not yet in use.
2300 * \param handle Handle to the key to use for the operation.
2301 * It must remain valid until the operation
2302 * terminates.
2303 * \param alg The AEAD algorithm to compute
2304 * (\c PSA_ALG_XXX value such that
2305 * #PSA_ALG_IS_AEAD(\p alg) is true).
2306 *
2307 * \retval #PSA_SUCCESS
2308 * Success.
2309 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine30a9e412019-01-14 18:36:12 +01002310 * \retval #PSA_ERROR_NOT_PERMITTED
2311 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002312 * \p handle is not compatible with \p alg.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002313 * \retval #PSA_ERROR_NOT_SUPPORTED
2314 * \p alg is not supported or is not an AEAD algorithm.
2315 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2316 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2317 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002318 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw3e412492019-08-08 15:10:33 +01002319 * \retval #PSA_ERROR_STORAGE_FAILURE
Gilles Peskine30a9e412019-01-14 18:36:12 +01002320 * \retval #PSA_ERROR_BAD_STATE
2321 * The library has not been previously initialized by psa_crypto_init().
2322 * It is implementation-dependent whether a failure to initialize
2323 * results in this error code.
2324 */
2325psa_status_t psa_aead_encrypt_setup(psa_aead_operation_t *operation,
2326 psa_key_handle_t handle,
2327 psa_algorithm_t alg);
2328
2329/** Set the key for a multipart authenticated decryption operation.
2330 *
2331 * The sequence of operations to decrypt a message with authentication
2332 * is as follows:
2333 * -# Allocate an operation object which will be passed to all the functions
2334 * listed here.
2335 * -# Initialize the operation object with one of the methods described in the
2336 * documentation for #psa_aead_operation_t, e.g.
2337 * PSA_AEAD_OPERATION_INIT.
2338 * -# Call psa_aead_decrypt_setup() to specify the algorithm and key.
Gilles Peskinebc59c852019-01-17 15:26:08 +01002339 * -# If needed, call psa_aead_set_lengths() to specify the length of the
2340 * inputs to the subsequent calls to psa_aead_update_ad() and
2341 * psa_aead_update(). See the documentation of psa_aead_set_lengths()
2342 * for details.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002343 * -# Call psa_aead_set_nonce() with the nonce for the decryption.
2344 * -# Call psa_aead_update_ad() zero, one or more times, passing a fragment
2345 * of the non-encrypted additional authenticated data each time.
2346 * -# Call psa_aead_update() zero, one or more times, passing a fragment
Gilles Peskinea05602d2019-01-17 15:25:52 +01002347 * of the ciphertext to decrypt each time.
2348 * -# Call psa_aead_verify().
Gilles Peskine30a9e412019-01-14 18:36:12 +01002349 *
2350 * The application may call psa_aead_abort() at any time after the operation
2351 * has been initialized.
2352 *
2353 * After a successful call to psa_aead_decrypt_setup(), the application must
2354 * eventually terminate the operation. The following events terminate an
2355 * operation:
2356 * - A failed call to any of the \c psa_aead_xxx functions.
2357 * - A call to psa_aead_finish(), psa_aead_verify() or psa_aead_abort().
2358 *
2359 * \param[in,out] operation The operation object to set up. It must have
2360 * been initialized as per the documentation for
2361 * #psa_aead_operation_t and not yet in use.
2362 * \param handle Handle to the key to use for the operation.
2363 * It must remain valid until the operation
2364 * terminates.
2365 * \param alg The AEAD algorithm to compute
2366 * (\c PSA_ALG_XXX value such that
2367 * #PSA_ALG_IS_AEAD(\p alg) is true).
2368 *
2369 * \retval #PSA_SUCCESS
2370 * Success.
2371 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine30a9e412019-01-14 18:36:12 +01002372 * \retval #PSA_ERROR_NOT_PERMITTED
2373 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002374 * \p handle is not compatible with \p alg.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002375 * \retval #PSA_ERROR_NOT_SUPPORTED
2376 * \p alg is not supported or is not an AEAD algorithm.
2377 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2378 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2379 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002380 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw3e412492019-08-08 15:10:33 +01002381 * \retval #PSA_ERROR_STORAGE_FAILURE
Gilles Peskine30a9e412019-01-14 18:36:12 +01002382 * \retval #PSA_ERROR_BAD_STATE
2383 * The library has not been previously initialized by psa_crypto_init().
2384 * It is implementation-dependent whether a failure to initialize
2385 * results in this error code.
2386 */
2387psa_status_t psa_aead_decrypt_setup(psa_aead_operation_t *operation,
2388 psa_key_handle_t handle,
2389 psa_algorithm_t alg);
2390
2391/** Generate a random nonce for an authenticated encryption operation.
2392 *
2393 * This function generates a random nonce for the authenticated encryption
2394 * operation with an appropriate size for the chosen algorithm, key type
2395 * and key size.
2396 *
2397 * The application must call psa_aead_encrypt_setup() before
2398 * calling this function.
2399 *
2400 * If this function returns an error status, the operation becomes inactive.
2401 *
2402 * \param[in,out] operation Active AEAD operation.
2403 * \param[out] nonce Buffer where the generated nonce is to be
2404 * written.
2405 * \param nonce_size Size of the \p nonce buffer in bytes.
2406 * \param[out] nonce_length On success, the number of bytes of the
2407 * generated nonce.
2408 *
2409 * \retval #PSA_SUCCESS
2410 * Success.
2411 * \retval #PSA_ERROR_BAD_STATE
2412 * The operation state is not valid (not set up, or nonce already set).
2413 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
2414 * The size of the \p nonce buffer is too small.
2415 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2416 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2417 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002418 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw484ba882019-08-13 14:41:52 +01002419 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01002420 * \retval #PSA_ERROR_BAD_STATE
2421 * The library has not been previously initialized by psa_crypto_init().
2422 * It is implementation-dependent whether a failure to initialize
2423 * results in this error code.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002424 */
2425psa_status_t psa_aead_generate_nonce(psa_aead_operation_t *operation,
Andrew Thoelked16bdac2019-05-15 12:34:01 +01002426 uint8_t *nonce,
Gilles Peskine30a9e412019-01-14 18:36:12 +01002427 size_t nonce_size,
2428 size_t *nonce_length);
2429
2430/** Set the nonce for an authenticated encryption or decryption operation.
2431 *
2432 * This function sets the nonce for the authenticated
2433 * encryption or decryption operation.
2434 *
2435 * The application must call psa_aead_encrypt_setup() before
2436 * calling this function.
2437 *
2438 * If this function returns an error status, the operation becomes inactive.
2439 *
Gilles Peskinea05602d2019-01-17 15:25:52 +01002440 * \note When encrypting, applications should use psa_aead_generate_nonce()
Gilles Peskine30a9e412019-01-14 18:36:12 +01002441 * instead of this function, unless implementing a protocol that requires
2442 * a non-random IV.
2443 *
2444 * \param[in,out] operation Active AEAD operation.
Gilles Peskinea05602d2019-01-17 15:25:52 +01002445 * \param[in] nonce Buffer containing the nonce to use.
2446 * \param nonce_length Size of the nonce in bytes.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002447 *
2448 * \retval #PSA_SUCCESS
2449 * Success.
2450 * \retval #PSA_ERROR_BAD_STATE
2451 * The operation state is not valid (not set up, or nonce already set).
2452 * \retval #PSA_ERROR_INVALID_ARGUMENT
2453 * The size of \p nonce is not acceptable for the chosen algorithm.
2454 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2455 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2456 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002457 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw484ba882019-08-13 14:41:52 +01002458 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01002459 * \retval #PSA_ERROR_BAD_STATE
2460 * The library has not been previously initialized by psa_crypto_init().
2461 * It is implementation-dependent whether a failure to initialize
2462 * results in this error code.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002463 */
2464psa_status_t psa_aead_set_nonce(psa_aead_operation_t *operation,
Andrew Thoelked16bdac2019-05-15 12:34:01 +01002465 const uint8_t *nonce,
Gilles Peskine30a9e412019-01-14 18:36:12 +01002466 size_t nonce_length);
2467
Gilles Peskinebc59c852019-01-17 15:26:08 +01002468/** Declare the lengths of the message and additional data for AEAD.
2469 *
2470 * The application must call this function before calling
2471 * psa_aead_update_ad() or psa_aead_update() if the algorithm for
2472 * the operation requires it. If the algorithm does not require it,
2473 * calling this function is optional, but if this function is called
2474 * then the implementation must enforce the lengths.
2475 *
2476 * You may call this function before or after setting the nonce with
2477 * psa_aead_set_nonce() or psa_aead_generate_nonce().
2478 *
2479 * - For #PSA_ALG_CCM, calling this function is required.
2480 * - For the other AEAD algorithms defined in this specification, calling
2481 * this function is not required.
2482 * - For vendor-defined algorithm, refer to the vendor documentation.
2483 *
2484 * \param[in,out] operation Active AEAD operation.
2485 * \param ad_length Size of the non-encrypted additional
2486 * authenticated data in bytes.
2487 * \param plaintext_length Size of the plaintext to encrypt in bytes.
2488 *
2489 * \retval #PSA_SUCCESS
2490 * Success.
2491 * \retval #PSA_ERROR_BAD_STATE
2492 * The operation state is not valid (not set up, already completed,
2493 * or psa_aead_update_ad() or psa_aead_update() already called).
2494 * \retval #PSA_ERROR_INVALID_ARGUMENT
2495 * At least one of the lengths is not acceptable for the chosen
2496 * algorithm.
2497 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2498 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2499 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002500 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01002501 * \retval #PSA_ERROR_BAD_STATE
2502 * The library has not been previously initialized by psa_crypto_init().
2503 * It is implementation-dependent whether a failure to initialize
2504 * results in this error code.
Gilles Peskinebc59c852019-01-17 15:26:08 +01002505 */
2506psa_status_t psa_aead_set_lengths(psa_aead_operation_t *operation,
2507 size_t ad_length,
2508 size_t plaintext_length);
2509
Gilles Peskine30a9e412019-01-14 18:36:12 +01002510/** Pass additional data to an active AEAD operation.
2511 *
2512 * Additional data is authenticated, but not encrypted.
2513 *
2514 * You may call this function multiple times to pass successive fragments
2515 * of the additional data. You may not call this function after passing
2516 * data to encrypt or decrypt with psa_aead_update().
2517 *
2518 * Before calling this function, you must:
2519 * 1. Call either psa_aead_encrypt_setup() or psa_aead_decrypt_setup().
2520 * 2. Set the nonce with psa_aead_generate_nonce() or psa_aead_set_nonce().
2521 *
2522 * If this function returns an error status, the operation becomes inactive.
2523 *
2524 * \warning When decrypting, until psa_aead_verify() has returned #PSA_SUCCESS,
2525 * there is no guarantee that the input is valid. Therefore, until
2526 * you have called psa_aead_verify() and it has returned #PSA_SUCCESS,
2527 * treat the input as untrusted and prepare to undo any action that
2528 * depends on the input if psa_aead_verify() returns an error status.
2529 *
2530 * \param[in,out] operation Active AEAD operation.
2531 * \param[in] input Buffer containing the fragment of
2532 * additional data.
2533 * \param input_length Size of the \p input buffer in bytes.
2534 *
2535 * \retval #PSA_SUCCESS
2536 * Success.
2537 * \retval #PSA_ERROR_BAD_STATE
2538 * The operation state is not valid (not set up, nonce not set,
2539 * psa_aead_update() already called, or operation already completed).
Gilles Peskinebc59c852019-01-17 15:26:08 +01002540 * \retval #PSA_ERROR_INVALID_ARGUMENT
2541 * The total input length overflows the additional data length that
2542 * was previously specified with psa_aead_set_lengths().
Gilles Peskine30a9e412019-01-14 18:36:12 +01002543 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2544 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2545 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002546 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw484ba882019-08-13 14:41:52 +01002547 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01002548 * \retval #PSA_ERROR_BAD_STATE
2549 * The library has not been previously initialized by psa_crypto_init().
2550 * It is implementation-dependent whether a failure to initialize
2551 * results in this error code.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002552 */
2553psa_status_t psa_aead_update_ad(psa_aead_operation_t *operation,
2554 const uint8_t *input,
2555 size_t input_length);
2556
2557/** Encrypt or decrypt a message fragment in an active AEAD operation.
2558 *
2559 * Before calling this function, you must:
2560 * 1. Call either psa_aead_encrypt_setup() or psa_aead_decrypt_setup().
2561 * The choice of setup function determines whether this function
2562 * encrypts or decrypts its input.
2563 * 2. Set the nonce with psa_aead_generate_nonce() or psa_aead_set_nonce().
2564 * 3. Call psa_aead_update_ad() to pass all the additional data.
2565 *
2566 * If this function returns an error status, the operation becomes inactive.
2567 *
2568 * \warning When decrypting, until psa_aead_verify() has returned #PSA_SUCCESS,
2569 * there is no guarantee that the input is valid. Therefore, until
2570 * you have called psa_aead_verify() and it has returned #PSA_SUCCESS:
2571 * - Do not use the output in any way other than storing it in a
2572 * confidential location. If you take any action that depends
2573 * on the tentative decrypted data, this action will need to be
2574 * undone if the input turns out not to be valid. Furthermore,
2575 * if an adversary can observe that this action took place
2576 * (for example through timing), they may be able to use this
2577 * fact as an oracle to decrypt any message encrypted with the
2578 * same key.
2579 * - In particular, do not copy the output anywhere but to a
2580 * memory or storage space that you have exclusive access to.
2581 *
Gilles Peskinef02aec92019-05-06 15:42:54 +02002582 * This function does not require the input to be aligned to any
2583 * particular block boundary. If the implementation can only process
Gilles Peskineac99e322019-05-14 16:10:53 +02002584 * a whole block at a time, it must consume all the input provided, but
2585 * it may delay the end of the corresponding output until a subsequent
2586 * call to psa_aead_update(), psa_aead_finish() or psa_aead_verify()
2587 * provides sufficient input. The amount of data that can be delayed
2588 * in this way is bounded by #PSA_AEAD_UPDATE_OUTPUT_SIZE.
Gilles Peskinef02aec92019-05-06 15:42:54 +02002589 *
Gilles Peskine30a9e412019-01-14 18:36:12 +01002590 * \param[in,out] operation Active AEAD operation.
2591 * \param[in] input Buffer containing the message fragment to
2592 * encrypt or decrypt.
2593 * \param input_length Size of the \p input buffer in bytes.
2594 * \param[out] output Buffer where the output is to be written.
2595 * \param output_size Size of the \p output buffer in bytes.
Gilles Peskine49dd8d82019-05-06 15:16:19 +02002596 * This must be at least
2597 * #PSA_AEAD_UPDATE_OUTPUT_SIZE(\c alg,
2598 * \p input_length) where \c alg is the
2599 * algorithm that is being calculated.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002600 * \param[out] output_length On success, the number of bytes
2601 * that make up the returned output.
2602 *
2603 * \retval #PSA_SUCCESS
2604 * Success.
2605 * \retval #PSA_ERROR_BAD_STATE
2606 * The operation state is not valid (not set up, nonce not set
2607 * or already completed).
2608 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
2609 * The size of the \p output buffer is too small.
Gilles Peskine49dd8d82019-05-06 15:16:19 +02002610 * You can determine a sufficient buffer size by calling
2611 * #PSA_AEAD_UPDATE_OUTPUT_SIZE(\c alg, \p input_length)
2612 * where \c alg is the algorithm that is being calculated.
Gilles Peskinebc59c852019-01-17 15:26:08 +01002613 * \retval #PSA_ERROR_INVALID_ARGUMENT
2614 * The total length of input to psa_aead_update_ad() so far is
2615 * less than the additional data length that was previously
2616 * specified with psa_aead_set_lengths().
2617 * \retval #PSA_ERROR_INVALID_ARGUMENT
2618 * The total input length overflows the plaintext length that
2619 * was previously specified with psa_aead_set_lengths().
Gilles Peskine30a9e412019-01-14 18:36:12 +01002620 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2621 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2622 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002623 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw484ba882019-08-13 14:41:52 +01002624 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01002625 * \retval #PSA_ERROR_BAD_STATE
2626 * The library has not been previously initialized by psa_crypto_init().
2627 * It is implementation-dependent whether a failure to initialize
2628 * results in this error code.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002629 */
2630psa_status_t psa_aead_update(psa_aead_operation_t *operation,
2631 const uint8_t *input,
2632 size_t input_length,
Andrew Thoelked16bdac2019-05-15 12:34:01 +01002633 uint8_t *output,
Gilles Peskine30a9e412019-01-14 18:36:12 +01002634 size_t output_size,
2635 size_t *output_length);
2636
2637/** Finish encrypting a message in an AEAD operation.
2638 *
2639 * The operation must have been set up with psa_aead_encrypt_setup().
2640 *
2641 * This function finishes the authentication of the additional data
2642 * formed by concatenating the inputs passed to preceding calls to
2643 * psa_aead_update_ad() with the plaintext formed by concatenating the
2644 * inputs passed to preceding calls to psa_aead_update().
2645 *
2646 * This function has two output buffers:
2647 * - \p ciphertext contains trailing ciphertext that was buffered from
Gilles Peskinef02aec92019-05-06 15:42:54 +02002648 * preceding calls to psa_aead_update().
Gilles Peskine30a9e412019-01-14 18:36:12 +01002649 * - \p tag contains the authentication tag. Its length is always
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002650 * #PSA_AEAD_TAG_LENGTH(\c alg) where \c alg is the AEAD algorithm
Gilles Peskine30a9e412019-01-14 18:36:12 +01002651 * that the operation performs.
2652 *
2653 * When this function returns, the operation becomes inactive.
2654 *
2655 * \param[in,out] operation Active AEAD operation.
2656 * \param[out] ciphertext Buffer where the last part of the ciphertext
2657 * is to be written.
2658 * \param ciphertext_size Size of the \p ciphertext buffer in bytes.
Gilles Peskine49dd8d82019-05-06 15:16:19 +02002659 * This must be at least
2660 * #PSA_AEAD_FINISH_OUTPUT_SIZE(\c alg) where
2661 * \c alg is the algorithm that is being
2662 * calculated.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002663 * \param[out] ciphertext_length On success, the number of bytes of
2664 * returned ciphertext.
2665 * \param[out] tag Buffer where the authentication tag is
2666 * to be written.
2667 * \param tag_size Size of the \p tag buffer in bytes.
Gilles Peskine49dd8d82019-05-06 15:16:19 +02002668 * This must be at least
2669 * #PSA_AEAD_TAG_LENGTH(\c alg) where \c alg is
2670 * the algorithm that is being calculated.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002671 * \param[out] tag_length On success, the number of bytes
2672 * that make up the returned tag.
2673 *
2674 * \retval #PSA_SUCCESS
2675 * Success.
2676 * \retval #PSA_ERROR_BAD_STATE
2677 * The operation state is not valid (not set up, nonce not set,
2678 * decryption, or already completed).
2679 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002680 * The size of the \p ciphertext or \p tag buffer is too small.
Gilles Peskine49dd8d82019-05-06 15:16:19 +02002681 * You can determine a sufficient buffer size for \p ciphertext by
2682 * calling #PSA_AEAD_FINISH_OUTPUT_SIZE(\c alg)
2683 * where \c alg is the algorithm that is being calculated.
2684 * You can determine a sufficient buffer size for \p tag by
2685 * calling #PSA_AEAD_TAG_LENGTH(\c alg).
Gilles Peskinebc59c852019-01-17 15:26:08 +01002686 * \retval #PSA_ERROR_INVALID_ARGUMENT
2687 * The total length of input to psa_aead_update_ad() so far is
2688 * less than the additional data length that was previously
2689 * specified with psa_aead_set_lengths().
2690 * \retval #PSA_ERROR_INVALID_ARGUMENT
2691 * The total length of input to psa_aead_update() so far is
2692 * less than the plaintext length that was previously
2693 * specified with psa_aead_set_lengths().
Gilles Peskine30a9e412019-01-14 18:36:12 +01002694 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2695 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2696 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002697 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw484ba882019-08-13 14:41:52 +01002698 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01002699 * \retval #PSA_ERROR_BAD_STATE
2700 * The library has not been previously initialized by psa_crypto_init().
2701 * It is implementation-dependent whether a failure to initialize
2702 * results in this error code.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002703 */
2704psa_status_t psa_aead_finish(psa_aead_operation_t *operation,
Gilles Peskinea05602d2019-01-17 15:25:52 +01002705 uint8_t *ciphertext,
2706 size_t ciphertext_size,
2707 size_t *ciphertext_length,
Gilles Peskine30a9e412019-01-14 18:36:12 +01002708 uint8_t *tag,
2709 size_t tag_size,
2710 size_t *tag_length);
2711
2712/** Finish authenticating and decrypting a message in an AEAD operation.
2713 *
2714 * The operation must have been set up with psa_aead_decrypt_setup().
2715 *
Andrew Thoelke5ae24ec2019-09-12 09:44:33 +01002716 * This function finishes the authenticated decryption of the message
2717 * components:
2718 *
2719 * - The additional data consisting of the concatenation of the inputs
2720 * passed to preceding calls to psa_aead_update_ad().
2721 * - The ciphertext consisting of the concatenation of the inputs passed to
2722 * preceding calls to psa_aead_update().
2723 * - The tag passed to this function call.
2724 *
2725 * If the authentication tag is correct, this function outputs any remaining
2726 * plaintext and reports success. If the authentication tag is not correct,
2727 * this function returns #PSA_ERROR_INVALID_SIGNATURE.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002728 *
2729 * When this function returns, the operation becomes inactive.
2730 *
Andrew Thoelke5ae24ec2019-09-12 09:44:33 +01002731 * \note Implementations shall make the best effort to ensure that the
2732 * comparison between the actual tag and the expected tag is performed
2733 * in constant time.
2734 *
Gilles Peskine30a9e412019-01-14 18:36:12 +01002735 * \param[in,out] operation Active AEAD operation.
Gilles Peskine5211efb2019-05-06 15:56:05 +02002736 * \param[out] plaintext Buffer where the last part of the plaintext
Gilles Peskineac99e322019-05-14 16:10:53 +02002737 * is to be written. This is the remaining data
Gilles Peskine5211efb2019-05-06 15:56:05 +02002738 * from previous calls to psa_aead_update()
2739 * that could not be processed until the end
2740 * of the input.
2741 * \param plaintext_size Size of the \p plaintext buffer in bytes.
Gilles Peskine49dd8d82019-05-06 15:16:19 +02002742 * This must be at least
2743 * #PSA_AEAD_VERIFY_OUTPUT_SIZE(\c alg) where
2744 * \c alg is the algorithm that is being
2745 * calculated.
Gilles Peskine5211efb2019-05-06 15:56:05 +02002746 * \param[out] plaintext_length On success, the number of bytes of
2747 * returned plaintext.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002748 * \param[in] tag Buffer containing the authentication tag.
2749 * \param tag_length Size of the \p tag buffer in bytes.
2750 *
2751 * \retval #PSA_SUCCESS
2752 * Success.
Andrew Thoelke5ae24ec2019-09-12 09:44:33 +01002753 * \retval #PSA_ERROR_INVALID_SIGNATURE
2754 * The calculations were successful, but the authentication tag is
2755 * not correct.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002756 * \retval #PSA_ERROR_BAD_STATE
2757 * The operation state is not valid (not set up, nonce not set,
2758 * encryption, or already completed).
Gilles Peskine49dd8d82019-05-06 15:16:19 +02002759 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
2760 * The size of the \p plaintext buffer is too small.
2761 * You can determine a sufficient buffer size for \p plaintext by
2762 * calling #PSA_AEAD_VERIFY_OUTPUT_SIZE(\c alg)
2763 * where \c alg is the algorithm that is being calculated.
Gilles Peskinebc59c852019-01-17 15:26:08 +01002764 * \retval #PSA_ERROR_INVALID_ARGUMENT
2765 * The total length of input to psa_aead_update_ad() so far is
2766 * less than the additional data length that was previously
2767 * specified with psa_aead_set_lengths().
2768 * \retval #PSA_ERROR_INVALID_ARGUMENT
2769 * The total length of input to psa_aead_update() so far is
2770 * less than the plaintext length that was previously
2771 * specified with psa_aead_set_lengths().
Gilles Peskine30a9e412019-01-14 18:36:12 +01002772 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2773 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2774 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002775 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw484ba882019-08-13 14:41:52 +01002776 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01002777 * \retval #PSA_ERROR_BAD_STATE
2778 * The library has not been previously initialized by psa_crypto_init().
2779 * It is implementation-dependent whether a failure to initialize
2780 * results in this error code.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002781 */
2782psa_status_t psa_aead_verify(psa_aead_operation_t *operation,
Gilles Peskine5211efb2019-05-06 15:56:05 +02002783 uint8_t *plaintext,
2784 size_t plaintext_size,
2785 size_t *plaintext_length,
Gilles Peskine30a9e412019-01-14 18:36:12 +01002786 const uint8_t *tag,
2787 size_t tag_length);
2788
2789/** Abort an AEAD operation.
2790 *
2791 * Aborting an operation frees all associated resources except for the
2792 * \p operation structure itself. Once aborted, the operation object
2793 * can be reused for another operation by calling
2794 * psa_aead_encrypt_setup() or psa_aead_decrypt_setup() again.
2795 *
2796 * You may call this function any time after the operation object has
2797 * been initialized by any of the following methods:
2798 * - A call to psa_aead_encrypt_setup() or psa_aead_decrypt_setup(),
2799 * whether it succeeds or not.
2800 * - Initializing the \c struct to all-bits-zero.
2801 * - Initializing the \c struct to logical zeros, e.g.
2802 * `psa_aead_operation_t operation = {0}`.
2803 *
2804 * In particular, calling psa_aead_abort() after the operation has been
2805 * terminated by a call to psa_aead_abort() or psa_aead_finish()
2806 * is safe and has no effect.
2807 *
2808 * \param[in,out] operation Initialized AEAD operation.
2809 *
2810 * \retval #PSA_SUCCESS
2811 * \retval #PSA_ERROR_BAD_STATE
2812 * \p operation is not an active AEAD operation.
2813 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2814 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002815 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01002816 * \retval #PSA_ERROR_BAD_STATE
2817 * The library has not been previously initialized by psa_crypto_init().
2818 * It is implementation-dependent whether a failure to initialize
2819 * results in this error code.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002820 */
2821psa_status_t psa_aead_abort(psa_aead_operation_t *operation);
2822
Gilles Peskine3b555712018-03-03 21:27:57 +01002823/**@}*/
2824
Gilles Peskine20035e32018-02-03 22:44:14 +01002825/** \defgroup asymmetric Asymmetric cryptography
2826 * @{
2827 */
2828
2829/**
2830 * \brief Sign a hash or short message with a private key.
2831 *
Gilles Peskine08bac712018-06-26 16:14:46 +02002832 * Note that to perform a hash-and-sign signature algorithm, you must
Gilles Peskineda8191d1c2018-07-08 19:46:38 +02002833 * first calculate the hash by calling psa_hash_setup(), psa_hash_update()
Gilles Peskine08bac712018-06-26 16:14:46 +02002834 * and psa_hash_finish(). Then pass the resulting hash as the \p hash
2835 * parameter to this function. You can use #PSA_ALG_SIGN_GET_HASH(\p alg)
2836 * to determine the hash algorithm to use.
2837 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01002838 * \param handle Handle to the key to use for the operation.
2839 * It must be an asymmetric key pair.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002840 * \param alg A signature algorithm that is compatible with
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002841 * the type of \p handle.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002842 * \param[in] hash The hash or message to sign.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002843 * \param hash_length Size of the \p hash buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002844 * \param[out] signature Buffer where the signature is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002845 * \param signature_size Size of the \p signature buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002846 * \param[out] signature_length On success, the number of bytes
2847 * that make up the returned signature value.
Gilles Peskine308b91d2018-02-08 09:47:44 +01002848 *
Gilles Peskine28538492018-07-11 17:34:00 +02002849 * \retval #PSA_SUCCESS
Adrian L. Shaw27c12152019-08-08 11:10:32 +01002850 * \retval #PSA_ERROR_INVALID_HANDLE
2851 * \retval #PSA_ERROR_NOT_PERMITTED
Gilles Peskine28538492018-07-11 17:34:00 +02002852 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002853 * The size of the \p signature buffer is too small. You can
Gilles Peskine308b91d2018-02-08 09:47:44 +01002854 * determine a sufficient buffer size by calling
Gilles Peskine7256e6c2018-07-12 00:34:26 +02002855 * #PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
Gilles Peskine308b91d2018-02-08 09:47:44 +01002856 * where \c key_type and \c key_bits are the type and bit-size
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002857 * respectively of \p handle.
Gilles Peskine28538492018-07-11 17:34:00 +02002858 * \retval #PSA_ERROR_NOT_SUPPORTED
2859 * \retval #PSA_ERROR_INVALID_ARGUMENT
2860 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2861 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2862 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002863 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw27c12152019-08-08 11:10:32 +01002864 * \retval #PSA_ERROR_STORAGE_FAILURE
Gilles Peskine28538492018-07-11 17:34:00 +02002865 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
itayzafrir90d8c7a2018-09-12 11:44:52 +03002866 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03002867 * The library has not been previously initialized by psa_crypto_init().
2868 * It is implementation-dependent whether a failure to initialize
2869 * results in this error code.
Gilles Peskine20035e32018-02-03 22:44:14 +01002870 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01002871psa_status_t psa_asymmetric_sign(psa_key_handle_t handle,
Gilles Peskine20035e32018-02-03 22:44:14 +01002872 psa_algorithm_t alg,
2873 const uint8_t *hash,
2874 size_t hash_length,
Gilles Peskine20035e32018-02-03 22:44:14 +01002875 uint8_t *signature,
2876 size_t signature_size,
2877 size_t *signature_length);
2878
2879/**
2880 * \brief Verify the signature a hash or short message using a public key.
2881 *
Gilles Peskine08bac712018-06-26 16:14:46 +02002882 * Note that to perform a hash-and-sign signature algorithm, you must
Gilles Peskineda8191d1c2018-07-08 19:46:38 +02002883 * first calculate the hash by calling psa_hash_setup(), psa_hash_update()
Gilles Peskine08bac712018-06-26 16:14:46 +02002884 * and psa_hash_finish(). Then pass the resulting hash as the \p hash
2885 * parameter to this function. You can use #PSA_ALG_SIGN_GET_HASH(\p alg)
2886 * to determine the hash algorithm to use.
2887 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01002888 * \param handle Handle to the key to use for the operation.
2889 * It must be a public key or an asymmetric key pair.
Gilles Peskine308b91d2018-02-08 09:47:44 +01002890 * \param alg A signature algorithm that is compatible with
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002891 * the type of \p handle.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002892 * \param[in] hash The hash or message whose signature is to be
Gilles Peskine08bac712018-06-26 16:14:46 +02002893 * verified.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002894 * \param hash_length Size of the \p hash buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002895 * \param[in] signature Buffer containing the signature to verify.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002896 * \param signature_length Size of the \p signature buffer in bytes.
Gilles Peskine308b91d2018-02-08 09:47:44 +01002897 *
Gilles Peskine28538492018-07-11 17:34:00 +02002898 * \retval #PSA_SUCCESS
Gilles Peskine308b91d2018-02-08 09:47:44 +01002899 * The signature is valid.
Adrian L. Shaw6e758c92019-08-08 11:11:43 +01002900 * \retval #PSA_ERROR_INVALID_HANDLE
2901 * \retval #PSA_ERROR_NOT_PERMITTED
Gilles Peskine28538492018-07-11 17:34:00 +02002902 * \retval #PSA_ERROR_INVALID_SIGNATURE
Gilles Peskine308b91d2018-02-08 09:47:44 +01002903 * The calculation was perfomed successfully, but the passed
2904 * signature is not a valid signature.
Gilles Peskine28538492018-07-11 17:34:00 +02002905 * \retval #PSA_ERROR_NOT_SUPPORTED
2906 * \retval #PSA_ERROR_INVALID_ARGUMENT
2907 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2908 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2909 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002910 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw6e758c92019-08-08 11:11:43 +01002911 * \retval #PSA_ERROR_STORAGE_FAILURE
itayzafrir90d8c7a2018-09-12 11:44:52 +03002912 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03002913 * The library has not been previously initialized by psa_crypto_init().
2914 * It is implementation-dependent whether a failure to initialize
2915 * results in this error code.
Gilles Peskine20035e32018-02-03 22:44:14 +01002916 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01002917psa_status_t psa_asymmetric_verify(psa_key_handle_t handle,
Gilles Peskine20035e32018-02-03 22:44:14 +01002918 psa_algorithm_t alg,
2919 const uint8_t *hash,
2920 size_t hash_length,
Gilles Peskinee9191ff2018-06-27 14:58:41 +02002921 const uint8_t *signature,
Gilles Peskine526fab02018-06-27 18:19:40 +02002922 size_t signature_length);
Gilles Peskine20035e32018-02-03 22:44:14 +01002923
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002924/**
2925 * \brief Encrypt a short message with a public 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 a public key or an asymmetric
2929 * key pair.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002930 * \param alg An asymmetric encryption algorithm that is
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002931 * compatible with the type of \p handle.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002932 * \param[in] input The message to encrypt.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002933 * \param input_length Size of the \p input buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002934 * \param[in] salt A salt or label, if supported by the
2935 * encryption algorithm.
2936 * If the algorithm does not support a
2937 * salt, pass \c NULL.
2938 * If the algorithm supports an optional
2939 * salt and you do not want to pass a salt,
2940 * pass \c NULL.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002941 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02002942 * - For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is
2943 * supported.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002944 * \param salt_length Size of the \p salt buffer in bytes.
2945 * If \p salt is \c NULL, pass 0.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002946 * \param[out] output Buffer where the encrypted message is to
2947 * be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002948 * \param output_size Size of the \p output buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002949 * \param[out] output_length On success, the number of bytes
2950 * that make up the returned output.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002951 *
Gilles Peskine28538492018-07-11 17:34:00 +02002952 * \retval #PSA_SUCCESS
Adrian L. Shawf961d5c2019-08-08 10:27:50 +01002953 * \retval #PSA_ERROR_INVALID_HANDLE
2954 * \retval #PSA_ERROR_NOT_PERMITTED
Gilles Peskine28538492018-07-11 17:34:00 +02002955 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002956 * The size of the \p output buffer is too small. You can
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002957 * determine a sufficient buffer size by calling
Gilles Peskine7256e6c2018-07-12 00:34:26 +02002958 * #PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002959 * where \c key_type and \c key_bits are the type and bit-size
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002960 * respectively of \p handle.
Gilles Peskine28538492018-07-11 17:34:00 +02002961 * \retval #PSA_ERROR_NOT_SUPPORTED
2962 * \retval #PSA_ERROR_INVALID_ARGUMENT
2963 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2964 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2965 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002966 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawf961d5c2019-08-08 10:27:50 +01002967 * \retval #PSA_ERROR_STORAGE_FAILURE
Gilles Peskine28538492018-07-11 17:34:00 +02002968 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
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_encrypt(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
2984/**
2985 * \brief Decrypt a short message with a private key.
2986 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01002987 * \param handle Handle to the key to use for the operation.
2988 * It must be an asymmetric key pair.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002989 * \param alg An asymmetric encryption algorithm that is
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002990 * compatible with the type of \p handle.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002991 * \param[in] input The message to decrypt.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002992 * \param input_length Size of the \p input buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002993 * \param[in] salt A salt or label, if supported by the
2994 * encryption algorithm.
2995 * If the algorithm does not support a
2996 * salt, pass \c NULL.
2997 * If the algorithm supports an optional
2998 * salt and you do not want to pass a salt,
2999 * pass \c NULL.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02003000 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02003001 * - For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is
3002 * supported.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02003003 * \param salt_length Size of the \p salt buffer in bytes.
3004 * If \p salt is \c NULL, pass 0.
Gilles Peskineedd11a12018-07-12 01:08:58 +02003005 * \param[out] output Buffer where the decrypted message is to
3006 * be written.
3007 * \param output_size Size of the \c output buffer in bytes.
3008 * \param[out] output_length On success, the number of bytes
3009 * that make up the returned output.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02003010 *
Gilles Peskine28538492018-07-11 17:34:00 +02003011 * \retval #PSA_SUCCESS
Adrian L. Shaw96f31ad2019-08-08 10:30:58 +01003012 * \retval #PSA_ERROR_INVALID_HANDLE
3013 * \retval #PSA_ERROR_NOT_PERMITTED
Gilles Peskine28538492018-07-11 17:34:00 +02003014 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinefa4070c2018-07-12 19:23:03 +02003015 * The size of the \p output buffer is too small. You can
Gilles Peskine6944f9a2018-03-28 14:18:39 +02003016 * determine a sufficient buffer size by calling
Gilles Peskinedda3bd32018-07-12 19:40:46 +02003017 * #PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
Gilles Peskine6944f9a2018-03-28 14:18:39 +02003018 * where \c key_type and \c key_bits are the type and bit-size
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01003019 * respectively of \p handle.
Gilles Peskine28538492018-07-11 17:34:00 +02003020 * \retval #PSA_ERROR_NOT_SUPPORTED
3021 * \retval #PSA_ERROR_INVALID_ARGUMENT
3022 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3023 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3024 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003025 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw96f31ad2019-08-08 10:30:58 +01003026 * \retval #PSA_ERROR_STORAGE_FAILURE
Gilles Peskine28538492018-07-11 17:34:00 +02003027 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
3028 * \retval #PSA_ERROR_INVALID_PADDING
itayzafrir90d8c7a2018-09-12 11:44:52 +03003029 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03003030 * The library has not been previously initialized by psa_crypto_init().
3031 * It is implementation-dependent whether a failure to initialize
3032 * results in this error code.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02003033 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01003034psa_status_t psa_asymmetric_decrypt(psa_key_handle_t handle,
Gilles Peskine6944f9a2018-03-28 14:18:39 +02003035 psa_algorithm_t alg,
3036 const uint8_t *input,
3037 size_t input_length,
3038 const uint8_t *salt,
3039 size_t salt_length,
3040 uint8_t *output,
3041 size_t output_size,
3042 size_t *output_length);
3043
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +01003044/**@}*/
3045
Gilles Peskine35675b62019-05-16 17:26:11 +02003046/** \defgroup key_derivation Key derivation and pseudorandom generation
Gilles Peskineeab56e42018-07-12 17:12:33 +02003047 * @{
3048 */
3049
Gilles Peskine35675b62019-05-16 17:26:11 +02003050/** The type of the state data structure for key derivation operations.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003051 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003052 * Before calling any function on a key derivation operation object, the
3053 * application must initialize it by any of the following means:
Gilles Peskineeab56e42018-07-12 17:12:33 +02003054 * - Set the structure to all-bits-zero, for example:
3055 * \code
Gilles Peskine35675b62019-05-16 17:26:11 +02003056 * psa_key_derivation_operation_t operation;
3057 * memset(&operation, 0, sizeof(operation));
Gilles Peskineeab56e42018-07-12 17:12:33 +02003058 * \endcode
3059 * - Initialize the structure to logical zero values, for example:
3060 * \code
Gilles Peskine35675b62019-05-16 17:26:11 +02003061 * psa_key_derivation_operation_t operation = {0};
Gilles Peskineeab56e42018-07-12 17:12:33 +02003062 * \endcode
Gilles Peskinea99d3fb2019-05-16 15:28:51 +02003063 * - Initialize the structure to the initializer #PSA_KEY_DERIVATION_OPERATION_INIT,
Gilles Peskineeab56e42018-07-12 17:12:33 +02003064 * for example:
3065 * \code
Gilles Peskine35675b62019-05-16 17:26:11 +02003066 * psa_key_derivation_operation_t operation = PSA_KEY_DERIVATION_OPERATION_INIT;
Gilles Peskineeab56e42018-07-12 17:12:33 +02003067 * \endcode
Gilles Peskinea99d3fb2019-05-16 15:28:51 +02003068 * - Assign the result of the function psa_key_derivation_operation_init()
Gilles Peskineeab56e42018-07-12 17:12:33 +02003069 * to the structure, for example:
3070 * \code
Gilles Peskine35675b62019-05-16 17:26:11 +02003071 * psa_key_derivation_operation_t operation;
3072 * operation = psa_key_derivation_operation_init();
Gilles Peskineeab56e42018-07-12 17:12:33 +02003073 * \endcode
3074 *
3075 * This is an implementation-defined \c struct. Applications should not
3076 * make any assumptions about the content of this structure except
3077 * as directed by the documentation of a specific implementation.
3078 */
Gilles Peskinecbe66502019-05-16 16:59:18 +02003079typedef struct psa_key_derivation_s psa_key_derivation_operation_t;
Gilles Peskineeab56e42018-07-12 17:12:33 +02003080
Gilles Peskinea99d3fb2019-05-16 15:28:51 +02003081/** \def PSA_KEY_DERIVATION_OPERATION_INIT
Gilles Peskineeab56e42018-07-12 17:12:33 +02003082 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003083 * This macro returns a suitable initializer for a key derivation operation
3084 * object of type #psa_key_derivation_operation_t.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003085 */
3086#ifdef __DOXYGEN_ONLY__
3087/* This is an example definition for documentation purposes.
3088 * Implementations should define a suitable value in `crypto_struct.h`.
3089 */
Gilles Peskinea99d3fb2019-05-16 15:28:51 +02003090#define PSA_KEY_DERIVATION_OPERATION_INIT {0}
Gilles Peskineeab56e42018-07-12 17:12:33 +02003091#endif
3092
Gilles Peskine35675b62019-05-16 17:26:11 +02003093/** Return an initial value for a key derivation operation object.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003094 */
Gilles Peskinea99d3fb2019-05-16 15:28:51 +02003095static psa_key_derivation_operation_t psa_key_derivation_operation_init(void);
Gilles Peskineeab56e42018-07-12 17:12:33 +02003096
Gilles Peskine1cb9a082019-05-16 17:56:47 +02003097/** Set up a key derivation operation.
3098 *
3099 * A key derivation algorithm takes some inputs and uses them to generate
3100 * a byte stream in a deterministic way.
3101 * This byte stream can be used to produce keys and other
3102 * cryptographic material.
3103 *
3104 * To derive a key:
3105 * - Start with an initialized object of type #psa_key_derivation_operation_t.
3106 * - Call psa_key_derivation_setup() to select the algorithm.
3107 * - Provide the inputs for the key derivation by calling
3108 * psa_key_derivation_input_bytes() or psa_key_derivation_input_key()
3109 * as appropriate. Which inputs are needed, in what order, and whether
3110 * they may be keys and if so of what type depends on the algorithm.
3111 * - Optionally set the operation's maximum capacity with
3112 * psa_key_derivation_set_capacity(). You may do this before, in the middle
3113 * of or after providing inputs. For some algorithms, this step is mandatory
3114 * because the output depends on the maximum capacity.
3115 * - To derive a key, call psa_key_derivation_output_key().
3116 * To derive a byte string for a different purpose, call
3117 * - psa_key_derivation_output_bytes().
3118 * Successive calls to these functions use successive output bytes
3119 * calculated by the key derivation algorithm.
3120 * - Clean up the key derivation operation object with
3121 * psa_key_derivation_abort().
3122 *
Gilles Peskine05c900b2019-09-12 18:29:43 +02003123 * Implementations must reject an attempt to derive a key of size 0.
3124 *
Gilles Peskine1cb9a082019-05-16 17:56:47 +02003125 * \param[in,out] operation The key derivation operation object
3126 * to set up. It must
3127 * have been initialized but not set up yet.
3128 * \param alg The key derivation algorithm to compute
3129 * (\c PSA_ALG_XXX value such that
3130 * #PSA_ALG_IS_KEY_DERIVATION(\p alg) is true).
3131 *
3132 * \retval #PSA_SUCCESS
3133 * Success.
3134 * \retval #PSA_ERROR_INVALID_ARGUMENT
3135 * \c alg is not a key derivation algorithm.
3136 * \retval #PSA_ERROR_NOT_SUPPORTED
3137 * \c alg is not supported or is not a key derivation algorithm.
3138 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3139 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3140 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003141 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawfa2cefa2019-09-03 16:51:19 +01003142 * \retval #PSA_ERROR_STORAGE_FAILURE
Gilles Peskine1cb9a082019-05-16 17:56:47 +02003143 * \retval #PSA_ERROR_BAD_STATE
Adrian L. Shaw320659b2019-08-08 14:49:01 +01003144 * The operation state is either not initialized or has already been setup.
Adrian L. Shawdec47b62019-08-07 14:25:38 +01003145 * \retval #PSA_ERROR_BAD_STATE
3146 * The library has not been previously initialized by psa_crypto_init().
3147 * It is implementation-dependent whether a failure to initialize
3148 * results in this error code.
Gilles Peskine1cb9a082019-05-16 17:56:47 +02003149 */
3150psa_status_t psa_key_derivation_setup(
3151 psa_key_derivation_operation_t *operation,
3152 psa_algorithm_t alg);
3153
Gilles Peskine35675b62019-05-16 17:26:11 +02003154/** Retrieve the current capacity of a key derivation operation.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003155 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003156 * The capacity of a key derivation is the maximum number of bytes that it can
3157 * return. When you get *N* bytes of output from a key derivation operation,
3158 * this reduces its capacity by *N*.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003159 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003160 * \param[in] operation The operation to query.
3161 * \param[out] capacity On success, the capacity of the operation.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003162 *
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003163 * \retval #PSA_SUCCESS
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003164 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01003165 * \retval #PSA_ERROR_BAD_STATE
3166 * The operation state is not valid.
Adrian L. Shaw484ba882019-08-13 14:41:52 +01003167 * \retval #PSA_ERROR_HARDWARE_FAILURE
3168 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01003169 * \retval #PSA_ERROR_BAD_STATE
3170 * The library has not been previously initialized by psa_crypto_init().
3171 * It is implementation-dependent whether a failure to initialize
3172 * results in this error code.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003173 */
Gilles Peskinecf7292e2019-05-16 17:53:40 +02003174psa_status_t psa_key_derivation_get_capacity(
3175 const psa_key_derivation_operation_t *operation,
3176 size_t *capacity);
Gilles Peskineeab56e42018-07-12 17:12:33 +02003177
Gilles Peskine35675b62019-05-16 17:26:11 +02003178/** Set the maximum capacity of a key derivation operation.
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01003179 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003180 * The capacity of a key derivation operation is the maximum number of bytes
3181 * that the key derivation operation can return from this point onwards.
3182 *
3183 * \param[in,out] operation The key derivation operation object to modify.
3184 * \param capacity The new capacity of the operation.
3185 * It must be less or equal to the operation's
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01003186 * current capacity.
3187 *
3188 * \retval #PSA_SUCCESS
3189 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine35675b62019-05-16 17:26:11 +02003190 * \p capacity is larger than the operation's current capacity.
3191 * In this case, the operation object remains valid and its capacity
3192 * remains unchanged.
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01003193 * \retval #PSA_ERROR_BAD_STATE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01003194 * The operation state is not valid.
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01003195 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
Adrian L. Shaw484ba882019-08-13 14:41:52 +01003196 * \retval #PSA_ERROR_HARDWARE_FAILURE
3197 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01003198 * \retval #PSA_ERROR_BAD_STATE
3199 * The library has not been previously initialized by psa_crypto_init().
3200 * It is implementation-dependent whether a failure to initialize
3201 * results in this error code.
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01003202 */
Gilles Peskinecf7292e2019-05-16 17:53:40 +02003203psa_status_t psa_key_derivation_set_capacity(
3204 psa_key_derivation_operation_t *operation,
3205 size_t capacity);
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01003206
Gilles Peskine1cb9a082019-05-16 17:56:47 +02003207/** Use the maximum possible capacity for a key derivation operation.
3208 *
3209 * Use this value as the capacity argument when setting up a key derivation
3210 * to indicate that the operation should have the maximum possible capacity.
3211 * The value of the maximum possible capacity depends on the key derivation
3212 * algorithm.
3213 */
3214#define PSA_KEY_DERIVATION_UNLIMITED_CAPACITY ((size_t)(-1))
3215
3216/** Provide an input for key derivation or key agreement.
3217 *
3218 * Which inputs are required and in what order depends on the algorithm.
3219 * Refer to the documentation of each key derivation or key agreement
3220 * algorithm for information.
3221 *
3222 * This function passes direct inputs. Some inputs must be passed as keys
3223 * using psa_key_derivation_input_key() instead of this function. Refer to
3224 * the documentation of individual step types for information.
3225 *
3226 * \param[in,out] operation The key derivation operation object to use.
3227 * It must have been set up with
3228 * psa_key_derivation_setup() and must not
3229 * have produced any output yet.
3230 * \param step Which step the input data is for.
3231 * \param[in] data Input data to use.
3232 * \param data_length Size of the \p data buffer in bytes.
3233 *
3234 * \retval #PSA_SUCCESS
3235 * Success.
3236 * \retval #PSA_ERROR_INVALID_ARGUMENT
3237 * \c step is not compatible with the operation's algorithm.
3238 * \retval #PSA_ERROR_INVALID_ARGUMENT
3239 * \c step does not allow direct inputs.
3240 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3241 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3242 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003243 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw484ba882019-08-13 14:41:52 +01003244 * \retval #PSA_ERROR_STORAGE_FAILURE
Gilles Peskine1cb9a082019-05-16 17:56:47 +02003245 * \retval #PSA_ERROR_BAD_STATE
3246 * The value of \p step is not valid given the state of \p operation.
3247 * \retval #PSA_ERROR_BAD_STATE
3248 * The library has not been previously initialized by psa_crypto_init().
3249 * It is implementation-dependent whether a failure to initialize
3250 * results in this error code.
3251 */
3252psa_status_t psa_key_derivation_input_bytes(
3253 psa_key_derivation_operation_t *operation,
3254 psa_key_derivation_step_t step,
3255 const uint8_t *data,
3256 size_t data_length);
3257
3258/** Provide an input for key derivation in the form of a key.
3259 *
3260 * Which inputs are required and in what order depends on the algorithm.
3261 * Refer to the documentation of each key derivation or key agreement
3262 * algorithm for information.
3263 *
3264 * This function passes key inputs. Some inputs must be passed as keys
3265 * of the appropriate type using this function, while others must be
3266 * passed as direct inputs using psa_key_derivation_input_bytes(). Refer to
3267 * the documentation of individual step types for information.
3268 *
3269 * \param[in,out] operation The key derivation operation object to use.
3270 * It must have been set up with
3271 * psa_key_derivation_setup() and must not
3272 * have produced any output yet.
3273 * \param step Which step the input data is for.
3274 * \param handle Handle to the key. It must have an
3275 * appropriate type for \p step and must
3276 * allow the usage #PSA_KEY_USAGE_DERIVE.
3277 *
3278 * \retval #PSA_SUCCESS
3279 * Success.
3280 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine1cb9a082019-05-16 17:56:47 +02003281 * \retval #PSA_ERROR_NOT_PERMITTED
3282 * \retval #PSA_ERROR_INVALID_ARGUMENT
3283 * \c step is not compatible with the operation's algorithm.
3284 * \retval #PSA_ERROR_INVALID_ARGUMENT
3285 * \c step does not allow key inputs.
3286 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3287 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3288 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003289 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw484ba882019-08-13 14:41:52 +01003290 * \retval #PSA_ERROR_STORAGE_FAILURE
Gilles Peskine1cb9a082019-05-16 17:56:47 +02003291 * \retval #PSA_ERROR_BAD_STATE
3292 * The value of \p step is not valid given the state of \p operation.
3293 * \retval #PSA_ERROR_BAD_STATE
3294 * The library has not been previously initialized by psa_crypto_init().
3295 * It is implementation-dependent whether a failure to initialize
3296 * results in this error code.
3297 */
3298psa_status_t psa_key_derivation_input_key(
3299 psa_key_derivation_operation_t *operation,
3300 psa_key_derivation_step_t step,
3301 psa_key_handle_t handle);
3302
3303/** Perform a key agreement and use the shared secret as input to a key
3304 * derivation.
3305 *
3306 * A key agreement algorithm takes two inputs: a private key \p private_key
3307 * a public key \p peer_key.
3308 * The result of this function is passed as input to a key derivation.
3309 * The output of this key derivation can be extracted by reading from the
3310 * resulting operation to produce keys and other cryptographic material.
3311 *
3312 * \param[in,out] operation The key derivation operation object to use.
3313 * It must have been set up with
3314 * psa_key_derivation_setup() with a
3315 * key agreement and derivation algorithm
3316 * \c alg (\c PSA_ALG_XXX value such that
3317 * #PSA_ALG_IS_KEY_AGREEMENT(\c alg) is true
3318 * and #PSA_ALG_IS_RAW_KEY_AGREEMENT(\c alg)
3319 * is false).
3320 * The operation must be ready for an
3321 * input of the type given by \p step.
3322 * \param step Which step the input data is for.
3323 * \param private_key Handle to the private key to use.
3324 * \param[in] peer_key Public key of the peer. The peer key must be in the
3325 * same format that psa_import_key() accepts for the
3326 * public key type corresponding to the type of
3327 * private_key. That is, this function performs the
3328 * equivalent of
3329 * #psa_import_key(...,
3330 * `peer_key`, `peer_key_length`) where
3331 * with key attributes indicating the public key
3332 * type corresponding to the type of `private_key`.
3333 * For example, for EC keys, this means that peer_key
3334 * is interpreted as a point on the curve that the
3335 * private key is on. The standard formats for public
3336 * keys are documented in the documentation of
3337 * psa_export_public_key().
3338 * \param peer_key_length Size of \p peer_key in bytes.
3339 *
3340 * \retval #PSA_SUCCESS
3341 * Success.
3342 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine1cb9a082019-05-16 17:56:47 +02003343 * \retval #PSA_ERROR_NOT_PERMITTED
3344 * \retval #PSA_ERROR_INVALID_ARGUMENT
3345 * \c private_key is not compatible with \c alg,
3346 * or \p peer_key is not valid for \c alg or not compatible with
3347 * \c private_key.
3348 * \retval #PSA_ERROR_NOT_SUPPORTED
3349 * \c alg is not supported or is not a key derivation algorithm.
3350 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3351 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3352 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003353 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw484ba882019-08-13 14:41:52 +01003354 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01003355 * \retval #PSA_ERROR_BAD_STATE
3356 * The library has not been previously initialized by psa_crypto_init().
3357 * It is implementation-dependent whether a failure to initialize
3358 * results in this error code.
Gilles Peskine1cb9a082019-05-16 17:56:47 +02003359 */
3360psa_status_t psa_key_derivation_key_agreement(
3361 psa_key_derivation_operation_t *operation,
3362 psa_key_derivation_step_t step,
3363 psa_key_handle_t private_key,
3364 const uint8_t *peer_key,
3365 size_t peer_key_length);
3366
Gilles Peskine35675b62019-05-16 17:26:11 +02003367/** Read some data from a key derivation operation.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003368 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003369 * This function calculates output bytes from a key derivation algorithm and
3370 * return those bytes.
3371 * If you view the key derivation's output as a stream of bytes, this
3372 * function destructively reads the requested number of bytes from the
3373 * stream.
3374 * The operation's capacity decreases by the number of bytes read.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003375 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003376 * \param[in,out] operation The key derivation operation object to read from.
3377 * \param[out] output Buffer where the output will be written.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003378 * \param output_length Number of bytes to output.
3379 *
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003380 * \retval #PSA_SUCCESS
David Saadab4ecc272019-02-14 13:48:10 +02003381 * \retval #PSA_ERROR_INSUFFICIENT_DATA
Gilles Peskine35675b62019-05-16 17:26:11 +02003382 * The operation's capacity was less than
3383 * \p output_length bytes. Note that in this case,
3384 * no output is written to the output buffer.
3385 * The operation's capacity is set to 0, thus
Gilles Peskineeab56e42018-07-12 17:12:33 +02003386 * subsequent calls to this function will not
3387 * succeed, even with a smaller output buffer.
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003388 * \retval #PSA_ERROR_BAD_STATE
3389 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3390 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3391 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003392 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw484ba882019-08-13 14:41:52 +01003393 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01003394 * \retval #PSA_ERROR_BAD_STATE
3395 * The library has not been previously initialized by psa_crypto_init().
3396 * It is implementation-dependent whether a failure to initialize
3397 * results in this error code.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003398 */
Gilles Peskinecf7292e2019-05-16 17:53:40 +02003399psa_status_t psa_key_derivation_output_bytes(
3400 psa_key_derivation_operation_t *operation,
3401 uint8_t *output,
3402 size_t output_length);
Gilles Peskineeab56e42018-07-12 17:12:33 +02003403
Gilles Peskine35675b62019-05-16 17:26:11 +02003404/** Derive a key from an ongoing key derivation operation.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003405 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003406 * This function calculates output bytes from a key derivation algorithm
3407 * and uses those bytes to generate a key deterministically.
Gilles Peskinea170d922019-09-12 16:59:37 +02003408 * The key's location, usage policy, type and size are taken from
3409 * \p attributes.
3410 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003411 * If you view the key derivation's output as a stream of bytes, this
3412 * function destructively reads as many bytes as required from the
3413 * stream.
3414 * The operation's capacity decreases by the number of bytes read.
3415 *
3416 * How much output is produced and consumed from the operation, and how
3417 * the key is derived, depends on the key type:
Gilles Peskineeab56e42018-07-12 17:12:33 +02003418 *
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003419 * - For key types for which the key is an arbitrary sequence of bytes
Gilles Peskinecf7292e2019-05-16 17:53:40 +02003420 * of a given size, this function is functionally equivalent to
3421 * calling #psa_key_derivation_output_bytes
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003422 * and passing the resulting output to #psa_import_key.
3423 * However, this function has a security benefit:
3424 * if the implementation provides an isolation boundary then
3425 * the key material is not exposed outside the isolation boundary.
3426 * As a consequence, for these key types, this function always consumes
Gilles Peskine35675b62019-05-16 17:26:11 +02003427 * exactly (\p bits / 8) bytes from the operation.
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003428 * The following key types defined in this specification follow this scheme:
3429 *
3430 * - #PSA_KEY_TYPE_AES;
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003431 * - #PSA_KEY_TYPE_ARC4;
3432 * - #PSA_KEY_TYPE_CAMELLIA;
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003433 * - #PSA_KEY_TYPE_DERIVE;
3434 * - #PSA_KEY_TYPE_HMAC.
3435 *
3436 * - For ECC keys on a Montgomery elliptic curve
Gilles Peskinec93b80c2019-05-16 19:39:54 +02003437 * (#PSA_KEY_TYPE_ECC_KEY_PAIR(\c curve) where \c curve designates a
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003438 * Montgomery curve), this function always draws a byte string whose
3439 * length is determined by the curve, and sets the mandatory bits
3440 * accordingly. That is:
3441 *
3442 * - #PSA_ECC_CURVE_CURVE25519: draw a 32-byte string
3443 * and process it as specified in RFC 7748 &sect;5.
3444 * - #PSA_ECC_CURVE_CURVE448: draw a 56-byte string
3445 * and process it as specified in RFC 7748 &sect;5.
3446 *
3447 * - For key types for which the key is represented by a single sequence of
3448 * \p bits bits with constraints as to which bit sequences are acceptable,
3449 * this function draws a byte string of length (\p bits / 8) bytes rounded
3450 * up to the nearest whole number of bytes. If the resulting byte string
3451 * is acceptable, it becomes the key, otherwise the drawn bytes are discarded.
3452 * This process is repeated until an acceptable byte string is drawn.
Gilles Peskine35675b62019-05-16 17:26:11 +02003453 * The byte string drawn from the operation is interpreted as specified
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003454 * for the output produced by psa_export_key().
3455 * The following key types defined in this specification follow this scheme:
3456 *
Gilles Peskine2de2c0d2019-03-11 17:59:16 +01003457 * - #PSA_KEY_TYPE_DES.
3458 * Force-set the parity bits, but discard forbidden weak keys.
3459 * For 2-key and 3-key triple-DES, the three keys are generated
3460 * successively (for example, for 3-key triple-DES,
3461 * if the first 8 bytes specify a weak key and the next 8 bytes do not,
3462 * discard the first 8 bytes, use the next 8 bytes as the first key,
Gilles Peskine35675b62019-05-16 17:26:11 +02003463 * and continue reading output from the operation to derive the other
Gilles Peskine2de2c0d2019-03-11 17:59:16 +01003464 * two keys).
Gilles Peskinec93b80c2019-05-16 19:39:54 +02003465 * - Finite-field Diffie-Hellman keys (#PSA_KEY_TYPE_DH_KEY_PAIR(\c group)
Gilles Peskinea1302192019-05-16 13:58:24 +02003466 * where \c group designates any Diffie-Hellman group) and
Gilles Peskine2de2c0d2019-03-11 17:59:16 +01003467 * ECC keys on a Weierstrass elliptic curve
Gilles Peskinec93b80c2019-05-16 19:39:54 +02003468 * (#PSA_KEY_TYPE_ECC_KEY_PAIR(\c curve) where \c curve designates a
Gilles Peskine2de2c0d2019-03-11 17:59:16 +01003469 * Weierstrass curve).
3470 * For these key types, interpret the byte string as integer
3471 * in big-endian order. Discard it if it is not in the range
3472 * [0, *N* - 2] where *N* is the boundary of the private key domain
3473 * (the prime *p* for Diffie-Hellman, the subprime *q* for DSA,
Gilles Peskine55799712019-03-12 11:50:26 +01003474 * or the order of the curve's base point for ECC).
Gilles Peskine2de2c0d2019-03-11 17:59:16 +01003475 * Add 1 to the resulting integer and use this as the private key *x*.
Gilles Peskine55799712019-03-12 11:50:26 +01003476 * This method allows compliance to NIST standards, specifically
3477 * the methods titled "key-pair generation by testing candidates"
Gilles Peskine2de2c0d2019-03-11 17:59:16 +01003478 * in NIST SP 800-56A &sect;5.6.1.1.4 for Diffie-Hellman,
3479 * in FIPS 186-4 &sect;B.1.2 for DSA, and
3480 * in NIST SP 800-56A &sect;5.6.1.2.2 or
3481 * FIPS 186-4 &sect;B.4.2 for elliptic curve keys.
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003482 *
Gilles Peskinec93b80c2019-05-16 19:39:54 +02003483 * - For other key types, including #PSA_KEY_TYPE_RSA_KEY_PAIR,
Gilles Peskine35675b62019-05-16 17:26:11 +02003484 * the way in which the operation output is consumed is
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003485 * implementation-defined.
3486 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003487 * In all cases, the data that is read is discarded from the operation.
3488 * The operation's capacity is decreased by the number of bytes read.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003489 *
Gilles Peskine20628592019-04-19 19:29:50 +02003490 * \param[in] attributes The attributes for the new key.
Gilles Peskine35675b62019-05-16 17:26:11 +02003491 * \param[in,out] operation The key derivation operation object to read from.
Gilles Peskine20628592019-04-19 19:29:50 +02003492 * \param[out] handle On success, a handle to the newly created key.
3493 * \c 0 on failure.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003494 *
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003495 * \retval #PSA_SUCCESS
Gilles Peskineeab56e42018-07-12 17:12:33 +02003496 * Success.
Gilles Peskine23fd2bd2018-12-11 15:51:32 +01003497 * If the key is persistent, the key material and the key's metadata
3498 * have been saved to persistent storage.
Gilles Peskine20628592019-04-19 19:29:50 +02003499 * \retval #PSA_ERROR_ALREADY_EXISTS
3500 * This is an attempt to create a persistent key, and there is
3501 * already a persistent key with the given identifier.
David Saadab4ecc272019-02-14 13:48:10 +02003502 * \retval #PSA_ERROR_INSUFFICIENT_DATA
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003503 * There was not enough data to create the desired key.
3504 * Note that in this case, no output is written to the output buffer.
Gilles Peskine35675b62019-05-16 17:26:11 +02003505 * The operation's capacity is set to 0, thus subsequent calls to
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003506 * this function will not succeed, even with a smaller output buffer.
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003507 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskineeab56e42018-07-12 17:12:33 +02003508 * The key type or key size is not supported, either by the
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +01003509 * implementation in general or in this particular location.
k-stachowiakb9b4f092019-08-15 19:01:59 +02003510 * \retval #PSA_ERROR_INVALID_ARGUMENT
3511 * The provided key attributes are not valid for the operation.
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003512 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003513 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3514 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
3515 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3516 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003517 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw484ba882019-08-13 14:41:52 +01003518 * \retval #PSA_ERROR_STORAGE_FAILURE
itayzafrir90d8c7a2018-09-12 11:44:52 +03003519 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03003520 * The library has not been previously initialized by psa_crypto_init().
3521 * It is implementation-dependent whether a failure to initialize
3522 * results in this error code.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003523 */
Gilles Peskinecf7292e2019-05-16 17:53:40 +02003524psa_status_t psa_key_derivation_output_key(
3525 const psa_key_attributes_t *attributes,
3526 psa_key_derivation_operation_t *operation,
3527 psa_key_handle_t *handle);
Gilles Peskineeab56e42018-07-12 17:12:33 +02003528
Gilles Peskine35675b62019-05-16 17:26:11 +02003529/** Abort a key derivation operation.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003530 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003531 * Once a key derivation operation has been aborted, its capacity is zero.
3532 * Aborting an operation frees all associated resources except for the
3533 * \c operation structure itself.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003534 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003535 * This function may be called at any time as long as the operation
Gilles Peskinea99d3fb2019-05-16 15:28:51 +02003536 * object has been initialized to #PSA_KEY_DERIVATION_OPERATION_INIT, to
Gilles Peskinecf7292e2019-05-16 17:53:40 +02003537 * psa_key_derivation_operation_init() or a zero value. In particular,
3538 * it is valid to call psa_key_derivation_abort() twice, or to call
3539 * psa_key_derivation_abort() on an operation that has not been set up.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003540 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003541 * Once aborted, the key derivation operation object may be called.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003542 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003543 * \param[in,out] operation The operation to abort.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003544 *
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003545 * \retval #PSA_SUCCESS
3546 * \retval #PSA_ERROR_BAD_STATE
3547 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3548 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003549 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawdec47b62019-08-07 14:25:38 +01003550 * \retval #PSA_ERROR_BAD_STATE
3551 * The library has not been previously initialized by psa_crypto_init().
3552 * It is implementation-dependent whether a failure to initialize
3553 * results in this error code.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003554 */
Gilles Peskinecf7292e2019-05-16 17:53:40 +02003555psa_status_t psa_key_derivation_abort(
3556 psa_key_derivation_operation_t *operation);
Gilles Peskineeab56e42018-07-12 17:12:33 +02003557
Gilles Peskine58fe9e82019-05-16 18:01:45 +02003558/** Perform a key agreement and return the raw shared secret.
Gilles Peskine769c7a62019-01-18 16:42:29 +01003559 *
3560 * \warning The raw result of a key agreement algorithm such as finite-field
3561 * Diffie-Hellman or elliptic curve Diffie-Hellman has biases and should
3562 * not be used directly as key material. It should instead be passed as
3563 * input to a key derivation algorithm. To chain a key agreement with
Gilles Peskinecf7292e2019-05-16 17:53:40 +02003564 * a key derivation, use psa_key_derivation_key_agreement() and other
3565 * functions from the key derivation interface.
Gilles Peskine769c7a62019-01-18 16:42:29 +01003566 *
Gilles Peskine47e79fb2019-02-08 11:24:59 +01003567 * \param alg The key agreement algorithm to compute
3568 * (\c PSA_ALG_XXX value such that
3569 * #PSA_ALG_IS_RAW_KEY_AGREEMENT(\p alg)
3570 * is true).
Gilles Peskine769c7a62019-01-18 16:42:29 +01003571 * \param private_key Handle to the private key to use.
3572 * \param[in] peer_key Public key of the peer. It must be
3573 * in the same format that psa_import_key()
3574 * accepts. The standard formats for public
3575 * keys are documented in the documentation
3576 * of psa_export_public_key().
3577 * \param peer_key_length Size of \p peer_key in bytes.
3578 * \param[out] output Buffer where the decrypted message is to
3579 * be written.
3580 * \param output_size Size of the \c output buffer in bytes.
3581 * \param[out] output_length On success, the number of bytes
3582 * that make up the returned output.
3583 *
3584 * \retval #PSA_SUCCESS
3585 * Success.
3586 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine769c7a62019-01-18 16:42:29 +01003587 * \retval #PSA_ERROR_NOT_PERMITTED
3588 * \retval #PSA_ERROR_INVALID_ARGUMENT
3589 * \p alg is not a key agreement algorithm
3590 * \retval #PSA_ERROR_INVALID_ARGUMENT
3591 * \p private_key is not compatible with \p alg,
3592 * or \p peer_key is not valid for \p alg or not compatible with
3593 * \p private_key.
Adrian L. Shaw0d280b92019-08-08 15:07:07 +01003594 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
3595 * \p output_size is too small
Gilles Peskine769c7a62019-01-18 16:42:29 +01003596 * \retval #PSA_ERROR_NOT_SUPPORTED
3597 * \p alg is not a supported key agreement algorithm.
3598 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3599 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3600 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003601 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw0d280b92019-08-08 15:07:07 +01003602 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shawdec47b62019-08-07 14:25:38 +01003603 * \retval #PSA_ERROR_BAD_STATE
3604 * The library has not been previously initialized by psa_crypto_init().
3605 * It is implementation-dependent whether a failure to initialize
3606 * results in this error code.
Gilles Peskine769c7a62019-01-18 16:42:29 +01003607 */
Gilles Peskinebe697d82019-05-16 18:00:41 +02003608psa_status_t psa_raw_key_agreement(psa_algorithm_t alg,
3609 psa_key_handle_t private_key,
3610 const uint8_t *peer_key,
3611 size_t peer_key_length,
3612 uint8_t *output,
3613 size_t output_size,
3614 size_t *output_length);
Gilles Peskine01d718c2018-09-18 12:01:02 +02003615
Gilles Peskineea0fb492018-07-12 17:17:20 +02003616/**@}*/
3617
Gilles Peskineedd76872018-07-20 17:42:05 +02003618/** \defgroup random Random generation
Gilles Peskine9e7dc712018-03-28 14:18:50 +02003619 * @{
3620 */
3621
3622/**
3623 * \brief Generate random bytes.
3624 *
3625 * \warning This function **can** fail! Callers MUST check the return status
3626 * and MUST NOT use the content of the output buffer if the return
3627 * status is not #PSA_SUCCESS.
3628 *
Gilles Peskine35ef36b2019-05-16 19:42:05 +02003629 * \note To generate a key, use psa_generate_key() instead.
Gilles Peskine9e7dc712018-03-28 14:18:50 +02003630 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02003631 * \param[out] output Output buffer for the generated data.
Gilles Peskine9e7dc712018-03-28 14:18:50 +02003632 * \param output_size Number of bytes to generate and output.
3633 *
Gilles Peskine28538492018-07-11 17:34:00 +02003634 * \retval #PSA_SUCCESS
3635 * \retval #PSA_ERROR_NOT_SUPPORTED
3636 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
Adrian L. Shaw71b33ff2019-08-08 15:07:57 +01003637 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
Gilles Peskine28538492018-07-11 17:34:00 +02003638 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3639 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003640 * \retval #PSA_ERROR_CORRUPTION_DETECTED
itayzafrir0adf0fc2018-09-06 16:24:41 +03003641 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03003642 * The library has not been previously initialized by psa_crypto_init().
3643 * It is implementation-dependent whether a failure to initialize
3644 * results in this error code.
Gilles Peskine9e7dc712018-03-28 14:18:50 +02003645 */
3646psa_status_t psa_generate_random(uint8_t *output,
3647 size_t output_size);
3648
3649/**
3650 * \brief Generate a key or key pair.
3651 *
Gilles Peskinee56e8782019-04-26 17:34:02 +02003652 * The key is generated randomly.
Gilles Peskinea170d922019-09-12 16:59:37 +02003653 * Its location, usage policy, type and size are taken from \p attributes.
Gilles Peskinee56e8782019-04-26 17:34:02 +02003654 *
Gilles Peskine05c900b2019-09-12 18:29:43 +02003655 * Implementations must reject an attempt to generate a key of size 0.
Gilles Peskinee56e8782019-04-26 17:34:02 +02003656 *
Gilles Peskine20a77ae2019-05-16 14:05:56 +02003657 * The following type-specific considerations apply:
Gilles Peskinec93b80c2019-05-16 19:39:54 +02003658 * - For RSA keys (#PSA_KEY_TYPE_RSA_KEY_PAIR),
Gilles Peskine20a77ae2019-05-16 14:05:56 +02003659 * the public exponent is 65537.
3660 * The modulus is a product of two probabilistic primes
3661 * between 2^{n-1} and 2^n where n is the bit size specified in the
3662 * attributes.
3663 *
Gilles Peskine20628592019-04-19 19:29:50 +02003664 * \param[in] attributes The attributes for the new key.
Gilles Peskine20628592019-04-19 19:29:50 +02003665 * \param[out] handle On success, a handle to the newly created key.
3666 * \c 0 on failure.
Gilles Peskine9e7dc712018-03-28 14:18:50 +02003667 *
Gilles Peskine28538492018-07-11 17:34:00 +02003668 * \retval #PSA_SUCCESS
Gilles Peskine23fd2bd2018-12-11 15:51:32 +01003669 * Success.
3670 * If the key is persistent, the key material and the key's metadata
3671 * have been saved to persistent storage.
David Saadab4ecc272019-02-14 13:48:10 +02003672 * \retval #PSA_ERROR_ALREADY_EXISTS
Gilles Peskine20628592019-04-19 19:29:50 +02003673 * This is an attempt to create a persistent key, and there is
3674 * already a persistent key with the given identifier.
Gilles Peskine28538492018-07-11 17:34:00 +02003675 * \retval #PSA_ERROR_NOT_SUPPORTED
3676 * \retval #PSA_ERROR_INVALID_ARGUMENT
3677 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3678 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
3679 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3680 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003681 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawd21c6e62019-08-08 10:58:08 +01003682 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
3683 * \retval #PSA_ERROR_STORAGE_FAILURE
itayzafrir90d8c7a2018-09-12 11:44:52 +03003684 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03003685 * The library has not been previously initialized by psa_crypto_init().
3686 * It is implementation-dependent whether a failure to initialize
3687 * results in this error code.
Gilles Peskine9e7dc712018-03-28 14:18:50 +02003688 */
Gilles Peskine35ef36b2019-05-16 19:42:05 +02003689psa_status_t psa_generate_key(const psa_key_attributes_t *attributes,
Gilles Peskinee56e8782019-04-26 17:34:02 +02003690 psa_key_handle_t *handle);
Gilles Peskine9e7dc712018-03-28 14:18:50 +02003691
3692/**@}*/
3693
Gilles Peskinee59236f2018-01-27 23:32:46 +01003694#ifdef __cplusplus
3695}
3696#endif
3697
Gilles Peskine0cad07c2018-06-27 19:49:02 +02003698/* The file "crypto_sizes.h" contains definitions for size calculation
3699 * macros whose definitions are implementation-specific. */
3700#include "crypto_sizes.h"
3701
Gilles Peskine9ef733f2018-02-07 21:05:37 +01003702/* The file "crypto_struct.h" contains definitions for
3703 * implementation-specific structs that are declared above. */
3704#include "crypto_struct.h"
3705
3706/* The file "crypto_extra.h" contains vendor-specific definitions. This
3707 * can include vendor-defined algorithms, extra functions, etc. */
Gilles Peskinee59236f2018-01-27 23:32:46 +01003708#include "crypto_extra.h"
3709
3710#endif /* PSA_CRYPTO_H */