blob: de79c9b21039caa4dc9d11aea0532b5f43e90111 [file] [log] [blame]
Gilles Peskinee59236f2018-01-27 23:32:46 +01001/**
2 * \file psa/crypto.h
3 * \brief Platform Security Architecture cryptography module
4 */
Jaeden Amerocab54942018-07-25 13:26:13 +01005/*
6 * Copyright (C) 2018, ARM Limited, All Rights Reserved
7 * SPDX-License-Identifier: Apache-2.0
8 *
9 * Licensed under the Apache License, Version 2.0 (the "License"); you may
10 * not use this file except in compliance with the License.
11 * You may obtain a copy of the License at
12 *
13 * http://www.apache.org/licenses/LICENSE-2.0
14 *
15 * Unless required by applicable law or agreed to in writing, software
16 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
17 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
18 * See the License for the specific language governing permissions and
19 * limitations under the License.
20 */
Gilles Peskinee59236f2018-01-27 23:32:46 +010021
22#ifndef PSA_CRYPTO_H
23#define PSA_CRYPTO_H
24
25#include "crypto_platform.h"
26
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +010027#include <stddef.h>
28
Gilles Peskine62a7e7e2018-02-07 21:54:47 +010029#ifdef __DOXYGEN_ONLY__
Gilles Peskinef5b9fa12018-03-07 16:40:18 +010030/* This __DOXYGEN_ONLY__ block contains mock definitions for things that
31 * must be defined in the crypto_platform.h header. These mock definitions
32 * are present in this file as a convenience to generate pretty-printed
33 * documentation that includes those definitions. */
34
Gilles Peskine62a7e7e2018-02-07 21:54:47 +010035/** \defgroup platform Implementation-specific definitions
36 * @{
37 */
38
Gilles Peskineae32aac2018-11-30 14:39:32 +010039/** \brief Key handle.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +010040 *
Gilles Peskineae32aac2018-11-30 14:39:32 +010041 * This type represents open handles to keys. It must be an unsigned integral
Gilles Peskine308b91d2018-02-08 09:47:44 +010042 * type. The choice of type is implementation-dependent.
Gilles Peskineae32aac2018-11-30 14:39:32 +010043 *
Gilles Peskine23fd2bd2018-12-11 15:51:32 +010044 * 0 is not a valid key handle. How other handle values are assigned is
45 * implementation-dependent.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +010046 */
Gilles Peskineae32aac2018-11-30 14:39:32 +010047typedef _unsigned_integral_type_ psa_key_handle_t;
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +010048
Gilles Peskine62a7e7e2018-02-07 21:54:47 +010049/**@}*/
Gilles Peskinef5b9fa12018-03-07 16:40:18 +010050#endif /* __DOXYGEN_ONLY__ */
Gilles Peskine62a7e7e2018-02-07 21:54:47 +010051
Gilles Peskinee59236f2018-01-27 23:32:46 +010052#ifdef __cplusplus
53extern "C" {
54#endif
55
Gilles Peskinef3b731e2018-12-12 13:38:31 +010056/* The file "crypto_types.h" declares types that encode errors,
57 * algorithms, key types, policies, etc. */
58#include "crypto_types.h"
59
60/* The file "crypto_values.h" declares macros to build and analyze values
61 * of integral types defined in "crypto_types.h". */
62#include "crypto_values.h"
63
64/** \defgroup initialization Library initialization
Gilles Peskinee59236f2018-01-27 23:32:46 +010065 * @{
66 */
67
68/**
Gilles Peskinee59236f2018-01-27 23:32:46 +010069 * \brief Library initialization.
70 *
71 * Applications must call this function before calling any other
72 * function in this module.
73 *
74 * Applications may call this function more than once. Once a call
75 * succeeds, subsequent calls are guaranteed to succeed.
76 *
itayzafrir18617092018-09-16 12:22:41 +030077 * If the application calls other functions before calling psa_crypto_init(),
78 * the behavior is undefined. Implementations are encouraged to either perform
79 * the operation as if the library had been initialized or to return
80 * #PSA_ERROR_BAD_STATE or some other applicable error. In particular,
81 * implementations should not return a success status if the lack of
82 * initialization may have security implications, for example due to improper
83 * seeding of the random number generator.
84 *
Gilles Peskine28538492018-07-11 17:34:00 +020085 * \retval #PSA_SUCCESS
86 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
87 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
88 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +020089 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine28538492018-07-11 17:34:00 +020090 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
Gilles Peskinee59236f2018-01-27 23:32:46 +010091 */
92psa_status_t psa_crypto_init(void);
93
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +010094/**@}*/
95
Gilles Peskine105f67f2019-07-23 18:16:05 +020096/** \addtogroup attributes
Gilles Peskine87a5e562019-04-17 12:28:25 +020097 * @{
98 */
99
Gilles Peskinea0c06552019-05-21 15:54:54 +0200100/** \def PSA_KEY_ATTRIBUTES_INIT
101 *
102 * This macro returns a suitable initializer for a key attribute structure
103 * of type #psa_key_attributes_t.
104 */
105#ifdef __DOXYGEN_ONLY__
106/* This is an example definition for documentation purposes.
107 * Implementations should define a suitable value in `crypto_struct.h`.
108 */
109#define PSA_KEY_ATTRIBUTES_INIT {0}
110#endif
111
112/** Return an initial value for a key attributes structure.
113 */
114static psa_key_attributes_t psa_key_attributes_init(void);
115
Gilles Peskinedc8219a2019-05-15 16:11:15 +0200116/** Declare a key as persistent and set its key identifier.
Gilles Peskine20628592019-04-19 19:29:50 +0200117 *
Gilles Peskinef1b76942019-05-16 16:10:59 +0200118 * If the attribute structure currently declares the key as volatile (which
119 * is the default content of an attribute structure), this function sets
Gilles Peskinedc8219a2019-05-15 16:11:15 +0200120 * the lifetime attribute to #PSA_KEY_LIFETIME_PERSISTENT.
Gilles Peskine20628592019-04-19 19:29:50 +0200121 *
Gilles Peskinef1b76942019-05-16 16:10:59 +0200122 * This function does not access storage, it merely stores the given
123 * value in the structure.
124 * The persistent key will be written to storage when the attribute
125 * structure is passed to a key creation function such as
Gilles Peskine35ef36b2019-05-16 19:42:05 +0200126 * psa_import_key(), psa_generate_key(),
Gilles Peskinea99d3fb2019-05-16 15:28:51 +0200127 * psa_key_derivation_output_key() or psa_copy_key().
Gilles Peskine20628592019-04-19 19:29:50 +0200128 *
Gilles Peskine20628592019-04-19 19:29:50 +0200129 * This function may be declared as `static` (i.e. without external
130 * linkage). This function may be provided as a function-like macro,
131 * but in this case it must evaluate each of its arguments exactly once.
132 *
133 * \param[out] attributes The attribute structure to write to.
134 * \param id The persistent identifier for the key.
Gilles Peskinedc8219a2019-05-15 16:11:15 +0200135 */
136static void psa_set_key_id(psa_key_attributes_t *attributes,
137 psa_key_id_t id);
138
139/** Set the location of a persistent key.
140 *
141 * To make a key persistent, you must give it a persistent key identifier
Gilles Peskinef1b76942019-05-16 16:10:59 +0200142 * with psa_set_key_id(). By default, a key that has a persistent identifier
143 * is stored in the default storage area identifier by
144 * #PSA_KEY_LIFETIME_PERSISTENT. Call this function to choose a storage
145 * area, or to explicitly declare the key as volatile.
Gilles Peskinedc8219a2019-05-15 16:11:15 +0200146 *
Gilles Peskinef1b76942019-05-16 16:10:59 +0200147 * This function does not access storage, it merely stores the given
148 * value in the structure.
149 * The persistent key will be written to storage when the attribute
150 * structure is passed to a key creation function such as
Gilles Peskine35ef36b2019-05-16 19:42:05 +0200151 * psa_import_key(), psa_generate_key(),
Gilles Peskinea99d3fb2019-05-16 15:28:51 +0200152 * psa_key_derivation_output_key() or psa_copy_key().
Gilles Peskinedc8219a2019-05-15 16:11:15 +0200153 *
154 * This function may be declared as `static` (i.e. without external
155 * linkage). This function may be provided as a function-like macro,
156 * but in this case it must evaluate each of its arguments exactly once.
157 *
158 * \param[out] attributes The attribute structure to write to.
Gilles Peskine20628592019-04-19 19:29:50 +0200159 * \param lifetime The lifetime for the key.
160 * If this is #PSA_KEY_LIFETIME_VOLATILE, the
Gilles Peskinedc8219a2019-05-15 16:11:15 +0200161 * key will be volatile, and the key identifier
162 * attribute is reset to 0.
Gilles Peskine20628592019-04-19 19:29:50 +0200163 */
Gilles Peskinedc8219a2019-05-15 16:11:15 +0200164static void psa_set_key_lifetime(psa_key_attributes_t *attributes,
165 psa_key_lifetime_t lifetime);
Gilles Peskine4747d192019-04-17 15:05:45 +0200166
Gilles Peskine20628592019-04-19 19:29:50 +0200167/** Retrieve the key identifier from key attributes.
168 *
169 * This function may be declared as `static` (i.e. without external
170 * linkage). This function may be provided as a function-like macro,
171 * but in this case it must evaluate its argument exactly once.
172 *
173 * \param[in] attributes The key attribute structure to query.
174 *
175 * \return The persistent identifier stored in the attribute structure.
176 * This value is unspecified if the attribute structure declares
177 * the key as volatile.
178 */
Gilles Peskine4747d192019-04-17 15:05:45 +0200179static psa_key_id_t psa_get_key_id(const psa_key_attributes_t *attributes);
180
Gilles Peskine20628592019-04-19 19:29:50 +0200181/** Retrieve the lifetime from key attributes.
182 *
183 * This function may be declared as `static` (i.e. without external
184 * linkage). This function may be provided as a function-like macro,
185 * but in this case it must evaluate its argument exactly once.
186 *
187 * \param[in] attributes The key attribute structure to query.
188 *
189 * \return The lifetime value stored in the attribute structure.
190 */
Gilles Peskine4747d192019-04-17 15:05:45 +0200191static psa_key_lifetime_t psa_get_key_lifetime(
192 const psa_key_attributes_t *attributes);
193
Gilles Peskine20628592019-04-19 19:29:50 +0200194/** Declare usage flags for a key.
195 *
196 * Usage flags are part of a key's usage policy. They encode what
197 * kind of operations are permitted on the key. For more details,
198 * refer to the documentation of the type #psa_key_usage_t.
199 *
200 * This function overwrites any usage flags
201 * previously set in \p attributes.
202 *
203 * This function may be declared as `static` (i.e. without external
204 * linkage). This function may be provided as a function-like macro,
205 * but in this case it must evaluate each of its arguments exactly once.
206 *
207 * \param[out] attributes The attribute structure to write to.
208 * \param usage_flags The usage flags to write.
209 */
Gilles Peskine4747d192019-04-17 15:05:45 +0200210static void psa_set_key_usage_flags(psa_key_attributes_t *attributes,
211 psa_key_usage_t usage_flags);
212
Gilles Peskine20628592019-04-19 19:29:50 +0200213/** Retrieve the usage flags from key attributes.
214 *
215 * This function may be declared as `static` (i.e. without external
216 * linkage). This function may be provided as a function-like macro,
217 * but in this case it must evaluate its argument exactly once.
218 *
219 * \param[in] attributes The key attribute structure to query.
220 *
221 * \return The usage flags stored in the attribute structure.
222 */
Gilles Peskine4747d192019-04-17 15:05:45 +0200223static psa_key_usage_t psa_get_key_usage_flags(
224 const psa_key_attributes_t *attributes);
225
Gilles Peskine20628592019-04-19 19:29:50 +0200226/** Declare the permitted algorithm policy for a key.
227 *
228 * The permitted algorithm policy of a key encodes which algorithm or
229 * algorithms are permitted to be used with this key.
230 *
231 * This function overwrites any algorithm policy
232 * previously set in \p attributes.
233 *
234 * This function may be declared as `static` (i.e. without external
235 * linkage). This function may be provided as a function-like macro,
236 * but in this case it must evaluate each of its arguments exactly once.
237 *
238 * \param[out] attributes The attribute structure to write to.
239 * \param alg The permitted algorithm policy to write.
240 */
Gilles Peskine4747d192019-04-17 15:05:45 +0200241static void psa_set_key_algorithm(psa_key_attributes_t *attributes,
242 psa_algorithm_t alg);
243
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +0100244
Gilles Peskine20628592019-04-19 19:29:50 +0200245/** Retrieve the algorithm policy from key attributes.
246 *
247 * This function may be declared as `static` (i.e. without external
248 * linkage). This function may be provided as a function-like macro,
249 * but in this case it must evaluate its argument exactly once.
250 *
251 * \param[in] attributes The key attribute structure to query.
252 *
253 * \return The algorithm stored in the attribute structure.
254 */
Gilles Peskine4747d192019-04-17 15:05:45 +0200255static psa_algorithm_t psa_get_key_algorithm(
256 const psa_key_attributes_t *attributes);
257
Gilles Peskine20628592019-04-19 19:29:50 +0200258/** Declare the type of a key.
259 *
Gilles Peskine24f10f82019-05-16 12:18:32 +0200260 * This function overwrites any key type
Gilles Peskine20628592019-04-19 19:29:50 +0200261 * previously set in \p attributes.
262 *
263 * This function may be declared as `static` (i.e. without external
264 * linkage). This function may be provided as a function-like macro,
265 * but in this case it must evaluate each of its arguments exactly once.
266 *
267 * \param[out] attributes The attribute structure to write to.
268 * \param type The key type to write.
269 */
Gilles Peskine4747d192019-04-17 15:05:45 +0200270static void psa_set_key_type(psa_key_attributes_t *attributes,
271 psa_key_type_t type);
272
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +0100273
Gilles Peskine3a4f1f82019-04-26 13:49:28 +0200274/** Declare the size of a key.
275 *
276 * This function overwrites any key size previously set in \p attributes.
277 *
278 * This function may be declared as `static` (i.e. without external
279 * linkage). This function may be provided as a function-like macro,
280 * but in this case it must evaluate each of its arguments exactly once.
281 *
282 * \param[out] attributes The attribute structure to write to.
283 * \param bits The key size in bits.
284 */
285static void psa_set_key_bits(psa_key_attributes_t *attributes,
286 size_t bits);
287
Gilles Peskine20628592019-04-19 19:29:50 +0200288/** Retrieve the key type from key attributes.
289 *
290 * This function may be declared as `static` (i.e. without external
291 * linkage). This function may be provided as a function-like macro,
292 * but in this case it must evaluate its argument exactly once.
293 *
294 * \param[in] attributes The key attribute structure to query.
295 *
296 * \return The key type stored in the attribute structure.
297 */
Gilles Peskine4747d192019-04-17 15:05:45 +0200298static psa_key_type_t psa_get_key_type(const psa_key_attributes_t *attributes);
299
Gilles Peskine20628592019-04-19 19:29:50 +0200300/** Retrieve the key size from key attributes.
301 *
302 * This function may be declared as `static` (i.e. without external
303 * linkage). This function may be provided as a function-like macro,
304 * but in this case it must evaluate its argument exactly once.
305 *
306 * \param[in] attributes The key attribute structure to query.
307 *
308 * \return The key size stored in the attribute structure, in bits.
309 */
Gilles Peskine4747d192019-04-17 15:05:45 +0200310static size_t psa_get_key_bits(const psa_key_attributes_t *attributes);
311
Gilles Peskine20628592019-04-19 19:29:50 +0200312/** Retrieve the attributes of a key.
313 *
314 * This function first resets the attribute structure as with
Gilles Peskine9c640f92019-04-28 11:36:21 +0200315 * psa_reset_key_attributes(). It then copies the attributes of
316 * the given key into the given attribute structure.
Gilles Peskine20628592019-04-19 19:29:50 +0200317 *
Gilles Peskine9c640f92019-04-28 11:36:21 +0200318 * \note This function may allocate memory or other resources.
319 * Once you have called this function on an attribute structure,
320 * you must call psa_reset_key_attributes() to free these resources.
Gilles Peskine20628592019-04-19 19:29:50 +0200321 *
Gilles Peskine20628592019-04-19 19:29:50 +0200322 * \param[in] handle Handle to the key to query.
323 * \param[in,out] attributes On success, the attributes of the key.
324 * On failure, equivalent to a
325 * freshly-initialized structure.
326 *
327 * \retval #PSA_SUCCESS
328 * \retval #PSA_ERROR_INVALID_HANDLE
329 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
330 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
Adrian L. Shaw29b64072019-08-06 16:02:12 +0100331 * \retval #PSA_ERROR_CORRUPTION_DETECTED
332 * \retval #PSA_ERROR_STORAGE_FAILURE
Gilles Peskine20628592019-04-19 19:29:50 +0200333 */
Gilles Peskine4747d192019-04-17 15:05:45 +0200334psa_status_t psa_get_key_attributes(psa_key_handle_t handle,
335 psa_key_attributes_t *attributes);
336
Gilles Peskine20628592019-04-19 19:29:50 +0200337/** Reset a key attribute structure to a freshly initialized state.
338 *
339 * You must initialize the attribute structure as described in the
340 * documentation of the type #psa_key_attributes_t before calling this
341 * function. Once the structure has been initialized, you may call this
342 * function at any time.
343 *
344 * This function frees any auxiliary resources that the structure
345 * may contain.
346 *
347 * \param[in,out] attributes The attribute structure to reset.
348 */
Gilles Peskine8c8f2ab2019-04-18 21:44:46 +0200349void psa_reset_key_attributes(psa_key_attributes_t *attributes);
Gilles Peskine4747d192019-04-17 15:05:45 +0200350
Gilles Peskine87a5e562019-04-17 12:28:25 +0200351/**@}*/
352
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100353/** \defgroup key_management Key management
354 * @{
355 */
356
Gilles Peskinef535eb22018-11-30 14:08:36 +0100357/** Open a handle to an existing persistent key.
358 *
Gilles Peskine4754cde2019-05-21 15:56:29 +0200359 * Open a handle to a persistent key. A key is persistent if it was created
360 * with a lifetime other than #PSA_KEY_LIFETIME_VOLATILE. A persistent key
361 * always has a nonzero key identifier, set with psa_set_key_id() when
362 * creating the key. Implementations may provide additional pre-provisioned
Andrew Thoelke203491c2019-08-21 17:55:30 +0100363 * keys that can be opened with psa_open_key(). Such keys have a key identifier
364 * in the vendor range, as documented in the description of #psa_key_id_t.
Gilles Peskine4754cde2019-05-21 15:56:29 +0200365 *
366 * The application must eventually close the handle with psa_close_key()
367 * to release associated resources. If the application dies without calling
368 * psa_close_key(), the implementation should perform the equivalent of a
369 * call to psa_close_key().
Gilles Peskinef535eb22018-11-30 14:08:36 +0100370 *
Andrew Thoelke9741b112019-08-21 18:20:41 +0100371 * Some implementations permit an application to open the same key multiple
372 * times. Applications that rely on this behavior will not be portable to
373 * implementations that only permit a single key handle to be opened. See
374 * also :ref:\`key-handles\`.
375 *
Gilles Peskinef535eb22018-11-30 14:08:36 +0100376 * \param id The persistent identifier of the key.
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +0100377 * \param[out] handle On success, a handle to the key.
Gilles Peskinef535eb22018-11-30 14:08:36 +0100378 *
379 * \retval #PSA_SUCCESS
380 * Success. The application can now use the value of `*handle`
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +0100381 * to access the key.
Gilles Peskinef535eb22018-11-30 14:08:36 +0100382 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
Andrew Thoelke9741b112019-08-21 18:20:41 +0100383 * The implementation does not have sufficient resources to open the
384 * key. This can be due to reaching an implementation limit on the
385 * number of open keys, the number of open key handles, or available
386 * memory.
David Saadab4ecc272019-02-14 13:48:10 +0200387 * \retval #PSA_ERROR_DOES_NOT_EXIST
Andrew Thoelke9741b112019-08-21 18:20:41 +0100388 * There is no persistent key with key identifier \p id.
Gilles Peskinef535eb22018-11-30 14:08:36 +0100389 * \retval #PSA_ERROR_INVALID_ARGUMENT
Andrew Thoelke9741b112019-08-21 18:20:41 +0100390 * \p id is not a valid persistent key identifier.
Gilles Peskinef535eb22018-11-30 14:08:36 +0100391 * \retval #PSA_ERROR_NOT_PERMITTED
392 * The specified key exists, but the application does not have the
393 * permission to access it. Note that this specification does not
394 * define any way to create such a key, but it may be possible
395 * through implementation-specific means.
Gilles Peskine225010f2019-05-06 18:44:55 +0200396 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
397 * \retval #PSA_ERROR_STORAGE_FAILURE
Gilles Peskinef535eb22018-11-30 14:08:36 +0100398 */
Gilles Peskine225010f2019-05-06 18:44:55 +0200399psa_status_t psa_open_key(psa_key_id_t id,
Gilles Peskinef535eb22018-11-30 14:08:36 +0100400 psa_key_handle_t *handle);
401
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +0100402
Gilles Peskinef535eb22018-11-30 14:08:36 +0100403/** Close a key handle.
404 *
Andrew Thoelke3daba812019-08-21 22:46:56 +0100405 * If the handle designates a volatile key, this will destroy the key material
406 * and free all associated resources, just like psa_destroy_key().
Gilles Peskinef535eb22018-11-30 14:08:36 +0100407 *
Andrew Thoelke3daba812019-08-21 22:46:56 +0100408 * If this is the last open handle to a persistent key, then closing the handle
409 * will free all resources associated with the key in volatile memory. The key
410 * data in persistent storage is not affected and can be opened again later
411 * with a call to psa_open_key().
Gilles Peskinef535eb22018-11-30 14:08:36 +0100412 *
Andrew Thoelke3daba812019-08-21 22:46:56 +0100413 * Closing the key handle makes the handle invalid, and the key handle
Andrew Thoelke8824dae2019-08-22 15:04:48 +0100414 * must not be used again by the application.
Andrew Thoelke3daba812019-08-21 22:46:56 +0100415 *
416 * If the key is currently in use in a multipart operation, then closing the
Andrew Thoelke8824dae2019-08-22 15:04:48 +0100417 * last remaining handle to the key will abort the multipart operation.
Gilles Peskine5f25dd02019-01-14 18:24:53 +0100418 *
Gilles Peskinef535eb22018-11-30 14:08:36 +0100419 * \param handle The key handle to close.
420 *
421 * \retval #PSA_SUCCESS
422 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskineae32aac2018-11-30 14:39:32 +0100423 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
Gilles Peskinef535eb22018-11-30 14:08:36 +0100424 */
425psa_status_t psa_close_key(psa_key_handle_t handle);
426
Gilles Peskine3cac8c42018-11-30 14:07:45 +0100427/**@}*/
428
429/** \defgroup import_export Key import and export
430 * @{
431 */
432
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100433/**
434 * \brief Import a key in binary format.
435 *
Gilles Peskinef5b9fa12018-03-07 16:40:18 +0100436 * This function supports any output from psa_export_key(). Refer to the
Gilles Peskinef7933932018-10-31 14:07:52 +0100437 * documentation of psa_export_public_key() for the format of public keys
438 * and to the documentation of psa_export_key() for the format for
439 * other key types.
440 *
441 * This specification supports a single format for each key type.
442 * Implementations may support other formats as long as the standard
443 * format is supported. Implementations that support other formats
444 * should ensure that the formats are clearly unambiguous so as to
445 * minimize the risk that an invalid input is accidentally interpreted
446 * according to a different format.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100447 *
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +0100448
Gilles Peskine20628592019-04-19 19:29:50 +0200449 * \param[in] attributes The attributes for the new key.
Gilles Peskine4ce2a9d2019-05-03 16:57:15 +0200450 * The key size is always determined from the
451 * \p data buffer.
452 * If the key size in \p attributes is nonzero,
453 * it must be equal to the size from \p data.
Gilles Peskine20628592019-04-19 19:29:50 +0200454 * \param[out] handle On success, a handle to the newly created key.
455 * \c 0 on failure.
Gilles Peskinef7933932018-10-31 14:07:52 +0100456 * \param[in] data Buffer containing the key data. The content of this
Gilles Peskine24f10f82019-05-16 12:18:32 +0200457 * buffer is interpreted according to the type declared
458 * in \p attributes.
Gilles Peskine20628592019-04-19 19:29:50 +0200459 * All implementations must support at least the format
460 * described in the documentation
Gilles Peskinef7933932018-10-31 14:07:52 +0100461 * of psa_export_key() or psa_export_public_key() for
Gilles Peskine20628592019-04-19 19:29:50 +0200462 * the chosen type. Implementations may allow other
463 * formats, but should be conservative: implementations
464 * should err on the side of rejecting content if it
465 * may be erroneous (e.g. wrong type or truncated data).
Gilles Peskinefa4070c2018-07-12 19:23:03 +0200466 * \param data_length Size of the \p data buffer in bytes.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100467 *
Gilles Peskine28538492018-07-11 17:34:00 +0200468 * \retval #PSA_SUCCESS
Gilles Peskine308b91d2018-02-08 09:47:44 +0100469 * Success.
Gilles Peskine23fd2bd2018-12-11 15:51:32 +0100470 * If the key is persistent, the key material and the key's metadata
471 * have been saved to persistent storage.
Gilles Peskine20628592019-04-19 19:29:50 +0200472 * \retval #PSA_ERROR_ALREADY_EXISTS
473 * This is an attempt to create a persistent key, and there is
474 * already a persistent key with the given identifier.
Gilles Peskine28538492018-07-11 17:34:00 +0200475 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskine65eb8582018-04-19 08:28:58 +0200476 * The key type or key size is not supported, either by the
Gilles Peskine20628592019-04-19 19:29:50 +0200477 * implementation in general or in this particular persistent location.
Gilles Peskine28538492018-07-11 17:34:00 +0200478 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine4ce2a9d2019-05-03 16:57:15 +0200479 * The key attributes, as a whole, are invalid.
480 * \retval #PSA_ERROR_INVALID_ARGUMENT
481 * The key data is not correctly formatted.
482 * \retval #PSA_ERROR_INVALID_ARGUMENT
483 * The size in \p attributes is nonzero and does not match the size
484 * of the key data.
Gilles Peskine28538492018-07-11 17:34:00 +0200485 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
486 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
487 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
Darryl Greend49a4992018-06-18 17:27:26 +0100488 * \retval #PSA_ERROR_STORAGE_FAILURE
Gilles Peskine28538492018-07-11 17:34:00 +0200489 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +0200490 * \retval #PSA_ERROR_CORRUPTION_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +0300491 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +0300492 * The library has not been previously initialized by psa_crypto_init().
493 * It is implementation-dependent whether a failure to initialize
494 * results in this error code.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100495 */
Gilles Peskine87a5e562019-04-17 12:28:25 +0200496psa_status_t psa_import_key(const psa_key_attributes_t *attributes,
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100497 const uint8_t *data,
Gilles Peskine73676cb2019-05-15 20:15:10 +0200498 size_t data_length,
499 psa_key_handle_t *handle);
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100500
501/**
Gilles Peskineae32aac2018-11-30 14:39:32 +0100502 * \brief Destroy a key.
Gilles Peskine154bd952018-04-19 08:38:16 +0200503 *
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +0100504 * This function destroys a key from both volatile
Gilles Peskine154bd952018-04-19 08:38:16 +0200505 * memory and, if applicable, non-volatile storage. Implementations shall
Adrian L. Shawd56456c2019-05-15 11:36:13 +0100506 * make a best effort to ensure that that the key material cannot be recovered.
Gilles Peskine154bd952018-04-19 08:38:16 +0200507 *
Gilles Peskineae32aac2018-11-30 14:39:32 +0100508 * This function also erases any metadata such as policies and frees all
509 * resources associated with the key.
Gilles Peskine154bd952018-04-19 08:38:16 +0200510 *
Andrew Thoelke07f16b72019-08-21 22:48:47 +0100511 * Destroying a key will invalidate all existing handles to the key.
512 *
513 * If the key is currently in use in a multipart operation, then destroying the
514 * key will abort the multipart operation.
515 *
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +0100516 * \param handle Handle to the key to erase.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100517 *
Gilles Peskine28538492018-07-11 17:34:00 +0200518 * \retval #PSA_SUCCESS
Adrian L. Shawd56456c2019-05-15 11:36:13 +0100519 * The key material has been erased.
Gilles Peskine28538492018-07-11 17:34:00 +0200520 * \retval #PSA_ERROR_NOT_PERMITTED
Adrian L. Shaw0a695bd2019-05-15 13:28:41 +0100521 * The key cannot be erased because it is
Gilles Peskine65eb8582018-04-19 08:28:58 +0200522 * read-only, either due to a policy or due to physical restrictions.
Gilles Peskineae32aac2018-11-30 14:39:32 +0100523 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine28538492018-07-11 17:34:00 +0200524 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
Gilles Peskine65eb8582018-04-19 08:28:58 +0200525 * There was an failure in communication with the cryptoprocessor.
526 * The key material may still be present in the cryptoprocessor.
Gilles Peskine28538492018-07-11 17:34:00 +0200527 * \retval #PSA_ERROR_STORAGE_FAILURE
Gilles Peskine65eb8582018-04-19 08:28:58 +0200528 * The storage is corrupted. Implementations shall make a best effort
529 * to erase key material even in this stage, however applications
530 * should be aware that it may be impossible to guarantee that the
531 * key material is not recoverable in such cases.
Gilles Peskine4b3eb692019-05-16 21:35:18 +0200532 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine65eb8582018-04-19 08:28:58 +0200533 * An unexpected condition which is not a storage corruption or
534 * a communication failure occurred. The cryptoprocessor may have
535 * been compromised.
itayzafrir90d8c7a2018-09-12 11:44:52 +0300536 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +0300537 * The library has not been previously initialized by psa_crypto_init().
538 * It is implementation-dependent whether a failure to initialize
539 * results in this error code.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100540 */
Gilles Peskineae32aac2018-11-30 14:39:32 +0100541psa_status_t psa_destroy_key(psa_key_handle_t handle);
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100542
543/**
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100544 * \brief Export a key in binary format.
545 *
546 * The output of this function can be passed to psa_import_key() to
547 * create an equivalent object.
548 *
Gilles Peskinef7933932018-10-31 14:07:52 +0100549 * If the implementation of psa_import_key() supports other formats
550 * beyond the format specified here, the output from psa_export_key()
551 * must use the representation specified here, not the original
552 * representation.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100553 *
Gilles Peskine308b91d2018-02-08 09:47:44 +0100554 * For standard key types, the output format is as follows:
555 *
556 * - For symmetric keys (including MAC keys), the format is the
557 * raw bytes of the key.
558 * - For DES, the key data consists of 8 bytes. The parity bits must be
559 * correct.
560 * - For Triple-DES, the format is the concatenation of the
561 * two or three DES keys.
Gilles Peskinec93b80c2019-05-16 19:39:54 +0200562 * - For RSA key pairs (#PSA_KEY_TYPE_RSA_KEY_PAIR), the format
Gilles Peskine4e1e9be2018-08-10 18:57:40 +0200563 * is the non-encrypted DER encoding of the representation defined by
564 * PKCS\#1 (RFC 8017) as `RSAPrivateKey`, version 0.
565 * ```
566 * RSAPrivateKey ::= SEQUENCE {
Gilles Peskine4f6c77b2018-08-11 01:17:53 +0200567 * version INTEGER, -- must be 0
Gilles Peskine4e1e9be2018-08-10 18:57:40 +0200568 * modulus INTEGER, -- n
569 * publicExponent INTEGER, -- e
570 * privateExponent INTEGER, -- d
571 * prime1 INTEGER, -- p
572 * prime2 INTEGER, -- q
573 * exponent1 INTEGER, -- d mod (p-1)
574 * exponent2 INTEGER, -- d mod (q-1)
575 * coefficient INTEGER, -- (inverse of q) mod p
576 * }
577 * ```
Gilles Peskine4e1e9be2018-08-10 18:57:40 +0200578 * - For elliptic curve key pairs (key types for which
Gilles Peskinec93b80c2019-05-16 19:39:54 +0200579 * #PSA_KEY_TYPE_IS_ECC_KEY_PAIR is true), the format is
Gilles Peskine6c6a0232018-11-15 17:44:43 +0100580 * a representation of the private value as a `ceiling(m/8)`-byte string
581 * where `m` is the bit size associated with the curve, i.e. the bit size
582 * of the order of the curve's coordinate field. This byte string is
583 * in little-endian order for Montgomery curves (curve types
584 * `PSA_ECC_CURVE_CURVEXXX`), and in big-endian order for Weierstrass
585 * curves (curve types `PSA_ECC_CURVE_SECTXXX`, `PSA_ECC_CURVE_SECPXXX`
586 * and `PSA_ECC_CURVE_BRAINPOOL_PXXX`).
Gilles Peskinef76aa772018-10-29 19:24:33 +0100587 * This is the content of the `privateKey` field of the `ECPrivateKey`
588 * format defined by RFC 5915.
Gilles Peskinedcaefae2019-05-16 12:55:35 +0200589 * - For Diffie-Hellman key exchange key pairs (key types for which
Gilles Peskinec93b80c2019-05-16 19:39:54 +0200590 * #PSA_KEY_TYPE_IS_DH_KEY_PAIR is true), the
Jaeden Amero8851c402019-01-11 14:20:03 +0000591 * format is the representation of the private key `x` as a big-endian byte
592 * string. The length of the byte string is the private key size in bytes
593 * (leading zeroes are not stripped).
Gilles Peskine4e1e9be2018-08-10 18:57:40 +0200594 * - For public keys (key types for which #PSA_KEY_TYPE_IS_PUBLIC_KEY is
595 * true), the format is the same as for psa_export_public_key().
Gilles Peskine308b91d2018-02-08 09:47:44 +0100596 *
Gilles Peskine4318dfc2019-05-14 14:23:32 +0200597 * The policy on the key must have the usage flag #PSA_KEY_USAGE_EXPORT set.
598 *
Gilles Peskineae32aac2018-11-30 14:39:32 +0100599 * \param handle Handle to the key to export.
Gilles Peskineedd11a12018-07-12 01:08:58 +0200600 * \param[out] data Buffer where the key data is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +0200601 * \param data_size Size of the \p data buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +0200602 * \param[out] data_length On success, the number of bytes
603 * that make up the key data.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100604 *
Gilles Peskine28538492018-07-11 17:34:00 +0200605 * \retval #PSA_SUCCESS
Gilles Peskineae32aac2018-11-30 14:39:32 +0100606 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine28538492018-07-11 17:34:00 +0200607 * \retval #PSA_ERROR_NOT_PERMITTED
Gilles Peskine4318dfc2019-05-14 14:23:32 +0200608 * The key does not have the #PSA_KEY_USAGE_EXPORT flag.
Darryl Green9e2d7a02018-07-24 16:33:30 +0100609 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskine1be949b2018-08-10 19:06:59 +0200610 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
611 * The size of the \p data buffer is too small. You can determine a
612 * sufficient buffer size by calling
613 * #PSA_KEY_EXPORT_MAX_SIZE(\c type, \c bits)
614 * where \c type is the key type
615 * and \c bits is the key size in bits.
Gilles Peskine28538492018-07-11 17:34:00 +0200616 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
617 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +0200618 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw89b71522019-08-06 16:21:00 +0100619 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shaw0542d592019-08-06 16:34:44 +0100620 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
itayzafrir90d8c7a2018-09-12 11:44:52 +0300621 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +0300622 * The library has not been previously initialized by psa_crypto_init().
623 * It is implementation-dependent whether a failure to initialize
624 * results in this error code.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100625 */
Gilles Peskineae32aac2018-11-30 14:39:32 +0100626psa_status_t psa_export_key(psa_key_handle_t handle,
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100627 uint8_t *data,
628 size_t data_size,
629 size_t *data_length);
630
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100631/**
632 * \brief Export a public key or the public part of a key pair in binary format.
633 *
634 * The output of this function can be passed to psa_import_key() to
635 * create an object that is equivalent to the public key.
636 *
Jaeden Amerod3a0c2c2019-01-11 17:15:56 +0000637 * This specification supports a single format for each key type.
638 * Implementations may support other formats as long as the standard
639 * format is supported. Implementations that support other formats
640 * should ensure that the formats are clearly unambiguous so as to
641 * minimize the risk that an invalid input is accidentally interpreted
642 * according to a different format.
643 *
Jaeden Amero6b196002019-01-10 10:23:21 +0000644 * For standard key types, the output format is as follows:
645 * - For RSA public keys (#PSA_KEY_TYPE_RSA_PUBLIC_KEY), the DER encoding of
646 * the representation defined by RFC 3279 &sect;2.3.1 as `RSAPublicKey`.
647 * ```
648 * RSAPublicKey ::= SEQUENCE {
649 * modulus INTEGER, -- n
650 * publicExponent INTEGER } -- e
651 * ```
Jaeden Amero0ae445f2019-01-10 11:42:27 +0000652 * - For elliptic curve public keys (key types for which
653 * #PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY is true), the format is the uncompressed
654 * representation defined by SEC1 &sect;2.3.3 as the content of an ECPoint.
655 * Let `m` be the bit size associated with the curve, i.e. the bit size of
656 * `q` for a curve over `F_q`. The representation consists of:
657 * - The byte 0x04;
658 * - `x_P` as a `ceiling(m/8)`-byte string, big-endian;
659 * - `y_P` as a `ceiling(m/8)`-byte string, big-endian.
Gilles Peskinedcaefae2019-05-16 12:55:35 +0200660 * - For Diffie-Hellman key exchange public keys (key types for which
661 * #PSA_KEY_TYPE_IS_DH_PUBLIC_KEY is true),
Jaeden Amero8851c402019-01-11 14:20:03 +0000662 * the format is the representation of the public key `y = g^x mod p` as a
663 * big-endian byte string. The length of the byte string is the length of the
664 * base prime `p` in bytes.
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100665 *
Gilles Peskine4318dfc2019-05-14 14:23:32 +0200666 * Exporting a public key object or the public part of a key pair is
667 * always permitted, regardless of the key's usage flags.
668 *
Gilles Peskineae32aac2018-11-30 14:39:32 +0100669 * \param handle Handle to the key to export.
Gilles Peskineedd11a12018-07-12 01:08:58 +0200670 * \param[out] data Buffer where the key data is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +0200671 * \param data_size Size of the \p data buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +0200672 * \param[out] data_length On success, the number of bytes
673 * that make up the key data.
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100674 *
Gilles Peskine28538492018-07-11 17:34:00 +0200675 * \retval #PSA_SUCCESS
Gilles Peskineae32aac2018-11-30 14:39:32 +0100676 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine28538492018-07-11 17:34:00 +0200677 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine1be949b2018-08-10 19:06:59 +0200678 * The key is neither a public key nor a key pair.
679 * \retval #PSA_ERROR_NOT_SUPPORTED
680 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
681 * The size of the \p data buffer is too small. You can determine a
682 * sufficient buffer size by calling
Gilles Peskinec93b80c2019-05-16 19:39:54 +0200683 * #PSA_KEY_EXPORT_MAX_SIZE(#PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(\c type), \c bits)
Gilles Peskine1be949b2018-08-10 19:06:59 +0200684 * where \c type is the key type
685 * and \c bits is the key size in bits.
Gilles Peskine28538492018-07-11 17:34:00 +0200686 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
687 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +0200688 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shaw398b3c22019-08-06 17:22:41 +0100689 * \retval #PSA_ERROR_STORAGE_FAILURE
Adrian L. Shaw88c51ad2019-08-06 17:09:33 +0100690 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
itayzafrir90d8c7a2018-09-12 11:44:52 +0300691 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +0300692 * The library has not been previously initialized by psa_crypto_init().
693 * It is implementation-dependent whether a failure to initialize
694 * results in this error code.
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100695 */
Gilles Peskineae32aac2018-11-30 14:39:32 +0100696psa_status_t psa_export_public_key(psa_key_handle_t handle,
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100697 uint8_t *data,
698 size_t data_size,
699 size_t *data_length);
700
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100701/** Make a copy of a key.
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100702 *
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100703 * Copy key material from one location to another.
Jaeden Amero70261c52019-01-04 11:47:20 +0000704 *
Gilles Peskineaec5a7f2019-02-05 20:26:09 +0100705 * This function is primarily useful to copy a key from one location
706 * to another, since it populates a key using the material from
707 * another key which may have a different lifetime.
Gilles Peskine6ac73a92018-07-12 19:47:19 +0200708 *
Adrian L. Shaw0a695bd2019-05-15 13:28:41 +0100709 * This function may be used to share a key with a different party,
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100710 * subject to implementation-defined restrictions on key sharing.
Gilles Peskine7e198532018-03-08 07:50:30 +0100711 *
Gilles Peskine8e0206a2019-05-14 14:24:28 +0200712 * The policy on the source key must have the usage flag
713 * #PSA_KEY_USAGE_COPY set.
Gilles Peskined6a8f5f2019-05-14 16:25:50 +0200714 * This flag is sufficient to permit the copy if the key has the lifetime
715 * #PSA_KEY_LIFETIME_VOLATILE or #PSA_KEY_LIFETIME_PERSISTENT.
716 * Some secure elements do not provide a way to copy a key without
717 * making it extractable from the secure element. If a key is located
718 * in such a secure element, then the key must have both usage flags
719 * #PSA_KEY_USAGE_COPY and #PSA_KEY_USAGE_EXPORT in order to make
720 * a copy of the key outside the secure element.
Gilles Peskine8e0206a2019-05-14 14:24:28 +0200721 *
Gilles Peskine20628592019-04-19 19:29:50 +0200722 * The resulting key may only be used in a way that conforms to
723 * both the policy of the original key and the policy specified in
724 * the \p attributes parameter:
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100725 * - The usage flags on the resulting key are the bitwise-and of the
Gilles Peskine20628592019-04-19 19:29:50 +0200726 * usage flags on the source policy and the usage flags in \p attributes.
727 * - If both allow the same algorithm or wildcard-based
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100728 * algorithm policy, the resulting key has the same algorithm policy.
Gilles Peskine20628592019-04-19 19:29:50 +0200729 * - If either of the policies allows an algorithm and the other policy
730 * allows a wildcard-based algorithm policy that includes this algorithm,
731 * the resulting key allows the same algorithm.
732 * - If the policies do not allow any algorithm in common, this function
733 * fails with the status #PSA_ERROR_INVALID_ARGUMENT.
Gilles Peskine6ac73a92018-07-12 19:47:19 +0200734 *
Gilles Peskine20628592019-04-19 19:29:50 +0200735 * The effect of this function on implementation-defined attributes is
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100736 * implementation-defined.
Gilles Peskine6ac73a92018-07-12 19:47:19 +0200737 *
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +0100738 * \param source_handle The key to copy. It must be a valid key handle.
Gilles Peskine20628592019-04-19 19:29:50 +0200739 * \param[in] attributes The attributes for the new key.
740 * They are used as follows:
Gilles Peskine4ce2a9d2019-05-03 16:57:15 +0200741 * - The key type and size may be 0. If either is
742 * nonzero, it must match the corresponding
743 * attribute of the source key.
Gilles Peskine20628592019-04-19 19:29:50 +0200744 * - The key location (the lifetime and, for
745 * persistent keys, the key identifier) is
746 * used directly.
747 * - The policy constraints (usage flags and
748 * algorithm policy) are combined from
749 * the source key and \p attributes so that
750 * both sets of restrictions apply, as
751 * described in the documentation of this function.
752 * \param[out] target_handle On success, a handle to the newly created key.
753 * \c 0 on failure.
Gilles Peskine6ac73a92018-07-12 19:47:19 +0200754 *
755 * \retval #PSA_SUCCESS
Gilles Peskineae32aac2018-11-30 14:39:32 +0100756 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine20628592019-04-19 19:29:50 +0200757 * \p source_handle is invalid.
David Saadab4ecc272019-02-14 13:48:10 +0200758 * \retval #PSA_ERROR_ALREADY_EXISTS
Gilles Peskine20628592019-04-19 19:29:50 +0200759 * This is an attempt to create a persistent key, and there is
760 * already a persistent key with the given identifier.
Gilles Peskine6ac73a92018-07-12 19:47:19 +0200761 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine20628592019-04-19 19:29:50 +0200762 * The lifetime or identifier in \p attributes are invalid.
763 * \retval #PSA_ERROR_INVALID_ARGUMENT
764 * The policy constraints on the source and specified in
765 * \p attributes are incompatible.
Gilles Peskine4ce2a9d2019-05-03 16:57:15 +0200766 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine24f10f82019-05-16 12:18:32 +0200767 * \p attributes specifies a key type or key size
Gilles Peskine4ce2a9d2019-05-03 16:57:15 +0200768 * which does not match the attributes of the source key.
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100769 * \retval #PSA_ERROR_NOT_PERMITTED
Gilles Peskine8e0206a2019-05-14 14:24:28 +0200770 * The source key does not have the #PSA_KEY_USAGE_COPY usage flag.
771 * \retval #PSA_ERROR_NOT_PERMITTED
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100772 * The source key is not exportable and its lifetime does not
773 * allow copying it to the target's lifetime.
774 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
775 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
Gilles Peskine6ac73a92018-07-12 19:47:19 +0200776 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
777 * \retval #PSA_ERROR_HARDWARE_FAILURE
Adrian L. Shaw60b03202019-08-06 17:26:16 +0100778 * \retval #PSA_ERROR_STORAGE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +0200779 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100780 */
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100781psa_status_t psa_copy_key(psa_key_handle_t source_handle,
Gilles Peskine87a5e562019-04-17 12:28:25 +0200782 const psa_key_attributes_t *attributes,
783 psa_key_handle_t *target_handle);
Gilles Peskine20035e32018-02-03 22:44:14 +0100784
785/**@}*/
786
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100787/** \defgroup hash Message digests
788 * @{
789 */
790
Gilles Peskine69647a42019-01-14 20:18:12 +0100791/** Calculate the hash (digest) of a message.
792 *
793 * \note To verify the hash of a message against an
794 * expected value, use psa_hash_compare() instead.
795 *
796 * \param alg The hash algorithm to compute (\c PSA_ALG_XXX value
797 * such that #PSA_ALG_IS_HASH(\p alg) is true).
798 * \param[in] input Buffer containing the message to hash.
799 * \param input_length Size of the \p input buffer in bytes.
800 * \param[out] hash Buffer where the hash is to be written.
801 * \param hash_size Size of the \p hash buffer in bytes.
802 * \param[out] hash_length On success, the number of bytes
803 * that make up the hash value. This is always
Gilles Peskined338b912019-02-15 13:01:41 +0100804 * #PSA_HASH_SIZE(\p alg).
Gilles Peskine69647a42019-01-14 20:18:12 +0100805 *
806 * \retval #PSA_SUCCESS
807 * Success.
808 * \retval #PSA_ERROR_NOT_SUPPORTED
809 * \p alg is not supported or is not a hash algorithm.
Adrian L. Shawf7d852a2019-08-06 17:50:26 +0100810 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
811 * \p hash_size is too small
Gilles Peskine69647a42019-01-14 20:18:12 +0100812 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
813 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
814 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +0200815 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine69647a42019-01-14 20:18:12 +0100816 */
817psa_status_t psa_hash_compute(psa_algorithm_t alg,
818 const uint8_t *input,
819 size_t input_length,
820 uint8_t *hash,
821 size_t hash_size,
822 size_t *hash_length);
823
824/** Calculate the hash (digest) of a message and compare it with a
825 * reference value.
826 *
827 * \param alg The hash algorithm to compute (\c PSA_ALG_XXX value
828 * such that #PSA_ALG_IS_HASH(\p alg) is true).
829 * \param[in] input Buffer containing the message to hash.
830 * \param input_length Size of the \p input buffer in bytes.
831 * \param[out] hash Buffer containing the expected hash value.
Gilles Peskinea05602d2019-01-17 15:25:52 +0100832 * \param hash_length Size of the \p hash buffer in bytes.
Gilles Peskine69647a42019-01-14 20:18:12 +0100833 *
834 * \retval #PSA_SUCCESS
835 * The expected hash is identical to the actual hash of the input.
836 * \retval #PSA_ERROR_INVALID_SIGNATURE
837 * The hash of the message was calculated successfully, but it
838 * differs from the expected hash.
839 * \retval #PSA_ERROR_NOT_SUPPORTED
840 * \p alg is not supported or is not a hash algorithm.
841 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
842 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
843 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +0200844 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine69647a42019-01-14 20:18:12 +0100845 */
846psa_status_t psa_hash_compare(psa_algorithm_t alg,
847 const uint8_t *input,
848 size_t input_length,
849 const uint8_t *hash,
850 const size_t hash_length);
851
Gilles Peskine308b91d2018-02-08 09:47:44 +0100852/** The type of the state data structure for multipart hash operations.
853 *
Jaeden Amero6a25b412019-01-04 11:47:44 +0000854 * Before calling any function on a hash operation object, the application must
855 * initialize it by any of the following means:
856 * - Set the structure to all-bits-zero, for example:
857 * \code
858 * psa_hash_operation_t operation;
859 * memset(&operation, 0, sizeof(operation));
860 * \endcode
861 * - Initialize the structure to logical zero values, for example:
862 * \code
863 * psa_hash_operation_t operation = {0};
864 * \endcode
865 * - Initialize the structure to the initializer #PSA_HASH_OPERATION_INIT,
866 * for example:
867 * \code
868 * psa_hash_operation_t operation = PSA_HASH_OPERATION_INIT;
869 * \endcode
870 * - Assign the result of the function psa_hash_operation_init()
871 * to the structure, for example:
872 * \code
873 * psa_hash_operation_t operation;
874 * operation = psa_hash_operation_init();
875 * \endcode
876 *
Gilles Peskine92b30732018-03-03 21:29:30 +0100877 * This is an implementation-defined \c struct. Applications should not
Gilles Peskine308b91d2018-02-08 09:47:44 +0100878 * make any assumptions about the content of this structure except
879 * as directed by the documentation of a specific implementation. */
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100880typedef struct psa_hash_operation_s psa_hash_operation_t;
881
Jaeden Amero6a25b412019-01-04 11:47:44 +0000882/** \def PSA_HASH_OPERATION_INIT
883 *
884 * This macro returns a suitable initializer for a hash operation object
885 * of type #psa_hash_operation_t.
886 */
887#ifdef __DOXYGEN_ONLY__
888/* This is an example definition for documentation purposes.
889 * Implementations should define a suitable value in `crypto_struct.h`.
890 */
891#define PSA_HASH_OPERATION_INIT {0}
892#endif
893
894/** Return an initial value for a hash operation object.
895 */
896static psa_hash_operation_t psa_hash_operation_init(void);
897
Gilles Peskinef45adda2019-01-14 18:29:18 +0100898/** Set up a multipart hash operation.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100899 *
900 * The sequence of operations to calculate a hash (message digest)
901 * is as follows:
902 * -# Allocate an operation object which will be passed to all the functions
903 * listed here.
Jaeden Amero6a25b412019-01-04 11:47:44 +0000904 * -# Initialize the operation object with one of the methods described in the
905 * documentation for #psa_hash_operation_t, e.g. PSA_HASH_OPERATION_INIT.
Gilles Peskineda8191d1c2018-07-08 19:46:38 +0200906 * -# Call psa_hash_setup() to specify the algorithm.
Gilles Peskine7e4acc52018-02-16 21:24:11 +0100907 * -# Call psa_hash_update() zero, one or more times, passing a fragment
Gilles Peskine308b91d2018-02-08 09:47:44 +0100908 * of the message each time. The hash that is calculated is the hash
909 * of the concatenation of these messages in order.
910 * -# To calculate the hash, call psa_hash_finish().
911 * To compare the hash with an expected value, call psa_hash_verify().
912 *
913 * The application may call psa_hash_abort() at any time after the operation
Jaeden Amero6a25b412019-01-04 11:47:44 +0000914 * has been initialized.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100915 *
Gilles Peskineda8191d1c2018-07-08 19:46:38 +0200916 * After a successful call to psa_hash_setup(), the application must
Gilles Peskineed522972018-03-20 17:54:15 +0100917 * eventually terminate the operation. The following events terminate an
918 * operation:
Gilles Peskine308b91d2018-02-08 09:47:44 +0100919 * - A failed call to psa_hash_update().
Gilles Peskine19067982018-03-20 17:54:53 +0100920 * - A call to psa_hash_finish(), psa_hash_verify() or psa_hash_abort().
Gilles Peskine308b91d2018-02-08 09:47:44 +0100921 *
Jaeden Amero6a25b412019-01-04 11:47:44 +0000922 * \param[in,out] operation The operation object to set up. It must have
923 * been initialized as per the documentation for
924 * #psa_hash_operation_t and not yet in use.
Gilles Peskineedd11a12018-07-12 01:08:58 +0200925 * \param alg The hash algorithm to compute (\c PSA_ALG_XXX value
926 * such that #PSA_ALG_IS_HASH(\p alg) is true).
Gilles Peskine308b91d2018-02-08 09:47:44 +0100927 *
Gilles Peskine28538492018-07-11 17:34:00 +0200928 * \retval #PSA_SUCCESS
Gilles Peskine308b91d2018-02-08 09:47:44 +0100929 * Success.
Gilles Peskine28538492018-07-11 17:34:00 +0200930 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskinefa4070c2018-07-12 19:23:03 +0200931 * \p alg is not supported or is not a hash algorithm.
Gilles Peskine8e1addc2019-01-10 11:51:17 +0100932 * \retval #PSA_ERROR_BAD_STATE
933 * The operation state is not valid (already set up and not
934 * subsequently completed).
Gilles Peskine28538492018-07-11 17:34:00 +0200935 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
936 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
937 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +0200938 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine308b91d2018-02-08 09:47:44 +0100939 */
Gilles Peskineda8191d1c2018-07-08 19:46:38 +0200940psa_status_t psa_hash_setup(psa_hash_operation_t *operation,
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100941 psa_algorithm_t alg);
942
Gilles Peskine308b91d2018-02-08 09:47:44 +0100943/** Add a message fragment to a multipart hash operation.
944 *
Gilles Peskineda8191d1c2018-07-08 19:46:38 +0200945 * The application must call psa_hash_setup() before calling this function.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100946 *
947 * If this function returns an error status, the operation becomes inactive.
948 *
Gilles Peskineedd11a12018-07-12 01:08:58 +0200949 * \param[in,out] operation Active hash operation.
950 * \param[in] input Buffer containing the message fragment to hash.
Gilles Peskinefa4070c2018-07-12 19:23:03 +0200951 * \param input_length Size of the \p input buffer in bytes.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100952 *
Gilles Peskine28538492018-07-11 17:34:00 +0200953 * \retval #PSA_SUCCESS
Gilles Peskine308b91d2018-02-08 09:47:44 +0100954 * Success.
Gilles Peskine28538492018-07-11 17:34:00 +0200955 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +0100956 * The operation state is not valid (not set up, or already completed).
Gilles Peskine28538492018-07-11 17:34:00 +0200957 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
958 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
959 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +0200960 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine308b91d2018-02-08 09:47:44 +0100961 */
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100962psa_status_t psa_hash_update(psa_hash_operation_t *operation,
963 const uint8_t *input,
964 size_t input_length);
965
Gilles Peskine308b91d2018-02-08 09:47:44 +0100966/** Finish the calculation of the hash of a message.
967 *
Gilles Peskineda8191d1c2018-07-08 19:46:38 +0200968 * The application must call psa_hash_setup() before calling this function.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100969 * This function calculates the hash of the message formed by concatenating
970 * the inputs passed to preceding calls to psa_hash_update().
971 *
972 * When this function returns, the operation becomes inactive.
973 *
974 * \warning Applications should not call this function if they expect
975 * a specific value for the hash. Call psa_hash_verify() instead.
976 * Beware that comparing integrity or authenticity data such as
977 * hash values with a function such as \c memcmp is risky
978 * because the time taken by the comparison may leak information
979 * about the hashed data which could allow an attacker to guess
980 * a valid hash and thereby bypass security controls.
981 *
Gilles Peskineedd11a12018-07-12 01:08:58 +0200982 * \param[in,out] operation Active hash operation.
983 * \param[out] hash Buffer where the hash is to be written.
984 * \param hash_size Size of the \p hash buffer in bytes.
985 * \param[out] hash_length On success, the number of bytes
986 * that make up the hash value. This is always
Gilles Peskinebe42f312018-07-13 14:38:15 +0200987 * #PSA_HASH_SIZE(\c alg) where \c alg is the
Gilles Peskineedd11a12018-07-12 01:08:58 +0200988 * hash algorithm that is calculated.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100989 *
Gilles Peskine28538492018-07-11 17:34:00 +0200990 * \retval #PSA_SUCCESS
Gilles Peskine308b91d2018-02-08 09:47:44 +0100991 * Success.
Gilles Peskine28538492018-07-11 17:34:00 +0200992 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +0100993 * The operation state is not valid (not set up, or already completed).
Gilles Peskine28538492018-07-11 17:34:00 +0200994 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinefa4070c2018-07-12 19:23:03 +0200995 * The size of the \p hash buffer is too small. You can determine a
Gilles Peskine7256e6c2018-07-12 00:34:26 +0200996 * sufficient buffer size by calling #PSA_HASH_SIZE(\c alg)
Gilles Peskine308b91d2018-02-08 09:47:44 +0100997 * where \c alg is the hash algorithm that is calculated.
Gilles Peskine28538492018-07-11 17:34:00 +0200998 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
999 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1000 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001001 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine308b91d2018-02-08 09:47:44 +01001002 */
Gilles Peskine9ef733f2018-02-07 21:05:37 +01001003psa_status_t psa_hash_finish(psa_hash_operation_t *operation,
1004 uint8_t *hash,
1005 size_t hash_size,
1006 size_t *hash_length);
1007
Gilles Peskine308b91d2018-02-08 09:47:44 +01001008/** Finish the calculation of the hash of a message and compare it with
1009 * an expected value.
1010 *
Gilles Peskineda8191d1c2018-07-08 19:46:38 +02001011 * The application must call psa_hash_setup() before calling this function.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001012 * This function calculates the hash of the message formed by concatenating
1013 * the inputs passed to preceding calls to psa_hash_update(). It then
1014 * compares the calculated hash with the expected hash passed as a
1015 * parameter to this function.
1016 *
1017 * When this function returns, the operation becomes inactive.
1018 *
Gilles Peskine19067982018-03-20 17:54:53 +01001019 * \note Implementations shall make the best effort to ensure that the
Gilles Peskine308b91d2018-02-08 09:47:44 +01001020 * comparison between the actual hash and the expected hash is performed
1021 * in constant time.
1022 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001023 * \param[in,out] operation Active hash operation.
1024 * \param[in] hash Buffer containing the expected hash value.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001025 * \param hash_length Size of the \p hash buffer in bytes.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001026 *
Gilles Peskine28538492018-07-11 17:34:00 +02001027 * \retval #PSA_SUCCESS
Gilles Peskine308b91d2018-02-08 09:47:44 +01001028 * The expected hash is identical to the actual hash of the message.
Gilles Peskine28538492018-07-11 17:34:00 +02001029 * \retval #PSA_ERROR_INVALID_SIGNATURE
Gilles Peskine308b91d2018-02-08 09:47:44 +01001030 * The hash of the message was calculated successfully, but it
1031 * differs from the expected hash.
Gilles Peskine28538492018-07-11 17:34:00 +02001032 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001033 * The operation state is not valid (not set up, or already completed).
Gilles Peskine28538492018-07-11 17:34:00 +02001034 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1035 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1036 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001037 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine308b91d2018-02-08 09:47:44 +01001038 */
Gilles Peskine9ef733f2018-02-07 21:05:37 +01001039psa_status_t psa_hash_verify(psa_hash_operation_t *operation,
1040 const uint8_t *hash,
1041 size_t hash_length);
1042
Gilles Peskine308b91d2018-02-08 09:47:44 +01001043/** Abort a hash operation.
1044 *
Gilles Peskine308b91d2018-02-08 09:47:44 +01001045 * Aborting an operation frees all associated resources except for the
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001046 * \p operation structure itself. Once aborted, the operation object
1047 * can be reused for another operation by calling
1048 * psa_hash_setup() again.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001049 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001050 * You may call this function any time after the operation object has
1051 * been initialized by any of the following methods:
1052 * - A call to psa_hash_setup(), whether it succeeds or not.
1053 * - Initializing the \c struct to all-bits-zero.
1054 * - Initializing the \c struct to logical zeros, e.g.
1055 * `psa_hash_operation_t operation = {0}`.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001056 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001057 * In particular, calling psa_hash_abort() after the operation has been
1058 * terminated by a call to psa_hash_abort(), psa_hash_finish() or
1059 * psa_hash_verify() is safe and has no effect.
1060 *
1061 * \param[in,out] operation Initialized hash operation.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001062 *
Gilles Peskine28538492018-07-11 17:34:00 +02001063 * \retval #PSA_SUCCESS
1064 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001065 * \p operation is not an active hash operation.
Gilles Peskine28538492018-07-11 17:34:00 +02001066 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1067 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001068 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine308b91d2018-02-08 09:47:44 +01001069 */
1070psa_status_t psa_hash_abort(psa_hash_operation_t *operation);
Gilles Peskine9ef733f2018-02-07 21:05:37 +01001071
Gilles Peskineebb2c3e2019-01-19 12:03:41 +01001072/** Clone a hash operation.
1073 *
Gilles Peskinee43aa392019-01-21 14:50:37 +01001074 * This function copies the state of an ongoing hash operation to
1075 * a new operation object. In other words, this function is equivalent
1076 * to calling psa_hash_setup() on \p target_operation with the same
1077 * algorithm that \p source_operation was set up for, then
1078 * psa_hash_update() on \p target_operation with the same input that
1079 * that was passed to \p source_operation. After this function returns, the
1080 * two objects are independent, i.e. subsequent calls involving one of
1081 * the objects do not affect the other object.
1082 *
Gilles Peskineebb2c3e2019-01-19 12:03:41 +01001083 * \param[in] source_operation The active hash operation to clone.
1084 * \param[in,out] target_operation The operation object to set up.
1085 * It must be initialized but not active.
1086 *
1087 * \retval #PSA_SUCCESS
1088 * \retval #PSA_ERROR_BAD_STATE
1089 * \p source_operation is not an active hash operation.
1090 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinee43aa392019-01-21 14:50:37 +01001091 * \p target_operation is active.
Gilles Peskineebb2c3e2019-01-19 12:03:41 +01001092 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1093 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001094 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskineebb2c3e2019-01-19 12:03:41 +01001095 */
1096psa_status_t psa_hash_clone(const psa_hash_operation_t *source_operation,
1097 psa_hash_operation_t *target_operation);
1098
Gilles Peskine9ef733f2018-02-07 21:05:37 +01001099/**@}*/
1100
Gilles Peskine8c9def32018-02-08 10:02:12 +01001101/** \defgroup MAC Message authentication codes
1102 * @{
1103 */
1104
Gilles Peskine69647a42019-01-14 20:18:12 +01001105/** Calculate the MAC (message authentication code) of a message.
1106 *
1107 * \note To verify the MAC of a message against an
1108 * expected value, use psa_mac_verify() instead.
1109 * Beware that comparing integrity or authenticity data such as
1110 * MAC values with a function such as \c memcmp is risky
1111 * because the time taken by the comparison may leak information
1112 * about the MAC value which could allow an attacker to guess
1113 * a valid MAC and thereby bypass security controls.
1114 *
1115 * \param handle Handle to the key to use for the operation.
1116 * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
Gilles Peskine63f79302019-02-15 13:01:17 +01001117 * such that #PSA_ALG_IS_MAC(\p alg) is true).
Gilles Peskine69647a42019-01-14 20:18:12 +01001118 * \param[in] input Buffer containing the input message.
1119 * \param input_length Size of the \p input buffer in bytes.
1120 * \param[out] mac Buffer where the MAC value is to be written.
1121 * \param mac_size Size of the \p mac buffer in bytes.
1122 * \param[out] mac_length On success, the number of bytes
Gilles Peskined338b912019-02-15 13:01:41 +01001123 * that make up the MAC value.
Gilles Peskine69647a42019-01-14 20:18:12 +01001124 *
1125 * \retval #PSA_SUCCESS
1126 * Success.
1127 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine69647a42019-01-14 20:18:12 +01001128 * \retval #PSA_ERROR_NOT_PERMITTED
1129 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001130 * \p handle is not compatible with \p alg.
Gilles Peskine69647a42019-01-14 20:18:12 +01001131 * \retval #PSA_ERROR_NOT_SUPPORTED
1132 * \p alg is not supported or is not a MAC algorithm.
1133 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1134 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1135 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001136 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Adrian L. Shawfa591c42019-08-07 10:47:47 +01001137 * \retval #PSA_ERROR_STORAGE_FAILURE
1138 * The key could not be retrieved from storage.
Gilles Peskine69647a42019-01-14 20:18:12 +01001139 * \retval #PSA_ERROR_BAD_STATE
1140 * The library has not been previously initialized by psa_crypto_init().
1141 * It is implementation-dependent whether a failure to initialize
1142 * results in this error code.
1143 */
1144psa_status_t psa_mac_compute(psa_key_handle_t handle,
1145 psa_algorithm_t alg,
1146 const uint8_t *input,
1147 size_t input_length,
1148 uint8_t *mac,
1149 size_t mac_size,
1150 size_t *mac_length);
1151
1152/** Calculate the MAC of a message and compare it with a reference value.
1153 *
1154 * \param handle Handle to the key to use for the operation.
1155 * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
Gilles Peskine63f79302019-02-15 13:01:17 +01001156 * such that #PSA_ALG_IS_MAC(\p alg) is true).
Gilles Peskine69647a42019-01-14 20:18:12 +01001157 * \param[in] input Buffer containing the input message.
1158 * \param input_length Size of the \p input buffer in bytes.
1159 * \param[out] mac Buffer containing the expected MAC value.
1160 * \param mac_length Size of the \p mac buffer in bytes.
1161 *
1162 * \retval #PSA_SUCCESS
1163 * The expected MAC is identical to the actual MAC of the input.
1164 * \retval #PSA_ERROR_INVALID_SIGNATURE
1165 * The MAC of the message was calculated successfully, but it
1166 * differs from the expected value.
1167 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine69647a42019-01-14 20:18:12 +01001168 * \retval #PSA_ERROR_NOT_PERMITTED
1169 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001170 * \p handle is not compatible with \p alg.
Gilles Peskine69647a42019-01-14 20:18:12 +01001171 * \retval #PSA_ERROR_NOT_SUPPORTED
1172 * \p alg is not supported or is not a MAC algorithm.
1173 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1174 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1175 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001176 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine69647a42019-01-14 20:18:12 +01001177 */
Gilles Peskinea05602d2019-01-17 15:25:52 +01001178psa_status_t psa_mac_verify(psa_key_handle_t handle,
1179 psa_algorithm_t alg,
Gilles Peskine69647a42019-01-14 20:18:12 +01001180 const uint8_t *input,
1181 size_t input_length,
1182 const uint8_t *mac,
1183 const size_t mac_length);
1184
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001185/** The type of the state data structure for multipart MAC operations.
1186 *
Jaeden Amero769ce272019-01-04 11:48:03 +00001187 * Before calling any function on a MAC operation object, the application must
1188 * initialize it by any of the following means:
1189 * - Set the structure to all-bits-zero, for example:
1190 * \code
1191 * psa_mac_operation_t operation;
1192 * memset(&operation, 0, sizeof(operation));
1193 * \endcode
1194 * - Initialize the structure to logical zero values, for example:
1195 * \code
1196 * psa_mac_operation_t operation = {0};
1197 * \endcode
1198 * - Initialize the structure to the initializer #PSA_MAC_OPERATION_INIT,
1199 * for example:
1200 * \code
1201 * psa_mac_operation_t operation = PSA_MAC_OPERATION_INIT;
1202 * \endcode
1203 * - Assign the result of the function psa_mac_operation_init()
1204 * to the structure, for example:
1205 * \code
1206 * psa_mac_operation_t operation;
1207 * operation = psa_mac_operation_init();
1208 * \endcode
1209 *
Gilles Peskine92b30732018-03-03 21:29:30 +01001210 * This is an implementation-defined \c struct. Applications should not
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001211 * make any assumptions about the content of this structure except
1212 * as directed by the documentation of a specific implementation. */
Gilles Peskine8c9def32018-02-08 10:02:12 +01001213typedef struct psa_mac_operation_s psa_mac_operation_t;
1214
Jaeden Amero769ce272019-01-04 11:48:03 +00001215/** \def PSA_MAC_OPERATION_INIT
1216 *
1217 * This macro returns a suitable initializer for a MAC operation object of type
1218 * #psa_mac_operation_t.
1219 */
1220#ifdef __DOXYGEN_ONLY__
1221/* This is an example definition for documentation purposes.
1222 * Implementations should define a suitable value in `crypto_struct.h`.
1223 */
1224#define PSA_MAC_OPERATION_INIT {0}
1225#endif
1226
1227/** Return an initial value for a MAC operation object.
1228 */
1229static psa_mac_operation_t psa_mac_operation_init(void);
1230
Gilles Peskinef45adda2019-01-14 18:29:18 +01001231/** Set up a multipart MAC calculation operation.
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001232 *
Gilles Peskine89167cb2018-07-08 20:12:23 +02001233 * This function sets up the calculation of the MAC
1234 * (message authentication code) of a byte string.
1235 * To verify the MAC of a message against an
1236 * expected value, use psa_mac_verify_setup() instead.
1237 *
1238 * The sequence of operations to calculate a MAC is as follows:
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001239 * -# Allocate an operation object which will be passed to all the functions
1240 * listed here.
Jaeden Amero769ce272019-01-04 11:48:03 +00001241 * -# Initialize the operation object with one of the methods described in the
1242 * documentation for #psa_mac_operation_t, e.g. PSA_MAC_OPERATION_INIT.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001243 * -# Call psa_mac_sign_setup() to specify the algorithm and key.
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001244 * -# Call psa_mac_update() zero, one or more times, passing a fragment
1245 * of the message each time. The MAC that is calculated is the MAC
1246 * of the concatenation of these messages in order.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001247 * -# At the end of the message, call psa_mac_sign_finish() to finish
1248 * calculating the MAC value and retrieve it.
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001249 *
1250 * The application may call psa_mac_abort() at any time after the operation
Jaeden Amero769ce272019-01-04 11:48:03 +00001251 * has been initialized.
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001252 *
Gilles Peskine89167cb2018-07-08 20:12:23 +02001253 * After a successful call to psa_mac_sign_setup(), the application must
1254 * eventually terminate the operation through one of the following methods:
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001255 * - A failed call to psa_mac_update().
Gilles Peskine89167cb2018-07-08 20:12:23 +02001256 * - A call to psa_mac_sign_finish() or psa_mac_abort().
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001257 *
Jaeden Amero769ce272019-01-04 11:48:03 +00001258 * \param[in,out] operation The operation object to set up. It must have
1259 * been initialized as per the documentation for
1260 * #psa_mac_operation_t and not yet in use.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001261 * \param handle Handle to the key to use for the operation.
Gilles Peskine5f25dd02019-01-14 18:24:53 +01001262 * It must remain valid until the operation
1263 * terminates.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001264 * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
Gilles Peskine63f79302019-02-15 13:01:17 +01001265 * such that #PSA_ALG_IS_MAC(\p alg) is true).
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001266 *
Gilles Peskine28538492018-07-11 17:34:00 +02001267 * \retval #PSA_SUCCESS
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001268 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001269 * \retval #PSA_ERROR_INVALID_HANDLE
David Saadab4ecc272019-02-14 13:48:10 +02001270 * \retval #PSA_ERROR_DOES_NOT_EXIST
Gilles Peskine28538492018-07-11 17:34:00 +02001271 * \retval #PSA_ERROR_NOT_PERMITTED
1272 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001273 * \p handle is not compatible with \p alg.
Gilles Peskine28538492018-07-11 17:34:00 +02001274 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001275 * \p alg is not supported or is not a MAC algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02001276 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1277 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1278 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001279 * \retval #PSA_ERROR_CORRUPTION_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03001280 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskine8e1addc2019-01-10 11:51:17 +01001281 * The operation state is not valid (already set up and not
1282 * subsequently completed).
1283 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03001284 * The library has not been previously initialized by psa_crypto_init().
1285 * It is implementation-dependent whether a failure to initialize
1286 * results in this error code.
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001287 */
Gilles Peskine89167cb2018-07-08 20:12:23 +02001288psa_status_t psa_mac_sign_setup(psa_mac_operation_t *operation,
Gilles Peskineae32aac2018-11-30 14:39:32 +01001289 psa_key_handle_t handle,
Gilles Peskine89167cb2018-07-08 20:12:23 +02001290 psa_algorithm_t alg);
1291
Gilles Peskinef45adda2019-01-14 18:29:18 +01001292/** Set up a multipart MAC verification operation.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001293 *
1294 * This function sets up the verification of the MAC
1295 * (message authentication code) of a byte string against an expected value.
1296 *
1297 * The sequence of operations to verify a MAC is as follows:
1298 * -# Allocate an operation object which will be passed to all the functions
1299 * listed here.
Jaeden Amero769ce272019-01-04 11:48:03 +00001300 * -# Initialize the operation object with one of the methods described in the
1301 * documentation for #psa_mac_operation_t, e.g. PSA_MAC_OPERATION_INIT.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001302 * -# Call psa_mac_verify_setup() to specify the algorithm and key.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001303 * -# Call psa_mac_update() zero, one or more times, passing a fragment
1304 * of the message each time. The MAC that is calculated is the MAC
1305 * of the concatenation of these messages in order.
1306 * -# At the end of the message, call psa_mac_verify_finish() to finish
1307 * calculating the actual MAC of the message and verify it against
1308 * the expected value.
1309 *
1310 * The application may call psa_mac_abort() at any time after the operation
Jaeden Amero769ce272019-01-04 11:48:03 +00001311 * has been initialized.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001312 *
1313 * After a successful call to psa_mac_verify_setup(), the application must
1314 * eventually terminate the operation through one of the following methods:
1315 * - A failed call to psa_mac_update().
1316 * - A call to psa_mac_verify_finish() or psa_mac_abort().
1317 *
Jaeden Amero769ce272019-01-04 11:48:03 +00001318 * \param[in,out] operation The operation object to set up. It must have
1319 * been initialized as per the documentation for
1320 * #psa_mac_operation_t and not yet in use.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001321 * \param handle Handle to the key to use for the operation.
Gilles Peskine5f25dd02019-01-14 18:24:53 +01001322 * It must remain valid until the operation
1323 * terminates.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001324 * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
1325 * such that #PSA_ALG_IS_MAC(\p alg) is true).
Gilles Peskine89167cb2018-07-08 20:12:23 +02001326 *
Gilles Peskine28538492018-07-11 17:34:00 +02001327 * \retval #PSA_SUCCESS
Gilles Peskine89167cb2018-07-08 20:12:23 +02001328 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001329 * \retval #PSA_ERROR_INVALID_HANDLE
David Saadab4ecc272019-02-14 13:48:10 +02001330 * \retval #PSA_ERROR_DOES_NOT_EXIST
Gilles Peskine28538492018-07-11 17:34:00 +02001331 * \retval #PSA_ERROR_NOT_PERMITTED
1332 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine89167cb2018-07-08 20:12:23 +02001333 * \c key is not compatible with \c alg.
Gilles Peskine28538492018-07-11 17:34:00 +02001334 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskine89167cb2018-07-08 20:12:23 +02001335 * \c alg is not supported or is not a MAC algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02001336 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1337 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1338 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001339 * \retval #PSA_ERROR_CORRUPTION_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03001340 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskine8e1addc2019-01-10 11:51:17 +01001341 * The operation state is not valid (already set up and not
1342 * subsequently completed).
1343 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03001344 * The library has not been previously initialized by psa_crypto_init().
1345 * It is implementation-dependent whether a failure to initialize
1346 * results in this error code.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001347 */
1348psa_status_t psa_mac_verify_setup(psa_mac_operation_t *operation,
Gilles Peskineae32aac2018-11-30 14:39:32 +01001349 psa_key_handle_t handle,
Gilles Peskine89167cb2018-07-08 20:12:23 +02001350 psa_algorithm_t alg);
Gilles Peskine8c9def32018-02-08 10:02:12 +01001351
Gilles Peskinedcd14942018-07-12 00:30:52 +02001352/** Add a message fragment to a multipart MAC operation.
1353 *
1354 * The application must call psa_mac_sign_setup() or psa_mac_verify_setup()
1355 * before calling this function.
1356 *
1357 * If this function returns an error status, the operation becomes inactive.
1358 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001359 * \param[in,out] operation Active MAC operation.
1360 * \param[in] input Buffer containing the message fragment to add to
1361 * the MAC calculation.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001362 * \param input_length Size of the \p input buffer in bytes.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001363 *
1364 * \retval #PSA_SUCCESS
1365 * Success.
1366 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001367 * The operation state is not valid (not set up, or already completed).
Gilles Peskinedcd14942018-07-12 00:30:52 +02001368 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1369 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1370 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001371 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskinedcd14942018-07-12 00:30:52 +02001372 */
Gilles Peskine8c9def32018-02-08 10:02:12 +01001373psa_status_t psa_mac_update(psa_mac_operation_t *operation,
1374 const uint8_t *input,
1375 size_t input_length);
1376
Gilles Peskinedcd14942018-07-12 00:30:52 +02001377/** Finish the calculation of the MAC of a message.
1378 *
1379 * The application must call psa_mac_sign_setup() before calling this function.
1380 * This function calculates the MAC of the message formed by concatenating
1381 * the inputs passed to preceding calls to psa_mac_update().
1382 *
1383 * When this function returns, the operation becomes inactive.
1384 *
1385 * \warning Applications should not call this function if they expect
1386 * a specific value for the MAC. Call psa_mac_verify_finish() instead.
1387 * Beware that comparing integrity or authenticity data such as
1388 * MAC values with a function such as \c memcmp is risky
1389 * because the time taken by the comparison may leak information
1390 * about the MAC value which could allow an attacker to guess
1391 * a valid MAC and thereby bypass security controls.
1392 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001393 * \param[in,out] operation Active MAC operation.
1394 * \param[out] mac Buffer where the MAC value is to be written.
1395 * \param mac_size Size of the \p mac buffer in bytes.
1396 * \param[out] mac_length On success, the number of bytes
1397 * that make up the MAC value. This is always
Gilles Peskinedda3bd32018-07-12 19:40:46 +02001398 * #PSA_MAC_FINAL_SIZE(\c key_type, \c key_bits, \c alg)
Gilles Peskineedd11a12018-07-12 01:08:58 +02001399 * where \c key_type and \c key_bits are the type and
Gilles Peskinedda3bd32018-07-12 19:40:46 +02001400 * bit-size respectively of the key and \c alg is the
Gilles Peskineedd11a12018-07-12 01:08:58 +02001401 * MAC algorithm that is calculated.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001402 *
1403 * \retval #PSA_SUCCESS
1404 * Success.
1405 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001406 * The operation state is not valid (not set up, or already completed).
Gilles Peskinedcd14942018-07-12 00:30:52 +02001407 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001408 * The size of the \p mac buffer is too small. You can determine a
Gilles Peskinedcd14942018-07-12 00:30:52 +02001409 * sufficient buffer size by calling PSA_MAC_FINAL_SIZE().
1410 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1411 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1412 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001413 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskinedcd14942018-07-12 00:30:52 +02001414 */
Gilles Peskineacd4be32018-07-08 19:56:25 +02001415psa_status_t psa_mac_sign_finish(psa_mac_operation_t *operation,
1416 uint8_t *mac,
1417 size_t mac_size,
1418 size_t *mac_length);
Gilles Peskine8c9def32018-02-08 10:02:12 +01001419
Gilles Peskinedcd14942018-07-12 00:30:52 +02001420/** Finish the calculation of the MAC of a message and compare it with
1421 * an expected value.
1422 *
1423 * The application must call psa_mac_verify_setup() before calling this function.
1424 * This function calculates the MAC of the message formed by concatenating
1425 * the inputs passed to preceding calls to psa_mac_update(). It then
1426 * compares the calculated MAC with the expected MAC passed as a
1427 * parameter to this function.
1428 *
1429 * When this function returns, the operation becomes inactive.
1430 *
1431 * \note Implementations shall make the best effort to ensure that the
1432 * comparison between the actual MAC and the expected MAC is performed
1433 * in constant time.
1434 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001435 * \param[in,out] operation Active MAC operation.
1436 * \param[in] mac Buffer containing the expected MAC value.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001437 * \param mac_length Size of the \p mac buffer in bytes.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001438 *
1439 * \retval #PSA_SUCCESS
1440 * The expected MAC is identical to the actual MAC of the message.
1441 * \retval #PSA_ERROR_INVALID_SIGNATURE
1442 * The MAC of the message was calculated successfully, but it
1443 * differs from the expected MAC.
1444 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001445 * The operation state is not valid (not set up, or already completed).
Gilles Peskinedcd14942018-07-12 00:30:52 +02001446 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1447 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1448 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001449 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskinedcd14942018-07-12 00:30:52 +02001450 */
Gilles Peskineacd4be32018-07-08 19:56:25 +02001451psa_status_t psa_mac_verify_finish(psa_mac_operation_t *operation,
1452 const uint8_t *mac,
1453 size_t mac_length);
Gilles Peskine8c9def32018-02-08 10:02:12 +01001454
Gilles Peskinedcd14942018-07-12 00:30:52 +02001455/** Abort a MAC operation.
1456 *
Gilles Peskinedcd14942018-07-12 00:30:52 +02001457 * Aborting an operation frees all associated resources except for the
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001458 * \p operation structure itself. Once aborted, the operation object
1459 * can be reused for another operation by calling
1460 * psa_mac_sign_setup() or psa_mac_verify_setup() again.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001461 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001462 * You may call this function any time after the operation object has
1463 * been initialized by any of the following methods:
1464 * - A call to psa_mac_sign_setup() or psa_mac_verify_setup(), whether
1465 * it succeeds or not.
1466 * - Initializing the \c struct to all-bits-zero.
1467 * - Initializing the \c struct to logical zeros, e.g.
1468 * `psa_mac_operation_t operation = {0}`.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001469 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001470 * In particular, calling psa_mac_abort() after the operation has been
1471 * terminated by a call to psa_mac_abort(), psa_mac_sign_finish() or
1472 * psa_mac_verify_finish() is safe and has no effect.
1473 *
1474 * \param[in,out] operation Initialized MAC operation.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001475 *
1476 * \retval #PSA_SUCCESS
1477 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001478 * \p operation is not an active MAC operation.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001479 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1480 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001481 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskinedcd14942018-07-12 00:30:52 +02001482 */
Gilles Peskine8c9def32018-02-08 10:02:12 +01001483psa_status_t psa_mac_abort(psa_mac_operation_t *operation);
1484
1485/**@}*/
1486
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001487/** \defgroup cipher Symmetric ciphers
1488 * @{
1489 */
1490
Gilles Peskine69647a42019-01-14 20:18:12 +01001491/** Encrypt a message using a symmetric cipher.
1492 *
1493 * This function encrypts a message with a random IV (initialization
1494 * vector).
1495 *
1496 * \param handle Handle to the key to use for the operation.
1497 * It must remain valid until the operation
1498 * terminates.
1499 * \param alg The cipher algorithm to compute
1500 * (\c PSA_ALG_XXX value such that
1501 * #PSA_ALG_IS_CIPHER(\p alg) is true).
1502 * \param[in] input Buffer containing the message to encrypt.
1503 * \param input_length Size of the \p input buffer in bytes.
1504 * \param[out] output Buffer where the output is to be written.
1505 * The output contains the IV followed by
1506 * the ciphertext proper.
1507 * \param output_size Size of the \p output buffer in bytes.
1508 * \param[out] output_length On success, the number of bytes
1509 * that make up the output.
1510 *
1511 * \retval #PSA_SUCCESS
1512 * Success.
1513 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine69647a42019-01-14 20:18:12 +01001514 * \retval #PSA_ERROR_NOT_PERMITTED
1515 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001516 * \p handle is not compatible with \p alg.
Gilles Peskine69647a42019-01-14 20:18:12 +01001517 * \retval #PSA_ERROR_NOT_SUPPORTED
1518 * \p alg is not supported or is not a cipher algorithm.
1519 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
1520 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1521 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1522 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001523 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine69647a42019-01-14 20:18:12 +01001524 */
1525psa_status_t psa_cipher_encrypt(psa_key_handle_t handle,
1526 psa_algorithm_t alg,
1527 const uint8_t *input,
1528 size_t input_length,
1529 uint8_t *output,
1530 size_t output_size,
1531 size_t *output_length);
1532
1533/** Decrypt a message using a symmetric cipher.
1534 *
1535 * This function decrypts a message encrypted with a symmetric cipher.
1536 *
1537 * \param handle Handle to the key to use for the operation.
1538 * It must remain valid until the operation
1539 * terminates.
1540 * \param alg The cipher algorithm to compute
1541 * (\c PSA_ALG_XXX value such that
1542 * #PSA_ALG_IS_CIPHER(\p alg) is true).
1543 * \param[in] input Buffer containing the message to decrypt.
1544 * This consists of the IV followed by the
1545 * ciphertext proper.
1546 * \param input_length Size of the \p input buffer in bytes.
1547 * \param[out] output Buffer where the plaintext is to be written.
1548 * \param output_size Size of the \p output buffer in bytes.
1549 * \param[out] output_length On success, the number of bytes
1550 * that make up the output.
1551 *
1552 * \retval #PSA_SUCCESS
1553 * Success.
1554 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine69647a42019-01-14 20:18:12 +01001555 * \retval #PSA_ERROR_NOT_PERMITTED
1556 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001557 * \p handle is not compatible with \p alg.
Gilles Peskine69647a42019-01-14 20:18:12 +01001558 * \retval #PSA_ERROR_NOT_SUPPORTED
1559 * \p alg is not supported or is not a cipher algorithm.
1560 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
1561 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1562 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1563 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001564 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine69647a42019-01-14 20:18:12 +01001565 */
1566psa_status_t psa_cipher_decrypt(psa_key_handle_t handle,
1567 psa_algorithm_t alg,
1568 const uint8_t *input,
1569 size_t input_length,
1570 uint8_t *output,
1571 size_t output_size,
1572 size_t *output_length);
1573
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001574/** The type of the state data structure for multipart cipher operations.
1575 *
Jaeden Amero5bae2272019-01-04 11:48:27 +00001576 * Before calling any function on a cipher operation object, the application
1577 * must initialize it by any of the following means:
1578 * - Set the structure to all-bits-zero, for example:
1579 * \code
1580 * psa_cipher_operation_t operation;
1581 * memset(&operation, 0, sizeof(operation));
1582 * \endcode
1583 * - Initialize the structure to logical zero values, for example:
1584 * \code
1585 * psa_cipher_operation_t operation = {0};
1586 * \endcode
1587 * - Initialize the structure to the initializer #PSA_CIPHER_OPERATION_INIT,
1588 * for example:
1589 * \code
1590 * psa_cipher_operation_t operation = PSA_CIPHER_OPERATION_INIT;
1591 * \endcode
1592 * - Assign the result of the function psa_cipher_operation_init()
1593 * to the structure, for example:
1594 * \code
1595 * psa_cipher_operation_t operation;
1596 * operation = psa_cipher_operation_init();
1597 * \endcode
1598 *
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001599 * This is an implementation-defined \c struct. Applications should not
1600 * make any assumptions about the content of this structure except
1601 * as directed by the documentation of a specific implementation. */
1602typedef struct psa_cipher_operation_s psa_cipher_operation_t;
1603
Jaeden Amero5bae2272019-01-04 11:48:27 +00001604/** \def PSA_CIPHER_OPERATION_INIT
1605 *
1606 * This macro returns a suitable initializer for a cipher operation object of
1607 * type #psa_cipher_operation_t.
1608 */
1609#ifdef __DOXYGEN_ONLY__
1610/* This is an example definition for documentation purposes.
1611 * Implementations should define a suitable value in `crypto_struct.h`.
1612 */
1613#define PSA_CIPHER_OPERATION_INIT {0}
1614#endif
1615
1616/** Return an initial value for a cipher operation object.
1617 */
1618static psa_cipher_operation_t psa_cipher_operation_init(void);
1619
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001620/** Set the key for a multipart symmetric encryption operation.
1621 *
1622 * The sequence of operations to encrypt a message with a symmetric cipher
1623 * is as follows:
1624 * -# Allocate an operation object which will be passed to all the functions
1625 * listed here.
Jaeden Amero5bae2272019-01-04 11:48:27 +00001626 * -# Initialize the operation object with one of the methods described in the
1627 * documentation for #psa_cipher_operation_t, e.g.
1628 * PSA_CIPHER_OPERATION_INIT.
Gilles Peskinefe119512018-07-08 21:39:34 +02001629 * -# Call psa_cipher_encrypt_setup() to specify the algorithm and key.
itayzafrired7382f2018-08-02 14:19:33 +03001630 * -# Call either psa_cipher_generate_iv() or psa_cipher_set_iv() to
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001631 * generate or set the IV (initialization vector). You should use
itayzafrired7382f2018-08-02 14:19:33 +03001632 * psa_cipher_generate_iv() unless the protocol you are implementing
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001633 * requires a specific IV value.
1634 * -# Call psa_cipher_update() zero, one or more times, passing a fragment
1635 * of the message each time.
1636 * -# Call psa_cipher_finish().
1637 *
1638 * The application may call psa_cipher_abort() at any time after the operation
Jaeden Amero5bae2272019-01-04 11:48:27 +00001639 * has been initialized.
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001640 *
Gilles Peskinefe119512018-07-08 21:39:34 +02001641 * After a successful call to psa_cipher_encrypt_setup(), the application must
Gilles Peskineed522972018-03-20 17:54:15 +01001642 * eventually terminate the operation. The following events terminate an
1643 * operation:
Gilles Peskinef45adda2019-01-14 18:29:18 +01001644 * - A failed call to any of the \c psa_cipher_xxx functions.
Gilles Peskine19067982018-03-20 17:54:53 +01001645 * - A call to psa_cipher_finish() or psa_cipher_abort().
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001646 *
Jaeden Amero5bae2272019-01-04 11:48:27 +00001647 * \param[in,out] operation The operation object to set up. It must have
1648 * been initialized as per the documentation for
1649 * #psa_cipher_operation_t and not yet in use.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001650 * \param handle Handle to the key to use for the operation.
Gilles Peskine5f25dd02019-01-14 18:24:53 +01001651 * It must remain valid until the operation
1652 * terminates.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001653 * \param alg The cipher algorithm to compute
1654 * (\c PSA_ALG_XXX value such that
1655 * #PSA_ALG_IS_CIPHER(\p alg) is true).
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001656 *
Gilles Peskine28538492018-07-11 17:34:00 +02001657 * \retval #PSA_SUCCESS
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001658 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001659 * \retval #PSA_ERROR_INVALID_HANDLE
David Saadab4ecc272019-02-14 13:48:10 +02001660 * \retval #PSA_ERROR_DOES_NOT_EXIST
Gilles Peskine28538492018-07-11 17:34:00 +02001661 * \retval #PSA_ERROR_NOT_PERMITTED
1662 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001663 * \p handle is not compatible with \p alg.
Gilles Peskine28538492018-07-11 17:34:00 +02001664 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001665 * \p alg is not supported or is not a cipher algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02001666 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1667 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1668 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001669 * \retval #PSA_ERROR_CORRUPTION_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03001670 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskine8e1addc2019-01-10 11:51:17 +01001671 * The operation state is not valid (already set up and not
1672 * subsequently completed).
1673 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03001674 * The library has not been previously initialized by psa_crypto_init().
1675 * It is implementation-dependent whether a failure to initialize
1676 * results in this error code.
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001677 */
Gilles Peskinefe119512018-07-08 21:39:34 +02001678psa_status_t psa_cipher_encrypt_setup(psa_cipher_operation_t *operation,
Gilles Peskineae32aac2018-11-30 14:39:32 +01001679 psa_key_handle_t handle,
Gilles Peskinefe119512018-07-08 21:39:34 +02001680 psa_algorithm_t alg);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001681
1682/** Set the key for a multipart symmetric decryption operation.
1683 *
1684 * The sequence of operations to decrypt a message with a symmetric cipher
1685 * is as follows:
1686 * -# Allocate an operation object which will be passed to all the functions
1687 * listed here.
Jaeden Amero5bae2272019-01-04 11:48:27 +00001688 * -# Initialize the operation object with one of the methods described in the
1689 * documentation for #psa_cipher_operation_t, e.g.
1690 * PSA_CIPHER_OPERATION_INIT.
Gilles Peskinefe119512018-07-08 21:39:34 +02001691 * -# Call psa_cipher_decrypt_setup() to specify the algorithm and key.
Gilles Peskinef45adda2019-01-14 18:29:18 +01001692 * -# Call psa_cipher_set_iv() with the IV (initialization vector) for the
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001693 * decryption. If the IV is prepended to the ciphertext, you can call
1694 * psa_cipher_update() on a buffer containing the IV followed by the
1695 * beginning of the message.
1696 * -# Call psa_cipher_update() zero, one or more times, passing a fragment
1697 * of the message each time.
1698 * -# Call psa_cipher_finish().
1699 *
1700 * The application may call psa_cipher_abort() at any time after the operation
Jaeden Amero5bae2272019-01-04 11:48:27 +00001701 * has been initialized.
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001702 *
Gilles Peskinefe119512018-07-08 21:39:34 +02001703 * After a successful call to psa_cipher_decrypt_setup(), the application must
Gilles Peskineed522972018-03-20 17:54:15 +01001704 * eventually terminate the operation. The following events terminate an
1705 * operation:
Gilles Peskinef45adda2019-01-14 18:29:18 +01001706 * - A failed call to any of the \c psa_cipher_xxx functions.
Gilles Peskine19067982018-03-20 17:54:53 +01001707 * - A call to psa_cipher_finish() or psa_cipher_abort().
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001708 *
Jaeden Amero5bae2272019-01-04 11:48:27 +00001709 * \param[in,out] operation The operation object to set up. It must have
1710 * been initialized as per the documentation for
1711 * #psa_cipher_operation_t and not yet in use.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001712 * \param handle Handle to the key to use for the operation.
Gilles Peskine5f25dd02019-01-14 18:24:53 +01001713 * It must remain valid until the operation
1714 * terminates.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001715 * \param alg The cipher algorithm to compute
1716 * (\c PSA_ALG_XXX value such that
1717 * #PSA_ALG_IS_CIPHER(\p alg) is true).
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001718 *
Gilles Peskine28538492018-07-11 17:34:00 +02001719 * \retval #PSA_SUCCESS
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001720 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001721 * \retval #PSA_ERROR_INVALID_HANDLE
David Saadab4ecc272019-02-14 13:48:10 +02001722 * \retval #PSA_ERROR_DOES_NOT_EXIST
Gilles Peskine28538492018-07-11 17:34:00 +02001723 * \retval #PSA_ERROR_NOT_PERMITTED
1724 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001725 * \p handle is not compatible with \p alg.
Gilles Peskine28538492018-07-11 17:34:00 +02001726 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001727 * \p alg is not supported or is not a cipher algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02001728 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1729 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1730 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001731 * \retval #PSA_ERROR_CORRUPTION_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03001732 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskine8e1addc2019-01-10 11:51:17 +01001733 * The operation state is not valid (already set up and not
1734 * subsequently completed).
1735 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03001736 * The library has not been previously initialized by psa_crypto_init().
1737 * It is implementation-dependent whether a failure to initialize
1738 * results in this error code.
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001739 */
Gilles Peskinefe119512018-07-08 21:39:34 +02001740psa_status_t psa_cipher_decrypt_setup(psa_cipher_operation_t *operation,
Gilles Peskineae32aac2018-11-30 14:39:32 +01001741 psa_key_handle_t handle,
Gilles Peskinefe119512018-07-08 21:39:34 +02001742 psa_algorithm_t alg);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001743
Gilles Peskinedcd14942018-07-12 00:30:52 +02001744/** Generate an IV for a symmetric encryption operation.
1745 *
1746 * This function generates a random IV (initialization vector), nonce
1747 * or initial counter value for the encryption operation as appropriate
1748 * for the chosen algorithm, key type and key size.
1749 *
1750 * The application must call psa_cipher_encrypt_setup() before
1751 * calling this function.
1752 *
1753 * If this function returns an error status, the operation becomes inactive.
1754 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001755 * \param[in,out] operation Active cipher operation.
1756 * \param[out] iv Buffer where the generated IV is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001757 * \param iv_size Size of the \p iv buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001758 * \param[out] iv_length On success, the number of bytes of the
1759 * generated IV.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001760 *
1761 * \retval #PSA_SUCCESS
1762 * Success.
1763 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001764 * The operation state is not valid (not set up, or IV already set).
Gilles Peskinedcd14942018-07-12 00:30:52 +02001765 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinedda3bd32018-07-12 19:40:46 +02001766 * The size of the \p iv buffer is too small.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001767 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1768 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1769 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001770 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskinedcd14942018-07-12 00:30:52 +02001771 */
Gilles Peskinefe119512018-07-08 21:39:34 +02001772psa_status_t psa_cipher_generate_iv(psa_cipher_operation_t *operation,
Andrew Thoelke47629d02019-03-22 11:24:17 +00001773 uint8_t *iv,
Gilles Peskinefe119512018-07-08 21:39:34 +02001774 size_t iv_size,
1775 size_t *iv_length);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001776
Gilles Peskinedcd14942018-07-12 00:30:52 +02001777/** Set the IV for a symmetric encryption or decryption operation.
1778 *
Gilles Peskinef45adda2019-01-14 18:29:18 +01001779 * This function sets the IV (initialization vector), nonce
Gilles Peskinedcd14942018-07-12 00:30:52 +02001780 * or initial counter value for the encryption or decryption operation.
1781 *
1782 * The application must call psa_cipher_encrypt_setup() before
1783 * calling this function.
1784 *
1785 * If this function returns an error status, the operation becomes inactive.
1786 *
1787 * \note When encrypting, applications should use psa_cipher_generate_iv()
1788 * instead of this function, unless implementing a protocol that requires
1789 * a non-random IV.
1790 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001791 * \param[in,out] operation Active cipher operation.
1792 * \param[in] iv Buffer containing the IV to use.
1793 * \param iv_length Size of the IV in bytes.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001794 *
1795 * \retval #PSA_SUCCESS
1796 * Success.
1797 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001798 * The operation state is not valid (not set up, or IV already set).
Gilles Peskinedcd14942018-07-12 00:30:52 +02001799 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001800 * The size of \p iv is not acceptable for the chosen algorithm,
Gilles Peskinedcd14942018-07-12 00:30:52 +02001801 * or the chosen algorithm does not use an IV.
1802 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1803 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1804 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001805 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskinedcd14942018-07-12 00:30:52 +02001806 */
Gilles Peskinefe119512018-07-08 21:39:34 +02001807psa_status_t psa_cipher_set_iv(psa_cipher_operation_t *operation,
Andrew Thoelke47629d02019-03-22 11:24:17 +00001808 const uint8_t *iv,
Gilles Peskinefe119512018-07-08 21:39:34 +02001809 size_t iv_length);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001810
Gilles Peskinedcd14942018-07-12 00:30:52 +02001811/** Encrypt or decrypt a message fragment in an active cipher operation.
1812 *
Gilles Peskine9ac94262018-07-12 20:15:32 +02001813 * Before calling this function, you must:
1814 * 1. Call either psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup().
1815 * The choice of setup function determines whether this function
1816 * encrypts or decrypts its input.
1817 * 2. If the algorithm requires an IV, call psa_cipher_generate_iv()
1818 * (recommended when encrypting) or psa_cipher_set_iv().
Gilles Peskinedcd14942018-07-12 00:30:52 +02001819 *
1820 * If this function returns an error status, the operation becomes inactive.
1821 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001822 * \param[in,out] operation Active cipher operation.
1823 * \param[in] input Buffer containing the message fragment to
1824 * encrypt or decrypt.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001825 * \param input_length Size of the \p input buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001826 * \param[out] output Buffer where the output is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001827 * \param output_size Size of the \p output buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001828 * \param[out] output_length On success, the number of bytes
1829 * that make up the returned output.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001830 *
1831 * \retval #PSA_SUCCESS
1832 * Success.
1833 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001834 * The operation state is not valid (not set up, IV required but
Gilles Peskinedcd14942018-07-12 00:30:52 +02001835 * not set, or already completed).
1836 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
1837 * The size of the \p output buffer is too small.
1838 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1839 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1840 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001841 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskinedcd14942018-07-12 00:30:52 +02001842 */
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001843psa_status_t psa_cipher_update(psa_cipher_operation_t *operation,
1844 const uint8_t *input,
mohammad1603503973b2018-03-12 15:59:30 +02001845 size_t input_length,
Andrew Thoelke47629d02019-03-22 11:24:17 +00001846 uint8_t *output,
Gilles Peskine2d277862018-06-18 15:41:12 +02001847 size_t output_size,
mohammad1603503973b2018-03-12 15:59:30 +02001848 size_t *output_length);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001849
Gilles Peskinedcd14942018-07-12 00:30:52 +02001850/** Finish encrypting or decrypting a message in a cipher operation.
1851 *
1852 * The application must call psa_cipher_encrypt_setup() or
1853 * psa_cipher_decrypt_setup() before calling this function. The choice
1854 * of setup function determines whether this function encrypts or
1855 * decrypts its input.
1856 *
1857 * This function finishes the encryption or decryption of the message
1858 * formed by concatenating the inputs passed to preceding calls to
1859 * psa_cipher_update().
1860 *
1861 * When this function returns, the operation becomes inactive.
1862 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001863 * \param[in,out] operation Active cipher operation.
1864 * \param[out] output Buffer where the output is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001865 * \param output_size Size of the \p output buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001866 * \param[out] output_length On success, the number of bytes
1867 * that make up the returned output.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001868 *
1869 * \retval #PSA_SUCCESS
1870 * Success.
1871 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001872 * The operation state is not valid (not set up, IV required but
Gilles Peskinedcd14942018-07-12 00:30:52 +02001873 * not set, or already completed).
1874 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
1875 * The size of the \p output buffer is too small.
1876 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1877 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1878 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001879 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskinedcd14942018-07-12 00:30:52 +02001880 */
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001881psa_status_t psa_cipher_finish(psa_cipher_operation_t *operation,
mohammad1603503973b2018-03-12 15:59:30 +02001882 uint8_t *output,
Moran Peker0071b872018-04-22 20:16:58 +03001883 size_t output_size,
mohammad1603503973b2018-03-12 15:59:30 +02001884 size_t *output_length);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001885
Gilles Peskinedcd14942018-07-12 00:30:52 +02001886/** Abort a cipher operation.
1887 *
Gilles Peskinedcd14942018-07-12 00:30:52 +02001888 * Aborting an operation frees all associated resources except for the
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001889 * \p operation structure itself. Once aborted, the operation object
1890 * can be reused for another operation by calling
1891 * psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup() again.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001892 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001893 * You may call this function any time after the operation object has
1894 * been initialized by any of the following methods:
1895 * - A call to psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup(),
1896 * whether it succeeds or not.
1897 * - Initializing the \c struct to all-bits-zero.
1898 * - Initializing the \c struct to logical zeros, e.g.
1899 * `psa_cipher_operation_t operation = {0}`.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001900 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001901 * In particular, calling psa_cipher_abort() after the operation has been
1902 * terminated by a call to psa_cipher_abort() or psa_cipher_finish()
1903 * is safe and has no effect.
1904 *
1905 * \param[in,out] operation Initialized cipher operation.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001906 *
1907 * \retval #PSA_SUCCESS
1908 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001909 * \p operation is not an active cipher operation.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001910 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1911 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001912 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskinedcd14942018-07-12 00:30:52 +02001913 */
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001914psa_status_t psa_cipher_abort(psa_cipher_operation_t *operation);
1915
1916/**@}*/
1917
Gilles Peskine3b555712018-03-03 21:27:57 +01001918/** \defgroup aead Authenticated encryption with associated data (AEAD)
1919 * @{
1920 */
1921
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02001922/** Process an authenticated encryption operation.
Gilles Peskine3b555712018-03-03 21:27:57 +01001923 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01001924 * \param handle Handle to the key to use for the operation.
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02001925 * \param alg The AEAD algorithm to compute
1926 * (\c PSA_ALG_XXX value such that
Gilles Peskine7256e6c2018-07-12 00:34:26 +02001927 * #PSA_ALG_IS_AEAD(\p alg) is true).
Gilles Peskineedd11a12018-07-12 01:08:58 +02001928 * \param[in] nonce Nonce or IV to use.
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02001929 * \param nonce_length Size of the \p nonce buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001930 * \param[in] additional_data Additional data that will be authenticated
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02001931 * but not encrypted.
1932 * \param additional_data_length Size of \p additional_data in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001933 * \param[in] plaintext Data that will be authenticated and
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02001934 * encrypted.
1935 * \param plaintext_length Size of \p plaintext in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001936 * \param[out] ciphertext Output buffer for the authenticated and
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02001937 * encrypted data. The additional data is not
1938 * part of this output. For algorithms where the
1939 * encrypted data and the authentication tag
1940 * are defined as separate outputs, the
1941 * authentication tag is appended to the
1942 * encrypted data.
1943 * \param ciphertext_size Size of the \p ciphertext buffer in bytes.
1944 * This must be at least
1945 * #PSA_AEAD_ENCRYPT_OUTPUT_SIZE(\p alg,
1946 * \p plaintext_length).
Gilles Peskineedd11a12018-07-12 01:08:58 +02001947 * \param[out] ciphertext_length On success, the size of the output
Gilles Peskine4c6fdbb2019-02-08 11:22:39 +01001948 * in the \p ciphertext buffer.
Gilles Peskine3b555712018-03-03 21:27:57 +01001949 *
Gilles Peskine28538492018-07-11 17:34:00 +02001950 * \retval #PSA_SUCCESS
Gilles Peskine3b555712018-03-03 21:27:57 +01001951 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001952 * \retval #PSA_ERROR_INVALID_HANDLE
David Saadab4ecc272019-02-14 13:48:10 +02001953 * \retval #PSA_ERROR_DOES_NOT_EXIST
Gilles Peskine28538492018-07-11 17:34:00 +02001954 * \retval #PSA_ERROR_NOT_PERMITTED
1955 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001956 * \p handle is not compatible with \p alg.
Gilles Peskine28538492018-07-11 17:34:00 +02001957 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001958 * \p alg is not supported or is not an AEAD algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02001959 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1960 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1961 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02001962 * \retval #PSA_ERROR_CORRUPTION_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03001963 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03001964 * The library has not been previously initialized by psa_crypto_init().
1965 * It is implementation-dependent whether a failure to initialize
1966 * results in this error code.
Gilles Peskine3b555712018-03-03 21:27:57 +01001967 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01001968psa_status_t psa_aead_encrypt(psa_key_handle_t handle,
Gilles Peskine9fb0e012018-07-19 15:51:49 +02001969 psa_algorithm_t alg,
1970 const uint8_t *nonce,
1971 size_t nonce_length,
1972 const uint8_t *additional_data,
1973 size_t additional_data_length,
1974 const uint8_t *plaintext,
1975 size_t plaintext_length,
1976 uint8_t *ciphertext,
1977 size_t ciphertext_size,
1978 size_t *ciphertext_length);
Gilles Peskine3b555712018-03-03 21:27:57 +01001979
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02001980/** Process an authenticated decryption operation.
Gilles Peskine3b555712018-03-03 21:27:57 +01001981 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01001982 * \param handle Handle to the key to use for the operation.
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02001983 * \param alg The AEAD algorithm to compute
1984 * (\c PSA_ALG_XXX value such that
Gilles Peskine7256e6c2018-07-12 00:34:26 +02001985 * #PSA_ALG_IS_AEAD(\p alg) is true).
Gilles Peskineedd11a12018-07-12 01:08:58 +02001986 * \param[in] nonce Nonce or IV to use.
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02001987 * \param nonce_length Size of the \p nonce buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001988 * \param[in] additional_data Additional data that has been authenticated
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02001989 * but not encrypted.
1990 * \param additional_data_length Size of \p additional_data in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001991 * \param[in] ciphertext Data that has been authenticated and
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02001992 * encrypted. For algorithms where the
1993 * encrypted data and the authentication tag
1994 * are defined as separate inputs, the buffer
1995 * must contain the encrypted data followed
1996 * by the authentication tag.
1997 * \param ciphertext_length Size of \p ciphertext in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001998 * \param[out] plaintext Output buffer for the decrypted data.
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02001999 * \param plaintext_size Size of the \p plaintext buffer in bytes.
2000 * This must be at least
2001 * #PSA_AEAD_DECRYPT_OUTPUT_SIZE(\p alg,
2002 * \p ciphertext_length).
Gilles Peskineedd11a12018-07-12 01:08:58 +02002003 * \param[out] plaintext_length On success, the size of the output
Gilles Peskine4c6fdbb2019-02-08 11:22:39 +01002004 * in the \p plaintext buffer.
Gilles Peskine3b555712018-03-03 21:27:57 +01002005 *
Gilles Peskine28538492018-07-11 17:34:00 +02002006 * \retval #PSA_SUCCESS
Gilles Peskine3b555712018-03-03 21:27:57 +01002007 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01002008 * \retval #PSA_ERROR_INVALID_HANDLE
David Saadab4ecc272019-02-14 13:48:10 +02002009 * \retval #PSA_ERROR_DOES_NOT_EXIST
Gilles Peskine28538492018-07-11 17:34:00 +02002010 * \retval #PSA_ERROR_INVALID_SIGNATURE
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002011 * The ciphertext is not authentic.
Gilles Peskine28538492018-07-11 17:34:00 +02002012 * \retval #PSA_ERROR_NOT_PERMITTED
2013 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002014 * \p handle is not compatible with \p alg.
Gilles Peskine28538492018-07-11 17:34:00 +02002015 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002016 * \p alg is not supported or is not an AEAD algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02002017 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2018 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2019 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002020 * \retval #PSA_ERROR_CORRUPTION_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03002021 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03002022 * The library has not been previously initialized by psa_crypto_init().
2023 * It is implementation-dependent whether a failure to initialize
2024 * results in this error code.
Gilles Peskine3b555712018-03-03 21:27:57 +01002025 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01002026psa_status_t psa_aead_decrypt(psa_key_handle_t handle,
Gilles Peskine9fb0e012018-07-19 15:51:49 +02002027 psa_algorithm_t alg,
2028 const uint8_t *nonce,
2029 size_t nonce_length,
2030 const uint8_t *additional_data,
2031 size_t additional_data_length,
2032 const uint8_t *ciphertext,
2033 size_t ciphertext_length,
2034 uint8_t *plaintext,
2035 size_t plaintext_size,
2036 size_t *plaintext_length);
Gilles Peskine3b555712018-03-03 21:27:57 +01002037
Gilles Peskine30a9e412019-01-14 18:36:12 +01002038/** The type of the state data structure for multipart AEAD operations.
2039 *
2040 * Before calling any function on an AEAD operation object, the application
2041 * must initialize it by any of the following means:
2042 * - Set the structure to all-bits-zero, for example:
2043 * \code
2044 * psa_aead_operation_t operation;
2045 * memset(&operation, 0, sizeof(operation));
2046 * \endcode
2047 * - Initialize the structure to logical zero values, for example:
2048 * \code
2049 * psa_aead_operation_t operation = {0};
2050 * \endcode
2051 * - Initialize the structure to the initializer #PSA_AEAD_OPERATION_INIT,
2052 * for example:
2053 * \code
2054 * psa_aead_operation_t operation = PSA_AEAD_OPERATION_INIT;
2055 * \endcode
2056 * - Assign the result of the function psa_aead_operation_init()
2057 * to the structure, for example:
2058 * \code
2059 * psa_aead_operation_t operation;
2060 * operation = psa_aead_operation_init();
2061 * \endcode
2062 *
2063 * This is an implementation-defined \c struct. Applications should not
2064 * make any assumptions about the content of this structure except
2065 * as directed by the documentation of a specific implementation. */
2066typedef struct psa_aead_operation_s psa_aead_operation_t;
2067
2068/** \def PSA_AEAD_OPERATION_INIT
2069 *
2070 * This macro returns a suitable initializer for an AEAD operation object of
2071 * type #psa_aead_operation_t.
2072 */
2073#ifdef __DOXYGEN_ONLY__
2074/* This is an example definition for documentation purposes.
2075 * Implementations should define a suitable value in `crypto_struct.h`.
2076 */
2077#define PSA_AEAD_OPERATION_INIT {0}
2078#endif
2079
2080/** Return an initial value for an AEAD operation object.
2081 */
2082static psa_aead_operation_t psa_aead_operation_init(void);
2083
2084/** Set the key for a multipart authenticated encryption operation.
2085 *
2086 * The sequence of operations to encrypt a message with authentication
2087 * is as follows:
2088 * -# Allocate an operation object which will be passed to all the functions
2089 * listed here.
2090 * -# Initialize the operation object with one of the methods described in the
2091 * documentation for #psa_aead_operation_t, e.g.
2092 * PSA_AEAD_OPERATION_INIT.
2093 * -# Call psa_aead_encrypt_setup() to specify the algorithm and key.
Gilles Peskinebc59c852019-01-17 15:26:08 +01002094 * -# If needed, call psa_aead_set_lengths() to specify the length of the
2095 * inputs to the subsequent calls to psa_aead_update_ad() and
2096 * psa_aead_update(). See the documentation of psa_aead_set_lengths()
2097 * for details.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002098 * -# Call either psa_aead_generate_nonce() or psa_aead_set_nonce() to
2099 * generate or set the nonce. You should use
2100 * psa_aead_generate_nonce() unless the protocol you are implementing
2101 * requires a specific nonce value.
2102 * -# Call psa_aead_update_ad() zero, one or more times, passing a fragment
2103 * of the non-encrypted additional authenticated data each time.
2104 * -# Call psa_aead_update() zero, one or more times, passing a fragment
Gilles Peskinea05602d2019-01-17 15:25:52 +01002105 * of the message to encrypt each time.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002106 * -# Call psa_aead_finish().
2107 *
2108 * The application may call psa_aead_abort() at any time after the operation
2109 * has been initialized.
2110 *
2111 * After a successful call to psa_aead_encrypt_setup(), the application must
2112 * eventually terminate the operation. The following events terminate an
2113 * operation:
2114 * - A failed call to any of the \c psa_aead_xxx functions.
2115 * - A call to psa_aead_finish(), psa_aead_verify() or psa_aead_abort().
2116 *
2117 * \param[in,out] operation The operation object to set up. It must have
2118 * been initialized as per the documentation for
2119 * #psa_aead_operation_t and not yet in use.
2120 * \param handle Handle to the key to use for the operation.
2121 * It must remain valid until the operation
2122 * terminates.
2123 * \param alg The AEAD algorithm to compute
2124 * (\c PSA_ALG_XXX value such that
2125 * #PSA_ALG_IS_AEAD(\p alg) is true).
2126 *
2127 * \retval #PSA_SUCCESS
2128 * Success.
2129 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine30a9e412019-01-14 18:36:12 +01002130 * \retval #PSA_ERROR_NOT_PERMITTED
2131 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002132 * \p handle is not compatible with \p alg.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002133 * \retval #PSA_ERROR_NOT_SUPPORTED
2134 * \p alg is not supported or is not an AEAD algorithm.
2135 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2136 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2137 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002138 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine30a9e412019-01-14 18:36:12 +01002139 * \retval #PSA_ERROR_BAD_STATE
2140 * The library has not been previously initialized by psa_crypto_init().
2141 * It is implementation-dependent whether a failure to initialize
2142 * results in this error code.
2143 */
2144psa_status_t psa_aead_encrypt_setup(psa_aead_operation_t *operation,
2145 psa_key_handle_t handle,
2146 psa_algorithm_t alg);
2147
2148/** Set the key for a multipart authenticated decryption operation.
2149 *
2150 * The sequence of operations to decrypt a message with authentication
2151 * is as follows:
2152 * -# Allocate an operation object which will be passed to all the functions
2153 * listed here.
2154 * -# Initialize the operation object with one of the methods described in the
2155 * documentation for #psa_aead_operation_t, e.g.
2156 * PSA_AEAD_OPERATION_INIT.
2157 * -# Call psa_aead_decrypt_setup() to specify the algorithm and key.
Gilles Peskinebc59c852019-01-17 15:26:08 +01002158 * -# If needed, call psa_aead_set_lengths() to specify the length of the
2159 * inputs to the subsequent calls to psa_aead_update_ad() and
2160 * psa_aead_update(). See the documentation of psa_aead_set_lengths()
2161 * for details.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002162 * -# Call psa_aead_set_nonce() with the nonce for the decryption.
2163 * -# Call psa_aead_update_ad() zero, one or more times, passing a fragment
2164 * of the non-encrypted additional authenticated data each time.
2165 * -# Call psa_aead_update() zero, one or more times, passing a fragment
Gilles Peskinea05602d2019-01-17 15:25:52 +01002166 * of the ciphertext to decrypt each time.
2167 * -# Call psa_aead_verify().
Gilles Peskine30a9e412019-01-14 18:36:12 +01002168 *
2169 * The application may call psa_aead_abort() at any time after the operation
2170 * has been initialized.
2171 *
2172 * After a successful call to psa_aead_decrypt_setup(), the application must
2173 * eventually terminate the operation. The following events terminate an
2174 * operation:
2175 * - A failed call to any of the \c psa_aead_xxx functions.
2176 * - A call to psa_aead_finish(), psa_aead_verify() or psa_aead_abort().
2177 *
2178 * \param[in,out] operation The operation object to set up. It must have
2179 * been initialized as per the documentation for
2180 * #psa_aead_operation_t and not yet in use.
2181 * \param handle Handle to the key to use for the operation.
2182 * It must remain valid until the operation
2183 * terminates.
2184 * \param alg The AEAD algorithm to compute
2185 * (\c PSA_ALG_XXX value such that
2186 * #PSA_ALG_IS_AEAD(\p alg) is true).
2187 *
2188 * \retval #PSA_SUCCESS
2189 * Success.
2190 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine30a9e412019-01-14 18:36:12 +01002191 * \retval #PSA_ERROR_NOT_PERMITTED
2192 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002193 * \p handle is not compatible with \p alg.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002194 * \retval #PSA_ERROR_NOT_SUPPORTED
2195 * \p alg is not supported or is not an AEAD algorithm.
2196 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2197 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2198 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002199 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine30a9e412019-01-14 18:36:12 +01002200 * \retval #PSA_ERROR_BAD_STATE
2201 * The library has not been previously initialized by psa_crypto_init().
2202 * It is implementation-dependent whether a failure to initialize
2203 * results in this error code.
2204 */
2205psa_status_t psa_aead_decrypt_setup(psa_aead_operation_t *operation,
2206 psa_key_handle_t handle,
2207 psa_algorithm_t alg);
2208
2209/** Generate a random nonce for an authenticated encryption operation.
2210 *
2211 * This function generates a random nonce for the authenticated encryption
2212 * operation with an appropriate size for the chosen algorithm, key type
2213 * and key size.
2214 *
2215 * The application must call psa_aead_encrypt_setup() before
2216 * calling this function.
2217 *
2218 * If this function returns an error status, the operation becomes inactive.
2219 *
2220 * \param[in,out] operation Active AEAD operation.
2221 * \param[out] nonce Buffer where the generated nonce is to be
2222 * written.
2223 * \param nonce_size Size of the \p nonce buffer in bytes.
2224 * \param[out] nonce_length On success, the number of bytes of the
2225 * generated nonce.
2226 *
2227 * \retval #PSA_SUCCESS
2228 * Success.
2229 * \retval #PSA_ERROR_BAD_STATE
2230 * The operation state is not valid (not set up, or nonce already set).
2231 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
2232 * The size of the \p nonce buffer is too small.
2233 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2234 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2235 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002236 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine30a9e412019-01-14 18:36:12 +01002237 */
2238psa_status_t psa_aead_generate_nonce(psa_aead_operation_t *operation,
Andrew Thoelked16bdac2019-05-15 12:34:01 +01002239 uint8_t *nonce,
Gilles Peskine30a9e412019-01-14 18:36:12 +01002240 size_t nonce_size,
2241 size_t *nonce_length);
2242
2243/** Set the nonce for an authenticated encryption or decryption operation.
2244 *
2245 * This function sets the nonce for the authenticated
2246 * encryption or decryption operation.
2247 *
2248 * The application must call psa_aead_encrypt_setup() before
2249 * calling this function.
2250 *
2251 * If this function returns an error status, the operation becomes inactive.
2252 *
Gilles Peskinea05602d2019-01-17 15:25:52 +01002253 * \note When encrypting, applications should use psa_aead_generate_nonce()
Gilles Peskine30a9e412019-01-14 18:36:12 +01002254 * instead of this function, unless implementing a protocol that requires
2255 * a non-random IV.
2256 *
2257 * \param[in,out] operation Active AEAD operation.
Gilles Peskinea05602d2019-01-17 15:25:52 +01002258 * \param[in] nonce Buffer containing the nonce to use.
2259 * \param nonce_length Size of the nonce in bytes.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002260 *
2261 * \retval #PSA_SUCCESS
2262 * Success.
2263 * \retval #PSA_ERROR_BAD_STATE
2264 * The operation state is not valid (not set up, or nonce already set).
2265 * \retval #PSA_ERROR_INVALID_ARGUMENT
2266 * The size of \p nonce is not acceptable for the chosen algorithm.
2267 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2268 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2269 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002270 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine30a9e412019-01-14 18:36:12 +01002271 */
2272psa_status_t psa_aead_set_nonce(psa_aead_operation_t *operation,
Andrew Thoelked16bdac2019-05-15 12:34:01 +01002273 const uint8_t *nonce,
Gilles Peskine30a9e412019-01-14 18:36:12 +01002274 size_t nonce_length);
2275
Gilles Peskinebc59c852019-01-17 15:26:08 +01002276/** Declare the lengths of the message and additional data for AEAD.
2277 *
2278 * The application must call this function before calling
2279 * psa_aead_update_ad() or psa_aead_update() if the algorithm for
2280 * the operation requires it. If the algorithm does not require it,
2281 * calling this function is optional, but if this function is called
2282 * then the implementation must enforce the lengths.
2283 *
2284 * You may call this function before or after setting the nonce with
2285 * psa_aead_set_nonce() or psa_aead_generate_nonce().
2286 *
2287 * - For #PSA_ALG_CCM, calling this function is required.
2288 * - For the other AEAD algorithms defined in this specification, calling
2289 * this function is not required.
2290 * - For vendor-defined algorithm, refer to the vendor documentation.
2291 *
2292 * \param[in,out] operation Active AEAD operation.
2293 * \param ad_length Size of the non-encrypted additional
2294 * authenticated data in bytes.
2295 * \param plaintext_length Size of the plaintext to encrypt in bytes.
2296 *
2297 * \retval #PSA_SUCCESS
2298 * Success.
2299 * \retval #PSA_ERROR_BAD_STATE
2300 * The operation state is not valid (not set up, already completed,
2301 * or psa_aead_update_ad() or psa_aead_update() already called).
2302 * \retval #PSA_ERROR_INVALID_ARGUMENT
2303 * At least one of the lengths is not acceptable for the chosen
2304 * algorithm.
2305 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2306 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2307 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002308 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskinebc59c852019-01-17 15:26:08 +01002309 */
2310psa_status_t psa_aead_set_lengths(psa_aead_operation_t *operation,
2311 size_t ad_length,
2312 size_t plaintext_length);
2313
Gilles Peskine30a9e412019-01-14 18:36:12 +01002314/** Pass additional data to an active AEAD operation.
2315 *
2316 * Additional data is authenticated, but not encrypted.
2317 *
2318 * You may call this function multiple times to pass successive fragments
2319 * of the additional data. You may not call this function after passing
2320 * data to encrypt or decrypt with psa_aead_update().
2321 *
2322 * Before calling this function, you must:
2323 * 1. Call either psa_aead_encrypt_setup() or psa_aead_decrypt_setup().
2324 * 2. Set the nonce with psa_aead_generate_nonce() or psa_aead_set_nonce().
2325 *
2326 * If this function returns an error status, the operation becomes inactive.
2327 *
2328 * \warning When decrypting, until psa_aead_verify() has returned #PSA_SUCCESS,
2329 * there is no guarantee that the input is valid. Therefore, until
2330 * you have called psa_aead_verify() and it has returned #PSA_SUCCESS,
2331 * treat the input as untrusted and prepare to undo any action that
2332 * depends on the input if psa_aead_verify() returns an error status.
2333 *
2334 * \param[in,out] operation Active AEAD operation.
2335 * \param[in] input Buffer containing the fragment of
2336 * additional data.
2337 * \param input_length Size of the \p input buffer in bytes.
2338 *
2339 * \retval #PSA_SUCCESS
2340 * Success.
2341 * \retval #PSA_ERROR_BAD_STATE
2342 * The operation state is not valid (not set up, nonce not set,
2343 * psa_aead_update() already called, or operation already completed).
Gilles Peskinebc59c852019-01-17 15:26:08 +01002344 * \retval #PSA_ERROR_INVALID_ARGUMENT
2345 * The total input length overflows the additional data length that
2346 * was previously specified with psa_aead_set_lengths().
Gilles Peskine30a9e412019-01-14 18:36:12 +01002347 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2348 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2349 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002350 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine30a9e412019-01-14 18:36:12 +01002351 */
2352psa_status_t psa_aead_update_ad(psa_aead_operation_t *operation,
2353 const uint8_t *input,
2354 size_t input_length);
2355
2356/** Encrypt or decrypt a message fragment in an active AEAD operation.
2357 *
2358 * Before calling this function, you must:
2359 * 1. Call either psa_aead_encrypt_setup() or psa_aead_decrypt_setup().
2360 * The choice of setup function determines whether this function
2361 * encrypts or decrypts its input.
2362 * 2. Set the nonce with psa_aead_generate_nonce() or psa_aead_set_nonce().
2363 * 3. Call psa_aead_update_ad() to pass all the additional data.
2364 *
2365 * If this function returns an error status, the operation becomes inactive.
2366 *
2367 * \warning When decrypting, until psa_aead_verify() has returned #PSA_SUCCESS,
2368 * there is no guarantee that the input is valid. Therefore, until
2369 * you have called psa_aead_verify() and it has returned #PSA_SUCCESS:
2370 * - Do not use the output in any way other than storing it in a
2371 * confidential location. If you take any action that depends
2372 * on the tentative decrypted data, this action will need to be
2373 * undone if the input turns out not to be valid. Furthermore,
2374 * if an adversary can observe that this action took place
2375 * (for example through timing), they may be able to use this
2376 * fact as an oracle to decrypt any message encrypted with the
2377 * same key.
2378 * - In particular, do not copy the output anywhere but to a
2379 * memory or storage space that you have exclusive access to.
2380 *
Gilles Peskinef02aec92019-05-06 15:42:54 +02002381 * This function does not require the input to be aligned to any
2382 * particular block boundary. If the implementation can only process
Gilles Peskineac99e322019-05-14 16:10:53 +02002383 * a whole block at a time, it must consume all the input provided, but
2384 * it may delay the end of the corresponding output until a subsequent
2385 * call to psa_aead_update(), psa_aead_finish() or psa_aead_verify()
2386 * provides sufficient input. The amount of data that can be delayed
2387 * in this way is bounded by #PSA_AEAD_UPDATE_OUTPUT_SIZE.
Gilles Peskinef02aec92019-05-06 15:42:54 +02002388 *
Gilles Peskine30a9e412019-01-14 18:36:12 +01002389 * \param[in,out] operation Active AEAD operation.
2390 * \param[in] input Buffer containing the message fragment to
2391 * encrypt or decrypt.
2392 * \param input_length Size of the \p input buffer in bytes.
2393 * \param[out] output Buffer where the output is to be written.
2394 * \param output_size Size of the \p output buffer in bytes.
Gilles Peskine49dd8d82019-05-06 15:16:19 +02002395 * This must be at least
2396 * #PSA_AEAD_UPDATE_OUTPUT_SIZE(\c alg,
2397 * \p input_length) where \c alg is the
2398 * algorithm that is being calculated.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002399 * \param[out] output_length On success, the number of bytes
2400 * that make up the returned output.
2401 *
2402 * \retval #PSA_SUCCESS
2403 * Success.
2404 * \retval #PSA_ERROR_BAD_STATE
2405 * The operation state is not valid (not set up, nonce not set
2406 * or already completed).
2407 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
2408 * The size of the \p output buffer is too small.
Gilles Peskine49dd8d82019-05-06 15:16:19 +02002409 * You can determine a sufficient buffer size by calling
2410 * #PSA_AEAD_UPDATE_OUTPUT_SIZE(\c alg, \p input_length)
2411 * where \c alg is the algorithm that is being calculated.
Gilles Peskinebc59c852019-01-17 15:26:08 +01002412 * \retval #PSA_ERROR_INVALID_ARGUMENT
2413 * The total length of input to psa_aead_update_ad() so far is
2414 * less than the additional data length that was previously
2415 * specified with psa_aead_set_lengths().
2416 * \retval #PSA_ERROR_INVALID_ARGUMENT
2417 * The total input length overflows the plaintext length that
2418 * was previously specified with psa_aead_set_lengths().
Gilles Peskine30a9e412019-01-14 18:36:12 +01002419 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2420 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2421 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002422 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine30a9e412019-01-14 18:36:12 +01002423 */
2424psa_status_t psa_aead_update(psa_aead_operation_t *operation,
2425 const uint8_t *input,
2426 size_t input_length,
Andrew Thoelked16bdac2019-05-15 12:34:01 +01002427 uint8_t *output,
Gilles Peskine30a9e412019-01-14 18:36:12 +01002428 size_t output_size,
2429 size_t *output_length);
2430
2431/** Finish encrypting a message in an AEAD operation.
2432 *
2433 * The operation must have been set up with psa_aead_encrypt_setup().
2434 *
2435 * This function finishes the authentication of the additional data
2436 * formed by concatenating the inputs passed to preceding calls to
2437 * psa_aead_update_ad() with the plaintext formed by concatenating the
2438 * inputs passed to preceding calls to psa_aead_update().
2439 *
2440 * This function has two output buffers:
2441 * - \p ciphertext contains trailing ciphertext that was buffered from
Gilles Peskinef02aec92019-05-06 15:42:54 +02002442 * preceding calls to psa_aead_update().
Gilles Peskine30a9e412019-01-14 18:36:12 +01002443 * - \p tag contains the authentication tag. Its length is always
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002444 * #PSA_AEAD_TAG_LENGTH(\c alg) where \c alg is the AEAD algorithm
Gilles Peskine30a9e412019-01-14 18:36:12 +01002445 * that the operation performs.
2446 *
2447 * When this function returns, the operation becomes inactive.
2448 *
2449 * \param[in,out] operation Active AEAD operation.
2450 * \param[out] ciphertext Buffer where the last part of the ciphertext
2451 * is to be written.
2452 * \param ciphertext_size Size of the \p ciphertext buffer in bytes.
Gilles Peskine49dd8d82019-05-06 15:16:19 +02002453 * This must be at least
2454 * #PSA_AEAD_FINISH_OUTPUT_SIZE(\c alg) where
2455 * \c alg is the algorithm that is being
2456 * calculated.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002457 * \param[out] ciphertext_length On success, the number of bytes of
2458 * returned ciphertext.
2459 * \param[out] tag Buffer where the authentication tag is
2460 * to be written.
2461 * \param tag_size Size of the \p tag buffer in bytes.
Gilles Peskine49dd8d82019-05-06 15:16:19 +02002462 * This must be at least
2463 * #PSA_AEAD_TAG_LENGTH(\c alg) where \c alg is
2464 * the algorithm that is being calculated.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002465 * \param[out] tag_length On success, the number of bytes
2466 * that make up the returned tag.
2467 *
2468 * \retval #PSA_SUCCESS
2469 * Success.
2470 * \retval #PSA_ERROR_BAD_STATE
2471 * The operation state is not valid (not set up, nonce not set,
2472 * decryption, or already completed).
2473 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002474 * The size of the \p ciphertext or \p tag buffer is too small.
Gilles Peskine49dd8d82019-05-06 15:16:19 +02002475 * You can determine a sufficient buffer size for \p ciphertext by
2476 * calling #PSA_AEAD_FINISH_OUTPUT_SIZE(\c alg)
2477 * where \c alg is the algorithm that is being calculated.
2478 * You can determine a sufficient buffer size for \p tag by
2479 * calling #PSA_AEAD_TAG_LENGTH(\c alg).
Gilles Peskinebc59c852019-01-17 15:26:08 +01002480 * \retval #PSA_ERROR_INVALID_ARGUMENT
2481 * The total length of input to psa_aead_update_ad() so far is
2482 * less than the additional data length that was previously
2483 * specified with psa_aead_set_lengths().
2484 * \retval #PSA_ERROR_INVALID_ARGUMENT
2485 * The total length of input to psa_aead_update() so far is
2486 * less than the plaintext length that was previously
2487 * specified with psa_aead_set_lengths().
Gilles Peskine30a9e412019-01-14 18:36:12 +01002488 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2489 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2490 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002491 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine30a9e412019-01-14 18:36:12 +01002492 */
2493psa_status_t psa_aead_finish(psa_aead_operation_t *operation,
Gilles Peskinea05602d2019-01-17 15:25:52 +01002494 uint8_t *ciphertext,
2495 size_t ciphertext_size,
2496 size_t *ciphertext_length,
Gilles Peskine30a9e412019-01-14 18:36:12 +01002497 uint8_t *tag,
2498 size_t tag_size,
2499 size_t *tag_length);
2500
2501/** Finish authenticating and decrypting a message in an AEAD operation.
2502 *
2503 * The operation must have been set up with psa_aead_decrypt_setup().
2504 *
2505 * This function finishes the authentication of the additional data
2506 * formed by concatenating the inputs passed to preceding calls to
2507 * psa_aead_update_ad() with the ciphertext formed by concatenating the
2508 * inputs passed to preceding calls to psa_aead_update().
2509 *
2510 * When this function returns, the operation becomes inactive.
2511 *
2512 * \param[in,out] operation Active AEAD operation.
Gilles Peskine5211efb2019-05-06 15:56:05 +02002513 * \param[out] plaintext Buffer where the last part of the plaintext
Gilles Peskineac99e322019-05-14 16:10:53 +02002514 * is to be written. This is the remaining data
Gilles Peskine5211efb2019-05-06 15:56:05 +02002515 * from previous calls to psa_aead_update()
2516 * that could not be processed until the end
2517 * of the input.
2518 * \param plaintext_size Size of the \p plaintext buffer in bytes.
Gilles Peskine49dd8d82019-05-06 15:16:19 +02002519 * This must be at least
2520 * #PSA_AEAD_VERIFY_OUTPUT_SIZE(\c alg) where
2521 * \c alg is the algorithm that is being
2522 * calculated.
Gilles Peskine5211efb2019-05-06 15:56:05 +02002523 * \param[out] plaintext_length On success, the number of bytes of
2524 * returned plaintext.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002525 * \param[in] tag Buffer containing the authentication tag.
2526 * \param tag_length Size of the \p tag buffer in bytes.
2527 *
2528 * \retval #PSA_SUCCESS
2529 * Success.
2530 * \retval #PSA_ERROR_BAD_STATE
2531 * The operation state is not valid (not set up, nonce not set,
2532 * encryption, or already completed).
Gilles Peskine49dd8d82019-05-06 15:16:19 +02002533 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
2534 * The size of the \p plaintext buffer is too small.
2535 * You can determine a sufficient buffer size for \p plaintext by
2536 * calling #PSA_AEAD_VERIFY_OUTPUT_SIZE(\c alg)
2537 * where \c alg is the algorithm that is being calculated.
Gilles Peskinebc59c852019-01-17 15:26:08 +01002538 * \retval #PSA_ERROR_INVALID_ARGUMENT
2539 * The total length of input to psa_aead_update_ad() so far is
2540 * less than the additional data length that was previously
2541 * specified with psa_aead_set_lengths().
2542 * \retval #PSA_ERROR_INVALID_ARGUMENT
2543 * The total length of input to psa_aead_update() so far is
2544 * less than the plaintext length that was previously
2545 * specified with psa_aead_set_lengths().
Gilles Peskine30a9e412019-01-14 18:36:12 +01002546 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2547 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2548 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002549 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine30a9e412019-01-14 18:36:12 +01002550 */
2551psa_status_t psa_aead_verify(psa_aead_operation_t *operation,
Gilles Peskine5211efb2019-05-06 15:56:05 +02002552 uint8_t *plaintext,
2553 size_t plaintext_size,
2554 size_t *plaintext_length,
Gilles Peskine30a9e412019-01-14 18:36:12 +01002555 const uint8_t *tag,
2556 size_t tag_length);
2557
2558/** Abort an AEAD operation.
2559 *
2560 * Aborting an operation frees all associated resources except for the
2561 * \p operation structure itself. Once aborted, the operation object
2562 * can be reused for another operation by calling
2563 * psa_aead_encrypt_setup() or psa_aead_decrypt_setup() again.
2564 *
2565 * You may call this function any time after the operation object has
2566 * been initialized by any of the following methods:
2567 * - A call to psa_aead_encrypt_setup() or psa_aead_decrypt_setup(),
2568 * whether it succeeds or not.
2569 * - Initializing the \c struct to all-bits-zero.
2570 * - Initializing the \c struct to logical zeros, e.g.
2571 * `psa_aead_operation_t operation = {0}`.
2572 *
2573 * In particular, calling psa_aead_abort() after the operation has been
2574 * terminated by a call to psa_aead_abort() or psa_aead_finish()
2575 * is safe and has no effect.
2576 *
2577 * \param[in,out] operation Initialized AEAD operation.
2578 *
2579 * \retval #PSA_SUCCESS
2580 * \retval #PSA_ERROR_BAD_STATE
2581 * \p operation is not an active AEAD operation.
2582 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2583 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002584 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine30a9e412019-01-14 18:36:12 +01002585 */
2586psa_status_t psa_aead_abort(psa_aead_operation_t *operation);
2587
Gilles Peskine3b555712018-03-03 21:27:57 +01002588/**@}*/
2589
Gilles Peskine20035e32018-02-03 22:44:14 +01002590/** \defgroup asymmetric Asymmetric cryptography
2591 * @{
2592 */
2593
2594/**
2595 * \brief Sign a hash or short message with a private key.
2596 *
Gilles Peskine08bac712018-06-26 16:14:46 +02002597 * Note that to perform a hash-and-sign signature algorithm, you must
Gilles Peskineda8191d1c2018-07-08 19:46:38 +02002598 * first calculate the hash by calling psa_hash_setup(), psa_hash_update()
Gilles Peskine08bac712018-06-26 16:14:46 +02002599 * and psa_hash_finish(). Then pass the resulting hash as the \p hash
2600 * parameter to this function. You can use #PSA_ALG_SIGN_GET_HASH(\p alg)
2601 * to determine the hash algorithm to use.
2602 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01002603 * \param handle Handle to the key to use for the operation.
2604 * It must be an asymmetric key pair.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002605 * \param alg A signature algorithm that is compatible with
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002606 * the type of \p handle.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002607 * \param[in] hash The hash or message to sign.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002608 * \param hash_length Size of the \p hash buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002609 * \param[out] signature Buffer where the signature is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002610 * \param signature_size Size of the \p signature buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002611 * \param[out] signature_length On success, the number of bytes
2612 * that make up the returned signature value.
Gilles Peskine308b91d2018-02-08 09:47:44 +01002613 *
Gilles Peskine28538492018-07-11 17:34:00 +02002614 * \retval #PSA_SUCCESS
2615 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002616 * The size of the \p signature buffer is too small. You can
Gilles Peskine308b91d2018-02-08 09:47:44 +01002617 * determine a sufficient buffer size by calling
Gilles Peskine7256e6c2018-07-12 00:34:26 +02002618 * #PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
Gilles Peskine308b91d2018-02-08 09:47:44 +01002619 * where \c key_type and \c key_bits are the type and bit-size
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002620 * respectively of \p handle.
Gilles Peskine28538492018-07-11 17:34:00 +02002621 * \retval #PSA_ERROR_NOT_SUPPORTED
2622 * \retval #PSA_ERROR_INVALID_ARGUMENT
2623 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2624 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2625 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002626 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine28538492018-07-11 17:34:00 +02002627 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
itayzafrir90d8c7a2018-09-12 11:44:52 +03002628 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03002629 * The library has not been previously initialized by psa_crypto_init().
2630 * It is implementation-dependent whether a failure to initialize
2631 * results in this error code.
Gilles Peskine20035e32018-02-03 22:44:14 +01002632 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01002633psa_status_t psa_asymmetric_sign(psa_key_handle_t handle,
Gilles Peskine20035e32018-02-03 22:44:14 +01002634 psa_algorithm_t alg,
2635 const uint8_t *hash,
2636 size_t hash_length,
Gilles Peskine20035e32018-02-03 22:44:14 +01002637 uint8_t *signature,
2638 size_t signature_size,
2639 size_t *signature_length);
2640
2641/**
2642 * \brief Verify the signature a hash or short message using a public key.
2643 *
Gilles Peskine08bac712018-06-26 16:14:46 +02002644 * Note that to perform a hash-and-sign signature algorithm, you must
Gilles Peskineda8191d1c2018-07-08 19:46:38 +02002645 * first calculate the hash by calling psa_hash_setup(), psa_hash_update()
Gilles Peskine08bac712018-06-26 16:14:46 +02002646 * and psa_hash_finish(). Then pass the resulting hash as the \p hash
2647 * parameter to this function. You can use #PSA_ALG_SIGN_GET_HASH(\p alg)
2648 * to determine the hash algorithm to use.
2649 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01002650 * \param handle Handle to the key to use for the operation.
2651 * It must be a public key or an asymmetric key pair.
Gilles Peskine308b91d2018-02-08 09:47:44 +01002652 * \param alg A signature algorithm that is compatible with
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002653 * the type of \p handle.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002654 * \param[in] hash The hash or message whose signature is to be
Gilles Peskine08bac712018-06-26 16:14:46 +02002655 * verified.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002656 * \param hash_length Size of the \p hash buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002657 * \param[in] signature Buffer containing the signature to verify.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002658 * \param signature_length Size of the \p signature buffer in bytes.
Gilles Peskine308b91d2018-02-08 09:47:44 +01002659 *
Gilles Peskine28538492018-07-11 17:34:00 +02002660 * \retval #PSA_SUCCESS
Gilles Peskine308b91d2018-02-08 09:47:44 +01002661 * The signature is valid.
Gilles Peskine28538492018-07-11 17:34:00 +02002662 * \retval #PSA_ERROR_INVALID_SIGNATURE
Gilles Peskine308b91d2018-02-08 09:47:44 +01002663 * The calculation was perfomed successfully, but the passed
2664 * signature is not a valid signature.
Gilles Peskine28538492018-07-11 17:34:00 +02002665 * \retval #PSA_ERROR_NOT_SUPPORTED
2666 * \retval #PSA_ERROR_INVALID_ARGUMENT
2667 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2668 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2669 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002670 * \retval #PSA_ERROR_CORRUPTION_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03002671 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03002672 * The library has not been previously initialized by psa_crypto_init().
2673 * It is implementation-dependent whether a failure to initialize
2674 * results in this error code.
Gilles Peskine20035e32018-02-03 22:44:14 +01002675 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01002676psa_status_t psa_asymmetric_verify(psa_key_handle_t handle,
Gilles Peskine20035e32018-02-03 22:44:14 +01002677 psa_algorithm_t alg,
2678 const uint8_t *hash,
2679 size_t hash_length,
Gilles Peskinee9191ff2018-06-27 14:58:41 +02002680 const uint8_t *signature,
Gilles Peskine526fab02018-06-27 18:19:40 +02002681 size_t signature_length);
Gilles Peskine20035e32018-02-03 22:44:14 +01002682
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002683/**
2684 * \brief Encrypt a short message with a public key.
2685 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01002686 * \param handle Handle to the key to use for the operation.
2687 * It must be a public key or an asymmetric
2688 * key pair.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002689 * \param alg An asymmetric encryption algorithm that is
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002690 * compatible with the type of \p handle.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002691 * \param[in] input The message to encrypt.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002692 * \param input_length Size of the \p input buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002693 * \param[in] salt A salt or label, if supported by the
2694 * encryption algorithm.
2695 * If the algorithm does not support a
2696 * salt, pass \c NULL.
2697 * If the algorithm supports an optional
2698 * salt and you do not want to pass a salt,
2699 * pass \c NULL.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002700 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02002701 * - For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is
2702 * supported.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002703 * \param salt_length Size of the \p salt buffer in bytes.
2704 * If \p salt is \c NULL, pass 0.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002705 * \param[out] output Buffer where the encrypted message is to
2706 * be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002707 * \param output_size Size of the \p output buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002708 * \param[out] output_length On success, the number of bytes
2709 * that make up the returned output.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002710 *
Gilles Peskine28538492018-07-11 17:34:00 +02002711 * \retval #PSA_SUCCESS
2712 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002713 * The size of the \p output buffer is too small. You can
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002714 * determine a sufficient buffer size by calling
Gilles Peskine7256e6c2018-07-12 00:34:26 +02002715 * #PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002716 * where \c key_type and \c key_bits are the type and bit-size
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002717 * respectively of \p handle.
Gilles Peskine28538492018-07-11 17:34:00 +02002718 * \retval #PSA_ERROR_NOT_SUPPORTED
2719 * \retval #PSA_ERROR_INVALID_ARGUMENT
2720 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2721 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2722 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002723 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine28538492018-07-11 17:34:00 +02002724 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
itayzafrir90d8c7a2018-09-12 11:44:52 +03002725 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03002726 * The library has not been previously initialized by psa_crypto_init().
2727 * It is implementation-dependent whether a failure to initialize
2728 * results in this error code.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002729 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01002730psa_status_t psa_asymmetric_encrypt(psa_key_handle_t handle,
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002731 psa_algorithm_t alg,
2732 const uint8_t *input,
2733 size_t input_length,
2734 const uint8_t *salt,
2735 size_t salt_length,
2736 uint8_t *output,
2737 size_t output_size,
2738 size_t *output_length);
2739
2740/**
2741 * \brief Decrypt a short message with a private key.
2742 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01002743 * \param handle Handle to the key to use for the operation.
2744 * It must be an asymmetric key pair.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002745 * \param alg An asymmetric encryption algorithm that is
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002746 * compatible with the type of \p handle.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002747 * \param[in] input The message to decrypt.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002748 * \param input_length Size of the \p input buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002749 * \param[in] salt A salt or label, if supported by the
2750 * encryption algorithm.
2751 * If the algorithm does not support a
2752 * salt, pass \c NULL.
2753 * If the algorithm supports an optional
2754 * salt and you do not want to pass a salt,
2755 * pass \c NULL.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002756 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02002757 * - For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is
2758 * supported.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002759 * \param salt_length Size of the \p salt buffer in bytes.
2760 * If \p salt is \c NULL, pass 0.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002761 * \param[out] output Buffer where the decrypted message is to
2762 * be written.
2763 * \param output_size Size of the \c output buffer in bytes.
2764 * \param[out] output_length On success, the number of bytes
2765 * that make up the returned output.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002766 *
Gilles Peskine28538492018-07-11 17:34:00 +02002767 * \retval #PSA_SUCCESS
2768 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002769 * The size of the \p output buffer is too small. You can
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002770 * determine a sufficient buffer size by calling
Gilles Peskinedda3bd32018-07-12 19:40:46 +02002771 * #PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002772 * where \c key_type and \c key_bits are the type and bit-size
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002773 * respectively of \p handle.
Gilles Peskine28538492018-07-11 17:34:00 +02002774 * \retval #PSA_ERROR_NOT_SUPPORTED
2775 * \retval #PSA_ERROR_INVALID_ARGUMENT
2776 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2777 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2778 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002779 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine28538492018-07-11 17:34:00 +02002780 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
2781 * \retval #PSA_ERROR_INVALID_PADDING
itayzafrir90d8c7a2018-09-12 11:44:52 +03002782 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03002783 * The library has not been previously initialized by psa_crypto_init().
2784 * It is implementation-dependent whether a failure to initialize
2785 * results in this error code.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002786 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01002787psa_status_t psa_asymmetric_decrypt(psa_key_handle_t handle,
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002788 psa_algorithm_t alg,
2789 const uint8_t *input,
2790 size_t input_length,
2791 const uint8_t *salt,
2792 size_t salt_length,
2793 uint8_t *output,
2794 size_t output_size,
2795 size_t *output_length);
2796
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +01002797/**@}*/
2798
Gilles Peskine35675b62019-05-16 17:26:11 +02002799/** \defgroup key_derivation Key derivation and pseudorandom generation
Gilles Peskineeab56e42018-07-12 17:12:33 +02002800 * @{
2801 */
2802
Gilles Peskine35675b62019-05-16 17:26:11 +02002803/** The type of the state data structure for key derivation operations.
Gilles Peskineeab56e42018-07-12 17:12:33 +02002804 *
Gilles Peskine35675b62019-05-16 17:26:11 +02002805 * Before calling any function on a key derivation operation object, the
2806 * application must initialize it by any of the following means:
Gilles Peskineeab56e42018-07-12 17:12:33 +02002807 * - Set the structure to all-bits-zero, for example:
2808 * \code
Gilles Peskine35675b62019-05-16 17:26:11 +02002809 * psa_key_derivation_operation_t operation;
2810 * memset(&operation, 0, sizeof(operation));
Gilles Peskineeab56e42018-07-12 17:12:33 +02002811 * \endcode
2812 * - Initialize the structure to logical zero values, for example:
2813 * \code
Gilles Peskine35675b62019-05-16 17:26:11 +02002814 * psa_key_derivation_operation_t operation = {0};
Gilles Peskineeab56e42018-07-12 17:12:33 +02002815 * \endcode
Gilles Peskinea99d3fb2019-05-16 15:28:51 +02002816 * - Initialize the structure to the initializer #PSA_KEY_DERIVATION_OPERATION_INIT,
Gilles Peskineeab56e42018-07-12 17:12:33 +02002817 * for example:
2818 * \code
Gilles Peskine35675b62019-05-16 17:26:11 +02002819 * psa_key_derivation_operation_t operation = PSA_KEY_DERIVATION_OPERATION_INIT;
Gilles Peskineeab56e42018-07-12 17:12:33 +02002820 * \endcode
Gilles Peskinea99d3fb2019-05-16 15:28:51 +02002821 * - Assign the result of the function psa_key_derivation_operation_init()
Gilles Peskineeab56e42018-07-12 17:12:33 +02002822 * to the structure, for example:
2823 * \code
Gilles Peskine35675b62019-05-16 17:26:11 +02002824 * psa_key_derivation_operation_t operation;
2825 * operation = psa_key_derivation_operation_init();
Gilles Peskineeab56e42018-07-12 17:12:33 +02002826 * \endcode
2827 *
2828 * This is an implementation-defined \c struct. Applications should not
2829 * make any assumptions about the content of this structure except
2830 * as directed by the documentation of a specific implementation.
2831 */
Gilles Peskinecbe66502019-05-16 16:59:18 +02002832typedef struct psa_key_derivation_s psa_key_derivation_operation_t;
Gilles Peskineeab56e42018-07-12 17:12:33 +02002833
Gilles Peskinea99d3fb2019-05-16 15:28:51 +02002834/** \def PSA_KEY_DERIVATION_OPERATION_INIT
Gilles Peskineeab56e42018-07-12 17:12:33 +02002835 *
Gilles Peskine35675b62019-05-16 17:26:11 +02002836 * This macro returns a suitable initializer for a key derivation operation
2837 * object of type #psa_key_derivation_operation_t.
Gilles Peskineeab56e42018-07-12 17:12:33 +02002838 */
2839#ifdef __DOXYGEN_ONLY__
2840/* This is an example definition for documentation purposes.
2841 * Implementations should define a suitable value in `crypto_struct.h`.
2842 */
Gilles Peskinea99d3fb2019-05-16 15:28:51 +02002843#define PSA_KEY_DERIVATION_OPERATION_INIT {0}
Gilles Peskineeab56e42018-07-12 17:12:33 +02002844#endif
2845
Gilles Peskine35675b62019-05-16 17:26:11 +02002846/** Return an initial value for a key derivation operation object.
Gilles Peskineeab56e42018-07-12 17:12:33 +02002847 */
Gilles Peskinea99d3fb2019-05-16 15:28:51 +02002848static psa_key_derivation_operation_t psa_key_derivation_operation_init(void);
Gilles Peskineeab56e42018-07-12 17:12:33 +02002849
Gilles Peskine1cb9a082019-05-16 17:56:47 +02002850/** Set up a key derivation operation.
2851 *
2852 * A key derivation algorithm takes some inputs and uses them to generate
2853 * a byte stream in a deterministic way.
2854 * This byte stream can be used to produce keys and other
2855 * cryptographic material.
2856 *
2857 * To derive a key:
2858 * - Start with an initialized object of type #psa_key_derivation_operation_t.
2859 * - Call psa_key_derivation_setup() to select the algorithm.
2860 * - Provide the inputs for the key derivation by calling
2861 * psa_key_derivation_input_bytes() or psa_key_derivation_input_key()
2862 * as appropriate. Which inputs are needed, in what order, and whether
2863 * they may be keys and if so of what type depends on the algorithm.
2864 * - Optionally set the operation's maximum capacity with
2865 * psa_key_derivation_set_capacity(). You may do this before, in the middle
2866 * of or after providing inputs. For some algorithms, this step is mandatory
2867 * because the output depends on the maximum capacity.
2868 * - To derive a key, call psa_key_derivation_output_key().
2869 * To derive a byte string for a different purpose, call
2870 * - psa_key_derivation_output_bytes().
2871 * Successive calls to these functions use successive output bytes
2872 * calculated by the key derivation algorithm.
2873 * - Clean up the key derivation operation object with
2874 * psa_key_derivation_abort().
2875 *
2876 * \param[in,out] operation The key derivation operation object
2877 * to set up. It must
2878 * have been initialized but not set up yet.
2879 * \param alg The key derivation algorithm to compute
2880 * (\c PSA_ALG_XXX value such that
2881 * #PSA_ALG_IS_KEY_DERIVATION(\p alg) is true).
2882 *
2883 * \retval #PSA_SUCCESS
2884 * Success.
2885 * \retval #PSA_ERROR_INVALID_ARGUMENT
2886 * \c alg is not a key derivation algorithm.
2887 * \retval #PSA_ERROR_NOT_SUPPORTED
2888 * \c alg is not supported or is not a key derivation algorithm.
2889 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2890 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2891 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002892 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine1cb9a082019-05-16 17:56:47 +02002893 * \retval #PSA_ERROR_BAD_STATE
2894 */
2895psa_status_t psa_key_derivation_setup(
2896 psa_key_derivation_operation_t *operation,
2897 psa_algorithm_t alg);
2898
Gilles Peskine35675b62019-05-16 17:26:11 +02002899/** Retrieve the current capacity of a key derivation operation.
Gilles Peskineeab56e42018-07-12 17:12:33 +02002900 *
Gilles Peskine35675b62019-05-16 17:26:11 +02002901 * The capacity of a key derivation is the maximum number of bytes that it can
2902 * return. When you get *N* bytes of output from a key derivation operation,
2903 * this reduces its capacity by *N*.
Gilles Peskineeab56e42018-07-12 17:12:33 +02002904 *
Gilles Peskine35675b62019-05-16 17:26:11 +02002905 * \param[in] operation The operation to query.
2906 * \param[out] capacity On success, the capacity of the operation.
Gilles Peskineeab56e42018-07-12 17:12:33 +02002907 *
Gilles Peskine644cd5f2018-12-11 16:47:35 +01002908 * \retval #PSA_SUCCESS
2909 * \retval #PSA_ERROR_BAD_STATE
2910 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
Gilles Peskineeab56e42018-07-12 17:12:33 +02002911 */
Gilles Peskinecf7292e2019-05-16 17:53:40 +02002912psa_status_t psa_key_derivation_get_capacity(
2913 const psa_key_derivation_operation_t *operation,
2914 size_t *capacity);
Gilles Peskineeab56e42018-07-12 17:12:33 +02002915
Gilles Peskine35675b62019-05-16 17:26:11 +02002916/** Set the maximum capacity of a key derivation operation.
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01002917 *
Gilles Peskine35675b62019-05-16 17:26:11 +02002918 * The capacity of a key derivation operation is the maximum number of bytes
2919 * that the key derivation operation can return from this point onwards.
2920 *
2921 * \param[in,out] operation The key derivation operation object to modify.
2922 * \param capacity The new capacity of the operation.
2923 * It must be less or equal to the operation's
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01002924 * current capacity.
2925 *
2926 * \retval #PSA_SUCCESS
2927 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine35675b62019-05-16 17:26:11 +02002928 * \p capacity is larger than the operation's current capacity.
2929 * In this case, the operation object remains valid and its capacity
2930 * remains unchanged.
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01002931 * \retval #PSA_ERROR_BAD_STATE
2932 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2933 */
Gilles Peskinecf7292e2019-05-16 17:53:40 +02002934psa_status_t psa_key_derivation_set_capacity(
2935 psa_key_derivation_operation_t *operation,
2936 size_t capacity);
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01002937
Gilles Peskine1cb9a082019-05-16 17:56:47 +02002938/** Use the maximum possible capacity for a key derivation operation.
2939 *
2940 * Use this value as the capacity argument when setting up a key derivation
2941 * to indicate that the operation should have the maximum possible capacity.
2942 * The value of the maximum possible capacity depends on the key derivation
2943 * algorithm.
2944 */
2945#define PSA_KEY_DERIVATION_UNLIMITED_CAPACITY ((size_t)(-1))
2946
2947/** Provide an input for key derivation or key agreement.
2948 *
2949 * Which inputs are required and in what order depends on the algorithm.
2950 * Refer to the documentation of each key derivation or key agreement
2951 * algorithm for information.
2952 *
2953 * This function passes direct inputs. Some inputs must be passed as keys
2954 * using psa_key_derivation_input_key() instead of this function. Refer to
2955 * the documentation of individual step types for information.
2956 *
2957 * \param[in,out] operation The key derivation operation object to use.
2958 * It must have been set up with
2959 * psa_key_derivation_setup() and must not
2960 * have produced any output yet.
2961 * \param step Which step the input data is for.
2962 * \param[in] data Input data to use.
2963 * \param data_length Size of the \p data buffer in bytes.
2964 *
2965 * \retval #PSA_SUCCESS
2966 * Success.
2967 * \retval #PSA_ERROR_INVALID_ARGUMENT
2968 * \c step is not compatible with the operation's algorithm.
2969 * \retval #PSA_ERROR_INVALID_ARGUMENT
2970 * \c step does not allow direct inputs.
2971 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2972 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2973 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02002974 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine1cb9a082019-05-16 17:56:47 +02002975 * \retval #PSA_ERROR_BAD_STATE
2976 * The value of \p step is not valid given the state of \p operation.
2977 * \retval #PSA_ERROR_BAD_STATE
2978 * The library has not been previously initialized by psa_crypto_init().
2979 * It is implementation-dependent whether a failure to initialize
2980 * results in this error code.
2981 */
2982psa_status_t psa_key_derivation_input_bytes(
2983 psa_key_derivation_operation_t *operation,
2984 psa_key_derivation_step_t step,
2985 const uint8_t *data,
2986 size_t data_length);
2987
2988/** Provide an input for key derivation in the form of a key.
2989 *
2990 * Which inputs are required and in what order depends on the algorithm.
2991 * Refer to the documentation of each key derivation or key agreement
2992 * algorithm for information.
2993 *
2994 * This function passes key inputs. Some inputs must be passed as keys
2995 * of the appropriate type using this function, while others must be
2996 * passed as direct inputs using psa_key_derivation_input_bytes(). Refer to
2997 * the documentation of individual step types for information.
2998 *
2999 * \param[in,out] operation The key derivation operation object to use.
3000 * It must have been set up with
3001 * psa_key_derivation_setup() and must not
3002 * have produced any output yet.
3003 * \param step Which step the input data is for.
3004 * \param handle Handle to the key. It must have an
3005 * appropriate type for \p step and must
3006 * allow the usage #PSA_KEY_USAGE_DERIVE.
3007 *
3008 * \retval #PSA_SUCCESS
3009 * Success.
3010 * \retval #PSA_ERROR_INVALID_HANDLE
3011 * \retval #PSA_ERROR_DOES_NOT_EXIST
3012 * \retval #PSA_ERROR_NOT_PERMITTED
3013 * \retval #PSA_ERROR_INVALID_ARGUMENT
3014 * \c step is not compatible with the operation's algorithm.
3015 * \retval #PSA_ERROR_INVALID_ARGUMENT
3016 * \c step does not allow key inputs.
3017 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3018 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3019 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003020 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine1cb9a082019-05-16 17:56:47 +02003021 * \retval #PSA_ERROR_BAD_STATE
3022 * The value of \p step is not valid given the state of \p operation.
3023 * \retval #PSA_ERROR_BAD_STATE
3024 * The library has not been previously initialized by psa_crypto_init().
3025 * It is implementation-dependent whether a failure to initialize
3026 * results in this error code.
3027 */
3028psa_status_t psa_key_derivation_input_key(
3029 psa_key_derivation_operation_t *operation,
3030 psa_key_derivation_step_t step,
3031 psa_key_handle_t handle);
3032
3033/** Perform a key agreement and use the shared secret as input to a key
3034 * derivation.
3035 *
3036 * A key agreement algorithm takes two inputs: a private key \p private_key
3037 * a public key \p peer_key.
3038 * The result of this function is passed as input to a key derivation.
3039 * The output of this key derivation can be extracted by reading from the
3040 * resulting operation to produce keys and other cryptographic material.
3041 *
3042 * \param[in,out] operation The key derivation operation object to use.
3043 * It must have been set up with
3044 * psa_key_derivation_setup() with a
3045 * key agreement and derivation algorithm
3046 * \c alg (\c PSA_ALG_XXX value such that
3047 * #PSA_ALG_IS_KEY_AGREEMENT(\c alg) is true
3048 * and #PSA_ALG_IS_RAW_KEY_AGREEMENT(\c alg)
3049 * is false).
3050 * The operation must be ready for an
3051 * input of the type given by \p step.
3052 * \param step Which step the input data is for.
3053 * \param private_key Handle to the private key to use.
3054 * \param[in] peer_key Public key of the peer. The peer key must be in the
3055 * same format that psa_import_key() accepts for the
3056 * public key type corresponding to the type of
3057 * private_key. That is, this function performs the
3058 * equivalent of
3059 * #psa_import_key(...,
3060 * `peer_key`, `peer_key_length`) where
3061 * with key attributes indicating the public key
3062 * type corresponding to the type of `private_key`.
3063 * For example, for EC keys, this means that peer_key
3064 * is interpreted as a point on the curve that the
3065 * private key is on. The standard formats for public
3066 * keys are documented in the documentation of
3067 * psa_export_public_key().
3068 * \param peer_key_length Size of \p peer_key in bytes.
3069 *
3070 * \retval #PSA_SUCCESS
3071 * Success.
3072 * \retval #PSA_ERROR_INVALID_HANDLE
3073 * \retval #PSA_ERROR_DOES_NOT_EXIST
3074 * \retval #PSA_ERROR_NOT_PERMITTED
3075 * \retval #PSA_ERROR_INVALID_ARGUMENT
3076 * \c private_key is not compatible with \c alg,
3077 * or \p peer_key is not valid for \c alg or not compatible with
3078 * \c private_key.
3079 * \retval #PSA_ERROR_NOT_SUPPORTED
3080 * \c alg is not supported or is not a key derivation algorithm.
3081 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3082 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3083 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003084 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine1cb9a082019-05-16 17:56:47 +02003085 */
3086psa_status_t psa_key_derivation_key_agreement(
3087 psa_key_derivation_operation_t *operation,
3088 psa_key_derivation_step_t step,
3089 psa_key_handle_t private_key,
3090 const uint8_t *peer_key,
3091 size_t peer_key_length);
3092
Gilles Peskine35675b62019-05-16 17:26:11 +02003093/** Read some data from a key derivation operation.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003094 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003095 * This function calculates output bytes from a key derivation algorithm and
3096 * return those bytes.
3097 * If you view the key derivation's output as a stream of bytes, this
3098 * function destructively reads the requested number of bytes from the
3099 * stream.
3100 * The operation's capacity decreases by the number of bytes read.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003101 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003102 * \param[in,out] operation The key derivation operation object to read from.
3103 * \param[out] output Buffer where the output will be written.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003104 * \param output_length Number of bytes to output.
3105 *
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003106 * \retval #PSA_SUCCESS
David Saadab4ecc272019-02-14 13:48:10 +02003107 * \retval #PSA_ERROR_INSUFFICIENT_DATA
Gilles Peskine35675b62019-05-16 17:26:11 +02003108 * The operation's capacity was less than
3109 * \p output_length bytes. Note that in this case,
3110 * no output is written to the output buffer.
3111 * The operation's capacity is set to 0, thus
Gilles Peskineeab56e42018-07-12 17:12:33 +02003112 * subsequent calls to this function will not
3113 * succeed, even with a smaller output buffer.
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003114 * \retval #PSA_ERROR_BAD_STATE
3115 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3116 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3117 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003118 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskineeab56e42018-07-12 17:12:33 +02003119 */
Gilles Peskinecf7292e2019-05-16 17:53:40 +02003120psa_status_t psa_key_derivation_output_bytes(
3121 psa_key_derivation_operation_t *operation,
3122 uint8_t *output,
3123 size_t output_length);
Gilles Peskineeab56e42018-07-12 17:12:33 +02003124
Gilles Peskine35675b62019-05-16 17:26:11 +02003125/** Derive a key from an ongoing key derivation operation.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003126 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003127 * This function calculates output bytes from a key derivation algorithm
3128 * and uses those bytes to generate a key deterministically.
3129 * If you view the key derivation's output as a stream of bytes, this
3130 * function destructively reads as many bytes as required from the
3131 * stream.
3132 * The operation's capacity decreases by the number of bytes read.
3133 *
3134 * How much output is produced and consumed from the operation, and how
3135 * the key is derived, depends on the key type:
Gilles Peskineeab56e42018-07-12 17:12:33 +02003136 *
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003137 * - For key types for which the key is an arbitrary sequence of bytes
Gilles Peskinecf7292e2019-05-16 17:53:40 +02003138 * of a given size, this function is functionally equivalent to
3139 * calling #psa_key_derivation_output_bytes
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003140 * and passing the resulting output to #psa_import_key.
3141 * However, this function has a security benefit:
3142 * if the implementation provides an isolation boundary then
3143 * the key material is not exposed outside the isolation boundary.
3144 * As a consequence, for these key types, this function always consumes
Gilles Peskine35675b62019-05-16 17:26:11 +02003145 * exactly (\p bits / 8) bytes from the operation.
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003146 * The following key types defined in this specification follow this scheme:
3147 *
3148 * - #PSA_KEY_TYPE_AES;
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003149 * - #PSA_KEY_TYPE_ARC4;
3150 * - #PSA_KEY_TYPE_CAMELLIA;
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003151 * - #PSA_KEY_TYPE_DERIVE;
3152 * - #PSA_KEY_TYPE_HMAC.
3153 *
3154 * - For ECC keys on a Montgomery elliptic curve
Gilles Peskinec93b80c2019-05-16 19:39:54 +02003155 * (#PSA_KEY_TYPE_ECC_KEY_PAIR(\c curve) where \c curve designates a
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003156 * Montgomery curve), this function always draws a byte string whose
3157 * length is determined by the curve, and sets the mandatory bits
3158 * accordingly. That is:
3159 *
3160 * - #PSA_ECC_CURVE_CURVE25519: draw a 32-byte string
3161 * and process it as specified in RFC 7748 &sect;5.
3162 * - #PSA_ECC_CURVE_CURVE448: draw a 56-byte string
3163 * and process it as specified in RFC 7748 &sect;5.
3164 *
3165 * - For key types for which the key is represented by a single sequence of
3166 * \p bits bits with constraints as to which bit sequences are acceptable,
3167 * this function draws a byte string of length (\p bits / 8) bytes rounded
3168 * up to the nearest whole number of bytes. If the resulting byte string
3169 * is acceptable, it becomes the key, otherwise the drawn bytes are discarded.
3170 * This process is repeated until an acceptable byte string is drawn.
Gilles Peskine35675b62019-05-16 17:26:11 +02003171 * The byte string drawn from the operation is interpreted as specified
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003172 * for the output produced by psa_export_key().
3173 * The following key types defined in this specification follow this scheme:
3174 *
Gilles Peskine2de2c0d2019-03-11 17:59:16 +01003175 * - #PSA_KEY_TYPE_DES.
3176 * Force-set the parity bits, but discard forbidden weak keys.
3177 * For 2-key and 3-key triple-DES, the three keys are generated
3178 * successively (for example, for 3-key triple-DES,
3179 * if the first 8 bytes specify a weak key and the next 8 bytes do not,
3180 * discard the first 8 bytes, use the next 8 bytes as the first key,
Gilles Peskine35675b62019-05-16 17:26:11 +02003181 * and continue reading output from the operation to derive the other
Gilles Peskine2de2c0d2019-03-11 17:59:16 +01003182 * two keys).
Gilles Peskinec93b80c2019-05-16 19:39:54 +02003183 * - Finite-field Diffie-Hellman keys (#PSA_KEY_TYPE_DH_KEY_PAIR(\c group)
Gilles Peskinea1302192019-05-16 13:58:24 +02003184 * where \c group designates any Diffie-Hellman group) and
Gilles Peskine2de2c0d2019-03-11 17:59:16 +01003185 * ECC keys on a Weierstrass elliptic curve
Gilles Peskinec93b80c2019-05-16 19:39:54 +02003186 * (#PSA_KEY_TYPE_ECC_KEY_PAIR(\c curve) where \c curve designates a
Gilles Peskine2de2c0d2019-03-11 17:59:16 +01003187 * Weierstrass curve).
3188 * For these key types, interpret the byte string as integer
3189 * in big-endian order. Discard it if it is not in the range
3190 * [0, *N* - 2] where *N* is the boundary of the private key domain
3191 * (the prime *p* for Diffie-Hellman, the subprime *q* for DSA,
Gilles Peskine55799712019-03-12 11:50:26 +01003192 * or the order of the curve's base point for ECC).
Gilles Peskine2de2c0d2019-03-11 17:59:16 +01003193 * Add 1 to the resulting integer and use this as the private key *x*.
Gilles Peskine55799712019-03-12 11:50:26 +01003194 * This method allows compliance to NIST standards, specifically
3195 * the methods titled "key-pair generation by testing candidates"
Gilles Peskine2de2c0d2019-03-11 17:59:16 +01003196 * in NIST SP 800-56A &sect;5.6.1.1.4 for Diffie-Hellman,
3197 * in FIPS 186-4 &sect;B.1.2 for DSA, and
3198 * in NIST SP 800-56A &sect;5.6.1.2.2 or
3199 * FIPS 186-4 &sect;B.4.2 for elliptic curve keys.
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003200 *
Gilles Peskinec93b80c2019-05-16 19:39:54 +02003201 * - For other key types, including #PSA_KEY_TYPE_RSA_KEY_PAIR,
Gilles Peskine35675b62019-05-16 17:26:11 +02003202 * the way in which the operation output is consumed is
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003203 * implementation-defined.
3204 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003205 * In all cases, the data that is read is discarded from the operation.
3206 * The operation's capacity is decreased by the number of bytes read.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003207 *
Gilles Peskine20628592019-04-19 19:29:50 +02003208 * \param[in] attributes The attributes for the new key.
Gilles Peskine35675b62019-05-16 17:26:11 +02003209 * \param[in,out] operation The key derivation operation object to read from.
Gilles Peskine20628592019-04-19 19:29:50 +02003210 * \param[out] handle On success, a handle to the newly created key.
3211 * \c 0 on failure.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003212 *
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003213 * \retval #PSA_SUCCESS
Gilles Peskineeab56e42018-07-12 17:12:33 +02003214 * Success.
Gilles Peskine23fd2bd2018-12-11 15:51:32 +01003215 * If the key is persistent, the key material and the key's metadata
3216 * have been saved to persistent storage.
Gilles Peskine20628592019-04-19 19:29:50 +02003217 * \retval #PSA_ERROR_ALREADY_EXISTS
3218 * This is an attempt to create a persistent key, and there is
3219 * already a persistent key with the given identifier.
David Saadab4ecc272019-02-14 13:48:10 +02003220 * \retval #PSA_ERROR_INSUFFICIENT_DATA
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003221 * There was not enough data to create the desired key.
3222 * Note that in this case, no output is written to the output buffer.
Gilles Peskine35675b62019-05-16 17:26:11 +02003223 * The operation's capacity is set to 0, thus subsequent calls to
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003224 * this function will not succeed, even with a smaller output buffer.
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003225 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskineeab56e42018-07-12 17:12:33 +02003226 * The key type or key size is not supported, either by the
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +01003227 * implementation in general or in this particular location.
k-stachowiakb9b4f092019-08-15 19:01:59 +02003228 * \retval #PSA_ERROR_INVALID_ARGUMENT
3229 * The provided key attributes are not valid for the operation.
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003230 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003231 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3232 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
3233 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3234 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003235 * \retval #PSA_ERROR_CORRUPTION_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03003236 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03003237 * The library has not been previously initialized by psa_crypto_init().
3238 * It is implementation-dependent whether a failure to initialize
3239 * results in this error code.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003240 */
Gilles Peskinecf7292e2019-05-16 17:53:40 +02003241psa_status_t psa_key_derivation_output_key(
3242 const psa_key_attributes_t *attributes,
3243 psa_key_derivation_operation_t *operation,
3244 psa_key_handle_t *handle);
Gilles Peskineeab56e42018-07-12 17:12:33 +02003245
Gilles Peskine35675b62019-05-16 17:26:11 +02003246/** Abort a key derivation operation.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003247 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003248 * Once a key derivation operation has been aborted, its capacity is zero.
3249 * Aborting an operation frees all associated resources except for the
3250 * \c operation structure itself.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003251 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003252 * This function may be called at any time as long as the operation
Gilles Peskinea99d3fb2019-05-16 15:28:51 +02003253 * object has been initialized to #PSA_KEY_DERIVATION_OPERATION_INIT, to
Gilles Peskinecf7292e2019-05-16 17:53:40 +02003254 * psa_key_derivation_operation_init() or a zero value. In particular,
3255 * it is valid to call psa_key_derivation_abort() twice, or to call
3256 * psa_key_derivation_abort() on an operation that has not been set up.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003257 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003258 * Once aborted, the key derivation operation object may be called.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003259 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003260 * \param[in,out] operation The operation to abort.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003261 *
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003262 * \retval #PSA_SUCCESS
3263 * \retval #PSA_ERROR_BAD_STATE
3264 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3265 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003266 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskineeab56e42018-07-12 17:12:33 +02003267 */
Gilles Peskinecf7292e2019-05-16 17:53:40 +02003268psa_status_t psa_key_derivation_abort(
3269 psa_key_derivation_operation_t *operation);
Gilles Peskineeab56e42018-07-12 17:12:33 +02003270
Gilles Peskine58fe9e82019-05-16 18:01:45 +02003271/** Perform a key agreement and return the raw shared secret.
Gilles Peskine769c7a62019-01-18 16:42:29 +01003272 *
3273 * \warning The raw result of a key agreement algorithm such as finite-field
3274 * Diffie-Hellman or elliptic curve Diffie-Hellman has biases and should
3275 * not be used directly as key material. It should instead be passed as
3276 * input to a key derivation algorithm. To chain a key agreement with
Gilles Peskinecf7292e2019-05-16 17:53:40 +02003277 * a key derivation, use psa_key_derivation_key_agreement() and other
3278 * functions from the key derivation interface.
Gilles Peskine769c7a62019-01-18 16:42:29 +01003279 *
Gilles Peskine47e79fb2019-02-08 11:24:59 +01003280 * \param alg The key agreement algorithm to compute
3281 * (\c PSA_ALG_XXX value such that
3282 * #PSA_ALG_IS_RAW_KEY_AGREEMENT(\p alg)
3283 * is true).
Gilles Peskine769c7a62019-01-18 16:42:29 +01003284 * \param private_key Handle to the private key to use.
3285 * \param[in] peer_key Public key of the peer. It must be
3286 * in the same format that psa_import_key()
3287 * accepts. The standard formats for public
3288 * keys are documented in the documentation
3289 * of psa_export_public_key().
3290 * \param peer_key_length Size of \p peer_key in bytes.
3291 * \param[out] output Buffer where the decrypted message is to
3292 * be written.
3293 * \param output_size Size of the \c output buffer in bytes.
3294 * \param[out] output_length On success, the number of bytes
3295 * that make up the returned output.
3296 *
3297 * \retval #PSA_SUCCESS
3298 * Success.
3299 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine769c7a62019-01-18 16:42:29 +01003300 * \retval #PSA_ERROR_NOT_PERMITTED
3301 * \retval #PSA_ERROR_INVALID_ARGUMENT
3302 * \p alg is not a key agreement algorithm
3303 * \retval #PSA_ERROR_INVALID_ARGUMENT
3304 * \p private_key is not compatible with \p alg,
3305 * or \p peer_key is not valid for \p alg or not compatible with
3306 * \p private_key.
3307 * \retval #PSA_ERROR_NOT_SUPPORTED
3308 * \p alg is not a supported key agreement algorithm.
3309 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3310 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3311 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003312 * \retval #PSA_ERROR_CORRUPTION_DETECTED
Gilles Peskine769c7a62019-01-18 16:42:29 +01003313 */
Gilles Peskinebe697d82019-05-16 18:00:41 +02003314psa_status_t psa_raw_key_agreement(psa_algorithm_t alg,
3315 psa_key_handle_t private_key,
3316 const uint8_t *peer_key,
3317 size_t peer_key_length,
3318 uint8_t *output,
3319 size_t output_size,
3320 size_t *output_length);
Gilles Peskine01d718c2018-09-18 12:01:02 +02003321
Gilles Peskineea0fb492018-07-12 17:17:20 +02003322/**@}*/
3323
Gilles Peskineedd76872018-07-20 17:42:05 +02003324/** \defgroup random Random generation
Gilles Peskine9e7dc712018-03-28 14:18:50 +02003325 * @{
3326 */
3327
3328/**
3329 * \brief Generate random bytes.
3330 *
3331 * \warning This function **can** fail! Callers MUST check the return status
3332 * and MUST NOT use the content of the output buffer if the return
3333 * status is not #PSA_SUCCESS.
3334 *
Gilles Peskine35ef36b2019-05-16 19:42:05 +02003335 * \note To generate a key, use psa_generate_key() instead.
Gilles Peskine9e7dc712018-03-28 14:18:50 +02003336 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02003337 * \param[out] output Output buffer for the generated data.
Gilles Peskine9e7dc712018-03-28 14:18:50 +02003338 * \param output_size Number of bytes to generate and output.
3339 *
Gilles Peskine28538492018-07-11 17:34:00 +02003340 * \retval #PSA_SUCCESS
3341 * \retval #PSA_ERROR_NOT_SUPPORTED
3342 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
3343 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3344 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003345 * \retval #PSA_ERROR_CORRUPTION_DETECTED
itayzafrir0adf0fc2018-09-06 16:24:41 +03003346 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03003347 * The library has not been previously initialized by psa_crypto_init().
3348 * It is implementation-dependent whether a failure to initialize
3349 * results in this error code.
Gilles Peskine9e7dc712018-03-28 14:18:50 +02003350 */
3351psa_status_t psa_generate_random(uint8_t *output,
3352 size_t output_size);
3353
3354/**
3355 * \brief Generate a key or key pair.
3356 *
Gilles Peskinee56e8782019-04-26 17:34:02 +02003357 * The key is generated randomly.
3358 * Its location, policy, type and size are taken from \p attributes.
3359 *
Gilles Peskine20a77ae2019-05-16 14:05:56 +02003360 * The following type-specific considerations apply:
Gilles Peskinec93b80c2019-05-16 19:39:54 +02003361 * - For RSA keys (#PSA_KEY_TYPE_RSA_KEY_PAIR),
Gilles Peskine20a77ae2019-05-16 14:05:56 +02003362 * the public exponent is 65537.
3363 * The modulus is a product of two probabilistic primes
3364 * between 2^{n-1} and 2^n where n is the bit size specified in the
3365 * attributes.
3366 *
Gilles Peskine20628592019-04-19 19:29:50 +02003367 * \param[in] attributes The attributes for the new key.
Gilles Peskine20628592019-04-19 19:29:50 +02003368 * \param[out] handle On success, a handle to the newly created key.
3369 * \c 0 on failure.
Gilles Peskine9e7dc712018-03-28 14:18:50 +02003370 *
Gilles Peskine28538492018-07-11 17:34:00 +02003371 * \retval #PSA_SUCCESS
Gilles Peskine23fd2bd2018-12-11 15:51:32 +01003372 * Success.
3373 * If the key is persistent, the key material and the key's metadata
3374 * have been saved to persistent storage.
David Saadab4ecc272019-02-14 13:48:10 +02003375 * \retval #PSA_ERROR_ALREADY_EXISTS
Gilles Peskine20628592019-04-19 19:29:50 +02003376 * This is an attempt to create a persistent key, and there is
3377 * already a persistent key with the given identifier.
Gilles Peskine28538492018-07-11 17:34:00 +02003378 * \retval #PSA_ERROR_NOT_SUPPORTED
3379 * \retval #PSA_ERROR_INVALID_ARGUMENT
3380 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3381 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
3382 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3383 * \retval #PSA_ERROR_HARDWARE_FAILURE
Gilles Peskine4b3eb692019-05-16 21:35:18 +02003384 * \retval #PSA_ERROR_CORRUPTION_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03003385 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03003386 * The library has not been previously initialized by psa_crypto_init().
3387 * It is implementation-dependent whether a failure to initialize
3388 * results in this error code.
Gilles Peskine9e7dc712018-03-28 14:18:50 +02003389 */
Gilles Peskine35ef36b2019-05-16 19:42:05 +02003390psa_status_t psa_generate_key(const psa_key_attributes_t *attributes,
Gilles Peskinee56e8782019-04-26 17:34:02 +02003391 psa_key_handle_t *handle);
Gilles Peskine9e7dc712018-03-28 14:18:50 +02003392
3393/**@}*/
3394
Gilles Peskinee59236f2018-01-27 23:32:46 +01003395#ifdef __cplusplus
3396}
3397#endif
3398
Gilles Peskine0cad07c2018-06-27 19:49:02 +02003399/* The file "crypto_sizes.h" contains definitions for size calculation
3400 * macros whose definitions are implementation-specific. */
3401#include "crypto_sizes.h"
3402
Gilles Peskine9ef733f2018-02-07 21:05:37 +01003403/* The file "crypto_struct.h" contains definitions for
3404 * implementation-specific structs that are declared above. */
3405#include "crypto_struct.h"
3406
3407/* The file "crypto_extra.h" contains vendor-specific definitions. This
3408 * can include vendor-defined algorithms, extra functions, etc. */
Gilles Peskinee59236f2018-01-27 23:32:46 +01003409#include "crypto_extra.h"
3410
3411#endif /* PSA_CRYPTO_H */