blob: ca0d57dd7f4325cd8d2ce634045bf368cd0f556d [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
89 * \retval #PSA_ERROR_TAMPERING_DETECTED
90 * \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 Peskine87a5e562019-04-17 12:28:25 +020096/** \defgroup attributes Key attributes
97 * @{
98 */
99
100/** The type of a structure containing key attributes.
101 *
102 * This is an opaque structure that can represent the metadata of a key
Gilles Peskine9c640f92019-04-28 11:36:21 +0200103 * object. Metadata that can be stored in attributes includes:
104 * - The location of the key in storage, indicated by its key identifier
105 * and its lifetime.
106 * - The key's policy, comprising usage flags and a specification of
107 * the permitted algorithm(s).
108 * - Information about the key itself: the key type, the key size, and
109 * for some key type additional domain parameters.
110 * - Implementations may define additional attributes.
Gilles Peskine87a5e562019-04-17 12:28:25 +0200111 *
112 * The actual key material is not considered an attribute of a key.
113 * Key attributes do not contain information that is generally considered
114 * highly confidential.
Gilles Peskine20628592019-04-19 19:29:50 +0200115 *
Gilles Peskine9c640f92019-04-28 11:36:21 +0200116 * An attribute structure can be a simple data structure where each function
117 * `psa_set_key_xxx` sets a field and the corresponding function
118 * `psa_get_key_xxx` retrieves the value of the corresponding field.
119 * However, implementations may report values that are equivalent to the
120 * original one, but have a different encoding. For example, an
121 * implementation may use a more compact representation for types where
122 * many bit-patterns are invalid or not supported, and store all values
123 * that it does not support as a special marker value. In such an
124 * implementation, after setting an invalid value, the corresponding
125 * get function returns an invalid value which may not be the one that
126 * was originally stored.
127 *
128 * An attribute structure may contain references to auxiliary resources,
129 * for example pointers to allocated memory or indirect references to
130 * pre-calculated values. In order to free such resources, the application
131 * must call psa_reset_key_attributes(). As an exception, calling
132 * psa_reset_key_attributes() on an attribute structure is optional if
133 * the structure has only been modified by the following functions
134 * since it was initialized or last reset with psa_reset_key_attributes():
Gilles Peskinedc8219a2019-05-15 16:11:15 +0200135 * - psa_set_key_id()
136 * - psa_set_key_lifetime()
Gilles Peskine9c640f92019-04-28 11:36:21 +0200137 * - psa_set_key_type()
138 * - psa_set_key_bits()
139 * - psa_set_key_usage_flags()
140 * - psa_set_key_algorithm()
141 *
Gilles Peskine20628592019-04-19 19:29:50 +0200142 * Before calling any function on a key attribute structure, the application
143 * must initialize it by any of the following means:
144 * - Set the structure to all-bits-zero, for example:
145 * \code
146 * psa_key_attributes_t attributes;
147 * memset(&attributes, 0, sizeof(attributes));
148 * \endcode
149 * - Initialize the structure to logical zero values, for example:
150 * \code
151 * psa_key_attributes_t attributes = {0};
152 * \endcode
153 * - Initialize the structure to the initializer #PSA_KEY_ATTRIBUTES_INIT,
154 * for example:
155 * \code
156 * psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
157 * \endcode
158 * - Assign the result of the function psa_key_attributes_init()
159 * to the structure, for example:
160 * \code
161 * psa_key_attributes_t attributes;
162 * attributes = psa_key_attributes_init();
163 * \endcode
164 *
165 * A freshly initialized attribute structure contains the following
166 * values:
167 *
168 * - lifetime: #PSA_KEY_LIFETIME_VOLATILE.
169 * - key identifier: unspecified.
170 * - type: \c 0, with no domain parameters.
171 * - key size: \c 0.
172 * - usage flags: \c 0.
173 * - algorithm: \c 0.
174 *
Gilles Peskine9c640f92019-04-28 11:36:21 +0200175 * A typical sequence to create a key is as follows:
176 * -# Create and initialize an attribute structure.
Gilles Peskinedc8219a2019-05-15 16:11:15 +0200177 * -# If the key is persistent, call psa_set_key_id().
178 * Also call psa_set_key_lifetime() to place the key in a non-default
179 * location.
Gilles Peskine9c640f92019-04-28 11:36:21 +0200180 * -# Set the key policy with psa_set_key_usage_flags() and
181 * psa_set_key_algorithm().
182 * -# Set the key type with psa_set_key_type(). If the key type requires
183 * domain parameters, call psa_set_key_domain_parameters() instead.
184 * Skip this step if copying an existing key with psa_copy_key().
Adrian L. Shaw5a5a79a2019-05-03 15:44:28 +0100185 * -# When generating a random key with psa_generate_random_key() or deriving a key
Gilles Peskinea99d3fb2019-05-16 15:28:51 +0200186 * with psa_key_derivation_output_key(), set the desired key size with
Gilles Peskine9c640f92019-04-28 11:36:21 +0200187 * psa_set_key_bits().
Adrian L. Shaw5a5a79a2019-05-03 15:44:28 +0100188 * -# Call a key creation function: psa_import_key(), psa_generate_random_key(),
Gilles Peskinea99d3fb2019-05-16 15:28:51 +0200189 * psa_key_derivation_output_key() or psa_copy_key(). This function reads
Gilles Peskine1ea5e442019-05-02 20:31:10 +0200190 * the attribute structure, creates a key with these attributes, and
191 * outputs a handle to the newly created key.
192 * -# The attribute structure is now no longer necessary. If you called
Gilles Peskine9c640f92019-04-28 11:36:21 +0200193 * psa_set_key_domain_parameters() earlier, you must call
194 * psa_reset_key_attributes() to free any resources used by the
195 * domain parameters. Otherwise calling psa_reset_key_attributes()
196 * is optional.
Gilles Peskine20628592019-04-19 19:29:50 +0200197 *
Gilles Peskine9c640f92019-04-28 11:36:21 +0200198 * A typical sequence to query a key's attributes is as follows:
199 * -# Call psa_get_key_attributes().
200 * -# Call `psa_get_key_xxx` functions to retrieve the attribute(s) that
201 * you are interested in.
202 * -# Call psa_reset_key_attributes() to free any resources that may be
203 * used by the attribute structure.
204 *
205 * Once a key has been created, it is impossible to change its attributes.
Gilles Peskine87a5e562019-04-17 12:28:25 +0200206 */
207typedef struct psa_key_attributes_s psa_key_attributes_t;
208
Gilles Peskinedc8219a2019-05-15 16:11:15 +0200209/** Declare a key as persistent and set its key identifier.
Gilles Peskine20628592019-04-19 19:29:50 +0200210 *
Gilles Peskinef1b76942019-05-16 16:10:59 +0200211 * If the attribute structure currently declares the key as volatile (which
212 * is the default content of an attribute structure), this function sets
Gilles Peskinedc8219a2019-05-15 16:11:15 +0200213 * the lifetime attribute to #PSA_KEY_LIFETIME_PERSISTENT.
Gilles Peskine20628592019-04-19 19:29:50 +0200214 *
Gilles Peskinef1b76942019-05-16 16:10:59 +0200215 * This function does not access storage, it merely stores the given
216 * value in the structure.
217 * The persistent key will be written to storage when the attribute
218 * structure is passed to a key creation function such as
219 * psa_import_key(), psa_generate_random_key(),
Gilles Peskinea99d3fb2019-05-16 15:28:51 +0200220 * psa_key_derivation_output_key() or psa_copy_key().
Gilles Peskine20628592019-04-19 19:29:50 +0200221 *
Gilles Peskine20628592019-04-19 19:29:50 +0200222 * This function may be declared as `static` (i.e. without external
223 * linkage). This function may be provided as a function-like macro,
224 * but in this case it must evaluate each of its arguments exactly once.
225 *
226 * \param[out] attributes The attribute structure to write to.
227 * \param id The persistent identifier for the key.
Gilles Peskinedc8219a2019-05-15 16:11:15 +0200228 */
229static void psa_set_key_id(psa_key_attributes_t *attributes,
230 psa_key_id_t id);
231
232/** Set the location of a persistent key.
233 *
234 * To make a key persistent, you must give it a persistent key identifier
Gilles Peskinef1b76942019-05-16 16:10:59 +0200235 * with psa_set_key_id(). By default, a key that has a persistent identifier
236 * is stored in the default storage area identifier by
237 * #PSA_KEY_LIFETIME_PERSISTENT. Call this function to choose a storage
238 * area, or to explicitly declare the key as volatile.
Gilles Peskinedc8219a2019-05-15 16:11:15 +0200239 *
Gilles Peskinef1b76942019-05-16 16:10:59 +0200240 * This function does not access storage, it merely stores the given
241 * value in the structure.
242 * The persistent key will be written to storage when the attribute
243 * structure is passed to a key creation function such as
244 * psa_import_key(), psa_generate_random_key(),
Gilles Peskinea99d3fb2019-05-16 15:28:51 +0200245 * psa_key_derivation_output_key() or psa_copy_key().
Gilles Peskinedc8219a2019-05-15 16:11:15 +0200246 *
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 each of its arguments exactly once.
250 *
251 * \param[out] attributes The attribute structure to write to.
Gilles Peskine20628592019-04-19 19:29:50 +0200252 * \param lifetime The lifetime for the key.
253 * If this is #PSA_KEY_LIFETIME_VOLATILE, the
Gilles Peskinedc8219a2019-05-15 16:11:15 +0200254 * key will be volatile, and the key identifier
255 * attribute is reset to 0.
Gilles Peskine20628592019-04-19 19:29:50 +0200256 */
Gilles Peskinedc8219a2019-05-15 16:11:15 +0200257static void psa_set_key_lifetime(psa_key_attributes_t *attributes,
258 psa_key_lifetime_t lifetime);
Gilles Peskine4747d192019-04-17 15:05:45 +0200259
Gilles Peskine20628592019-04-19 19:29:50 +0200260/** Retrieve the key identifier from key attributes.
261 *
262 * This function may be declared as `static` (i.e. without external
263 * linkage). This function may be provided as a function-like macro,
264 * but in this case it must evaluate its argument exactly once.
265 *
266 * \param[in] attributes The key attribute structure to query.
267 *
268 * \return The persistent identifier stored in the attribute structure.
269 * This value is unspecified if the attribute structure declares
270 * the key as volatile.
271 */
Gilles Peskine4747d192019-04-17 15:05:45 +0200272static psa_key_id_t psa_get_key_id(const psa_key_attributes_t *attributes);
273
Gilles Peskine20628592019-04-19 19:29:50 +0200274/** Retrieve the lifetime from key attributes.
275 *
276 * This function may be declared as `static` (i.e. without external
277 * linkage). This function may be provided as a function-like macro,
278 * but in this case it must evaluate its argument exactly once.
279 *
280 * \param[in] attributes The key attribute structure to query.
281 *
282 * \return The lifetime value stored in the attribute structure.
283 */
Gilles Peskine4747d192019-04-17 15:05:45 +0200284static psa_key_lifetime_t psa_get_key_lifetime(
285 const psa_key_attributes_t *attributes);
286
Gilles Peskine20628592019-04-19 19:29:50 +0200287/** Declare usage flags for a key.
288 *
289 * Usage flags are part of a key's usage policy. They encode what
290 * kind of operations are permitted on the key. For more details,
291 * refer to the documentation of the type #psa_key_usage_t.
292 *
293 * This function overwrites any usage flags
294 * previously set in \p attributes.
295 *
296 * This function may be declared as `static` (i.e. without external
297 * linkage). This function may be provided as a function-like macro,
298 * but in this case it must evaluate each of its arguments exactly once.
299 *
300 * \param[out] attributes The attribute structure to write to.
301 * \param usage_flags The usage flags to write.
302 */
Gilles Peskine4747d192019-04-17 15:05:45 +0200303static void psa_set_key_usage_flags(psa_key_attributes_t *attributes,
304 psa_key_usage_t usage_flags);
305
Gilles Peskine20628592019-04-19 19:29:50 +0200306/** Retrieve the usage flags from key attributes.
307 *
308 * This function may be declared as `static` (i.e. without external
309 * linkage). This function may be provided as a function-like macro,
310 * but in this case it must evaluate its argument exactly once.
311 *
312 * \param[in] attributes The key attribute structure to query.
313 *
314 * \return The usage flags stored in the attribute structure.
315 */
Gilles Peskine4747d192019-04-17 15:05:45 +0200316static psa_key_usage_t psa_get_key_usage_flags(
317 const psa_key_attributes_t *attributes);
318
Gilles Peskine20628592019-04-19 19:29:50 +0200319/** Declare the permitted algorithm policy for a key.
320 *
321 * The permitted algorithm policy of a key encodes which algorithm or
322 * algorithms are permitted to be used with this key.
323 *
324 * This function overwrites any algorithm policy
325 * previously set in \p attributes.
326 *
327 * This function may be declared as `static` (i.e. without external
328 * linkage). This function may be provided as a function-like macro,
329 * but in this case it must evaluate each of its arguments exactly once.
330 *
331 * \param[out] attributes The attribute structure to write to.
332 * \param alg The permitted algorithm policy to write.
333 */
Gilles Peskine4747d192019-04-17 15:05:45 +0200334static void psa_set_key_algorithm(psa_key_attributes_t *attributes,
335 psa_algorithm_t alg);
336
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +0100337
Gilles Peskine20628592019-04-19 19:29:50 +0200338/** Retrieve the algorithm policy from key attributes.
339 *
340 * This function may be declared as `static` (i.e. without external
341 * linkage). This function may be provided as a function-like macro,
342 * but in this case it must evaluate its argument exactly once.
343 *
344 * \param[in] attributes The key attribute structure to query.
345 *
346 * \return The algorithm stored in the attribute structure.
347 */
Gilles Peskine4747d192019-04-17 15:05:45 +0200348static psa_algorithm_t psa_get_key_algorithm(
349 const psa_key_attributes_t *attributes);
350
Gilles Peskine20628592019-04-19 19:29:50 +0200351/** Declare the type of a key.
352 *
353 * If a type requires domain parameters, you must call
354 * psa_set_key_domain_parameters() instead of this function.
355 *
356 * This function overwrites any key type and domain parameters
357 * previously set in \p attributes.
358 *
359 * This function may be declared as `static` (i.e. without external
360 * linkage). This function may be provided as a function-like macro,
361 * but in this case it must evaluate each of its arguments exactly once.
362 *
363 * \param[out] attributes The attribute structure to write to.
364 * \param type The key type to write.
365 */
Gilles Peskine4747d192019-04-17 15:05:45 +0200366static void psa_set_key_type(psa_key_attributes_t *attributes,
367 psa_key_type_t type);
368
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +0100369
Gilles Peskine3a4f1f82019-04-26 13:49:28 +0200370/** Declare the size of a key.
371 *
372 * This function overwrites any key size previously set in \p attributes.
373 *
374 * This function may be declared as `static` (i.e. without external
375 * linkage). This function may be provided as a function-like macro,
376 * but in this case it must evaluate each of its arguments exactly once.
377 *
378 * \param[out] attributes The attribute structure to write to.
379 * \param bits The key size in bits.
380 */
381static void psa_set_key_bits(psa_key_attributes_t *attributes,
382 size_t bits);
383
Gilles Peskine20628592019-04-19 19:29:50 +0200384/** Retrieve the key type from key attributes.
385 *
386 * This function may be declared as `static` (i.e. without external
387 * linkage). This function may be provided as a function-like macro,
388 * but in this case it must evaluate its argument exactly once.
389 *
390 * \param[in] attributes The key attribute structure to query.
391 *
392 * \return The key type stored in the attribute structure.
393 */
Gilles Peskine4747d192019-04-17 15:05:45 +0200394static psa_key_type_t psa_get_key_type(const psa_key_attributes_t *attributes);
395
Gilles Peskine20628592019-04-19 19:29:50 +0200396/** Retrieve the key size from key attributes.
397 *
398 * This function may be declared as `static` (i.e. without external
399 * linkage). This function may be provided as a function-like macro,
400 * but in this case it must evaluate its argument exactly once.
401 *
402 * \param[in] attributes The key attribute structure to query.
403 *
404 * \return The key size stored in the attribute structure, in bits.
405 */
Gilles Peskine4747d192019-04-17 15:05:45 +0200406static size_t psa_get_key_bits(const psa_key_attributes_t *attributes);
407
Gilles Peskineb699f072019-04-26 16:06:02 +0200408/**
409 * \brief Set domain parameters for a key.
410 *
411 * Some key types require additional domain parameters in addition to
412 * the key type identifier and the key size.
413 * The format for the required domain parameters varies by the key type.
414 *
Gilles Peskinee56e8782019-04-26 17:34:02 +0200415 * - For RSA keys (#PSA_KEY_TYPE_RSA_PUBLIC_KEY or #PSA_KEY_TYPE_RSA_KEYPAIR),
416 * the domain parameter data consists of the public exponent,
Gilles Peskineb699f072019-04-26 16:06:02 +0200417 * represented as a big-endian integer with no leading zeros.
Gilles Peskinee56e8782019-04-26 17:34:02 +0200418 * This information is used when generating an RSA key pair.
Gilles Peskineb699f072019-04-26 16:06:02 +0200419 * When importing a key, the public exponent is read from the imported
420 * key data and the exponent recorded in the attribute structure is ignored.
Gilles Peskinee56e8782019-04-26 17:34:02 +0200421 * As an exception, the public exponent 65537 is represented by an empty
422 * byte string.
423 * - For DSA keys (#PSA_KEY_TYPE_DSA_PUBLIC_KEY or #PSA_KEY_TYPE_DSA_KEYPAIR),
Gilles Peskineb699f072019-04-26 16:06:02 +0200424 * the `Dss-Parms` format as defined by RFC 3279 &sect;2.3.2.
425 * ```
426 * Dss-Parms ::= SEQUENCE {
427 * p INTEGER,
428 * q INTEGER,
429 * g INTEGER
430 * }
431 * ```
Gilles Peskinee56e8782019-04-26 17:34:02 +0200432 * - For Diffie-Hellman key exchange keys (#PSA_KEY_TYPE_DH_PUBLIC_KEY or
433 * #PSA_KEY_TYPE_DH_KEYPAIR), the
Gilles Peskineb699f072019-04-26 16:06:02 +0200434 * `DomainParameters` format as defined by RFC 3279 &sect;2.3.3.
435 * ```
436 * DomainParameters ::= SEQUENCE {
437 * p INTEGER, -- odd prime, p=jq +1
438 * g INTEGER, -- generator, g
439 * q INTEGER, -- factor of p-1
440 * j INTEGER OPTIONAL, -- subgroup factor
441 * validationParms ValidationParms OPTIONAL
442 * }
443 * ValidationParms ::= SEQUENCE {
444 * seed BIT STRING,
445 * pgenCounter INTEGER
446 * }
447 * ```
448 *
Gilles Peskine9c640f92019-04-28 11:36:21 +0200449 * \note This function may allocate memory or other resources.
450 * Once you have called this function on an attribute structure,
451 * you must call psa_reset_key_attributes() to free these resources.
452 *
Gilles Peskineb699f072019-04-26 16:06:02 +0200453 * \param[in,out] attributes Attribute structure where the specified domain
454 * parameters will be stored.
455 * If this function fails, the content of
456 * \p attributes is not modified.
457 * \param type Key type (a \c PSA_KEY_TYPE_XXX value).
458 * \param[in] data Buffer containing the key domain parameters.
459 * The content of this buffer is interpreted
460 * according to \p type as described above.
461 * \param data_length Size of the \p data buffer in bytes.
462 *
463 * \retval #PSA_SUCCESS
464 * \retval #PSA_ERROR_INVALID_ARGUMENT
465 * \retval #PSA_ERROR_NOT_SUPPORTED
466 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
467 */
468psa_status_t psa_set_key_domain_parameters(psa_key_attributes_t *attributes,
469 psa_key_type_t type,
470 const uint8_t *data,
471 size_t data_length);
472
473/**
474 * \brief Get domain parameters for a key.
475 *
476 * Get the domain parameters for a key with this function, if any. The format
477 * of the domain parameters written to \p data is specified in the
478 * documentation for psa_set_key_domain_parameters().
479 *
480 * \param[in] attributes The key attribute structure to query.
481 * \param[out] data On success, the key domain parameters.
482 * \param data_size Size of the \p data buffer in bytes.
Gilles Peskineaa02c172019-04-28 11:44:17 +0200483 * The buffer is guaranteed to be large
484 * enough if its size in bytes is at least
485 * the value given by
486 * PSA_KEY_DOMAIN_PARAMETERS_SIZE().
Gilles Peskineb699f072019-04-26 16:06:02 +0200487 * \param[out] data_length On success, the number of bytes
488 * that make up the key domain parameters data.
489 *
490 * \retval #PSA_SUCCESS
491 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
492 */
493psa_status_t psa_get_key_domain_parameters(
494 const psa_key_attributes_t *attributes,
495 uint8_t *data,
496 size_t data_size,
497 size_t *data_length);
498
Gilles Peskine20628592019-04-19 19:29:50 +0200499/** Retrieve the attributes of a key.
500 *
501 * This function first resets the attribute structure as with
Gilles Peskine9c640f92019-04-28 11:36:21 +0200502 * psa_reset_key_attributes(). It then copies the attributes of
503 * the given key into the given attribute structure.
Gilles Peskine20628592019-04-19 19:29:50 +0200504 *
Gilles Peskine9c640f92019-04-28 11:36:21 +0200505 * \note This function may allocate memory or other resources.
506 * Once you have called this function on an attribute structure,
507 * you must call psa_reset_key_attributes() to free these resources.
Gilles Peskine20628592019-04-19 19:29:50 +0200508 *
Gilles Peskine20628592019-04-19 19:29:50 +0200509 * \param[in] handle Handle to the key to query.
510 * \param[in,out] attributes On success, the attributes of the key.
511 * On failure, equivalent to a
512 * freshly-initialized structure.
513 *
514 * \retval #PSA_SUCCESS
515 * \retval #PSA_ERROR_INVALID_HANDLE
516 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
517 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
518 */
Gilles Peskine4747d192019-04-17 15:05:45 +0200519psa_status_t psa_get_key_attributes(psa_key_handle_t handle,
520 psa_key_attributes_t *attributes);
521
Gilles Peskine20628592019-04-19 19:29:50 +0200522/** Reset a key attribute structure to a freshly initialized state.
523 *
524 * You must initialize the attribute structure as described in the
525 * documentation of the type #psa_key_attributes_t before calling this
526 * function. Once the structure has been initialized, you may call this
527 * function at any time.
528 *
529 * This function frees any auxiliary resources that the structure
530 * may contain.
531 *
532 * \param[in,out] attributes The attribute structure to reset.
533 */
Gilles Peskine8c8f2ab2019-04-18 21:44:46 +0200534void psa_reset_key_attributes(psa_key_attributes_t *attributes);
Gilles Peskine4747d192019-04-17 15:05:45 +0200535
Gilles Peskine87a5e562019-04-17 12:28:25 +0200536/**@}*/
537
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100538/** \defgroup key_management Key management
539 * @{
540 */
541
Adrian L. Shawd56456c2019-05-15 11:36:13 +0100542/** Open a handle to an existing persistent key.
Gilles Peskinef535eb22018-11-30 14:08:36 +0100543 *
Adrian L. Shawd56456c2019-05-15 11:36:13 +0100544 * Open a handle to a key which was previously created with
545 * psa_make_key_persistent() when setting its attributes.
Adrian L. Shaw52d83da2019-05-15 11:39:06 +0100546 * The handle should eventually be closed with psa_close_key()
547 * to release associated resources.
Gilles Peskinef535eb22018-11-30 14:08:36 +0100548 *
Gilles Peskine4a231b82019-05-06 18:56:14 +0200549 * Implementations may provide additional keys that can be opened with
550 * psa_open_key(). Such keys have a key identifier in the vendor range,
551 * as documented in the description of #psa_key_id_t.
552 *
Gilles Peskinef535eb22018-11-30 14:08:36 +0100553 * \param id The persistent identifier of the key.
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +0100554 * \param[out] handle On success, a handle to the key.
Gilles Peskinef535eb22018-11-30 14:08:36 +0100555 *
556 * \retval #PSA_SUCCESS
557 * Success. The application can now use the value of `*handle`
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +0100558 * to access the key.
Gilles Peskinef535eb22018-11-30 14:08:36 +0100559 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
David Saadab4ecc272019-02-14 13:48:10 +0200560 * \retval #PSA_ERROR_DOES_NOT_EXIST
Gilles Peskinef535eb22018-11-30 14:08:36 +0100561 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine225010f2019-05-06 18:44:55 +0200562 * \p id is invalid.
Gilles Peskinef535eb22018-11-30 14:08:36 +0100563 * \retval #PSA_ERROR_NOT_PERMITTED
564 * The specified key exists, but the application does not have the
565 * permission to access it. Note that this specification does not
566 * define any way to create such a key, but it may be possible
567 * through implementation-specific means.
Gilles Peskine225010f2019-05-06 18:44:55 +0200568 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
569 * \retval #PSA_ERROR_STORAGE_FAILURE
Gilles Peskinef535eb22018-11-30 14:08:36 +0100570 */
Gilles Peskine225010f2019-05-06 18:44:55 +0200571psa_status_t psa_open_key(psa_key_id_t id,
Gilles Peskinef535eb22018-11-30 14:08:36 +0100572 psa_key_handle_t *handle);
573
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +0100574
Gilles Peskinef535eb22018-11-30 14:08:36 +0100575/** Close a key handle.
576 *
577 * If the handle designates a volatile key, destroy the key material and
578 * free all associated resources, just like psa_destroy_key().
579 *
580 * If the handle designates a persistent key, free all resources associated
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +0100581 * with the key in volatile memory. The key in persistent storage is
Gilles Peskinef535eb22018-11-30 14:08:36 +0100582 * not affected and can be opened again later with psa_open_key().
583 *
Gilles Peskine5f25dd02019-01-14 18:24:53 +0100584 * If the key is currently in use in a multipart operation,
585 * the multipart operation is aborted.
586 *
Gilles Peskinef535eb22018-11-30 14:08:36 +0100587 * \param handle The key handle to close.
588 *
589 * \retval #PSA_SUCCESS
590 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskineae32aac2018-11-30 14:39:32 +0100591 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
Gilles Peskinef535eb22018-11-30 14:08:36 +0100592 */
593psa_status_t psa_close_key(psa_key_handle_t handle);
594
Gilles Peskine3cac8c42018-11-30 14:07:45 +0100595/**@}*/
596
597/** \defgroup import_export Key import and export
598 * @{
599 */
600
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100601/**
602 * \brief Import a key in binary format.
603 *
Gilles Peskinef5b9fa12018-03-07 16:40:18 +0100604 * This function supports any output from psa_export_key(). Refer to the
Gilles Peskinef7933932018-10-31 14:07:52 +0100605 * documentation of psa_export_public_key() for the format of public keys
606 * and to the documentation of psa_export_key() for the format for
607 * other key types.
608 *
609 * This specification supports a single format for each key type.
610 * Implementations may support other formats as long as the standard
611 * format is supported. Implementations that support other formats
612 * should ensure that the formats are clearly unambiguous so as to
613 * minimize the risk that an invalid input is accidentally interpreted
614 * according to a different format.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100615 *
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +0100616
Gilles Peskine20628592019-04-19 19:29:50 +0200617 * \param[in] attributes The attributes for the new key.
Gilles Peskine4ce2a9d2019-05-03 16:57:15 +0200618 * The key size is always determined from the
619 * \p data buffer.
620 * If the key size in \p attributes is nonzero,
621 * it must be equal to the size from \p data.
Gilles Peskine20628592019-04-19 19:29:50 +0200622 * \param[out] handle On success, a handle to the newly created key.
623 * \c 0 on failure.
Gilles Peskinef7933932018-10-31 14:07:52 +0100624 * \param[in] data Buffer containing the key data. The content of this
Gilles Peskine20628592019-04-19 19:29:50 +0200625 * buffer is interpreted according to the type and,
626 * if applicable, domain parameters declared in
627 * \p attributes.
628 * All implementations must support at least the format
629 * described in the documentation
Gilles Peskinef7933932018-10-31 14:07:52 +0100630 * of psa_export_key() or psa_export_public_key() for
Gilles Peskine20628592019-04-19 19:29:50 +0200631 * the chosen type. Implementations may allow other
632 * formats, but should be conservative: implementations
633 * should err on the side of rejecting content if it
634 * may be erroneous (e.g. wrong type or truncated data).
Gilles Peskinefa4070c2018-07-12 19:23:03 +0200635 * \param data_length Size of the \p data buffer in bytes.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100636 *
Gilles Peskine28538492018-07-11 17:34:00 +0200637 * \retval #PSA_SUCCESS
Gilles Peskine308b91d2018-02-08 09:47:44 +0100638 * Success.
Gilles Peskine23fd2bd2018-12-11 15:51:32 +0100639 * If the key is persistent, the key material and the key's metadata
640 * have been saved to persistent storage.
Gilles Peskine20628592019-04-19 19:29:50 +0200641 * \retval #PSA_ERROR_ALREADY_EXISTS
642 * This is an attempt to create a persistent key, and there is
643 * already a persistent key with the given identifier.
Gilles Peskine28538492018-07-11 17:34:00 +0200644 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskine65eb8582018-04-19 08:28:58 +0200645 * The key type or key size is not supported, either by the
Gilles Peskine20628592019-04-19 19:29:50 +0200646 * implementation in general or in this particular persistent location.
Gilles Peskine28538492018-07-11 17:34:00 +0200647 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine4ce2a9d2019-05-03 16:57:15 +0200648 * The key attributes, as a whole, are invalid.
649 * \retval #PSA_ERROR_INVALID_ARGUMENT
650 * The key data is not correctly formatted.
651 * \retval #PSA_ERROR_INVALID_ARGUMENT
652 * The size in \p attributes is nonzero and does not match the size
653 * of the key data.
Gilles Peskine28538492018-07-11 17:34:00 +0200654 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
655 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
656 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
Darryl Greend49a4992018-06-18 17:27:26 +0100657 * \retval #PSA_ERROR_STORAGE_FAILURE
Gilles Peskine28538492018-07-11 17:34:00 +0200658 * \retval #PSA_ERROR_HARDWARE_FAILURE
659 * \retval #PSA_ERROR_TAMPERING_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +0300660 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +0300661 * The library has not been previously initialized by psa_crypto_init().
662 * It is implementation-dependent whether a failure to initialize
663 * results in this error code.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100664 */
Gilles Peskine87a5e562019-04-17 12:28:25 +0200665psa_status_t psa_import_key(const psa_key_attributes_t *attributes,
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100666 const uint8_t *data,
Gilles Peskine73676cb2019-05-15 20:15:10 +0200667 size_t data_length,
668 psa_key_handle_t *handle);
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100669
670/**
Gilles Peskineae32aac2018-11-30 14:39:32 +0100671 * \brief Destroy a key.
Gilles Peskine154bd952018-04-19 08:38:16 +0200672 *
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +0100673 * This function destroys a key from both volatile
Gilles Peskine154bd952018-04-19 08:38:16 +0200674 * memory and, if applicable, non-volatile storage. Implementations shall
Adrian L. Shawd56456c2019-05-15 11:36:13 +0100675 * make a best effort to ensure that that the key material cannot be recovered.
Gilles Peskine154bd952018-04-19 08:38:16 +0200676 *
Gilles Peskineae32aac2018-11-30 14:39:32 +0100677 * This function also erases any metadata such as policies and frees all
678 * resources associated with the key.
Gilles Peskine154bd952018-04-19 08:38:16 +0200679 *
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +0100680 * \param handle Handle to the key to erase.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100681 *
Gilles Peskine28538492018-07-11 17:34:00 +0200682 * \retval #PSA_SUCCESS
Adrian L. Shawd56456c2019-05-15 11:36:13 +0100683 * The key material has been erased.
Gilles Peskine28538492018-07-11 17:34:00 +0200684 * \retval #PSA_ERROR_NOT_PERMITTED
Adrian L. Shaw0a695bd2019-05-15 13:28:41 +0100685 * The key cannot be erased because it is
Gilles Peskine65eb8582018-04-19 08:28:58 +0200686 * read-only, either due to a policy or due to physical restrictions.
Gilles Peskineae32aac2018-11-30 14:39:32 +0100687 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine28538492018-07-11 17:34:00 +0200688 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
Gilles Peskine65eb8582018-04-19 08:28:58 +0200689 * There was an failure in communication with the cryptoprocessor.
690 * The key material may still be present in the cryptoprocessor.
Gilles Peskine28538492018-07-11 17:34:00 +0200691 * \retval #PSA_ERROR_STORAGE_FAILURE
Gilles Peskine65eb8582018-04-19 08:28:58 +0200692 * The storage is corrupted. Implementations shall make a best effort
693 * to erase key material even in this stage, however applications
694 * should be aware that it may be impossible to guarantee that the
695 * key material is not recoverable in such cases.
Gilles Peskine28538492018-07-11 17:34:00 +0200696 * \retval #PSA_ERROR_TAMPERING_DETECTED
Gilles Peskine65eb8582018-04-19 08:28:58 +0200697 * An unexpected condition which is not a storage corruption or
698 * a communication failure occurred. The cryptoprocessor may have
699 * been compromised.
itayzafrir90d8c7a2018-09-12 11:44:52 +0300700 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +0300701 * The library has not been previously initialized by psa_crypto_init().
702 * It is implementation-dependent whether a failure to initialize
703 * results in this error code.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100704 */
Gilles Peskineae32aac2018-11-30 14:39:32 +0100705psa_status_t psa_destroy_key(psa_key_handle_t handle);
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100706
707/**
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100708 * \brief Export a key in binary format.
709 *
710 * The output of this function can be passed to psa_import_key() to
711 * create an equivalent object.
712 *
Gilles Peskinef7933932018-10-31 14:07:52 +0100713 * If the implementation of psa_import_key() supports other formats
714 * beyond the format specified here, the output from psa_export_key()
715 * must use the representation specified here, not the original
716 * representation.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100717 *
Gilles Peskine308b91d2018-02-08 09:47:44 +0100718 * For standard key types, the output format is as follows:
719 *
720 * - For symmetric keys (including MAC keys), the format is the
721 * raw bytes of the key.
722 * - For DES, the key data consists of 8 bytes. The parity bits must be
723 * correct.
724 * - For Triple-DES, the format is the concatenation of the
725 * two or three DES keys.
Gilles Peskine92b30732018-03-03 21:29:30 +0100726 * - For RSA key pairs (#PSA_KEY_TYPE_RSA_KEYPAIR), the format
Gilles Peskine4e1e9be2018-08-10 18:57:40 +0200727 * is the non-encrypted DER encoding of the representation defined by
728 * PKCS\#1 (RFC 8017) as `RSAPrivateKey`, version 0.
729 * ```
730 * RSAPrivateKey ::= SEQUENCE {
Gilles Peskine4f6c77b2018-08-11 01:17:53 +0200731 * version INTEGER, -- must be 0
Gilles Peskine4e1e9be2018-08-10 18:57:40 +0200732 * modulus INTEGER, -- n
733 * publicExponent INTEGER, -- e
734 * privateExponent INTEGER, -- d
735 * prime1 INTEGER, -- p
736 * prime2 INTEGER, -- q
737 * exponent1 INTEGER, -- d mod (p-1)
738 * exponent2 INTEGER, -- d mod (q-1)
739 * coefficient INTEGER, -- (inverse of q) mod p
740 * }
741 * ```
Jaeden Amero1308fb52019-01-11 13:50:43 +0000742 * - For DSA private keys (#PSA_KEY_TYPE_DSA_KEYPAIR), the format is the
743 * representation of the private key `x` as a big-endian byte string. The
744 * length of the byte string is the private key size in bytes (leading zeroes
745 * are not stripped).
Gilles Peskine4e1e9be2018-08-10 18:57:40 +0200746 * - For elliptic curve key pairs (key types for which
Gilles Peskinef76aa772018-10-29 19:24:33 +0100747 * #PSA_KEY_TYPE_IS_ECC_KEYPAIR is true), the format is
Gilles Peskine6c6a0232018-11-15 17:44:43 +0100748 * a representation of the private value as a `ceiling(m/8)`-byte string
749 * where `m` is the bit size associated with the curve, i.e. the bit size
750 * of the order of the curve's coordinate field. This byte string is
751 * in little-endian order for Montgomery curves (curve types
752 * `PSA_ECC_CURVE_CURVEXXX`), and in big-endian order for Weierstrass
753 * curves (curve types `PSA_ECC_CURVE_SECTXXX`, `PSA_ECC_CURVE_SECPXXX`
754 * and `PSA_ECC_CURVE_BRAINPOOL_PXXX`).
Gilles Peskinef76aa772018-10-29 19:24:33 +0100755 * This is the content of the `privateKey` field of the `ECPrivateKey`
756 * format defined by RFC 5915.
Jaeden Amero8851c402019-01-11 14:20:03 +0000757 * - For Diffie-Hellman key exchange key pairs (#PSA_KEY_TYPE_DH_KEYPAIR), the
758 * format is the representation of the private key `x` as a big-endian byte
759 * string. The length of the byte string is the private key size in bytes
760 * (leading zeroes are not stripped).
Gilles Peskine4e1e9be2018-08-10 18:57:40 +0200761 * - For public keys (key types for which #PSA_KEY_TYPE_IS_PUBLIC_KEY is
762 * true), the format is the same as for psa_export_public_key().
Gilles Peskine308b91d2018-02-08 09:47:44 +0100763 *
Gilles Peskine4318dfc2019-05-14 14:23:32 +0200764 * The policy on the key must have the usage flag #PSA_KEY_USAGE_EXPORT set.
765 *
Gilles Peskineae32aac2018-11-30 14:39:32 +0100766 * \param handle Handle to the key to export.
Gilles Peskineedd11a12018-07-12 01:08:58 +0200767 * \param[out] data Buffer where the key data is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +0200768 * \param data_size Size of the \p data buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +0200769 * \param[out] data_length On success, the number of bytes
770 * that make up the key data.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100771 *
Gilles Peskine28538492018-07-11 17:34:00 +0200772 * \retval #PSA_SUCCESS
Gilles Peskineae32aac2018-11-30 14:39:32 +0100773 * \retval #PSA_ERROR_INVALID_HANDLE
David Saadab4ecc272019-02-14 13:48:10 +0200774 * \retval #PSA_ERROR_DOES_NOT_EXIST
Gilles Peskine28538492018-07-11 17:34:00 +0200775 * \retval #PSA_ERROR_NOT_PERMITTED
Gilles Peskine4318dfc2019-05-14 14:23:32 +0200776 * The key does not have the #PSA_KEY_USAGE_EXPORT flag.
Darryl Green9e2d7a02018-07-24 16:33:30 +0100777 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskine1be949b2018-08-10 19:06:59 +0200778 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
779 * The size of the \p data buffer is too small. You can determine a
780 * sufficient buffer size by calling
781 * #PSA_KEY_EXPORT_MAX_SIZE(\c type, \c bits)
782 * where \c type is the key type
783 * and \c bits is the key size in bits.
Gilles Peskine28538492018-07-11 17:34:00 +0200784 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
785 * \retval #PSA_ERROR_HARDWARE_FAILURE
786 * \retval #PSA_ERROR_TAMPERING_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +0300787 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +0300788 * The library has not been previously initialized by psa_crypto_init().
789 * It is implementation-dependent whether a failure to initialize
790 * results in this error code.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100791 */
Gilles Peskineae32aac2018-11-30 14:39:32 +0100792psa_status_t psa_export_key(psa_key_handle_t handle,
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100793 uint8_t *data,
794 size_t data_size,
795 size_t *data_length);
796
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100797/**
798 * \brief Export a public key or the public part of a key pair in binary format.
799 *
800 * The output of this function can be passed to psa_import_key() to
801 * create an object that is equivalent to the public key.
802 *
Jaeden Amerod3a0c2c2019-01-11 17:15:56 +0000803 * This specification supports a single format for each key type.
804 * Implementations may support other formats as long as the standard
805 * format is supported. Implementations that support other formats
806 * should ensure that the formats are clearly unambiguous so as to
807 * minimize the risk that an invalid input is accidentally interpreted
808 * according to a different format.
809 *
Jaeden Amero6b196002019-01-10 10:23:21 +0000810 * For standard key types, the output format is as follows:
811 * - For RSA public keys (#PSA_KEY_TYPE_RSA_PUBLIC_KEY), the DER encoding of
812 * the representation defined by RFC 3279 &sect;2.3.1 as `RSAPublicKey`.
813 * ```
814 * RSAPublicKey ::= SEQUENCE {
815 * modulus INTEGER, -- n
816 * publicExponent INTEGER } -- e
817 * ```
Jaeden Amero0ae445f2019-01-10 11:42:27 +0000818 * - For elliptic curve public keys (key types for which
819 * #PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY is true), the format is the uncompressed
820 * representation defined by SEC1 &sect;2.3.3 as the content of an ECPoint.
821 * Let `m` be the bit size associated with the curve, i.e. the bit size of
822 * `q` for a curve over `F_q`. The representation consists of:
823 * - The byte 0x04;
824 * - `x_P` as a `ceiling(m/8)`-byte string, big-endian;
825 * - `y_P` as a `ceiling(m/8)`-byte string, big-endian.
Jaeden Amero1308fb52019-01-11 13:50:43 +0000826 * - For DSA public keys (#PSA_KEY_TYPE_DSA_PUBLIC_KEY), the format is the
827 * representation of the public key `y = g^x mod p` as a big-endian byte
828 * string. The length of the byte string is the length of the base prime `p`
829 * in bytes.
Jaeden Amero8851c402019-01-11 14:20:03 +0000830 * - For Diffie-Hellman key exchange public keys (#PSA_KEY_TYPE_DH_PUBLIC_KEY),
831 * the format is the representation of the public key `y = g^x mod p` as a
832 * big-endian byte string. The length of the byte string is the length of the
833 * base prime `p` in bytes.
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100834 *
Gilles Peskine4318dfc2019-05-14 14:23:32 +0200835 * Exporting a public key object or the public part of a key pair is
836 * always permitted, regardless of the key's usage flags.
837 *
Gilles Peskineae32aac2018-11-30 14:39:32 +0100838 * \param handle Handle to the key to export.
Gilles Peskineedd11a12018-07-12 01:08:58 +0200839 * \param[out] data Buffer where the key data is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +0200840 * \param data_size Size of the \p data buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +0200841 * \param[out] data_length On success, the number of bytes
842 * that make up the key data.
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100843 *
Gilles Peskine28538492018-07-11 17:34:00 +0200844 * \retval #PSA_SUCCESS
Gilles Peskineae32aac2018-11-30 14:39:32 +0100845 * \retval #PSA_ERROR_INVALID_HANDLE
David Saadab4ecc272019-02-14 13:48:10 +0200846 * \retval #PSA_ERROR_DOES_NOT_EXIST
Gilles Peskine28538492018-07-11 17:34:00 +0200847 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine1be949b2018-08-10 19:06:59 +0200848 * The key is neither a public key nor a key pair.
849 * \retval #PSA_ERROR_NOT_SUPPORTED
850 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
851 * The size of the \p data buffer is too small. You can determine a
852 * sufficient buffer size by calling
853 * #PSA_KEY_EXPORT_MAX_SIZE(#PSA_KEY_TYPE_PUBLIC_KEY_OF_KEYPAIR(\c type), \c bits)
854 * where \c type is the key type
855 * and \c bits is the key size in bits.
Gilles Peskine28538492018-07-11 17:34:00 +0200856 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
857 * \retval #PSA_ERROR_HARDWARE_FAILURE
858 * \retval #PSA_ERROR_TAMPERING_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +0300859 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +0300860 * The library has not been previously initialized by psa_crypto_init().
861 * It is implementation-dependent whether a failure to initialize
862 * results in this error code.
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100863 */
Gilles Peskineae32aac2018-11-30 14:39:32 +0100864psa_status_t psa_export_public_key(psa_key_handle_t handle,
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100865 uint8_t *data,
866 size_t data_size,
867 size_t *data_length);
868
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100869/** Make a copy of a key.
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100870 *
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100871 * Copy key material from one location to another.
Jaeden Amero70261c52019-01-04 11:47:20 +0000872 *
Gilles Peskineaec5a7f2019-02-05 20:26:09 +0100873 * This function is primarily useful to copy a key from one location
874 * to another, since it populates a key using the material from
875 * another key which may have a different lifetime.
Gilles Peskine6ac73a92018-07-12 19:47:19 +0200876 *
Adrian L. Shaw0a695bd2019-05-15 13:28:41 +0100877 * This function may be used to share a key with a different party,
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100878 * subject to implementation-defined restrictions on key sharing.
Gilles Peskine7e198532018-03-08 07:50:30 +0100879 *
Gilles Peskine8e0206a2019-05-14 14:24:28 +0200880 * The policy on the source key must have the usage flag
881 * #PSA_KEY_USAGE_COPY set.
Gilles Peskined6a8f5f2019-05-14 16:25:50 +0200882 * This flag is sufficient to permit the copy if the key has the lifetime
883 * #PSA_KEY_LIFETIME_VOLATILE or #PSA_KEY_LIFETIME_PERSISTENT.
884 * Some secure elements do not provide a way to copy a key without
885 * making it extractable from the secure element. If a key is located
886 * in such a secure element, then the key must have both usage flags
887 * #PSA_KEY_USAGE_COPY and #PSA_KEY_USAGE_EXPORT in order to make
888 * a copy of the key outside the secure element.
Gilles Peskine8e0206a2019-05-14 14:24:28 +0200889 *
Gilles Peskine20628592019-04-19 19:29:50 +0200890 * The resulting key may only be used in a way that conforms to
891 * both the policy of the original key and the policy specified in
892 * the \p attributes parameter:
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100893 * - The usage flags on the resulting key are the bitwise-and of the
Gilles Peskine20628592019-04-19 19:29:50 +0200894 * usage flags on the source policy and the usage flags in \p attributes.
895 * - If both allow the same algorithm or wildcard-based
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100896 * algorithm policy, the resulting key has the same algorithm policy.
Gilles Peskine20628592019-04-19 19:29:50 +0200897 * - If either of the policies allows an algorithm and the other policy
898 * allows a wildcard-based algorithm policy that includes this algorithm,
899 * the resulting key allows the same algorithm.
900 * - If the policies do not allow any algorithm in common, this function
901 * fails with the status #PSA_ERROR_INVALID_ARGUMENT.
Gilles Peskine6ac73a92018-07-12 19:47:19 +0200902 *
Gilles Peskine20628592019-04-19 19:29:50 +0200903 * The effect of this function on implementation-defined attributes is
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100904 * implementation-defined.
Gilles Peskine6ac73a92018-07-12 19:47:19 +0200905 *
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +0100906 * \param source_handle The key to copy. It must be a valid key handle.
Gilles Peskine20628592019-04-19 19:29:50 +0200907 * \param[in] attributes The attributes for the new key.
908 * They are used as follows:
Gilles Peskine4ce2a9d2019-05-03 16:57:15 +0200909 * - The key type and size may be 0. If either is
910 * nonzero, it must match the corresponding
911 * attribute of the source key.
912 * - If \p attributes contains domain parameters,
913 * they must match the domain parameters of
914 * the source key.
Gilles Peskine20628592019-04-19 19:29:50 +0200915 * - The key location (the lifetime and, for
916 * persistent keys, the key identifier) is
917 * used directly.
918 * - The policy constraints (usage flags and
919 * algorithm policy) are combined from
920 * the source key and \p attributes so that
921 * both sets of restrictions apply, as
922 * described in the documentation of this function.
923 * \param[out] target_handle On success, a handle to the newly created key.
924 * \c 0 on failure.
Gilles Peskine6ac73a92018-07-12 19:47:19 +0200925 *
926 * \retval #PSA_SUCCESS
Gilles Peskineae32aac2018-11-30 14:39:32 +0100927 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine20628592019-04-19 19:29:50 +0200928 * \p source_handle is invalid.
David Saadab4ecc272019-02-14 13:48:10 +0200929 * \retval #PSA_ERROR_ALREADY_EXISTS
Gilles Peskine20628592019-04-19 19:29:50 +0200930 * This is an attempt to create a persistent key, and there is
931 * already a persistent key with the given identifier.
Gilles Peskine6ac73a92018-07-12 19:47:19 +0200932 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine20628592019-04-19 19:29:50 +0200933 * The lifetime or identifier in \p attributes are invalid.
934 * \retval #PSA_ERROR_INVALID_ARGUMENT
935 * The policy constraints on the source and specified in
936 * \p attributes are incompatible.
Gilles Peskine4ce2a9d2019-05-03 16:57:15 +0200937 * \retval #PSA_ERROR_INVALID_ARGUMENT
938 * \p attributes specifies a key type, domain parameters or key size
939 * which does not match the attributes of the source key.
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100940 * \retval #PSA_ERROR_NOT_PERMITTED
Gilles Peskine8e0206a2019-05-14 14:24:28 +0200941 * The source key does not have the #PSA_KEY_USAGE_COPY usage flag.
942 * \retval #PSA_ERROR_NOT_PERMITTED
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100943 * The source key is not exportable and its lifetime does not
944 * allow copying it to the target's lifetime.
945 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
946 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
Gilles Peskine6ac73a92018-07-12 19:47:19 +0200947 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
948 * \retval #PSA_ERROR_HARDWARE_FAILURE
949 * \retval #PSA_ERROR_TAMPERING_DETECTED
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100950 */
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100951psa_status_t psa_copy_key(psa_key_handle_t source_handle,
Gilles Peskine87a5e562019-04-17 12:28:25 +0200952 const psa_key_attributes_t *attributes,
953 psa_key_handle_t *target_handle);
Gilles Peskine20035e32018-02-03 22:44:14 +0100954
955/**@}*/
956
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100957/** \defgroup hash Message digests
958 * @{
959 */
960
Gilles Peskine69647a42019-01-14 20:18:12 +0100961/** Calculate the hash (digest) of a message.
962 *
963 * \note To verify the hash of a message against an
964 * expected value, use psa_hash_compare() instead.
965 *
966 * \param alg The hash algorithm to compute (\c PSA_ALG_XXX value
967 * such that #PSA_ALG_IS_HASH(\p alg) is true).
968 * \param[in] input Buffer containing the message to hash.
969 * \param input_length Size of the \p input buffer in bytes.
970 * \param[out] hash Buffer where the hash is to be written.
971 * \param hash_size Size of the \p hash buffer in bytes.
972 * \param[out] hash_length On success, the number of bytes
973 * that make up the hash value. This is always
Gilles Peskined338b912019-02-15 13:01:41 +0100974 * #PSA_HASH_SIZE(\p alg).
Gilles Peskine69647a42019-01-14 20:18:12 +0100975 *
976 * \retval #PSA_SUCCESS
977 * Success.
978 * \retval #PSA_ERROR_NOT_SUPPORTED
979 * \p alg is not supported or is not a hash algorithm.
980 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
981 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
982 * \retval #PSA_ERROR_HARDWARE_FAILURE
983 * \retval #PSA_ERROR_TAMPERING_DETECTED
984 */
985psa_status_t psa_hash_compute(psa_algorithm_t alg,
986 const uint8_t *input,
987 size_t input_length,
988 uint8_t *hash,
989 size_t hash_size,
990 size_t *hash_length);
991
992/** Calculate the hash (digest) of a message and compare it with a
993 * reference value.
994 *
995 * \param alg The hash algorithm to compute (\c PSA_ALG_XXX value
996 * such that #PSA_ALG_IS_HASH(\p alg) is true).
997 * \param[in] input Buffer containing the message to hash.
998 * \param input_length Size of the \p input buffer in bytes.
999 * \param[out] hash Buffer containing the expected hash value.
Gilles Peskinea05602d2019-01-17 15:25:52 +01001000 * \param hash_length Size of the \p hash buffer in bytes.
Gilles Peskine69647a42019-01-14 20:18:12 +01001001 *
1002 * \retval #PSA_SUCCESS
1003 * The expected hash is identical to the actual hash of the input.
1004 * \retval #PSA_ERROR_INVALID_SIGNATURE
1005 * The hash of the message was calculated successfully, but it
1006 * differs from the expected hash.
1007 * \retval #PSA_ERROR_NOT_SUPPORTED
1008 * \p alg is not supported or is not a hash algorithm.
1009 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1010 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1011 * \retval #PSA_ERROR_HARDWARE_FAILURE
1012 * \retval #PSA_ERROR_TAMPERING_DETECTED
1013 */
1014psa_status_t psa_hash_compare(psa_algorithm_t alg,
1015 const uint8_t *input,
1016 size_t input_length,
1017 const uint8_t *hash,
1018 const size_t hash_length);
1019
Gilles Peskine308b91d2018-02-08 09:47:44 +01001020/** The type of the state data structure for multipart hash operations.
1021 *
Jaeden Amero6a25b412019-01-04 11:47:44 +00001022 * Before calling any function on a hash operation object, the application must
1023 * initialize it by any of the following means:
1024 * - Set the structure to all-bits-zero, for example:
1025 * \code
1026 * psa_hash_operation_t operation;
1027 * memset(&operation, 0, sizeof(operation));
1028 * \endcode
1029 * - Initialize the structure to logical zero values, for example:
1030 * \code
1031 * psa_hash_operation_t operation = {0};
1032 * \endcode
1033 * - Initialize the structure to the initializer #PSA_HASH_OPERATION_INIT,
1034 * for example:
1035 * \code
1036 * psa_hash_operation_t operation = PSA_HASH_OPERATION_INIT;
1037 * \endcode
1038 * - Assign the result of the function psa_hash_operation_init()
1039 * to the structure, for example:
1040 * \code
1041 * psa_hash_operation_t operation;
1042 * operation = psa_hash_operation_init();
1043 * \endcode
1044 *
Gilles Peskine92b30732018-03-03 21:29:30 +01001045 * This is an implementation-defined \c struct. Applications should not
Gilles Peskine308b91d2018-02-08 09:47:44 +01001046 * make any assumptions about the content of this structure except
1047 * as directed by the documentation of a specific implementation. */
Gilles Peskine9ef733f2018-02-07 21:05:37 +01001048typedef struct psa_hash_operation_s psa_hash_operation_t;
1049
Jaeden Amero6a25b412019-01-04 11:47:44 +00001050/** \def PSA_HASH_OPERATION_INIT
1051 *
1052 * This macro returns a suitable initializer for a hash operation object
1053 * of type #psa_hash_operation_t.
1054 */
1055#ifdef __DOXYGEN_ONLY__
1056/* This is an example definition for documentation purposes.
1057 * Implementations should define a suitable value in `crypto_struct.h`.
1058 */
1059#define PSA_HASH_OPERATION_INIT {0}
1060#endif
1061
1062/** Return an initial value for a hash operation object.
1063 */
1064static psa_hash_operation_t psa_hash_operation_init(void);
1065
Gilles Peskinef45adda2019-01-14 18:29:18 +01001066/** Set up a multipart hash operation.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001067 *
1068 * The sequence of operations to calculate a hash (message digest)
1069 * is as follows:
1070 * -# Allocate an operation object which will be passed to all the functions
1071 * listed here.
Jaeden Amero6a25b412019-01-04 11:47:44 +00001072 * -# Initialize the operation object with one of the methods described in the
1073 * documentation for #psa_hash_operation_t, e.g. PSA_HASH_OPERATION_INIT.
Gilles Peskineda8191d1c2018-07-08 19:46:38 +02001074 * -# Call psa_hash_setup() to specify the algorithm.
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001075 * -# Call psa_hash_update() zero, one or more times, passing a fragment
Gilles Peskine308b91d2018-02-08 09:47:44 +01001076 * of the message each time. The hash that is calculated is the hash
1077 * of the concatenation of these messages in order.
1078 * -# To calculate the hash, call psa_hash_finish().
1079 * To compare the hash with an expected value, call psa_hash_verify().
1080 *
1081 * The application may call psa_hash_abort() at any time after the operation
Jaeden Amero6a25b412019-01-04 11:47:44 +00001082 * has been initialized.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001083 *
Gilles Peskineda8191d1c2018-07-08 19:46:38 +02001084 * After a successful call to psa_hash_setup(), the application must
Gilles Peskineed522972018-03-20 17:54:15 +01001085 * eventually terminate the operation. The following events terminate an
1086 * operation:
Gilles Peskine308b91d2018-02-08 09:47:44 +01001087 * - A failed call to psa_hash_update().
Gilles Peskine19067982018-03-20 17:54:53 +01001088 * - A call to psa_hash_finish(), psa_hash_verify() or psa_hash_abort().
Gilles Peskine308b91d2018-02-08 09:47:44 +01001089 *
Jaeden Amero6a25b412019-01-04 11:47:44 +00001090 * \param[in,out] operation The operation object to set up. It must have
1091 * been initialized as per the documentation for
1092 * #psa_hash_operation_t and not yet in use.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001093 * \param alg The hash algorithm to compute (\c PSA_ALG_XXX value
1094 * such that #PSA_ALG_IS_HASH(\p alg) is true).
Gilles Peskine308b91d2018-02-08 09:47:44 +01001095 *
Gilles Peskine28538492018-07-11 17:34:00 +02001096 * \retval #PSA_SUCCESS
Gilles Peskine308b91d2018-02-08 09:47:44 +01001097 * Success.
Gilles Peskine28538492018-07-11 17:34:00 +02001098 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001099 * \p alg is not supported or is not a hash algorithm.
Gilles Peskine8e1addc2019-01-10 11:51:17 +01001100 * \retval #PSA_ERROR_BAD_STATE
1101 * The operation state is not valid (already set up and not
1102 * subsequently completed).
Gilles Peskine28538492018-07-11 17:34:00 +02001103 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1104 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1105 * \retval #PSA_ERROR_HARDWARE_FAILURE
1106 * \retval #PSA_ERROR_TAMPERING_DETECTED
Gilles Peskine308b91d2018-02-08 09:47:44 +01001107 */
Gilles Peskineda8191d1c2018-07-08 19:46:38 +02001108psa_status_t psa_hash_setup(psa_hash_operation_t *operation,
Gilles Peskine9ef733f2018-02-07 21:05:37 +01001109 psa_algorithm_t alg);
1110
Gilles Peskine308b91d2018-02-08 09:47:44 +01001111/** Add a message fragment to a multipart hash operation.
1112 *
Gilles Peskineda8191d1c2018-07-08 19:46:38 +02001113 * The application must call psa_hash_setup() before calling this function.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001114 *
1115 * If this function returns an error status, the operation becomes inactive.
1116 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001117 * \param[in,out] operation Active hash operation.
1118 * \param[in] input Buffer containing the message fragment to hash.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001119 * \param input_length Size of the \p input buffer in bytes.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001120 *
Gilles Peskine28538492018-07-11 17:34:00 +02001121 * \retval #PSA_SUCCESS
Gilles Peskine308b91d2018-02-08 09:47:44 +01001122 * Success.
Gilles Peskine28538492018-07-11 17:34:00 +02001123 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001124 * The operation state is not valid (not set up, or already completed).
Gilles Peskine28538492018-07-11 17:34:00 +02001125 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1126 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1127 * \retval #PSA_ERROR_HARDWARE_FAILURE
1128 * \retval #PSA_ERROR_TAMPERING_DETECTED
Gilles Peskine308b91d2018-02-08 09:47:44 +01001129 */
Gilles Peskine9ef733f2018-02-07 21:05:37 +01001130psa_status_t psa_hash_update(psa_hash_operation_t *operation,
1131 const uint8_t *input,
1132 size_t input_length);
1133
Gilles Peskine308b91d2018-02-08 09:47:44 +01001134/** Finish the calculation of the hash of a message.
1135 *
Gilles Peskineda8191d1c2018-07-08 19:46:38 +02001136 * The application must call psa_hash_setup() before calling this function.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001137 * This function calculates the hash of the message formed by concatenating
1138 * the inputs passed to preceding calls to psa_hash_update().
1139 *
1140 * When this function returns, the operation becomes inactive.
1141 *
1142 * \warning Applications should not call this function if they expect
1143 * a specific value for the hash. Call psa_hash_verify() instead.
1144 * Beware that comparing integrity or authenticity data such as
1145 * hash values with a function such as \c memcmp is risky
1146 * because the time taken by the comparison may leak information
1147 * about the hashed data which could allow an attacker to guess
1148 * a valid hash and thereby bypass security controls.
1149 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001150 * \param[in,out] operation Active hash operation.
1151 * \param[out] hash Buffer where the hash is to be written.
1152 * \param hash_size Size of the \p hash buffer in bytes.
1153 * \param[out] hash_length On success, the number of bytes
1154 * that make up the hash value. This is always
Gilles Peskinebe42f312018-07-13 14:38:15 +02001155 * #PSA_HASH_SIZE(\c alg) where \c alg is the
Gilles Peskineedd11a12018-07-12 01:08:58 +02001156 * hash algorithm that is calculated.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001157 *
Gilles Peskine28538492018-07-11 17:34:00 +02001158 * \retval #PSA_SUCCESS
Gilles Peskine308b91d2018-02-08 09:47:44 +01001159 * Success.
Gilles Peskine28538492018-07-11 17:34:00 +02001160 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001161 * The operation state is not valid (not set up, or already completed).
Gilles Peskine28538492018-07-11 17:34:00 +02001162 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001163 * The size of the \p hash buffer is too small. You can determine a
Gilles Peskine7256e6c2018-07-12 00:34:26 +02001164 * sufficient buffer size by calling #PSA_HASH_SIZE(\c alg)
Gilles Peskine308b91d2018-02-08 09:47:44 +01001165 * where \c alg is the hash algorithm that is calculated.
Gilles Peskine28538492018-07-11 17:34:00 +02001166 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1167 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1168 * \retval #PSA_ERROR_HARDWARE_FAILURE
1169 * \retval #PSA_ERROR_TAMPERING_DETECTED
Gilles Peskine308b91d2018-02-08 09:47:44 +01001170 */
Gilles Peskine9ef733f2018-02-07 21:05:37 +01001171psa_status_t psa_hash_finish(psa_hash_operation_t *operation,
1172 uint8_t *hash,
1173 size_t hash_size,
1174 size_t *hash_length);
1175
Gilles Peskine308b91d2018-02-08 09:47:44 +01001176/** Finish the calculation of the hash of a message and compare it with
1177 * an expected value.
1178 *
Gilles Peskineda8191d1c2018-07-08 19:46:38 +02001179 * The application must call psa_hash_setup() before calling this function.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001180 * This function calculates the hash of the message formed by concatenating
1181 * the inputs passed to preceding calls to psa_hash_update(). It then
1182 * compares the calculated hash with the expected hash passed as a
1183 * parameter to this function.
1184 *
1185 * When this function returns, the operation becomes inactive.
1186 *
Gilles Peskine19067982018-03-20 17:54:53 +01001187 * \note Implementations shall make the best effort to ensure that the
Gilles Peskine308b91d2018-02-08 09:47:44 +01001188 * comparison between the actual hash and the expected hash is performed
1189 * in constant time.
1190 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001191 * \param[in,out] operation Active hash operation.
1192 * \param[in] hash Buffer containing the expected hash value.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001193 * \param hash_length Size of the \p hash buffer in bytes.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001194 *
Gilles Peskine28538492018-07-11 17:34:00 +02001195 * \retval #PSA_SUCCESS
Gilles Peskine308b91d2018-02-08 09:47:44 +01001196 * The expected hash is identical to the actual hash of the message.
Gilles Peskine28538492018-07-11 17:34:00 +02001197 * \retval #PSA_ERROR_INVALID_SIGNATURE
Gilles Peskine308b91d2018-02-08 09:47:44 +01001198 * The hash of the message was calculated successfully, but it
1199 * differs from the expected hash.
Gilles Peskine28538492018-07-11 17:34:00 +02001200 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001201 * The operation state is not valid (not set up, or already completed).
Gilles Peskine28538492018-07-11 17:34:00 +02001202 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1203 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1204 * \retval #PSA_ERROR_HARDWARE_FAILURE
1205 * \retval #PSA_ERROR_TAMPERING_DETECTED
Gilles Peskine308b91d2018-02-08 09:47:44 +01001206 */
Gilles Peskine9ef733f2018-02-07 21:05:37 +01001207psa_status_t psa_hash_verify(psa_hash_operation_t *operation,
1208 const uint8_t *hash,
1209 size_t hash_length);
1210
Gilles Peskine308b91d2018-02-08 09:47:44 +01001211/** Abort a hash operation.
1212 *
Gilles Peskine308b91d2018-02-08 09:47:44 +01001213 * Aborting an operation frees all associated resources except for the
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001214 * \p operation structure itself. Once aborted, the operation object
1215 * can be reused for another operation by calling
1216 * psa_hash_setup() again.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001217 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001218 * You may call this function any time after the operation object has
1219 * been initialized by any of the following methods:
1220 * - A call to psa_hash_setup(), whether it succeeds or not.
1221 * - Initializing the \c struct to all-bits-zero.
1222 * - Initializing the \c struct to logical zeros, e.g.
1223 * `psa_hash_operation_t operation = {0}`.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001224 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001225 * In particular, calling psa_hash_abort() after the operation has been
1226 * terminated by a call to psa_hash_abort(), psa_hash_finish() or
1227 * psa_hash_verify() is safe and has no effect.
1228 *
1229 * \param[in,out] operation Initialized hash operation.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001230 *
Gilles Peskine28538492018-07-11 17:34:00 +02001231 * \retval #PSA_SUCCESS
1232 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001233 * \p operation is not an active hash operation.
Gilles Peskine28538492018-07-11 17:34:00 +02001234 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1235 * \retval #PSA_ERROR_HARDWARE_FAILURE
1236 * \retval #PSA_ERROR_TAMPERING_DETECTED
Gilles Peskine308b91d2018-02-08 09:47:44 +01001237 */
1238psa_status_t psa_hash_abort(psa_hash_operation_t *operation);
Gilles Peskine9ef733f2018-02-07 21:05:37 +01001239
Gilles Peskineebb2c3e2019-01-19 12:03:41 +01001240/** Clone a hash operation.
1241 *
Gilles Peskinee43aa392019-01-21 14:50:37 +01001242 * This function copies the state of an ongoing hash operation to
1243 * a new operation object. In other words, this function is equivalent
1244 * to calling psa_hash_setup() on \p target_operation with the same
1245 * algorithm that \p source_operation was set up for, then
1246 * psa_hash_update() on \p target_operation with the same input that
1247 * that was passed to \p source_operation. After this function returns, the
1248 * two objects are independent, i.e. subsequent calls involving one of
1249 * the objects do not affect the other object.
1250 *
Gilles Peskineebb2c3e2019-01-19 12:03:41 +01001251 * \param[in] source_operation The active hash operation to clone.
1252 * \param[in,out] target_operation The operation object to set up.
1253 * It must be initialized but not active.
1254 *
1255 * \retval #PSA_SUCCESS
1256 * \retval #PSA_ERROR_BAD_STATE
1257 * \p source_operation is not an active hash operation.
1258 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinee43aa392019-01-21 14:50:37 +01001259 * \p target_operation is active.
Gilles Peskineebb2c3e2019-01-19 12:03:41 +01001260 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1261 * \retval #PSA_ERROR_HARDWARE_FAILURE
1262 * \retval #PSA_ERROR_TAMPERING_DETECTED
1263 */
1264psa_status_t psa_hash_clone(const psa_hash_operation_t *source_operation,
1265 psa_hash_operation_t *target_operation);
1266
Gilles Peskine9ef733f2018-02-07 21:05:37 +01001267/**@}*/
1268
Gilles Peskine8c9def32018-02-08 10:02:12 +01001269/** \defgroup MAC Message authentication codes
1270 * @{
1271 */
1272
Gilles Peskine69647a42019-01-14 20:18:12 +01001273/** Calculate the MAC (message authentication code) of a message.
1274 *
1275 * \note To verify the MAC of a message against an
1276 * expected value, use psa_mac_verify() instead.
1277 * Beware that comparing integrity or authenticity data such as
1278 * MAC values with a function such as \c memcmp is risky
1279 * because the time taken by the comparison may leak information
1280 * about the MAC value which could allow an attacker to guess
1281 * a valid MAC and thereby bypass security controls.
1282 *
1283 * \param handle Handle to the key to use for the operation.
1284 * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
Gilles Peskine63f79302019-02-15 13:01:17 +01001285 * such that #PSA_ALG_IS_MAC(\p alg) is true).
Gilles Peskine69647a42019-01-14 20:18:12 +01001286 * \param[in] input Buffer containing the input message.
1287 * \param input_length Size of the \p input buffer in bytes.
1288 * \param[out] mac Buffer where the MAC value is to be written.
1289 * \param mac_size Size of the \p mac buffer in bytes.
1290 * \param[out] mac_length On success, the number of bytes
Gilles Peskined338b912019-02-15 13:01:41 +01001291 * that make up the MAC value.
Gilles Peskine69647a42019-01-14 20:18:12 +01001292 *
1293 * \retval #PSA_SUCCESS
1294 * Success.
1295 * \retval #PSA_ERROR_INVALID_HANDLE
1296 * \retval #PSA_ERROR_EMPTY_SLOT
1297 * \retval #PSA_ERROR_NOT_PERMITTED
1298 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001299 * \p handle is not compatible with \p alg.
Gilles Peskine69647a42019-01-14 20:18:12 +01001300 * \retval #PSA_ERROR_NOT_SUPPORTED
1301 * \p alg is not supported or is not a MAC algorithm.
1302 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1303 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1304 * \retval #PSA_ERROR_HARDWARE_FAILURE
1305 * \retval #PSA_ERROR_TAMPERING_DETECTED
1306 * \retval #PSA_ERROR_BAD_STATE
1307 * The library has not been previously initialized by psa_crypto_init().
1308 * It is implementation-dependent whether a failure to initialize
1309 * results in this error code.
1310 */
1311psa_status_t psa_mac_compute(psa_key_handle_t handle,
1312 psa_algorithm_t alg,
1313 const uint8_t *input,
1314 size_t input_length,
1315 uint8_t *mac,
1316 size_t mac_size,
1317 size_t *mac_length);
1318
1319/** Calculate the MAC of a message and compare it with a reference value.
1320 *
1321 * \param handle Handle to the key to use for the operation.
1322 * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
Gilles Peskine63f79302019-02-15 13:01:17 +01001323 * such that #PSA_ALG_IS_MAC(\p alg) is true).
Gilles Peskine69647a42019-01-14 20:18:12 +01001324 * \param[in] input Buffer containing the input message.
1325 * \param input_length Size of the \p input buffer in bytes.
1326 * \param[out] mac Buffer containing the expected MAC value.
1327 * \param mac_length Size of the \p mac buffer in bytes.
1328 *
1329 * \retval #PSA_SUCCESS
1330 * The expected MAC is identical to the actual MAC of the input.
1331 * \retval #PSA_ERROR_INVALID_SIGNATURE
1332 * The MAC of the message was calculated successfully, but it
1333 * differs from the expected value.
1334 * \retval #PSA_ERROR_INVALID_HANDLE
1335 * \retval #PSA_ERROR_EMPTY_SLOT
1336 * \retval #PSA_ERROR_NOT_PERMITTED
1337 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001338 * \p handle is not compatible with \p alg.
Gilles Peskine69647a42019-01-14 20:18:12 +01001339 * \retval #PSA_ERROR_NOT_SUPPORTED
1340 * \p alg is not supported or is not a MAC algorithm.
1341 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1342 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1343 * \retval #PSA_ERROR_HARDWARE_FAILURE
1344 * \retval #PSA_ERROR_TAMPERING_DETECTED
1345 */
Gilles Peskinea05602d2019-01-17 15:25:52 +01001346psa_status_t psa_mac_verify(psa_key_handle_t handle,
1347 psa_algorithm_t alg,
Gilles Peskine69647a42019-01-14 20:18:12 +01001348 const uint8_t *input,
1349 size_t input_length,
1350 const uint8_t *mac,
1351 const size_t mac_length);
1352
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001353/** The type of the state data structure for multipart MAC operations.
1354 *
Jaeden Amero769ce272019-01-04 11:48:03 +00001355 * Before calling any function on a MAC operation object, the application must
1356 * initialize it by any of the following means:
1357 * - Set the structure to all-bits-zero, for example:
1358 * \code
1359 * psa_mac_operation_t operation;
1360 * memset(&operation, 0, sizeof(operation));
1361 * \endcode
1362 * - Initialize the structure to logical zero values, for example:
1363 * \code
1364 * psa_mac_operation_t operation = {0};
1365 * \endcode
1366 * - Initialize the structure to the initializer #PSA_MAC_OPERATION_INIT,
1367 * for example:
1368 * \code
1369 * psa_mac_operation_t operation = PSA_MAC_OPERATION_INIT;
1370 * \endcode
1371 * - Assign the result of the function psa_mac_operation_init()
1372 * to the structure, for example:
1373 * \code
1374 * psa_mac_operation_t operation;
1375 * operation = psa_mac_operation_init();
1376 * \endcode
1377 *
Gilles Peskine92b30732018-03-03 21:29:30 +01001378 * This is an implementation-defined \c struct. Applications should not
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001379 * make any assumptions about the content of this structure except
1380 * as directed by the documentation of a specific implementation. */
Gilles Peskine8c9def32018-02-08 10:02:12 +01001381typedef struct psa_mac_operation_s psa_mac_operation_t;
1382
Jaeden Amero769ce272019-01-04 11:48:03 +00001383/** \def PSA_MAC_OPERATION_INIT
1384 *
1385 * This macro returns a suitable initializer for a MAC operation object of type
1386 * #psa_mac_operation_t.
1387 */
1388#ifdef __DOXYGEN_ONLY__
1389/* This is an example definition for documentation purposes.
1390 * Implementations should define a suitable value in `crypto_struct.h`.
1391 */
1392#define PSA_MAC_OPERATION_INIT {0}
1393#endif
1394
1395/** Return an initial value for a MAC operation object.
1396 */
1397static psa_mac_operation_t psa_mac_operation_init(void);
1398
Gilles Peskinef45adda2019-01-14 18:29:18 +01001399/** Set up a multipart MAC calculation operation.
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001400 *
Gilles Peskine89167cb2018-07-08 20:12:23 +02001401 * This function sets up the calculation of the MAC
1402 * (message authentication code) of a byte string.
1403 * To verify the MAC of a message against an
1404 * expected value, use psa_mac_verify_setup() instead.
1405 *
1406 * The sequence of operations to calculate a MAC is as follows:
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001407 * -# Allocate an operation object which will be passed to all the functions
1408 * listed here.
Jaeden Amero769ce272019-01-04 11:48:03 +00001409 * -# Initialize the operation object with one of the methods described in the
1410 * documentation for #psa_mac_operation_t, e.g. PSA_MAC_OPERATION_INIT.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001411 * -# Call psa_mac_sign_setup() to specify the algorithm and key.
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001412 * -# Call psa_mac_update() zero, one or more times, passing a fragment
1413 * of the message each time. The MAC that is calculated is the MAC
1414 * of the concatenation of these messages in order.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001415 * -# At the end of the message, call psa_mac_sign_finish() to finish
1416 * calculating the MAC value and retrieve it.
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001417 *
1418 * The application may call psa_mac_abort() at any time after the operation
Jaeden Amero769ce272019-01-04 11:48:03 +00001419 * has been initialized.
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001420 *
Gilles Peskine89167cb2018-07-08 20:12:23 +02001421 * After a successful call to psa_mac_sign_setup(), the application must
1422 * eventually terminate the operation through one of the following methods:
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001423 * - A failed call to psa_mac_update().
Gilles Peskine89167cb2018-07-08 20:12:23 +02001424 * - A call to psa_mac_sign_finish() or psa_mac_abort().
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001425 *
Jaeden Amero769ce272019-01-04 11:48:03 +00001426 * \param[in,out] operation The operation object to set up. It must have
1427 * been initialized as per the documentation for
1428 * #psa_mac_operation_t and not yet in use.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001429 * \param handle Handle to the key to use for the operation.
Gilles Peskine5f25dd02019-01-14 18:24:53 +01001430 * It must remain valid until the operation
1431 * terminates.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001432 * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
Gilles Peskine63f79302019-02-15 13:01:17 +01001433 * such that #PSA_ALG_IS_MAC(\p alg) is true).
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001434 *
Gilles Peskine28538492018-07-11 17:34:00 +02001435 * \retval #PSA_SUCCESS
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001436 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001437 * \retval #PSA_ERROR_INVALID_HANDLE
David Saadab4ecc272019-02-14 13:48:10 +02001438 * \retval #PSA_ERROR_DOES_NOT_EXIST
Gilles Peskine28538492018-07-11 17:34:00 +02001439 * \retval #PSA_ERROR_NOT_PERMITTED
1440 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001441 * \p handle is not compatible with \p alg.
Gilles Peskine28538492018-07-11 17:34:00 +02001442 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001443 * \p alg is not supported or is not a MAC algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02001444 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1445 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1446 * \retval #PSA_ERROR_HARDWARE_FAILURE
1447 * \retval #PSA_ERROR_TAMPERING_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03001448 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskine8e1addc2019-01-10 11:51:17 +01001449 * The operation state is not valid (already set up and not
1450 * subsequently completed).
1451 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03001452 * The library has not been previously initialized by psa_crypto_init().
1453 * It is implementation-dependent whether a failure to initialize
1454 * results in this error code.
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001455 */
Gilles Peskine89167cb2018-07-08 20:12:23 +02001456psa_status_t psa_mac_sign_setup(psa_mac_operation_t *operation,
Gilles Peskineae32aac2018-11-30 14:39:32 +01001457 psa_key_handle_t handle,
Gilles Peskine89167cb2018-07-08 20:12:23 +02001458 psa_algorithm_t alg);
1459
Gilles Peskinef45adda2019-01-14 18:29:18 +01001460/** Set up a multipart MAC verification operation.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001461 *
1462 * This function sets up the verification of the MAC
1463 * (message authentication code) of a byte string against an expected value.
1464 *
1465 * The sequence of operations to verify a MAC is as follows:
1466 * -# Allocate an operation object which will be passed to all the functions
1467 * listed here.
Jaeden Amero769ce272019-01-04 11:48:03 +00001468 * -# Initialize the operation object with one of the methods described in the
1469 * documentation for #psa_mac_operation_t, e.g. PSA_MAC_OPERATION_INIT.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001470 * -# Call psa_mac_verify_setup() to specify the algorithm and key.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001471 * -# Call psa_mac_update() zero, one or more times, passing a fragment
1472 * of the message each time. The MAC that is calculated is the MAC
1473 * of the concatenation of these messages in order.
1474 * -# At the end of the message, call psa_mac_verify_finish() to finish
1475 * calculating the actual MAC of the message and verify it against
1476 * the expected value.
1477 *
1478 * The application may call psa_mac_abort() at any time after the operation
Jaeden Amero769ce272019-01-04 11:48:03 +00001479 * has been initialized.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001480 *
1481 * After a successful call to psa_mac_verify_setup(), the application must
1482 * eventually terminate the operation through one of the following methods:
1483 * - A failed call to psa_mac_update().
1484 * - A call to psa_mac_verify_finish() or psa_mac_abort().
1485 *
Jaeden Amero769ce272019-01-04 11:48:03 +00001486 * \param[in,out] operation The operation object to set up. It must have
1487 * been initialized as per the documentation for
1488 * #psa_mac_operation_t and not yet in use.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001489 * \param handle Handle to the key to use for the operation.
Gilles Peskine5f25dd02019-01-14 18:24:53 +01001490 * It must remain valid until the operation
1491 * terminates.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001492 * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
1493 * such that #PSA_ALG_IS_MAC(\p alg) is true).
Gilles Peskine89167cb2018-07-08 20:12:23 +02001494 *
Gilles Peskine28538492018-07-11 17:34:00 +02001495 * \retval #PSA_SUCCESS
Gilles Peskine89167cb2018-07-08 20:12:23 +02001496 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001497 * \retval #PSA_ERROR_INVALID_HANDLE
David Saadab4ecc272019-02-14 13:48:10 +02001498 * \retval #PSA_ERROR_DOES_NOT_EXIST
Gilles Peskine28538492018-07-11 17:34:00 +02001499 * \retval #PSA_ERROR_NOT_PERMITTED
1500 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine89167cb2018-07-08 20:12:23 +02001501 * \c key is not compatible with \c alg.
Gilles Peskine28538492018-07-11 17:34:00 +02001502 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskine89167cb2018-07-08 20:12:23 +02001503 * \c alg is not supported or is not a MAC algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02001504 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1505 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1506 * \retval #PSA_ERROR_HARDWARE_FAILURE
1507 * \retval #PSA_ERROR_TAMPERING_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03001508 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskine8e1addc2019-01-10 11:51:17 +01001509 * The operation state is not valid (already set up and not
1510 * subsequently completed).
1511 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03001512 * The library has not been previously initialized by psa_crypto_init().
1513 * It is implementation-dependent whether a failure to initialize
1514 * results in this error code.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001515 */
1516psa_status_t psa_mac_verify_setup(psa_mac_operation_t *operation,
Gilles Peskineae32aac2018-11-30 14:39:32 +01001517 psa_key_handle_t handle,
Gilles Peskine89167cb2018-07-08 20:12:23 +02001518 psa_algorithm_t alg);
Gilles Peskine8c9def32018-02-08 10:02:12 +01001519
Gilles Peskinedcd14942018-07-12 00:30:52 +02001520/** Add a message fragment to a multipart MAC operation.
1521 *
1522 * The application must call psa_mac_sign_setup() or psa_mac_verify_setup()
1523 * before calling this function.
1524 *
1525 * If this function returns an error status, the operation becomes inactive.
1526 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001527 * \param[in,out] operation Active MAC operation.
1528 * \param[in] input Buffer containing the message fragment to add to
1529 * the MAC calculation.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001530 * \param input_length Size of the \p input buffer in bytes.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001531 *
1532 * \retval #PSA_SUCCESS
1533 * Success.
1534 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001535 * The operation state is not valid (not set up, or already completed).
Gilles Peskinedcd14942018-07-12 00:30:52 +02001536 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1537 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1538 * \retval #PSA_ERROR_HARDWARE_FAILURE
1539 * \retval #PSA_ERROR_TAMPERING_DETECTED
1540 */
Gilles Peskine8c9def32018-02-08 10:02:12 +01001541psa_status_t psa_mac_update(psa_mac_operation_t *operation,
1542 const uint8_t *input,
1543 size_t input_length);
1544
Gilles Peskinedcd14942018-07-12 00:30:52 +02001545/** Finish the calculation of the MAC of a message.
1546 *
1547 * The application must call psa_mac_sign_setup() before calling this function.
1548 * This function calculates the MAC of the message formed by concatenating
1549 * the inputs passed to preceding calls to psa_mac_update().
1550 *
1551 * When this function returns, the operation becomes inactive.
1552 *
1553 * \warning Applications should not call this function if they expect
1554 * a specific value for the MAC. Call psa_mac_verify_finish() instead.
1555 * Beware that comparing integrity or authenticity data such as
1556 * MAC values with a function such as \c memcmp is risky
1557 * because the time taken by the comparison may leak information
1558 * about the MAC value which could allow an attacker to guess
1559 * a valid MAC and thereby bypass security controls.
1560 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001561 * \param[in,out] operation Active MAC operation.
1562 * \param[out] mac Buffer where the MAC value is to be written.
1563 * \param mac_size Size of the \p mac buffer in bytes.
1564 * \param[out] mac_length On success, the number of bytes
1565 * that make up the MAC value. This is always
Gilles Peskinedda3bd32018-07-12 19:40:46 +02001566 * #PSA_MAC_FINAL_SIZE(\c key_type, \c key_bits, \c alg)
Gilles Peskineedd11a12018-07-12 01:08:58 +02001567 * where \c key_type and \c key_bits are the type and
Gilles Peskinedda3bd32018-07-12 19:40:46 +02001568 * bit-size respectively of the key and \c alg is the
Gilles Peskineedd11a12018-07-12 01:08:58 +02001569 * MAC algorithm that is calculated.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001570 *
1571 * \retval #PSA_SUCCESS
1572 * Success.
1573 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001574 * The operation state is not valid (not set up, or already completed).
Gilles Peskinedcd14942018-07-12 00:30:52 +02001575 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001576 * The size of the \p mac buffer is too small. You can determine a
Gilles Peskinedcd14942018-07-12 00:30:52 +02001577 * sufficient buffer size by calling PSA_MAC_FINAL_SIZE().
1578 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1579 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1580 * \retval #PSA_ERROR_HARDWARE_FAILURE
1581 * \retval #PSA_ERROR_TAMPERING_DETECTED
1582 */
Gilles Peskineacd4be32018-07-08 19:56:25 +02001583psa_status_t psa_mac_sign_finish(psa_mac_operation_t *operation,
1584 uint8_t *mac,
1585 size_t mac_size,
1586 size_t *mac_length);
Gilles Peskine8c9def32018-02-08 10:02:12 +01001587
Gilles Peskinedcd14942018-07-12 00:30:52 +02001588/** Finish the calculation of the MAC of a message and compare it with
1589 * an expected value.
1590 *
1591 * The application must call psa_mac_verify_setup() before calling this function.
1592 * This function calculates the MAC of the message formed by concatenating
1593 * the inputs passed to preceding calls to psa_mac_update(). It then
1594 * compares the calculated MAC with the expected MAC passed as a
1595 * parameter to this function.
1596 *
1597 * When this function returns, the operation becomes inactive.
1598 *
1599 * \note Implementations shall make the best effort to ensure that the
1600 * comparison between the actual MAC and the expected MAC is performed
1601 * in constant time.
1602 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001603 * \param[in,out] operation Active MAC operation.
1604 * \param[in] mac Buffer containing the expected MAC value.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001605 * \param mac_length Size of the \p mac buffer in bytes.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001606 *
1607 * \retval #PSA_SUCCESS
1608 * The expected MAC is identical to the actual MAC of the message.
1609 * \retval #PSA_ERROR_INVALID_SIGNATURE
1610 * The MAC of the message was calculated successfully, but it
1611 * differs from the expected MAC.
1612 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001613 * The operation state is not valid (not set up, or already completed).
Gilles Peskinedcd14942018-07-12 00:30:52 +02001614 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1615 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1616 * \retval #PSA_ERROR_HARDWARE_FAILURE
1617 * \retval #PSA_ERROR_TAMPERING_DETECTED
1618 */
Gilles Peskineacd4be32018-07-08 19:56:25 +02001619psa_status_t psa_mac_verify_finish(psa_mac_operation_t *operation,
1620 const uint8_t *mac,
1621 size_t mac_length);
Gilles Peskine8c9def32018-02-08 10:02:12 +01001622
Gilles Peskinedcd14942018-07-12 00:30:52 +02001623/** Abort a MAC operation.
1624 *
Gilles Peskinedcd14942018-07-12 00:30:52 +02001625 * Aborting an operation frees all associated resources except for the
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001626 * \p operation structure itself. Once aborted, the operation object
1627 * can be reused for another operation by calling
1628 * psa_mac_sign_setup() or psa_mac_verify_setup() again.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001629 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001630 * You may call this function any time after the operation object has
1631 * been initialized by any of the following methods:
1632 * - A call to psa_mac_sign_setup() or psa_mac_verify_setup(), whether
1633 * it succeeds or not.
1634 * - Initializing the \c struct to all-bits-zero.
1635 * - Initializing the \c struct to logical zeros, e.g.
1636 * `psa_mac_operation_t operation = {0}`.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001637 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001638 * In particular, calling psa_mac_abort() after the operation has been
1639 * terminated by a call to psa_mac_abort(), psa_mac_sign_finish() or
1640 * psa_mac_verify_finish() is safe and has no effect.
1641 *
1642 * \param[in,out] operation Initialized MAC operation.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001643 *
1644 * \retval #PSA_SUCCESS
1645 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001646 * \p operation is not an active MAC operation.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001647 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1648 * \retval #PSA_ERROR_HARDWARE_FAILURE
1649 * \retval #PSA_ERROR_TAMPERING_DETECTED
1650 */
Gilles Peskine8c9def32018-02-08 10:02:12 +01001651psa_status_t psa_mac_abort(psa_mac_operation_t *operation);
1652
1653/**@}*/
1654
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001655/** \defgroup cipher Symmetric ciphers
1656 * @{
1657 */
1658
Gilles Peskine69647a42019-01-14 20:18:12 +01001659/** Encrypt a message using a symmetric cipher.
1660 *
1661 * This function encrypts a message with a random IV (initialization
1662 * vector).
1663 *
1664 * \param handle Handle to the key to use for the operation.
1665 * It must remain valid until the operation
1666 * terminates.
1667 * \param alg The cipher algorithm to compute
1668 * (\c PSA_ALG_XXX value such that
1669 * #PSA_ALG_IS_CIPHER(\p alg) is true).
1670 * \param[in] input Buffer containing the message to encrypt.
1671 * \param input_length Size of the \p input buffer in bytes.
1672 * \param[out] output Buffer where the output is to be written.
1673 * The output contains the IV followed by
1674 * the ciphertext proper.
1675 * \param output_size Size of the \p output buffer in bytes.
1676 * \param[out] output_length On success, the number of bytes
1677 * that make up the output.
1678 *
1679 * \retval #PSA_SUCCESS
1680 * Success.
1681 * \retval #PSA_ERROR_INVALID_HANDLE
1682 * \retval #PSA_ERROR_EMPTY_SLOT
1683 * \retval #PSA_ERROR_NOT_PERMITTED
1684 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001685 * \p handle is not compatible with \p alg.
Gilles Peskine69647a42019-01-14 20:18:12 +01001686 * \retval #PSA_ERROR_NOT_SUPPORTED
1687 * \p alg is not supported or is not a cipher algorithm.
1688 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
1689 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1690 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1691 * \retval #PSA_ERROR_HARDWARE_FAILURE
1692 * \retval #PSA_ERROR_TAMPERING_DETECTED
1693 */
1694psa_status_t psa_cipher_encrypt(psa_key_handle_t handle,
1695 psa_algorithm_t alg,
1696 const uint8_t *input,
1697 size_t input_length,
1698 uint8_t *output,
1699 size_t output_size,
1700 size_t *output_length);
1701
1702/** Decrypt a message using a symmetric cipher.
1703 *
1704 * This function decrypts a message encrypted with a symmetric cipher.
1705 *
1706 * \param handle Handle to the key to use for the operation.
1707 * It must remain valid until the operation
1708 * terminates.
1709 * \param alg The cipher algorithm to compute
1710 * (\c PSA_ALG_XXX value such that
1711 * #PSA_ALG_IS_CIPHER(\p alg) is true).
1712 * \param[in] input Buffer containing the message to decrypt.
1713 * This consists of the IV followed by the
1714 * ciphertext proper.
1715 * \param input_length Size of the \p input buffer in bytes.
1716 * \param[out] output Buffer where the plaintext is to be written.
1717 * \param output_size Size of the \p output buffer in bytes.
1718 * \param[out] output_length On success, the number of bytes
1719 * that make up the output.
1720 *
1721 * \retval #PSA_SUCCESS
1722 * Success.
1723 * \retval #PSA_ERROR_INVALID_HANDLE
1724 * \retval #PSA_ERROR_EMPTY_SLOT
1725 * \retval #PSA_ERROR_NOT_PERMITTED
1726 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001727 * \p handle is not compatible with \p alg.
Gilles Peskine69647a42019-01-14 20:18:12 +01001728 * \retval #PSA_ERROR_NOT_SUPPORTED
1729 * \p alg is not supported or is not a cipher algorithm.
1730 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
1731 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1732 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1733 * \retval #PSA_ERROR_HARDWARE_FAILURE
1734 * \retval #PSA_ERROR_TAMPERING_DETECTED
1735 */
1736psa_status_t psa_cipher_decrypt(psa_key_handle_t handle,
1737 psa_algorithm_t alg,
1738 const uint8_t *input,
1739 size_t input_length,
1740 uint8_t *output,
1741 size_t output_size,
1742 size_t *output_length);
1743
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001744/** The type of the state data structure for multipart cipher operations.
1745 *
Jaeden Amero5bae2272019-01-04 11:48:27 +00001746 * Before calling any function on a cipher operation object, the application
1747 * must initialize it by any of the following means:
1748 * - Set the structure to all-bits-zero, for example:
1749 * \code
1750 * psa_cipher_operation_t operation;
1751 * memset(&operation, 0, sizeof(operation));
1752 * \endcode
1753 * - Initialize the structure to logical zero values, for example:
1754 * \code
1755 * psa_cipher_operation_t operation = {0};
1756 * \endcode
1757 * - Initialize the structure to the initializer #PSA_CIPHER_OPERATION_INIT,
1758 * for example:
1759 * \code
1760 * psa_cipher_operation_t operation = PSA_CIPHER_OPERATION_INIT;
1761 * \endcode
1762 * - Assign the result of the function psa_cipher_operation_init()
1763 * to the structure, for example:
1764 * \code
1765 * psa_cipher_operation_t operation;
1766 * operation = psa_cipher_operation_init();
1767 * \endcode
1768 *
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001769 * This is an implementation-defined \c struct. Applications should not
1770 * make any assumptions about the content of this structure except
1771 * as directed by the documentation of a specific implementation. */
1772typedef struct psa_cipher_operation_s psa_cipher_operation_t;
1773
Jaeden Amero5bae2272019-01-04 11:48:27 +00001774/** \def PSA_CIPHER_OPERATION_INIT
1775 *
1776 * This macro returns a suitable initializer for a cipher operation object of
1777 * type #psa_cipher_operation_t.
1778 */
1779#ifdef __DOXYGEN_ONLY__
1780/* This is an example definition for documentation purposes.
1781 * Implementations should define a suitable value in `crypto_struct.h`.
1782 */
1783#define PSA_CIPHER_OPERATION_INIT {0}
1784#endif
1785
1786/** Return an initial value for a cipher operation object.
1787 */
1788static psa_cipher_operation_t psa_cipher_operation_init(void);
1789
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001790/** Set the key for a multipart symmetric encryption operation.
1791 *
1792 * The sequence of operations to encrypt a message with a symmetric cipher
1793 * is as follows:
1794 * -# Allocate an operation object which will be passed to all the functions
1795 * listed here.
Jaeden Amero5bae2272019-01-04 11:48:27 +00001796 * -# Initialize the operation object with one of the methods described in the
1797 * documentation for #psa_cipher_operation_t, e.g.
1798 * PSA_CIPHER_OPERATION_INIT.
Gilles Peskinefe119512018-07-08 21:39:34 +02001799 * -# Call psa_cipher_encrypt_setup() to specify the algorithm and key.
itayzafrired7382f2018-08-02 14:19:33 +03001800 * -# Call either psa_cipher_generate_iv() or psa_cipher_set_iv() to
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001801 * generate or set the IV (initialization vector). You should use
itayzafrired7382f2018-08-02 14:19:33 +03001802 * psa_cipher_generate_iv() unless the protocol you are implementing
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001803 * requires a specific IV value.
1804 * -# Call psa_cipher_update() zero, one or more times, passing a fragment
1805 * of the message each time.
1806 * -# Call psa_cipher_finish().
1807 *
1808 * The application may call psa_cipher_abort() at any time after the operation
Jaeden Amero5bae2272019-01-04 11:48:27 +00001809 * has been initialized.
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001810 *
Gilles Peskinefe119512018-07-08 21:39:34 +02001811 * After a successful call to psa_cipher_encrypt_setup(), the application must
Gilles Peskineed522972018-03-20 17:54:15 +01001812 * eventually terminate the operation. The following events terminate an
1813 * operation:
Gilles Peskinef45adda2019-01-14 18:29:18 +01001814 * - A failed call to any of the \c psa_cipher_xxx functions.
Gilles Peskine19067982018-03-20 17:54:53 +01001815 * - A call to psa_cipher_finish() or psa_cipher_abort().
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001816 *
Jaeden Amero5bae2272019-01-04 11:48:27 +00001817 * \param[in,out] operation The operation object to set up. It must have
1818 * been initialized as per the documentation for
1819 * #psa_cipher_operation_t and not yet in use.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001820 * \param handle Handle to the key to use for the operation.
Gilles Peskine5f25dd02019-01-14 18:24:53 +01001821 * It must remain valid until the operation
1822 * terminates.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001823 * \param alg The cipher algorithm to compute
1824 * (\c PSA_ALG_XXX value such that
1825 * #PSA_ALG_IS_CIPHER(\p alg) is true).
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001826 *
Gilles Peskine28538492018-07-11 17:34:00 +02001827 * \retval #PSA_SUCCESS
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001828 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001829 * \retval #PSA_ERROR_INVALID_HANDLE
David Saadab4ecc272019-02-14 13:48:10 +02001830 * \retval #PSA_ERROR_DOES_NOT_EXIST
Gilles Peskine28538492018-07-11 17:34:00 +02001831 * \retval #PSA_ERROR_NOT_PERMITTED
1832 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001833 * \p handle is not compatible with \p alg.
Gilles Peskine28538492018-07-11 17:34:00 +02001834 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001835 * \p alg is not supported or is not a cipher algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02001836 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1837 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1838 * \retval #PSA_ERROR_HARDWARE_FAILURE
1839 * \retval #PSA_ERROR_TAMPERING_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03001840 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskine8e1addc2019-01-10 11:51:17 +01001841 * The operation state is not valid (already set up and not
1842 * subsequently completed).
1843 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03001844 * The library has not been previously initialized by psa_crypto_init().
1845 * It is implementation-dependent whether a failure to initialize
1846 * results in this error code.
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001847 */
Gilles Peskinefe119512018-07-08 21:39:34 +02001848psa_status_t psa_cipher_encrypt_setup(psa_cipher_operation_t *operation,
Gilles Peskineae32aac2018-11-30 14:39:32 +01001849 psa_key_handle_t handle,
Gilles Peskinefe119512018-07-08 21:39:34 +02001850 psa_algorithm_t alg);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001851
1852/** Set the key for a multipart symmetric decryption operation.
1853 *
1854 * The sequence of operations to decrypt a message with a symmetric cipher
1855 * is as follows:
1856 * -# Allocate an operation object which will be passed to all the functions
1857 * listed here.
Jaeden Amero5bae2272019-01-04 11:48:27 +00001858 * -# Initialize the operation object with one of the methods described in the
1859 * documentation for #psa_cipher_operation_t, e.g.
1860 * PSA_CIPHER_OPERATION_INIT.
Gilles Peskinefe119512018-07-08 21:39:34 +02001861 * -# Call psa_cipher_decrypt_setup() to specify the algorithm and key.
Gilles Peskinef45adda2019-01-14 18:29:18 +01001862 * -# Call psa_cipher_set_iv() with the IV (initialization vector) for the
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001863 * decryption. If the IV is prepended to the ciphertext, you can call
1864 * psa_cipher_update() on a buffer containing the IV followed by the
1865 * beginning of the message.
1866 * -# Call psa_cipher_update() zero, one or more times, passing a fragment
1867 * of the message each time.
1868 * -# Call psa_cipher_finish().
1869 *
1870 * The application may call psa_cipher_abort() at any time after the operation
Jaeden Amero5bae2272019-01-04 11:48:27 +00001871 * has been initialized.
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001872 *
Gilles Peskinefe119512018-07-08 21:39:34 +02001873 * After a successful call to psa_cipher_decrypt_setup(), the application must
Gilles Peskineed522972018-03-20 17:54:15 +01001874 * eventually terminate the operation. The following events terminate an
1875 * operation:
Gilles Peskinef45adda2019-01-14 18:29:18 +01001876 * - A failed call to any of the \c psa_cipher_xxx functions.
Gilles Peskine19067982018-03-20 17:54:53 +01001877 * - A call to psa_cipher_finish() or psa_cipher_abort().
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001878 *
Jaeden Amero5bae2272019-01-04 11:48:27 +00001879 * \param[in,out] operation The operation object to set up. It must have
1880 * been initialized as per the documentation for
1881 * #psa_cipher_operation_t and not yet in use.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001882 * \param handle Handle to the key to use for the operation.
Gilles Peskine5f25dd02019-01-14 18:24:53 +01001883 * It must remain valid until the operation
1884 * terminates.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001885 * \param alg The cipher algorithm to compute
1886 * (\c PSA_ALG_XXX value such that
1887 * #PSA_ALG_IS_CIPHER(\p alg) is true).
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001888 *
Gilles Peskine28538492018-07-11 17:34:00 +02001889 * \retval #PSA_SUCCESS
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001890 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001891 * \retval #PSA_ERROR_INVALID_HANDLE
David Saadab4ecc272019-02-14 13:48:10 +02001892 * \retval #PSA_ERROR_DOES_NOT_EXIST
Gilles Peskine28538492018-07-11 17:34:00 +02001893 * \retval #PSA_ERROR_NOT_PERMITTED
1894 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001895 * \p handle is not compatible with \p alg.
Gilles Peskine28538492018-07-11 17:34:00 +02001896 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001897 * \p alg is not supported or is not a cipher algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02001898 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1899 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1900 * \retval #PSA_ERROR_HARDWARE_FAILURE
1901 * \retval #PSA_ERROR_TAMPERING_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03001902 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskine8e1addc2019-01-10 11:51:17 +01001903 * The operation state is not valid (already set up and not
1904 * subsequently completed).
1905 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03001906 * The library has not been previously initialized by psa_crypto_init().
1907 * It is implementation-dependent whether a failure to initialize
1908 * results in this error code.
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001909 */
Gilles Peskinefe119512018-07-08 21:39:34 +02001910psa_status_t psa_cipher_decrypt_setup(psa_cipher_operation_t *operation,
Gilles Peskineae32aac2018-11-30 14:39:32 +01001911 psa_key_handle_t handle,
Gilles Peskinefe119512018-07-08 21:39:34 +02001912 psa_algorithm_t alg);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001913
Gilles Peskinedcd14942018-07-12 00:30:52 +02001914/** Generate an IV for a symmetric encryption operation.
1915 *
1916 * This function generates a random IV (initialization vector), nonce
1917 * or initial counter value for the encryption operation as appropriate
1918 * for the chosen algorithm, key type and key size.
1919 *
1920 * The application must call psa_cipher_encrypt_setup() before
1921 * calling this function.
1922 *
1923 * If this function returns an error status, the operation becomes inactive.
1924 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001925 * \param[in,out] operation Active cipher operation.
1926 * \param[out] iv Buffer where the generated IV is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001927 * \param iv_size Size of the \p iv buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001928 * \param[out] iv_length On success, the number of bytes of the
1929 * generated IV.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001930 *
1931 * \retval #PSA_SUCCESS
1932 * Success.
1933 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001934 * The operation state is not valid (not set up, or IV already set).
Gilles Peskinedcd14942018-07-12 00:30:52 +02001935 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinedda3bd32018-07-12 19:40:46 +02001936 * The size of the \p iv buffer is too small.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001937 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1938 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1939 * \retval #PSA_ERROR_HARDWARE_FAILURE
1940 * \retval #PSA_ERROR_TAMPERING_DETECTED
1941 */
Gilles Peskinefe119512018-07-08 21:39:34 +02001942psa_status_t psa_cipher_generate_iv(psa_cipher_operation_t *operation,
1943 unsigned char *iv,
1944 size_t iv_size,
1945 size_t *iv_length);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001946
Gilles Peskinedcd14942018-07-12 00:30:52 +02001947/** Set the IV for a symmetric encryption or decryption operation.
1948 *
Gilles Peskinef45adda2019-01-14 18:29:18 +01001949 * This function sets the IV (initialization vector), nonce
Gilles Peskinedcd14942018-07-12 00:30:52 +02001950 * or initial counter value for the encryption or decryption operation.
1951 *
1952 * The application must call psa_cipher_encrypt_setup() before
1953 * calling this function.
1954 *
1955 * If this function returns an error status, the operation becomes inactive.
1956 *
1957 * \note When encrypting, applications should use psa_cipher_generate_iv()
1958 * instead of this function, unless implementing a protocol that requires
1959 * a non-random IV.
1960 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001961 * \param[in,out] operation Active cipher operation.
1962 * \param[in] iv Buffer containing the IV to use.
1963 * \param iv_length Size of the IV in bytes.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001964 *
1965 * \retval #PSA_SUCCESS
1966 * Success.
1967 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001968 * The operation state is not valid (not set up, or IV already set).
Gilles Peskinedcd14942018-07-12 00:30:52 +02001969 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001970 * The size of \p iv is not acceptable for the chosen algorithm,
Gilles Peskinedcd14942018-07-12 00:30:52 +02001971 * or the chosen algorithm does not use an IV.
1972 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1973 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1974 * \retval #PSA_ERROR_HARDWARE_FAILURE
1975 * \retval #PSA_ERROR_TAMPERING_DETECTED
1976 */
Gilles Peskinefe119512018-07-08 21:39:34 +02001977psa_status_t psa_cipher_set_iv(psa_cipher_operation_t *operation,
1978 const unsigned char *iv,
1979 size_t iv_length);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001980
Gilles Peskinedcd14942018-07-12 00:30:52 +02001981/** Encrypt or decrypt a message fragment in an active cipher operation.
1982 *
Gilles Peskine9ac94262018-07-12 20:15:32 +02001983 * Before calling this function, you must:
1984 * 1. Call either psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup().
1985 * The choice of setup function determines whether this function
1986 * encrypts or decrypts its input.
1987 * 2. If the algorithm requires an IV, call psa_cipher_generate_iv()
1988 * (recommended when encrypting) or psa_cipher_set_iv().
Gilles Peskinedcd14942018-07-12 00:30:52 +02001989 *
1990 * If this function returns an error status, the operation becomes inactive.
1991 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001992 * \param[in,out] operation Active cipher operation.
1993 * \param[in] input Buffer containing the message fragment to
1994 * encrypt or decrypt.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001995 * \param input_length Size of the \p input buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001996 * \param[out] output Buffer where the output is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001997 * \param output_size Size of the \p output buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001998 * \param[out] output_length On success, the number of bytes
1999 * that make up the returned output.
Gilles Peskinedcd14942018-07-12 00:30:52 +02002000 *
2001 * \retval #PSA_SUCCESS
2002 * Success.
2003 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01002004 * The operation state is not valid (not set up, IV required but
Gilles Peskinedcd14942018-07-12 00:30:52 +02002005 * not set, or already completed).
2006 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
2007 * The size of the \p output buffer is too small.
2008 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2009 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2010 * \retval #PSA_ERROR_HARDWARE_FAILURE
2011 * \retval #PSA_ERROR_TAMPERING_DETECTED
2012 */
Gilles Peskine428dc5a2018-03-03 21:27:18 +01002013psa_status_t psa_cipher_update(psa_cipher_operation_t *operation,
2014 const uint8_t *input,
mohammad1603503973b2018-03-12 15:59:30 +02002015 size_t input_length,
Gilles Peskine2d277862018-06-18 15:41:12 +02002016 unsigned char *output,
2017 size_t output_size,
mohammad1603503973b2018-03-12 15:59:30 +02002018 size_t *output_length);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01002019
Gilles Peskinedcd14942018-07-12 00:30:52 +02002020/** Finish encrypting or decrypting a message in a cipher operation.
2021 *
2022 * The application must call psa_cipher_encrypt_setup() or
2023 * psa_cipher_decrypt_setup() before calling this function. The choice
2024 * of setup function determines whether this function encrypts or
2025 * decrypts its input.
2026 *
2027 * This function finishes the encryption or decryption of the message
2028 * formed by concatenating the inputs passed to preceding calls to
2029 * psa_cipher_update().
2030 *
2031 * When this function returns, the operation becomes inactive.
2032 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02002033 * \param[in,out] operation Active cipher operation.
2034 * \param[out] output Buffer where the output is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002035 * \param output_size Size of the \p output buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002036 * \param[out] output_length On success, the number of bytes
2037 * that make up the returned output.
Gilles Peskinedcd14942018-07-12 00:30:52 +02002038 *
2039 * \retval #PSA_SUCCESS
2040 * Success.
2041 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01002042 * The operation state is not valid (not set up, IV required but
Gilles Peskinedcd14942018-07-12 00:30:52 +02002043 * not set, or already completed).
2044 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
2045 * The size of the \p output buffer is too small.
2046 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2047 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2048 * \retval #PSA_ERROR_HARDWARE_FAILURE
2049 * \retval #PSA_ERROR_TAMPERING_DETECTED
2050 */
Gilles Peskine428dc5a2018-03-03 21:27:18 +01002051psa_status_t psa_cipher_finish(psa_cipher_operation_t *operation,
mohammad1603503973b2018-03-12 15:59:30 +02002052 uint8_t *output,
Moran Peker0071b872018-04-22 20:16:58 +03002053 size_t output_size,
mohammad1603503973b2018-03-12 15:59:30 +02002054 size_t *output_length);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01002055
Gilles Peskinedcd14942018-07-12 00:30:52 +02002056/** Abort a cipher operation.
2057 *
Gilles Peskinedcd14942018-07-12 00:30:52 +02002058 * Aborting an operation frees all associated resources except for the
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02002059 * \p operation structure itself. Once aborted, the operation object
2060 * can be reused for another operation by calling
2061 * psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup() again.
Gilles Peskinedcd14942018-07-12 00:30:52 +02002062 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02002063 * You may call this function any time after the operation object has
2064 * been initialized by any of the following methods:
2065 * - A call to psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup(),
2066 * whether it succeeds or not.
2067 * - Initializing the \c struct to all-bits-zero.
2068 * - Initializing the \c struct to logical zeros, e.g.
2069 * `psa_cipher_operation_t operation = {0}`.
Gilles Peskinedcd14942018-07-12 00:30:52 +02002070 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02002071 * In particular, calling psa_cipher_abort() after the operation has been
2072 * terminated by a call to psa_cipher_abort() or psa_cipher_finish()
2073 * is safe and has no effect.
2074 *
2075 * \param[in,out] operation Initialized cipher operation.
Gilles Peskinedcd14942018-07-12 00:30:52 +02002076 *
2077 * \retval #PSA_SUCCESS
2078 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002079 * \p operation is not an active cipher operation.
Gilles Peskinedcd14942018-07-12 00:30:52 +02002080 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2081 * \retval #PSA_ERROR_HARDWARE_FAILURE
2082 * \retval #PSA_ERROR_TAMPERING_DETECTED
2083 */
Gilles Peskine428dc5a2018-03-03 21:27:18 +01002084psa_status_t psa_cipher_abort(psa_cipher_operation_t *operation);
2085
2086/**@}*/
2087
Gilles Peskine3b555712018-03-03 21:27:57 +01002088/** \defgroup aead Authenticated encryption with associated data (AEAD)
2089 * @{
2090 */
2091
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002092/** Process an authenticated encryption operation.
Gilles Peskine3b555712018-03-03 21:27:57 +01002093 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01002094 * \param handle Handle to the key to use for the operation.
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002095 * \param alg The AEAD algorithm to compute
2096 * (\c PSA_ALG_XXX value such that
Gilles Peskine7256e6c2018-07-12 00:34:26 +02002097 * #PSA_ALG_IS_AEAD(\p alg) is true).
Gilles Peskineedd11a12018-07-12 01:08:58 +02002098 * \param[in] nonce Nonce or IV to use.
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002099 * \param nonce_length Size of the \p nonce buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002100 * \param[in] additional_data Additional data that will be authenticated
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002101 * but not encrypted.
2102 * \param additional_data_length Size of \p additional_data in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002103 * \param[in] plaintext Data that will be authenticated and
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002104 * encrypted.
2105 * \param plaintext_length Size of \p plaintext in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002106 * \param[out] ciphertext Output buffer for the authenticated and
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002107 * encrypted data. The additional data is not
2108 * part of this output. For algorithms where the
2109 * encrypted data and the authentication tag
2110 * are defined as separate outputs, the
2111 * authentication tag is appended to the
2112 * encrypted data.
2113 * \param ciphertext_size Size of the \p ciphertext buffer in bytes.
2114 * This must be at least
2115 * #PSA_AEAD_ENCRYPT_OUTPUT_SIZE(\p alg,
2116 * \p plaintext_length).
Gilles Peskineedd11a12018-07-12 01:08:58 +02002117 * \param[out] ciphertext_length On success, the size of the output
Gilles Peskine4c6fdbb2019-02-08 11:22:39 +01002118 * in the \p ciphertext buffer.
Gilles Peskine3b555712018-03-03 21:27:57 +01002119 *
Gilles Peskine28538492018-07-11 17:34:00 +02002120 * \retval #PSA_SUCCESS
Gilles Peskine3b555712018-03-03 21:27:57 +01002121 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01002122 * \retval #PSA_ERROR_INVALID_HANDLE
David Saadab4ecc272019-02-14 13:48:10 +02002123 * \retval #PSA_ERROR_DOES_NOT_EXIST
Gilles Peskine28538492018-07-11 17:34:00 +02002124 * \retval #PSA_ERROR_NOT_PERMITTED
2125 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002126 * \p handle is not compatible with \p alg.
Gilles Peskine28538492018-07-11 17:34:00 +02002127 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002128 * \p alg is not supported or is not an AEAD algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02002129 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2130 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2131 * \retval #PSA_ERROR_HARDWARE_FAILURE
2132 * \retval #PSA_ERROR_TAMPERING_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03002133 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03002134 * The library has not been previously initialized by psa_crypto_init().
2135 * It is implementation-dependent whether a failure to initialize
2136 * results in this error code.
Gilles Peskine3b555712018-03-03 21:27:57 +01002137 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01002138psa_status_t psa_aead_encrypt(psa_key_handle_t handle,
Gilles Peskine9fb0e012018-07-19 15:51:49 +02002139 psa_algorithm_t alg,
2140 const uint8_t *nonce,
2141 size_t nonce_length,
2142 const uint8_t *additional_data,
2143 size_t additional_data_length,
2144 const uint8_t *plaintext,
2145 size_t plaintext_length,
2146 uint8_t *ciphertext,
2147 size_t ciphertext_size,
2148 size_t *ciphertext_length);
Gilles Peskine3b555712018-03-03 21:27:57 +01002149
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002150/** Process an authenticated decryption operation.
Gilles Peskine3b555712018-03-03 21:27:57 +01002151 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01002152 * \param handle Handle to the key to use for the operation.
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002153 * \param alg The AEAD algorithm to compute
2154 * (\c PSA_ALG_XXX value such that
Gilles Peskine7256e6c2018-07-12 00:34:26 +02002155 * #PSA_ALG_IS_AEAD(\p alg) is true).
Gilles Peskineedd11a12018-07-12 01:08:58 +02002156 * \param[in] nonce Nonce or IV to use.
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002157 * \param nonce_length Size of the \p nonce buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002158 * \param[in] additional_data Additional data that has been authenticated
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002159 * but not encrypted.
2160 * \param additional_data_length Size of \p additional_data in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002161 * \param[in] ciphertext Data that has been authenticated and
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002162 * encrypted. For algorithms where the
2163 * encrypted data and the authentication tag
2164 * are defined as separate inputs, the buffer
2165 * must contain the encrypted data followed
2166 * by the authentication tag.
2167 * \param ciphertext_length Size of \p ciphertext in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002168 * \param[out] plaintext Output buffer for the decrypted data.
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002169 * \param plaintext_size Size of the \p plaintext buffer in bytes.
2170 * This must be at least
2171 * #PSA_AEAD_DECRYPT_OUTPUT_SIZE(\p alg,
2172 * \p ciphertext_length).
Gilles Peskineedd11a12018-07-12 01:08:58 +02002173 * \param[out] plaintext_length On success, the size of the output
Gilles Peskine4c6fdbb2019-02-08 11:22:39 +01002174 * in the \p plaintext buffer.
Gilles Peskine3b555712018-03-03 21:27:57 +01002175 *
Gilles Peskine28538492018-07-11 17:34:00 +02002176 * \retval #PSA_SUCCESS
Gilles Peskine3b555712018-03-03 21:27:57 +01002177 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01002178 * \retval #PSA_ERROR_INVALID_HANDLE
David Saadab4ecc272019-02-14 13:48:10 +02002179 * \retval #PSA_ERROR_DOES_NOT_EXIST
Gilles Peskine28538492018-07-11 17:34:00 +02002180 * \retval #PSA_ERROR_INVALID_SIGNATURE
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002181 * The ciphertext is not authentic.
Gilles Peskine28538492018-07-11 17:34:00 +02002182 * \retval #PSA_ERROR_NOT_PERMITTED
2183 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002184 * \p handle is not compatible with \p alg.
Gilles Peskine28538492018-07-11 17:34:00 +02002185 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002186 * \p alg is not supported or is not an AEAD algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02002187 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2188 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2189 * \retval #PSA_ERROR_HARDWARE_FAILURE
2190 * \retval #PSA_ERROR_TAMPERING_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03002191 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03002192 * The library has not been previously initialized by psa_crypto_init().
2193 * It is implementation-dependent whether a failure to initialize
2194 * results in this error code.
Gilles Peskine3b555712018-03-03 21:27:57 +01002195 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01002196psa_status_t psa_aead_decrypt(psa_key_handle_t handle,
Gilles Peskine9fb0e012018-07-19 15:51:49 +02002197 psa_algorithm_t alg,
2198 const uint8_t *nonce,
2199 size_t nonce_length,
2200 const uint8_t *additional_data,
2201 size_t additional_data_length,
2202 const uint8_t *ciphertext,
2203 size_t ciphertext_length,
2204 uint8_t *plaintext,
2205 size_t plaintext_size,
2206 size_t *plaintext_length);
Gilles Peskine3b555712018-03-03 21:27:57 +01002207
Gilles Peskine30a9e412019-01-14 18:36:12 +01002208/** The type of the state data structure for multipart AEAD operations.
2209 *
2210 * Before calling any function on an AEAD operation object, the application
2211 * must initialize it by any of the following means:
2212 * - Set the structure to all-bits-zero, for example:
2213 * \code
2214 * psa_aead_operation_t operation;
2215 * memset(&operation, 0, sizeof(operation));
2216 * \endcode
2217 * - Initialize the structure to logical zero values, for example:
2218 * \code
2219 * psa_aead_operation_t operation = {0};
2220 * \endcode
2221 * - Initialize the structure to the initializer #PSA_AEAD_OPERATION_INIT,
2222 * for example:
2223 * \code
2224 * psa_aead_operation_t operation = PSA_AEAD_OPERATION_INIT;
2225 * \endcode
2226 * - Assign the result of the function psa_aead_operation_init()
2227 * to the structure, for example:
2228 * \code
2229 * psa_aead_operation_t operation;
2230 * operation = psa_aead_operation_init();
2231 * \endcode
2232 *
2233 * This is an implementation-defined \c struct. Applications should not
2234 * make any assumptions about the content of this structure except
2235 * as directed by the documentation of a specific implementation. */
2236typedef struct psa_aead_operation_s psa_aead_operation_t;
2237
2238/** \def PSA_AEAD_OPERATION_INIT
2239 *
2240 * This macro returns a suitable initializer for an AEAD operation object of
2241 * type #psa_aead_operation_t.
2242 */
2243#ifdef __DOXYGEN_ONLY__
2244/* This is an example definition for documentation purposes.
2245 * Implementations should define a suitable value in `crypto_struct.h`.
2246 */
2247#define PSA_AEAD_OPERATION_INIT {0}
2248#endif
2249
2250/** Return an initial value for an AEAD operation object.
2251 */
2252static psa_aead_operation_t psa_aead_operation_init(void);
2253
2254/** Set the key for a multipart authenticated encryption operation.
2255 *
2256 * The sequence of operations to encrypt a message with authentication
2257 * is as follows:
2258 * -# Allocate an operation object which will be passed to all the functions
2259 * listed here.
2260 * -# Initialize the operation object with one of the methods described in the
2261 * documentation for #psa_aead_operation_t, e.g.
2262 * PSA_AEAD_OPERATION_INIT.
2263 * -# Call psa_aead_encrypt_setup() to specify the algorithm and key.
Gilles Peskinebc59c852019-01-17 15:26:08 +01002264 * -# If needed, call psa_aead_set_lengths() to specify the length of the
2265 * inputs to the subsequent calls to psa_aead_update_ad() and
2266 * psa_aead_update(). See the documentation of psa_aead_set_lengths()
2267 * for details.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002268 * -# Call either psa_aead_generate_nonce() or psa_aead_set_nonce() to
2269 * generate or set the nonce. You should use
2270 * psa_aead_generate_nonce() unless the protocol you are implementing
2271 * requires a specific nonce value.
2272 * -# Call psa_aead_update_ad() zero, one or more times, passing a fragment
2273 * of the non-encrypted additional authenticated data each time.
2274 * -# Call psa_aead_update() zero, one or more times, passing a fragment
Gilles Peskinea05602d2019-01-17 15:25:52 +01002275 * of the message to encrypt each time.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002276 * -# Call psa_aead_finish().
2277 *
2278 * The application may call psa_aead_abort() at any time after the operation
2279 * has been initialized.
2280 *
2281 * After a successful call to psa_aead_encrypt_setup(), the application must
2282 * eventually terminate the operation. The following events terminate an
2283 * operation:
2284 * - A failed call to any of the \c psa_aead_xxx functions.
2285 * - A call to psa_aead_finish(), psa_aead_verify() or psa_aead_abort().
2286 *
2287 * \param[in,out] operation The operation object to set up. It must have
2288 * been initialized as per the documentation for
2289 * #psa_aead_operation_t and not yet in use.
2290 * \param handle Handle to the key to use for the operation.
2291 * It must remain valid until the operation
2292 * terminates.
2293 * \param alg The AEAD algorithm to compute
2294 * (\c PSA_ALG_XXX value such that
2295 * #PSA_ALG_IS_AEAD(\p alg) is true).
2296 *
2297 * \retval #PSA_SUCCESS
2298 * Success.
2299 * \retval #PSA_ERROR_INVALID_HANDLE
2300 * \retval #PSA_ERROR_EMPTY_SLOT
2301 * \retval #PSA_ERROR_NOT_PERMITTED
2302 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002303 * \p handle is not compatible with \p alg.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002304 * \retval #PSA_ERROR_NOT_SUPPORTED
2305 * \p alg is not supported or is not an AEAD algorithm.
2306 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2307 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2308 * \retval #PSA_ERROR_HARDWARE_FAILURE
2309 * \retval #PSA_ERROR_TAMPERING_DETECTED
2310 * \retval #PSA_ERROR_BAD_STATE
2311 * The library has not been previously initialized by psa_crypto_init().
2312 * It is implementation-dependent whether a failure to initialize
2313 * results in this error code.
2314 */
2315psa_status_t psa_aead_encrypt_setup(psa_aead_operation_t *operation,
2316 psa_key_handle_t handle,
2317 psa_algorithm_t alg);
2318
2319/** Set the key for a multipart authenticated decryption operation.
2320 *
2321 * The sequence of operations to decrypt a message with authentication
2322 * is as follows:
2323 * -# Allocate an operation object which will be passed to all the functions
2324 * listed here.
2325 * -# Initialize the operation object with one of the methods described in the
2326 * documentation for #psa_aead_operation_t, e.g.
2327 * PSA_AEAD_OPERATION_INIT.
2328 * -# Call psa_aead_decrypt_setup() to specify the algorithm and key.
Gilles Peskinebc59c852019-01-17 15:26:08 +01002329 * -# If needed, call psa_aead_set_lengths() to specify the length of the
2330 * inputs to the subsequent calls to psa_aead_update_ad() and
2331 * psa_aead_update(). See the documentation of psa_aead_set_lengths()
2332 * for details.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002333 * -# Call psa_aead_set_nonce() with the nonce for the decryption.
2334 * -# Call psa_aead_update_ad() zero, one or more times, passing a fragment
2335 * of the non-encrypted additional authenticated data each time.
2336 * -# Call psa_aead_update() zero, one or more times, passing a fragment
Gilles Peskinea05602d2019-01-17 15:25:52 +01002337 * of the ciphertext to decrypt each time.
2338 * -# Call psa_aead_verify().
Gilles Peskine30a9e412019-01-14 18:36:12 +01002339 *
2340 * The application may call psa_aead_abort() at any time after the operation
2341 * has been initialized.
2342 *
2343 * After a successful call to psa_aead_decrypt_setup(), the application must
2344 * eventually terminate the operation. The following events terminate an
2345 * operation:
2346 * - A failed call to any of the \c psa_aead_xxx functions.
2347 * - A call to psa_aead_finish(), psa_aead_verify() or psa_aead_abort().
2348 *
2349 * \param[in,out] operation The operation object to set up. It must have
2350 * been initialized as per the documentation for
2351 * #psa_aead_operation_t and not yet in use.
2352 * \param handle Handle to the key to use for the operation.
2353 * It must remain valid until the operation
2354 * terminates.
2355 * \param alg The AEAD algorithm to compute
2356 * (\c PSA_ALG_XXX value such that
2357 * #PSA_ALG_IS_AEAD(\p alg) is true).
2358 *
2359 * \retval #PSA_SUCCESS
2360 * Success.
2361 * \retval #PSA_ERROR_INVALID_HANDLE
2362 * \retval #PSA_ERROR_EMPTY_SLOT
2363 * \retval #PSA_ERROR_NOT_PERMITTED
2364 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002365 * \p handle is not compatible with \p alg.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002366 * \retval #PSA_ERROR_NOT_SUPPORTED
2367 * \p alg is not supported or is not an AEAD algorithm.
2368 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2369 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2370 * \retval #PSA_ERROR_HARDWARE_FAILURE
2371 * \retval #PSA_ERROR_TAMPERING_DETECTED
2372 * \retval #PSA_ERROR_BAD_STATE
2373 * The library has not been previously initialized by psa_crypto_init().
2374 * It is implementation-dependent whether a failure to initialize
2375 * results in this error code.
2376 */
2377psa_status_t psa_aead_decrypt_setup(psa_aead_operation_t *operation,
2378 psa_key_handle_t handle,
2379 psa_algorithm_t alg);
2380
2381/** Generate a random nonce for an authenticated encryption operation.
2382 *
2383 * This function generates a random nonce for the authenticated encryption
2384 * operation with an appropriate size for the chosen algorithm, key type
2385 * and key size.
2386 *
2387 * The application must call psa_aead_encrypt_setup() before
2388 * calling this function.
2389 *
2390 * If this function returns an error status, the operation becomes inactive.
2391 *
2392 * \param[in,out] operation Active AEAD operation.
2393 * \param[out] nonce Buffer where the generated nonce is to be
2394 * written.
2395 * \param nonce_size Size of the \p nonce buffer in bytes.
2396 * \param[out] nonce_length On success, the number of bytes of the
2397 * generated nonce.
2398 *
2399 * \retval #PSA_SUCCESS
2400 * Success.
2401 * \retval #PSA_ERROR_BAD_STATE
2402 * The operation state is not valid (not set up, or nonce already set).
2403 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
2404 * The size of the \p nonce buffer is too small.
2405 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2406 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2407 * \retval #PSA_ERROR_HARDWARE_FAILURE
2408 * \retval #PSA_ERROR_TAMPERING_DETECTED
2409 */
2410psa_status_t psa_aead_generate_nonce(psa_aead_operation_t *operation,
2411 unsigned char *nonce,
2412 size_t nonce_size,
2413 size_t *nonce_length);
2414
2415/** Set the nonce for an authenticated encryption or decryption operation.
2416 *
2417 * This function sets the nonce for the authenticated
2418 * encryption or decryption operation.
2419 *
2420 * The application must call psa_aead_encrypt_setup() before
2421 * calling this function.
2422 *
2423 * If this function returns an error status, the operation becomes inactive.
2424 *
Gilles Peskinea05602d2019-01-17 15:25:52 +01002425 * \note When encrypting, applications should use psa_aead_generate_nonce()
Gilles Peskine30a9e412019-01-14 18:36:12 +01002426 * instead of this function, unless implementing a protocol that requires
2427 * a non-random IV.
2428 *
2429 * \param[in,out] operation Active AEAD operation.
Gilles Peskinea05602d2019-01-17 15:25:52 +01002430 * \param[in] nonce Buffer containing the nonce to use.
2431 * \param nonce_length Size of the nonce in bytes.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002432 *
2433 * \retval #PSA_SUCCESS
2434 * Success.
2435 * \retval #PSA_ERROR_BAD_STATE
2436 * The operation state is not valid (not set up, or nonce already set).
2437 * \retval #PSA_ERROR_INVALID_ARGUMENT
2438 * The size of \p nonce is not acceptable for the chosen algorithm.
2439 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2440 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2441 * \retval #PSA_ERROR_HARDWARE_FAILURE
2442 * \retval #PSA_ERROR_TAMPERING_DETECTED
2443 */
2444psa_status_t psa_aead_set_nonce(psa_aead_operation_t *operation,
2445 const unsigned char *nonce,
2446 size_t nonce_length);
2447
Gilles Peskinebc59c852019-01-17 15:26:08 +01002448/** Declare the lengths of the message and additional data for AEAD.
2449 *
2450 * The application must call this function before calling
2451 * psa_aead_update_ad() or psa_aead_update() if the algorithm for
2452 * the operation requires it. If the algorithm does not require it,
2453 * calling this function is optional, but if this function is called
2454 * then the implementation must enforce the lengths.
2455 *
2456 * You may call this function before or after setting the nonce with
2457 * psa_aead_set_nonce() or psa_aead_generate_nonce().
2458 *
2459 * - For #PSA_ALG_CCM, calling this function is required.
2460 * - For the other AEAD algorithms defined in this specification, calling
2461 * this function is not required.
2462 * - For vendor-defined algorithm, refer to the vendor documentation.
2463 *
2464 * \param[in,out] operation Active AEAD operation.
2465 * \param ad_length Size of the non-encrypted additional
2466 * authenticated data in bytes.
2467 * \param plaintext_length Size of the plaintext to encrypt in bytes.
2468 *
2469 * \retval #PSA_SUCCESS
2470 * Success.
2471 * \retval #PSA_ERROR_BAD_STATE
2472 * The operation state is not valid (not set up, already completed,
2473 * or psa_aead_update_ad() or psa_aead_update() already called).
2474 * \retval #PSA_ERROR_INVALID_ARGUMENT
2475 * At least one of the lengths is not acceptable for the chosen
2476 * algorithm.
2477 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2478 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2479 * \retval #PSA_ERROR_HARDWARE_FAILURE
2480 * \retval #PSA_ERROR_TAMPERING_DETECTED
2481 */
2482psa_status_t psa_aead_set_lengths(psa_aead_operation_t *operation,
2483 size_t ad_length,
2484 size_t plaintext_length);
2485
Gilles Peskine30a9e412019-01-14 18:36:12 +01002486/** Pass additional data to an active AEAD operation.
2487 *
2488 * Additional data is authenticated, but not encrypted.
2489 *
2490 * You may call this function multiple times to pass successive fragments
2491 * of the additional data. You may not call this function after passing
2492 * data to encrypt or decrypt with psa_aead_update().
2493 *
2494 * Before calling this function, you must:
2495 * 1. Call either psa_aead_encrypt_setup() or psa_aead_decrypt_setup().
2496 * 2. Set the nonce with psa_aead_generate_nonce() or psa_aead_set_nonce().
2497 *
2498 * If this function returns an error status, the operation becomes inactive.
2499 *
2500 * \warning When decrypting, until psa_aead_verify() has returned #PSA_SUCCESS,
2501 * there is no guarantee that the input is valid. Therefore, until
2502 * you have called psa_aead_verify() and it has returned #PSA_SUCCESS,
2503 * treat the input as untrusted and prepare to undo any action that
2504 * depends on the input if psa_aead_verify() returns an error status.
2505 *
2506 * \param[in,out] operation Active AEAD operation.
2507 * \param[in] input Buffer containing the fragment of
2508 * additional data.
2509 * \param input_length Size of the \p input buffer in bytes.
2510 *
2511 * \retval #PSA_SUCCESS
2512 * Success.
2513 * \retval #PSA_ERROR_BAD_STATE
2514 * The operation state is not valid (not set up, nonce not set,
2515 * psa_aead_update() already called, or operation already completed).
Gilles Peskinebc59c852019-01-17 15:26:08 +01002516 * \retval #PSA_ERROR_INVALID_ARGUMENT
2517 * The total input length overflows the additional data length that
2518 * was previously specified with psa_aead_set_lengths().
Gilles Peskine30a9e412019-01-14 18:36:12 +01002519 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2520 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2521 * \retval #PSA_ERROR_HARDWARE_FAILURE
2522 * \retval #PSA_ERROR_TAMPERING_DETECTED
2523 */
2524psa_status_t psa_aead_update_ad(psa_aead_operation_t *operation,
2525 const uint8_t *input,
2526 size_t input_length);
2527
2528/** Encrypt or decrypt a message fragment in an active AEAD operation.
2529 *
2530 * Before calling this function, you must:
2531 * 1. Call either psa_aead_encrypt_setup() or psa_aead_decrypt_setup().
2532 * The choice of setup function determines whether this function
2533 * encrypts or decrypts its input.
2534 * 2. Set the nonce with psa_aead_generate_nonce() or psa_aead_set_nonce().
2535 * 3. Call psa_aead_update_ad() to pass all the additional data.
2536 *
2537 * If this function returns an error status, the operation becomes inactive.
2538 *
2539 * \warning When decrypting, until psa_aead_verify() has returned #PSA_SUCCESS,
2540 * there is no guarantee that the input is valid. Therefore, until
2541 * you have called psa_aead_verify() and it has returned #PSA_SUCCESS:
2542 * - Do not use the output in any way other than storing it in a
2543 * confidential location. If you take any action that depends
2544 * on the tentative decrypted data, this action will need to be
2545 * undone if the input turns out not to be valid. Furthermore,
2546 * if an adversary can observe that this action took place
2547 * (for example through timing), they may be able to use this
2548 * fact as an oracle to decrypt any message encrypted with the
2549 * same key.
2550 * - In particular, do not copy the output anywhere but to a
2551 * memory or storage space that you have exclusive access to.
2552 *
Gilles Peskinef02aec92019-05-06 15:42:54 +02002553 * This function does not require the input to be aligned to any
2554 * particular block boundary. If the implementation can only process
Gilles Peskineac99e322019-05-14 16:10:53 +02002555 * a whole block at a time, it must consume all the input provided, but
2556 * it may delay the end of the corresponding output until a subsequent
2557 * call to psa_aead_update(), psa_aead_finish() or psa_aead_verify()
2558 * provides sufficient input. The amount of data that can be delayed
2559 * in this way is bounded by #PSA_AEAD_UPDATE_OUTPUT_SIZE.
Gilles Peskinef02aec92019-05-06 15:42:54 +02002560 *
Gilles Peskine30a9e412019-01-14 18:36:12 +01002561 * \param[in,out] operation Active AEAD operation.
2562 * \param[in] input Buffer containing the message fragment to
2563 * encrypt or decrypt.
2564 * \param input_length Size of the \p input buffer in bytes.
2565 * \param[out] output Buffer where the output is to be written.
2566 * \param output_size Size of the \p output buffer in bytes.
Gilles Peskine49dd8d82019-05-06 15:16:19 +02002567 * This must be at least
2568 * #PSA_AEAD_UPDATE_OUTPUT_SIZE(\c alg,
2569 * \p input_length) where \c alg is the
2570 * algorithm that is being calculated.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002571 * \param[out] output_length On success, the number of bytes
2572 * that make up the returned output.
2573 *
2574 * \retval #PSA_SUCCESS
2575 * Success.
2576 * \retval #PSA_ERROR_BAD_STATE
2577 * The operation state is not valid (not set up, nonce not set
2578 * or already completed).
2579 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
2580 * The size of the \p output buffer is too small.
Gilles Peskine49dd8d82019-05-06 15:16:19 +02002581 * You can determine a sufficient buffer size by calling
2582 * #PSA_AEAD_UPDATE_OUTPUT_SIZE(\c alg, \p input_length)
2583 * where \c alg is the algorithm that is being calculated.
Gilles Peskinebc59c852019-01-17 15:26:08 +01002584 * \retval #PSA_ERROR_INVALID_ARGUMENT
2585 * The total length of input to psa_aead_update_ad() so far is
2586 * less than the additional data length that was previously
2587 * specified with psa_aead_set_lengths().
2588 * \retval #PSA_ERROR_INVALID_ARGUMENT
2589 * The total input length overflows the plaintext length that
2590 * was previously specified with psa_aead_set_lengths().
Gilles Peskine30a9e412019-01-14 18:36:12 +01002591 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2592 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2593 * \retval #PSA_ERROR_HARDWARE_FAILURE
2594 * \retval #PSA_ERROR_TAMPERING_DETECTED
2595 */
2596psa_status_t psa_aead_update(psa_aead_operation_t *operation,
2597 const uint8_t *input,
2598 size_t input_length,
2599 unsigned char *output,
2600 size_t output_size,
2601 size_t *output_length);
2602
2603/** Finish encrypting a message in an AEAD operation.
2604 *
2605 * The operation must have been set up with psa_aead_encrypt_setup().
2606 *
2607 * This function finishes the authentication of the additional data
2608 * formed by concatenating the inputs passed to preceding calls to
2609 * psa_aead_update_ad() with the plaintext formed by concatenating the
2610 * inputs passed to preceding calls to psa_aead_update().
2611 *
2612 * This function has two output buffers:
2613 * - \p ciphertext contains trailing ciphertext that was buffered from
Gilles Peskinef02aec92019-05-06 15:42:54 +02002614 * preceding calls to psa_aead_update().
Gilles Peskine30a9e412019-01-14 18:36:12 +01002615 * - \p tag contains the authentication tag. Its length is always
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002616 * #PSA_AEAD_TAG_LENGTH(\c alg) where \c alg is the AEAD algorithm
Gilles Peskine30a9e412019-01-14 18:36:12 +01002617 * that the operation performs.
2618 *
2619 * When this function returns, the operation becomes inactive.
2620 *
2621 * \param[in,out] operation Active AEAD operation.
2622 * \param[out] ciphertext Buffer where the last part of the ciphertext
2623 * is to be written.
2624 * \param ciphertext_size Size of the \p ciphertext buffer in bytes.
Gilles Peskine49dd8d82019-05-06 15:16:19 +02002625 * This must be at least
2626 * #PSA_AEAD_FINISH_OUTPUT_SIZE(\c alg) where
2627 * \c alg is the algorithm that is being
2628 * calculated.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002629 * \param[out] ciphertext_length On success, the number of bytes of
2630 * returned ciphertext.
2631 * \param[out] tag Buffer where the authentication tag is
2632 * to be written.
2633 * \param tag_size Size of the \p tag buffer in bytes.
Gilles Peskine49dd8d82019-05-06 15:16:19 +02002634 * This must be at least
2635 * #PSA_AEAD_TAG_LENGTH(\c alg) where \c alg is
2636 * the algorithm that is being calculated.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002637 * \param[out] tag_length On success, the number of bytes
2638 * that make up the returned tag.
2639 *
2640 * \retval #PSA_SUCCESS
2641 * Success.
2642 * \retval #PSA_ERROR_BAD_STATE
2643 * The operation state is not valid (not set up, nonce not set,
2644 * decryption, or already completed).
2645 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002646 * The size of the \p ciphertext or \p tag buffer is too small.
Gilles Peskine49dd8d82019-05-06 15:16:19 +02002647 * You can determine a sufficient buffer size for \p ciphertext by
2648 * calling #PSA_AEAD_FINISH_OUTPUT_SIZE(\c alg)
2649 * where \c alg is the algorithm that is being calculated.
2650 * You can determine a sufficient buffer size for \p tag by
2651 * calling #PSA_AEAD_TAG_LENGTH(\c alg).
Gilles Peskinebc59c852019-01-17 15:26:08 +01002652 * \retval #PSA_ERROR_INVALID_ARGUMENT
2653 * The total length of input to psa_aead_update_ad() so far is
2654 * less than the additional data length that was previously
2655 * specified with psa_aead_set_lengths().
2656 * \retval #PSA_ERROR_INVALID_ARGUMENT
2657 * The total length of input to psa_aead_update() so far is
2658 * less than the plaintext length that was previously
2659 * specified with psa_aead_set_lengths().
Gilles Peskine30a9e412019-01-14 18:36:12 +01002660 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2661 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2662 * \retval #PSA_ERROR_HARDWARE_FAILURE
2663 * \retval #PSA_ERROR_TAMPERING_DETECTED
2664 */
2665psa_status_t psa_aead_finish(psa_aead_operation_t *operation,
Gilles Peskinea05602d2019-01-17 15:25:52 +01002666 uint8_t *ciphertext,
2667 size_t ciphertext_size,
2668 size_t *ciphertext_length,
Gilles Peskine30a9e412019-01-14 18:36:12 +01002669 uint8_t *tag,
2670 size_t tag_size,
2671 size_t *tag_length);
2672
2673/** Finish authenticating and decrypting a message in an AEAD operation.
2674 *
2675 * The operation must have been set up with psa_aead_decrypt_setup().
2676 *
2677 * This function finishes the authentication of the additional data
2678 * formed by concatenating the inputs passed to preceding calls to
2679 * psa_aead_update_ad() with the ciphertext formed by concatenating the
2680 * inputs passed to preceding calls to psa_aead_update().
2681 *
2682 * When this function returns, the operation becomes inactive.
2683 *
2684 * \param[in,out] operation Active AEAD operation.
Gilles Peskine5211efb2019-05-06 15:56:05 +02002685 * \param[out] plaintext Buffer where the last part of the plaintext
Gilles Peskineac99e322019-05-14 16:10:53 +02002686 * is to be written. This is the remaining data
Gilles Peskine5211efb2019-05-06 15:56:05 +02002687 * from previous calls to psa_aead_update()
2688 * that could not be processed until the end
2689 * of the input.
2690 * \param plaintext_size Size of the \p plaintext buffer in bytes.
Gilles Peskine49dd8d82019-05-06 15:16:19 +02002691 * This must be at least
2692 * #PSA_AEAD_VERIFY_OUTPUT_SIZE(\c alg) where
2693 * \c alg is the algorithm that is being
2694 * calculated.
Gilles Peskine5211efb2019-05-06 15:56:05 +02002695 * \param[out] plaintext_length On success, the number of bytes of
2696 * returned plaintext.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002697 * \param[in] tag Buffer containing the authentication tag.
2698 * \param tag_length Size of the \p tag buffer in bytes.
2699 *
2700 * \retval #PSA_SUCCESS
2701 * Success.
2702 * \retval #PSA_ERROR_BAD_STATE
2703 * The operation state is not valid (not set up, nonce not set,
2704 * encryption, or already completed).
Gilles Peskine49dd8d82019-05-06 15:16:19 +02002705 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
2706 * The size of the \p plaintext buffer is too small.
2707 * You can determine a sufficient buffer size for \p plaintext by
2708 * calling #PSA_AEAD_VERIFY_OUTPUT_SIZE(\c alg)
2709 * where \c alg is the algorithm that is being calculated.
Gilles Peskinebc59c852019-01-17 15:26:08 +01002710 * \retval #PSA_ERROR_INVALID_ARGUMENT
2711 * The total length of input to psa_aead_update_ad() so far is
2712 * less than the additional data length that was previously
2713 * specified with psa_aead_set_lengths().
2714 * \retval #PSA_ERROR_INVALID_ARGUMENT
2715 * The total length of input to psa_aead_update() so far is
2716 * less than the plaintext length that was previously
2717 * specified with psa_aead_set_lengths().
Gilles Peskine30a9e412019-01-14 18:36:12 +01002718 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2719 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2720 * \retval #PSA_ERROR_HARDWARE_FAILURE
2721 * \retval #PSA_ERROR_TAMPERING_DETECTED
2722 */
2723psa_status_t psa_aead_verify(psa_aead_operation_t *operation,
Gilles Peskine5211efb2019-05-06 15:56:05 +02002724 uint8_t *plaintext,
2725 size_t plaintext_size,
2726 size_t *plaintext_length,
Gilles Peskine30a9e412019-01-14 18:36:12 +01002727 const uint8_t *tag,
2728 size_t tag_length);
2729
2730/** Abort an AEAD operation.
2731 *
2732 * Aborting an operation frees all associated resources except for the
2733 * \p operation structure itself. Once aborted, the operation object
2734 * can be reused for another operation by calling
2735 * psa_aead_encrypt_setup() or psa_aead_decrypt_setup() again.
2736 *
2737 * You may call this function any time after the operation object has
2738 * been initialized by any of the following methods:
2739 * - A call to psa_aead_encrypt_setup() or psa_aead_decrypt_setup(),
2740 * whether it succeeds or not.
2741 * - Initializing the \c struct to all-bits-zero.
2742 * - Initializing the \c struct to logical zeros, e.g.
2743 * `psa_aead_operation_t operation = {0}`.
2744 *
2745 * In particular, calling psa_aead_abort() after the operation has been
2746 * terminated by a call to psa_aead_abort() or psa_aead_finish()
2747 * is safe and has no effect.
2748 *
2749 * \param[in,out] operation Initialized AEAD operation.
2750 *
2751 * \retval #PSA_SUCCESS
2752 * \retval #PSA_ERROR_BAD_STATE
2753 * \p operation is not an active AEAD operation.
2754 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2755 * \retval #PSA_ERROR_HARDWARE_FAILURE
2756 * \retval #PSA_ERROR_TAMPERING_DETECTED
2757 */
2758psa_status_t psa_aead_abort(psa_aead_operation_t *operation);
2759
Gilles Peskine3b555712018-03-03 21:27:57 +01002760/**@}*/
2761
Gilles Peskine20035e32018-02-03 22:44:14 +01002762/** \defgroup asymmetric Asymmetric cryptography
2763 * @{
2764 */
2765
2766/**
2767 * \brief Sign a hash or short message with a private key.
2768 *
Gilles Peskine08bac712018-06-26 16:14:46 +02002769 * Note that to perform a hash-and-sign signature algorithm, you must
Gilles Peskineda8191d1c2018-07-08 19:46:38 +02002770 * first calculate the hash by calling psa_hash_setup(), psa_hash_update()
Gilles Peskine08bac712018-06-26 16:14:46 +02002771 * and psa_hash_finish(). Then pass the resulting hash as the \p hash
2772 * parameter to this function. You can use #PSA_ALG_SIGN_GET_HASH(\p alg)
2773 * to determine the hash algorithm to use.
2774 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01002775 * \param handle Handle to the key to use for the operation.
2776 * It must be an asymmetric key pair.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002777 * \param alg A signature algorithm that is compatible with
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002778 * the type of \p handle.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002779 * \param[in] hash The hash or message to sign.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002780 * \param hash_length Size of the \p hash buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002781 * \param[out] signature Buffer where the signature is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002782 * \param signature_size Size of the \p signature buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002783 * \param[out] signature_length On success, the number of bytes
2784 * that make up the returned signature value.
Gilles Peskine308b91d2018-02-08 09:47:44 +01002785 *
Gilles Peskine28538492018-07-11 17:34:00 +02002786 * \retval #PSA_SUCCESS
2787 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002788 * The size of the \p signature buffer is too small. You can
Gilles Peskine308b91d2018-02-08 09:47:44 +01002789 * determine a sufficient buffer size by calling
Gilles Peskine7256e6c2018-07-12 00:34:26 +02002790 * #PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
Gilles Peskine308b91d2018-02-08 09:47:44 +01002791 * where \c key_type and \c key_bits are the type and bit-size
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002792 * respectively of \p handle.
Gilles Peskine28538492018-07-11 17:34:00 +02002793 * \retval #PSA_ERROR_NOT_SUPPORTED
2794 * \retval #PSA_ERROR_INVALID_ARGUMENT
2795 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2796 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2797 * \retval #PSA_ERROR_HARDWARE_FAILURE
2798 * \retval #PSA_ERROR_TAMPERING_DETECTED
2799 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
itayzafrir90d8c7a2018-09-12 11:44:52 +03002800 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03002801 * The library has not been previously initialized by psa_crypto_init().
2802 * It is implementation-dependent whether a failure to initialize
2803 * results in this error code.
Gilles Peskine20035e32018-02-03 22:44:14 +01002804 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01002805psa_status_t psa_asymmetric_sign(psa_key_handle_t handle,
Gilles Peskine20035e32018-02-03 22:44:14 +01002806 psa_algorithm_t alg,
2807 const uint8_t *hash,
2808 size_t hash_length,
Gilles Peskine20035e32018-02-03 22:44:14 +01002809 uint8_t *signature,
2810 size_t signature_size,
2811 size_t *signature_length);
2812
2813/**
2814 * \brief Verify the signature a hash or short message using a public key.
2815 *
Gilles Peskine08bac712018-06-26 16:14:46 +02002816 * Note that to perform a hash-and-sign signature algorithm, you must
Gilles Peskineda8191d1c2018-07-08 19:46:38 +02002817 * first calculate the hash by calling psa_hash_setup(), psa_hash_update()
Gilles Peskine08bac712018-06-26 16:14:46 +02002818 * and psa_hash_finish(). Then pass the resulting hash as the \p hash
2819 * parameter to this function. You can use #PSA_ALG_SIGN_GET_HASH(\p alg)
2820 * to determine the hash algorithm to use.
2821 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01002822 * \param handle Handle to the key to use for the operation.
2823 * It must be a public key or an asymmetric key pair.
Gilles Peskine308b91d2018-02-08 09:47:44 +01002824 * \param alg A signature algorithm that is compatible with
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002825 * the type of \p handle.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002826 * \param[in] hash The hash or message whose signature is to be
Gilles Peskine08bac712018-06-26 16:14:46 +02002827 * verified.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002828 * \param hash_length Size of the \p hash buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002829 * \param[in] signature Buffer containing the signature to verify.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002830 * \param signature_length Size of the \p signature buffer in bytes.
Gilles Peskine308b91d2018-02-08 09:47:44 +01002831 *
Gilles Peskine28538492018-07-11 17:34:00 +02002832 * \retval #PSA_SUCCESS
Gilles Peskine308b91d2018-02-08 09:47:44 +01002833 * The signature is valid.
Gilles Peskine28538492018-07-11 17:34:00 +02002834 * \retval #PSA_ERROR_INVALID_SIGNATURE
Gilles Peskine308b91d2018-02-08 09:47:44 +01002835 * The calculation was perfomed successfully, but the passed
2836 * signature is not a valid signature.
Gilles Peskine28538492018-07-11 17:34:00 +02002837 * \retval #PSA_ERROR_NOT_SUPPORTED
2838 * \retval #PSA_ERROR_INVALID_ARGUMENT
2839 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2840 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2841 * \retval #PSA_ERROR_HARDWARE_FAILURE
2842 * \retval #PSA_ERROR_TAMPERING_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03002843 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03002844 * The library has not been previously initialized by psa_crypto_init().
2845 * It is implementation-dependent whether a failure to initialize
2846 * results in this error code.
Gilles Peskine20035e32018-02-03 22:44:14 +01002847 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01002848psa_status_t psa_asymmetric_verify(psa_key_handle_t handle,
Gilles Peskine20035e32018-02-03 22:44:14 +01002849 psa_algorithm_t alg,
2850 const uint8_t *hash,
2851 size_t hash_length,
Gilles Peskinee9191ff2018-06-27 14:58:41 +02002852 const uint8_t *signature,
Gilles Peskine526fab02018-06-27 18:19:40 +02002853 size_t signature_length);
Gilles Peskine20035e32018-02-03 22:44:14 +01002854
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002855/**
2856 * \brief Encrypt a short message with a public key.
2857 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01002858 * \param handle Handle to the key to use for the operation.
2859 * It must be a public key or an asymmetric
2860 * key pair.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002861 * \param alg An asymmetric encryption algorithm that is
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002862 * compatible with the type of \p handle.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002863 * \param[in] input The message to encrypt.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002864 * \param input_length Size of the \p input buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002865 * \param[in] salt A salt or label, if supported by the
2866 * encryption algorithm.
2867 * If the algorithm does not support a
2868 * salt, pass \c NULL.
2869 * If the algorithm supports an optional
2870 * salt and you do not want to pass a salt,
2871 * pass \c NULL.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002872 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02002873 * - For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is
2874 * supported.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002875 * \param salt_length Size of the \p salt buffer in bytes.
2876 * If \p salt is \c NULL, pass 0.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002877 * \param[out] output Buffer where the encrypted message is to
2878 * be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002879 * \param output_size Size of the \p output buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002880 * \param[out] output_length On success, the number of bytes
2881 * that make up the returned output.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002882 *
Gilles Peskine28538492018-07-11 17:34:00 +02002883 * \retval #PSA_SUCCESS
2884 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002885 * The size of the \p output buffer is too small. You can
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002886 * determine a sufficient buffer size by calling
Gilles Peskine7256e6c2018-07-12 00:34:26 +02002887 * #PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002888 * where \c key_type and \c key_bits are the type and bit-size
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002889 * respectively of \p handle.
Gilles Peskine28538492018-07-11 17:34:00 +02002890 * \retval #PSA_ERROR_NOT_SUPPORTED
2891 * \retval #PSA_ERROR_INVALID_ARGUMENT
2892 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2893 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2894 * \retval #PSA_ERROR_HARDWARE_FAILURE
2895 * \retval #PSA_ERROR_TAMPERING_DETECTED
2896 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
itayzafrir90d8c7a2018-09-12 11:44:52 +03002897 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03002898 * The library has not been previously initialized by psa_crypto_init().
2899 * It is implementation-dependent whether a failure to initialize
2900 * results in this error code.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002901 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01002902psa_status_t psa_asymmetric_encrypt(psa_key_handle_t handle,
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002903 psa_algorithm_t alg,
2904 const uint8_t *input,
2905 size_t input_length,
2906 const uint8_t *salt,
2907 size_t salt_length,
2908 uint8_t *output,
2909 size_t output_size,
2910 size_t *output_length);
2911
2912/**
2913 * \brief Decrypt a short message with a private key.
2914 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01002915 * \param handle Handle to the key to use for the operation.
2916 * It must be an asymmetric key pair.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002917 * \param alg An asymmetric encryption algorithm that is
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002918 * compatible with the type of \p handle.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002919 * \param[in] input The message to decrypt.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002920 * \param input_length Size of the \p input buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002921 * \param[in] salt A salt or label, if supported by the
2922 * encryption algorithm.
2923 * If the algorithm does not support a
2924 * salt, pass \c NULL.
2925 * If the algorithm supports an optional
2926 * salt and you do not want to pass a salt,
2927 * pass \c NULL.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002928 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02002929 * - For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is
2930 * supported.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002931 * \param salt_length Size of the \p salt buffer in bytes.
2932 * If \p salt is \c NULL, pass 0.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002933 * \param[out] output Buffer where the decrypted message is to
2934 * be written.
2935 * \param output_size Size of the \c output buffer in bytes.
2936 * \param[out] output_length On success, the number of bytes
2937 * that make up the returned output.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002938 *
Gilles Peskine28538492018-07-11 17:34:00 +02002939 * \retval #PSA_SUCCESS
2940 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002941 * The size of the \p output buffer is too small. You can
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002942 * determine a sufficient buffer size by calling
Gilles Peskinedda3bd32018-07-12 19:40:46 +02002943 * #PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002944 * where \c key_type and \c key_bits are the type and bit-size
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002945 * respectively of \p handle.
Gilles Peskine28538492018-07-11 17:34:00 +02002946 * \retval #PSA_ERROR_NOT_SUPPORTED
2947 * \retval #PSA_ERROR_INVALID_ARGUMENT
2948 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2949 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2950 * \retval #PSA_ERROR_HARDWARE_FAILURE
2951 * \retval #PSA_ERROR_TAMPERING_DETECTED
2952 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
2953 * \retval #PSA_ERROR_INVALID_PADDING
itayzafrir90d8c7a2018-09-12 11:44:52 +03002954 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03002955 * The library has not been previously initialized by psa_crypto_init().
2956 * It is implementation-dependent whether a failure to initialize
2957 * results in this error code.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002958 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01002959psa_status_t psa_asymmetric_decrypt(psa_key_handle_t handle,
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002960 psa_algorithm_t alg,
2961 const uint8_t *input,
2962 size_t input_length,
2963 const uint8_t *salt,
2964 size_t salt_length,
2965 uint8_t *output,
2966 size_t output_size,
2967 size_t *output_length);
2968
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +01002969/**@}*/
2970
Gilles Peskine35675b62019-05-16 17:26:11 +02002971/** \defgroup key_derivation Key derivation and pseudorandom generation
Gilles Peskineeab56e42018-07-12 17:12:33 +02002972 * @{
2973 */
2974
Gilles Peskine35675b62019-05-16 17:26:11 +02002975/** The type of the state data structure for key derivation operations.
Gilles Peskineeab56e42018-07-12 17:12:33 +02002976 *
Gilles Peskine35675b62019-05-16 17:26:11 +02002977 * Before calling any function on a key derivation operation object, the
2978 * application must initialize it by any of the following means:
Gilles Peskineeab56e42018-07-12 17:12:33 +02002979 * - Set the structure to all-bits-zero, for example:
2980 * \code
Gilles Peskine35675b62019-05-16 17:26:11 +02002981 * psa_key_derivation_operation_t operation;
2982 * memset(&operation, 0, sizeof(operation));
Gilles Peskineeab56e42018-07-12 17:12:33 +02002983 * \endcode
2984 * - Initialize the structure to logical zero values, for example:
2985 * \code
Gilles Peskine35675b62019-05-16 17:26:11 +02002986 * psa_key_derivation_operation_t operation = {0};
Gilles Peskineeab56e42018-07-12 17:12:33 +02002987 * \endcode
Gilles Peskinea99d3fb2019-05-16 15:28:51 +02002988 * - Initialize the structure to the initializer #PSA_KEY_DERIVATION_OPERATION_INIT,
Gilles Peskineeab56e42018-07-12 17:12:33 +02002989 * for example:
2990 * \code
Gilles Peskine35675b62019-05-16 17:26:11 +02002991 * psa_key_derivation_operation_t operation = PSA_KEY_DERIVATION_OPERATION_INIT;
Gilles Peskineeab56e42018-07-12 17:12:33 +02002992 * \endcode
Gilles Peskinea99d3fb2019-05-16 15:28:51 +02002993 * - Assign the result of the function psa_key_derivation_operation_init()
Gilles Peskineeab56e42018-07-12 17:12:33 +02002994 * to the structure, for example:
2995 * \code
Gilles Peskine35675b62019-05-16 17:26:11 +02002996 * psa_key_derivation_operation_t operation;
2997 * operation = psa_key_derivation_operation_init();
Gilles Peskineeab56e42018-07-12 17:12:33 +02002998 * \endcode
2999 *
3000 * This is an implementation-defined \c struct. Applications should not
3001 * make any assumptions about the content of this structure except
3002 * as directed by the documentation of a specific implementation.
3003 */
Gilles Peskinecbe66502019-05-16 16:59:18 +02003004typedef struct psa_key_derivation_s psa_key_derivation_operation_t;
Gilles Peskineeab56e42018-07-12 17:12:33 +02003005
Gilles Peskinea99d3fb2019-05-16 15:28:51 +02003006/** \def PSA_KEY_DERIVATION_OPERATION_INIT
Gilles Peskineeab56e42018-07-12 17:12:33 +02003007 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003008 * This macro returns a suitable initializer for a key derivation operation
3009 * object of type #psa_key_derivation_operation_t.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003010 */
3011#ifdef __DOXYGEN_ONLY__
3012/* This is an example definition for documentation purposes.
3013 * Implementations should define a suitable value in `crypto_struct.h`.
3014 */
Gilles Peskinea99d3fb2019-05-16 15:28:51 +02003015#define PSA_KEY_DERIVATION_OPERATION_INIT {0}
Gilles Peskineeab56e42018-07-12 17:12:33 +02003016#endif
3017
Gilles Peskine35675b62019-05-16 17:26:11 +02003018/** Return an initial value for a key derivation operation object.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003019 */
Gilles Peskinea99d3fb2019-05-16 15:28:51 +02003020static psa_key_derivation_operation_t psa_key_derivation_operation_init(void);
Gilles Peskineeab56e42018-07-12 17:12:33 +02003021
Gilles Peskine1cb9a082019-05-16 17:56:47 +02003022/** Set up a key derivation operation.
3023 *
3024 * A key derivation algorithm takes some inputs and uses them to generate
3025 * a byte stream in a deterministic way.
3026 * This byte stream can be used to produce keys and other
3027 * cryptographic material.
3028 *
3029 * To derive a key:
3030 * - Start with an initialized object of type #psa_key_derivation_operation_t.
3031 * - Call psa_key_derivation_setup() to select the algorithm.
3032 * - Provide the inputs for the key derivation by calling
3033 * psa_key_derivation_input_bytes() or psa_key_derivation_input_key()
3034 * as appropriate. Which inputs are needed, in what order, and whether
3035 * they may be keys and if so of what type depends on the algorithm.
3036 * - Optionally set the operation's maximum capacity with
3037 * psa_key_derivation_set_capacity(). You may do this before, in the middle
3038 * of or after providing inputs. For some algorithms, this step is mandatory
3039 * because the output depends on the maximum capacity.
3040 * - To derive a key, call psa_key_derivation_output_key().
3041 * To derive a byte string for a different purpose, call
3042 * - psa_key_derivation_output_bytes().
3043 * Successive calls to these functions use successive output bytes
3044 * calculated by the key derivation algorithm.
3045 * - Clean up the key derivation operation object with
3046 * psa_key_derivation_abort().
3047 *
3048 * \param[in,out] operation The key derivation operation object
3049 * to set up. It must
3050 * have been initialized but not set up yet.
3051 * \param alg The key derivation algorithm to compute
3052 * (\c PSA_ALG_XXX value such that
3053 * #PSA_ALG_IS_KEY_DERIVATION(\p alg) is true).
3054 *
3055 * \retval #PSA_SUCCESS
3056 * Success.
3057 * \retval #PSA_ERROR_INVALID_ARGUMENT
3058 * \c alg is not a key derivation algorithm.
3059 * \retval #PSA_ERROR_NOT_SUPPORTED
3060 * \c alg is not supported or is not a key derivation algorithm.
3061 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3062 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3063 * \retval #PSA_ERROR_HARDWARE_FAILURE
3064 * \retval #PSA_ERROR_TAMPERING_DETECTED
3065 * \retval #PSA_ERROR_BAD_STATE
3066 */
3067psa_status_t psa_key_derivation_setup(
3068 psa_key_derivation_operation_t *operation,
3069 psa_algorithm_t alg);
3070
Gilles Peskine35675b62019-05-16 17:26:11 +02003071/** Retrieve the current capacity of a key derivation operation.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003072 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003073 * The capacity of a key derivation is the maximum number of bytes that it can
3074 * return. When you get *N* bytes of output from a key derivation operation,
3075 * this reduces its capacity by *N*.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003076 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003077 * \param[in] operation The operation to query.
3078 * \param[out] capacity On success, the capacity of the operation.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003079 *
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003080 * \retval #PSA_SUCCESS
3081 * \retval #PSA_ERROR_BAD_STATE
3082 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
Gilles Peskineeab56e42018-07-12 17:12:33 +02003083 */
Gilles Peskinecf7292e2019-05-16 17:53:40 +02003084psa_status_t psa_key_derivation_get_capacity(
3085 const psa_key_derivation_operation_t *operation,
3086 size_t *capacity);
Gilles Peskineeab56e42018-07-12 17:12:33 +02003087
Gilles Peskine35675b62019-05-16 17:26:11 +02003088/** Set the maximum capacity of a key derivation operation.
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01003089 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003090 * The capacity of a key derivation operation is the maximum number of bytes
3091 * that the key derivation operation can return from this point onwards.
3092 *
3093 * \param[in,out] operation The key derivation operation object to modify.
3094 * \param capacity The new capacity of the operation.
3095 * It must be less or equal to the operation's
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01003096 * current capacity.
3097 *
3098 * \retval #PSA_SUCCESS
3099 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine35675b62019-05-16 17:26:11 +02003100 * \p capacity is larger than the operation's current capacity.
3101 * In this case, the operation object remains valid and its capacity
3102 * remains unchanged.
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01003103 * \retval #PSA_ERROR_BAD_STATE
3104 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3105 */
Gilles Peskinecf7292e2019-05-16 17:53:40 +02003106psa_status_t psa_key_derivation_set_capacity(
3107 psa_key_derivation_operation_t *operation,
3108 size_t capacity);
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01003109
Gilles Peskine1cb9a082019-05-16 17:56:47 +02003110/** Use the maximum possible capacity for a key derivation operation.
3111 *
3112 * Use this value as the capacity argument when setting up a key derivation
3113 * to indicate that the operation should have the maximum possible capacity.
3114 * The value of the maximum possible capacity depends on the key derivation
3115 * algorithm.
3116 */
3117#define PSA_KEY_DERIVATION_UNLIMITED_CAPACITY ((size_t)(-1))
3118
3119/** Provide an input for key derivation or key agreement.
3120 *
3121 * Which inputs are required and in what order depends on the algorithm.
3122 * Refer to the documentation of each key derivation or key agreement
3123 * algorithm for information.
3124 *
3125 * This function passes direct inputs. Some inputs must be passed as keys
3126 * using psa_key_derivation_input_key() instead of this function. Refer to
3127 * the documentation of individual step types for information.
3128 *
3129 * \param[in,out] operation The key derivation operation object to use.
3130 * It must have been set up with
3131 * psa_key_derivation_setup() and must not
3132 * have produced any output yet.
3133 * \param step Which step the input data is for.
3134 * \param[in] data Input data to use.
3135 * \param data_length Size of the \p data buffer in bytes.
3136 *
3137 * \retval #PSA_SUCCESS
3138 * Success.
3139 * \retval #PSA_ERROR_INVALID_ARGUMENT
3140 * \c step is not compatible with the operation's algorithm.
3141 * \retval #PSA_ERROR_INVALID_ARGUMENT
3142 * \c step does not allow direct inputs.
3143 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3144 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3145 * \retval #PSA_ERROR_HARDWARE_FAILURE
3146 * \retval #PSA_ERROR_TAMPERING_DETECTED
3147 * \retval #PSA_ERROR_BAD_STATE
3148 * The value of \p step is not valid given the state of \p operation.
3149 * \retval #PSA_ERROR_BAD_STATE
3150 * The library has not been previously initialized by psa_crypto_init().
3151 * It is implementation-dependent whether a failure to initialize
3152 * results in this error code.
3153 */
3154psa_status_t psa_key_derivation_input_bytes(
3155 psa_key_derivation_operation_t *operation,
3156 psa_key_derivation_step_t step,
3157 const uint8_t *data,
3158 size_t data_length);
3159
3160/** Provide an input for key derivation in the form of a key.
3161 *
3162 * Which inputs are required and in what order depends on the algorithm.
3163 * Refer to the documentation of each key derivation or key agreement
3164 * algorithm for information.
3165 *
3166 * This function passes key inputs. Some inputs must be passed as keys
3167 * of the appropriate type using this function, while others must be
3168 * passed as direct inputs using psa_key_derivation_input_bytes(). Refer to
3169 * the documentation of individual step types for information.
3170 *
3171 * \param[in,out] operation The key derivation operation object to use.
3172 * It must have been set up with
3173 * psa_key_derivation_setup() and must not
3174 * have produced any output yet.
3175 * \param step Which step the input data is for.
3176 * \param handle Handle to the key. It must have an
3177 * appropriate type for \p step and must
3178 * allow the usage #PSA_KEY_USAGE_DERIVE.
3179 *
3180 * \retval #PSA_SUCCESS
3181 * Success.
3182 * \retval #PSA_ERROR_INVALID_HANDLE
3183 * \retval #PSA_ERROR_DOES_NOT_EXIST
3184 * \retval #PSA_ERROR_NOT_PERMITTED
3185 * \retval #PSA_ERROR_INVALID_ARGUMENT
3186 * \c step is not compatible with the operation's algorithm.
3187 * \retval #PSA_ERROR_INVALID_ARGUMENT
3188 * \c step does not allow key inputs.
3189 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3190 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3191 * \retval #PSA_ERROR_HARDWARE_FAILURE
3192 * \retval #PSA_ERROR_TAMPERING_DETECTED
3193 * \retval #PSA_ERROR_BAD_STATE
3194 * The value of \p step is not valid given the state of \p operation.
3195 * \retval #PSA_ERROR_BAD_STATE
3196 * The library has not been previously initialized by psa_crypto_init().
3197 * It is implementation-dependent whether a failure to initialize
3198 * results in this error code.
3199 */
3200psa_status_t psa_key_derivation_input_key(
3201 psa_key_derivation_operation_t *operation,
3202 psa_key_derivation_step_t step,
3203 psa_key_handle_t handle);
3204
3205/** Perform a key agreement and use the shared secret as input to a key
3206 * derivation.
3207 *
3208 * A key agreement algorithm takes two inputs: a private key \p private_key
3209 * a public key \p peer_key.
3210 * The result of this function is passed as input to a key derivation.
3211 * The output of this key derivation can be extracted by reading from the
3212 * resulting operation to produce keys and other cryptographic material.
3213 *
3214 * \param[in,out] operation The key derivation operation object to use.
3215 * It must have been set up with
3216 * psa_key_derivation_setup() with a
3217 * key agreement and derivation algorithm
3218 * \c alg (\c PSA_ALG_XXX value such that
3219 * #PSA_ALG_IS_KEY_AGREEMENT(\c alg) is true
3220 * and #PSA_ALG_IS_RAW_KEY_AGREEMENT(\c alg)
3221 * is false).
3222 * The operation must be ready for an
3223 * input of the type given by \p step.
3224 * \param step Which step the input data is for.
3225 * \param private_key Handle to the private key to use.
3226 * \param[in] peer_key Public key of the peer. The peer key must be in the
3227 * same format that psa_import_key() accepts for the
3228 * public key type corresponding to the type of
3229 * private_key. That is, this function performs the
3230 * equivalent of
3231 * #psa_import_key(...,
3232 * `peer_key`, `peer_key_length`) where
3233 * with key attributes indicating the public key
3234 * type corresponding to the type of `private_key`.
3235 * For example, for EC keys, this means that peer_key
3236 * is interpreted as a point on the curve that the
3237 * private key is on. The standard formats for public
3238 * keys are documented in the documentation of
3239 * psa_export_public_key().
3240 * \param peer_key_length Size of \p peer_key in bytes.
3241 *
3242 * \retval #PSA_SUCCESS
3243 * Success.
3244 * \retval #PSA_ERROR_INVALID_HANDLE
3245 * \retval #PSA_ERROR_DOES_NOT_EXIST
3246 * \retval #PSA_ERROR_NOT_PERMITTED
3247 * \retval #PSA_ERROR_INVALID_ARGUMENT
3248 * \c private_key is not compatible with \c alg,
3249 * or \p peer_key is not valid for \c alg or not compatible with
3250 * \c private_key.
3251 * \retval #PSA_ERROR_NOT_SUPPORTED
3252 * \c alg is not supported or is not a key derivation algorithm.
3253 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3254 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3255 * \retval #PSA_ERROR_HARDWARE_FAILURE
3256 * \retval #PSA_ERROR_TAMPERING_DETECTED
3257 */
3258psa_status_t psa_key_derivation_key_agreement(
3259 psa_key_derivation_operation_t *operation,
3260 psa_key_derivation_step_t step,
3261 psa_key_handle_t private_key,
3262 const uint8_t *peer_key,
3263 size_t peer_key_length);
3264
Gilles Peskine35675b62019-05-16 17:26:11 +02003265/** Read some data from a key derivation operation.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003266 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003267 * This function calculates output bytes from a key derivation algorithm and
3268 * return those bytes.
3269 * If you view the key derivation's output as a stream of bytes, this
3270 * function destructively reads the requested number of bytes from the
3271 * stream.
3272 * The operation's capacity decreases by the number of bytes read.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003273 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003274 * \param[in,out] operation The key derivation operation object to read from.
3275 * \param[out] output Buffer where the output will be written.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003276 * \param output_length Number of bytes to output.
3277 *
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003278 * \retval #PSA_SUCCESS
David Saadab4ecc272019-02-14 13:48:10 +02003279 * \retval #PSA_ERROR_INSUFFICIENT_DATA
Gilles Peskine35675b62019-05-16 17:26:11 +02003280 * The operation's capacity was less than
3281 * \p output_length bytes. Note that in this case,
3282 * no output is written to the output buffer.
3283 * The operation's capacity is set to 0, thus
Gilles Peskineeab56e42018-07-12 17:12:33 +02003284 * subsequent calls to this function will not
3285 * succeed, even with a smaller output buffer.
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003286 * \retval #PSA_ERROR_BAD_STATE
3287 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3288 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3289 * \retval #PSA_ERROR_HARDWARE_FAILURE
3290 * \retval #PSA_ERROR_TAMPERING_DETECTED
Gilles Peskineeab56e42018-07-12 17:12:33 +02003291 */
Gilles Peskinecf7292e2019-05-16 17:53:40 +02003292psa_status_t psa_key_derivation_output_bytes(
3293 psa_key_derivation_operation_t *operation,
3294 uint8_t *output,
3295 size_t output_length);
Gilles Peskineeab56e42018-07-12 17:12:33 +02003296
Gilles Peskine35675b62019-05-16 17:26:11 +02003297/** Derive a key from an ongoing key derivation operation.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003298 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003299 * This function calculates output bytes from a key derivation algorithm
3300 * and uses those bytes to generate a key deterministically.
3301 * If you view the key derivation's output as a stream of bytes, this
3302 * function destructively reads as many bytes as required from the
3303 * stream.
3304 * The operation's capacity decreases by the number of bytes read.
3305 *
3306 * How much output is produced and consumed from the operation, and how
3307 * the key is derived, depends on the key type:
Gilles Peskineeab56e42018-07-12 17:12:33 +02003308 *
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003309 * - For key types for which the key is an arbitrary sequence of bytes
Gilles Peskinecf7292e2019-05-16 17:53:40 +02003310 * of a given size, this function is functionally equivalent to
3311 * calling #psa_key_derivation_output_bytes
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003312 * and passing the resulting output to #psa_import_key.
3313 * However, this function has a security benefit:
3314 * if the implementation provides an isolation boundary then
3315 * the key material is not exposed outside the isolation boundary.
3316 * As a consequence, for these key types, this function always consumes
Gilles Peskine35675b62019-05-16 17:26:11 +02003317 * exactly (\p bits / 8) bytes from the operation.
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003318 * The following key types defined in this specification follow this scheme:
3319 *
3320 * - #PSA_KEY_TYPE_AES;
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003321 * - #PSA_KEY_TYPE_ARC4;
3322 * - #PSA_KEY_TYPE_CAMELLIA;
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003323 * - #PSA_KEY_TYPE_DERIVE;
3324 * - #PSA_KEY_TYPE_HMAC.
3325 *
3326 * - For ECC keys on a Montgomery elliptic curve
3327 * (#PSA_KEY_TYPE_ECC_KEYPAIR(\c curve) where \c curve designates a
3328 * Montgomery curve), this function always draws a byte string whose
3329 * length is determined by the curve, and sets the mandatory bits
3330 * accordingly. That is:
3331 *
3332 * - #PSA_ECC_CURVE_CURVE25519: draw a 32-byte string
3333 * and process it as specified in RFC 7748 &sect;5.
3334 * - #PSA_ECC_CURVE_CURVE448: draw a 56-byte string
3335 * and process it as specified in RFC 7748 &sect;5.
3336 *
3337 * - For key types for which the key is represented by a single sequence of
3338 * \p bits bits with constraints as to which bit sequences are acceptable,
3339 * this function draws a byte string of length (\p bits / 8) bytes rounded
3340 * up to the nearest whole number of bytes. If the resulting byte string
3341 * is acceptable, it becomes the key, otherwise the drawn bytes are discarded.
3342 * This process is repeated until an acceptable byte string is drawn.
Gilles Peskine35675b62019-05-16 17:26:11 +02003343 * The byte string drawn from the operation is interpreted as specified
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003344 * for the output produced by psa_export_key().
3345 * The following key types defined in this specification follow this scheme:
3346 *
Gilles Peskine2de2c0d2019-03-11 17:59:16 +01003347 * - #PSA_KEY_TYPE_DES.
3348 * Force-set the parity bits, but discard forbidden weak keys.
3349 * For 2-key and 3-key triple-DES, the three keys are generated
3350 * successively (for example, for 3-key triple-DES,
3351 * if the first 8 bytes specify a weak key and the next 8 bytes do not,
3352 * discard the first 8 bytes, use the next 8 bytes as the first key,
Gilles Peskine35675b62019-05-16 17:26:11 +02003353 * and continue reading output from the operation to derive the other
Gilles Peskine2de2c0d2019-03-11 17:59:16 +01003354 * two keys).
3355 * - Finite-field Diffie-Hellman keys (#PSA_KEY_TYPE_DH_KEYPAIR),
3356 * DSA keys (#PSA_KEY_TYPE_DSA_KEYPAIR), and
3357 * ECC keys on a Weierstrass elliptic curve
3358 * (#PSA_KEY_TYPE_ECC_KEYPAIR(\c curve) where \c curve designates a
3359 * Weierstrass curve).
3360 * For these key types, interpret the byte string as integer
3361 * in big-endian order. Discard it if it is not in the range
3362 * [0, *N* - 2] where *N* is the boundary of the private key domain
3363 * (the prime *p* for Diffie-Hellman, the subprime *q* for DSA,
Gilles Peskine55799712019-03-12 11:50:26 +01003364 * or the order of the curve's base point for ECC).
Gilles Peskine2de2c0d2019-03-11 17:59:16 +01003365 * Add 1 to the resulting integer and use this as the private key *x*.
Gilles Peskine55799712019-03-12 11:50:26 +01003366 * This method allows compliance to NIST standards, specifically
3367 * the methods titled "key-pair generation by testing candidates"
Gilles Peskine2de2c0d2019-03-11 17:59:16 +01003368 * in NIST SP 800-56A &sect;5.6.1.1.4 for Diffie-Hellman,
3369 * in FIPS 186-4 &sect;B.1.2 for DSA, and
3370 * in NIST SP 800-56A &sect;5.6.1.2.2 or
3371 * FIPS 186-4 &sect;B.4.2 for elliptic curve keys.
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003372 *
3373 * - For other key types, including #PSA_KEY_TYPE_RSA_KEYPAIR,
Gilles Peskine35675b62019-05-16 17:26:11 +02003374 * the way in which the operation output is consumed is
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003375 * implementation-defined.
3376 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003377 * In all cases, the data that is read is discarded from the operation.
3378 * The operation's capacity is decreased by the number of bytes read.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003379 *
Gilles Peskine20628592019-04-19 19:29:50 +02003380 * \param[in] attributes The attributes for the new key.
Gilles Peskine35675b62019-05-16 17:26:11 +02003381 * \param[in,out] operation The key derivation operation object to read from.
Gilles Peskine20628592019-04-19 19:29:50 +02003382 * \param[out] handle On success, a handle to the newly created key.
3383 * \c 0 on failure.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003384 *
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003385 * \retval #PSA_SUCCESS
Gilles Peskineeab56e42018-07-12 17:12:33 +02003386 * Success.
Gilles Peskine23fd2bd2018-12-11 15:51:32 +01003387 * If the key is persistent, the key material and the key's metadata
3388 * have been saved to persistent storage.
Gilles Peskine20628592019-04-19 19:29:50 +02003389 * \retval #PSA_ERROR_ALREADY_EXISTS
3390 * This is an attempt to create a persistent key, and there is
3391 * already a persistent key with the given identifier.
David Saadab4ecc272019-02-14 13:48:10 +02003392 * \retval #PSA_ERROR_INSUFFICIENT_DATA
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003393 * There was not enough data to create the desired key.
3394 * Note that in this case, no output is written to the output buffer.
Gilles Peskine35675b62019-05-16 17:26:11 +02003395 * The operation's capacity is set to 0, thus subsequent calls to
Gilles Peskinefa4486d2019-03-11 17:30:31 +01003396 * this function will not succeed, even with a smaller output buffer.
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003397 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskineeab56e42018-07-12 17:12:33 +02003398 * The key type or key size is not supported, either by the
Adrian L. Shaw67e1c7a2019-05-14 15:24:21 +01003399 * implementation in general or in this particular location.
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003400 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003401 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3402 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
3403 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3404 * \retval #PSA_ERROR_HARDWARE_FAILURE
3405 * \retval #PSA_ERROR_TAMPERING_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03003406 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03003407 * The library has not been previously initialized by psa_crypto_init().
3408 * It is implementation-dependent whether a failure to initialize
3409 * results in this error code.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003410 */
Gilles Peskinecf7292e2019-05-16 17:53:40 +02003411psa_status_t psa_key_derivation_output_key(
3412 const psa_key_attributes_t *attributes,
3413 psa_key_derivation_operation_t *operation,
3414 psa_key_handle_t *handle);
Gilles Peskineeab56e42018-07-12 17:12:33 +02003415
Gilles Peskine35675b62019-05-16 17:26:11 +02003416/** Abort a key derivation operation.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003417 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003418 * Once a key derivation operation has been aborted, its capacity is zero.
3419 * Aborting an operation frees all associated resources except for the
3420 * \c operation structure itself.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003421 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003422 * This function may be called at any time as long as the operation
Gilles Peskinea99d3fb2019-05-16 15:28:51 +02003423 * object has been initialized to #PSA_KEY_DERIVATION_OPERATION_INIT, to
Gilles Peskinecf7292e2019-05-16 17:53:40 +02003424 * psa_key_derivation_operation_init() or a zero value. In particular,
3425 * it is valid to call psa_key_derivation_abort() twice, or to call
3426 * psa_key_derivation_abort() on an operation that has not been set up.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003427 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003428 * Once aborted, the key derivation operation object may be called.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003429 *
Gilles Peskine35675b62019-05-16 17:26:11 +02003430 * \param[in,out] operation The operation to abort.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003431 *
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003432 * \retval #PSA_SUCCESS
3433 * \retval #PSA_ERROR_BAD_STATE
3434 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3435 * \retval #PSA_ERROR_HARDWARE_FAILURE
3436 * \retval #PSA_ERROR_TAMPERING_DETECTED
Gilles Peskineeab56e42018-07-12 17:12:33 +02003437 */
Gilles Peskinecf7292e2019-05-16 17:53:40 +02003438psa_status_t psa_key_derivation_abort(
3439 psa_key_derivation_operation_t *operation);
Gilles Peskineeab56e42018-07-12 17:12:33 +02003440
Gilles Peskine58fe9e82019-05-16 18:01:45 +02003441/** Perform a key agreement and return the raw shared secret.
Gilles Peskine769c7a62019-01-18 16:42:29 +01003442 *
3443 * \warning The raw result of a key agreement algorithm such as finite-field
3444 * Diffie-Hellman or elliptic curve Diffie-Hellman has biases and should
3445 * not be used directly as key material. It should instead be passed as
3446 * input to a key derivation algorithm. To chain a key agreement with
Gilles Peskinecf7292e2019-05-16 17:53:40 +02003447 * a key derivation, use psa_key_derivation_key_agreement() and other
3448 * functions from the key derivation interface.
Gilles Peskine769c7a62019-01-18 16:42:29 +01003449 *
Gilles Peskine47e79fb2019-02-08 11:24:59 +01003450 * \param alg The key agreement algorithm to compute
3451 * (\c PSA_ALG_XXX value such that
3452 * #PSA_ALG_IS_RAW_KEY_AGREEMENT(\p alg)
3453 * is true).
Gilles Peskine769c7a62019-01-18 16:42:29 +01003454 * \param private_key Handle to the private key to use.
3455 * \param[in] peer_key Public key of the peer. It must be
3456 * in the same format that psa_import_key()
3457 * accepts. The standard formats for public
3458 * keys are documented in the documentation
3459 * of psa_export_public_key().
3460 * \param peer_key_length Size of \p peer_key in bytes.
3461 * \param[out] output Buffer where the decrypted message is to
3462 * be written.
3463 * \param output_size Size of the \c output buffer in bytes.
3464 * \param[out] output_length On success, the number of bytes
3465 * that make up the returned output.
3466 *
3467 * \retval #PSA_SUCCESS
3468 * Success.
3469 * \retval #PSA_ERROR_INVALID_HANDLE
3470 * \retval #PSA_ERROR_EMPTY_SLOT
3471 * \retval #PSA_ERROR_NOT_PERMITTED
3472 * \retval #PSA_ERROR_INVALID_ARGUMENT
3473 * \p alg is not a key agreement algorithm
3474 * \retval #PSA_ERROR_INVALID_ARGUMENT
3475 * \p private_key is not compatible with \p alg,
3476 * or \p peer_key is not valid for \p alg or not compatible with
3477 * \p private_key.
3478 * \retval #PSA_ERROR_NOT_SUPPORTED
3479 * \p alg is not a supported key agreement algorithm.
3480 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3481 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3482 * \retval #PSA_ERROR_HARDWARE_FAILURE
3483 * \retval #PSA_ERROR_TAMPERING_DETECTED
3484 */
Gilles Peskinebe697d82019-05-16 18:00:41 +02003485psa_status_t psa_raw_key_agreement(psa_algorithm_t alg,
3486 psa_key_handle_t private_key,
3487 const uint8_t *peer_key,
3488 size_t peer_key_length,
3489 uint8_t *output,
3490 size_t output_size,
3491 size_t *output_length);
Gilles Peskine01d718c2018-09-18 12:01:02 +02003492
Gilles Peskineea0fb492018-07-12 17:17:20 +02003493/**@}*/
3494
Gilles Peskineedd76872018-07-20 17:42:05 +02003495/** \defgroup random Random generation
Gilles Peskine9e7dc712018-03-28 14:18:50 +02003496 * @{
3497 */
3498
3499/**
3500 * \brief Generate random bytes.
3501 *
3502 * \warning This function **can** fail! Callers MUST check the return status
3503 * and MUST NOT use the content of the output buffer if the return
3504 * status is not #PSA_SUCCESS.
3505 *
Adrian L. Shaw5a5a79a2019-05-03 15:44:28 +01003506 * \note To generate a key, use psa_generate_random_key() instead.
Gilles Peskine9e7dc712018-03-28 14:18:50 +02003507 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02003508 * \param[out] output Output buffer for the generated data.
Gilles Peskine9e7dc712018-03-28 14:18:50 +02003509 * \param output_size Number of bytes to generate and output.
3510 *
Gilles Peskine28538492018-07-11 17:34:00 +02003511 * \retval #PSA_SUCCESS
3512 * \retval #PSA_ERROR_NOT_SUPPORTED
3513 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
3514 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3515 * \retval #PSA_ERROR_HARDWARE_FAILURE
3516 * \retval #PSA_ERROR_TAMPERING_DETECTED
itayzafrir0adf0fc2018-09-06 16:24:41 +03003517 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03003518 * The library has not been previously initialized by psa_crypto_init().
3519 * It is implementation-dependent whether a failure to initialize
3520 * results in this error code.
Gilles Peskine9e7dc712018-03-28 14:18:50 +02003521 */
3522psa_status_t psa_generate_random(uint8_t *output,
3523 size_t output_size);
3524
3525/**
3526 * \brief Generate a key or key pair.
3527 *
Gilles Peskinee56e8782019-04-26 17:34:02 +02003528 * The key is generated randomly.
3529 * Its location, policy, type and size are taken from \p attributes.
3530 *
3531 * If the type requires additional domain parameters, these are taken
3532 * from \p attributes as well. The following types use domain parameters:
3533 * - When generating an RSA key (#PSA_KEY_TYPE_RSA_KEYPAIR),
3534 * the default public exponent is 65537. This value is used if
3535 * \p attributes was set with psa_set_key_type() or by passing an empty
3536 * byte string as domain parameters to psa_set_key_domain_parameters().
3537 * If psa_set_key_domain_parameters() was used to set a non-empty
3538 * domain parameter string in \p attributes, this string is read as
3539 * a big-endian integer which is used as the public exponent.
3540 * - When generating a DSA key (#PSA_KEY_TYPE_DSA_KEYPAIR) or a
3541 * Diffie-Hellman key (#PSA_KEY_TYPE_DH_KEYPAIR), the domain parameters
3542 * from \p attributes are interpreted as described for
3543 * psa_set_key_domain_parameters().
3544 *
Gilles Peskine20628592019-04-19 19:29:50 +02003545 * \param[in] attributes The attributes for the new key.
Gilles Peskine20628592019-04-19 19:29:50 +02003546 * \param[out] handle On success, a handle to the newly created key.
3547 * \c 0 on failure.
Gilles Peskine9e7dc712018-03-28 14:18:50 +02003548 *
Gilles Peskine28538492018-07-11 17:34:00 +02003549 * \retval #PSA_SUCCESS
Gilles Peskine23fd2bd2018-12-11 15:51:32 +01003550 * Success.
3551 * If the key is persistent, the key material and the key's metadata
3552 * have been saved to persistent storage.
David Saadab4ecc272019-02-14 13:48:10 +02003553 * \retval #PSA_ERROR_ALREADY_EXISTS
Gilles Peskine20628592019-04-19 19:29:50 +02003554 * This is an attempt to create a persistent key, and there is
3555 * already a persistent key with the given identifier.
Gilles Peskine28538492018-07-11 17:34:00 +02003556 * \retval #PSA_ERROR_NOT_SUPPORTED
3557 * \retval #PSA_ERROR_INVALID_ARGUMENT
3558 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3559 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
3560 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3561 * \retval #PSA_ERROR_HARDWARE_FAILURE
3562 * \retval #PSA_ERROR_TAMPERING_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03003563 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03003564 * The library has not been previously initialized by psa_crypto_init().
3565 * It is implementation-dependent whether a failure to initialize
3566 * results in this error code.
Gilles Peskine9e7dc712018-03-28 14:18:50 +02003567 */
Adrian L. Shaw5a5a79a2019-05-03 15:44:28 +01003568psa_status_t psa_generate_random_key(const psa_key_attributes_t *attributes,
Gilles Peskinee56e8782019-04-26 17:34:02 +02003569 psa_key_handle_t *handle);
Gilles Peskine9e7dc712018-03-28 14:18:50 +02003570
3571/**@}*/
3572
Gilles Peskinee59236f2018-01-27 23:32:46 +01003573#ifdef __cplusplus
3574}
3575#endif
3576
Gilles Peskine0cad07c2018-06-27 19:49:02 +02003577/* The file "crypto_sizes.h" contains definitions for size calculation
3578 * macros whose definitions are implementation-specific. */
3579#include "crypto_sizes.h"
3580
Gilles Peskine9ef733f2018-02-07 21:05:37 +01003581/* The file "crypto_struct.h" contains definitions for
3582 * implementation-specific structs that are declared above. */
3583#include "crypto_struct.h"
3584
3585/* The file "crypto_extra.h" contains vendor-specific definitions. This
3586 * can include vendor-defined algorithms, extra functions, etc. */
Gilles Peskinee59236f2018-01-27 23:32:46 +01003587#include "crypto_extra.h"
3588
3589#endif /* PSA_CRYPTO_H */