blob: 6a7bce8800f924aee7a2d59cf753c32f0fa87d1d [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 Peskine4cb9dde2019-01-19 13:40:11 +010096/** \defgroup policy Key policies
97 * @{
98 */
99
100/** The type of the key policy data structure.
101 *
102 * Before calling any function on a key policy, the application must initialize
103 * it by any of the following means:
104 * - Set the structure to all-bits-zero, for example:
105 * \code
106 * psa_key_policy_t policy;
107 * memset(&policy, 0, sizeof(policy));
108 * \endcode
109 * - Initialize the structure to logical zero values, for example:
110 * \code
111 * psa_key_policy_t policy = {0};
112 * \endcode
113 * - Initialize the structure to the initializer #PSA_KEY_POLICY_INIT,
114 * for example:
115 * \code
116 * psa_key_policy_t policy = PSA_KEY_POLICY_INIT;
117 * \endcode
118 * - Assign the result of the function psa_key_policy_init()
119 * to the structure, for example:
120 * \code
121 * psa_key_policy_t policy;
122 * policy = psa_key_policy_init();
123 * \endcode
124 *
125 * This is an implementation-defined \c struct. Applications should not
126 * make any assumptions about the content of this structure except
127 * as directed by the documentation of a specific implementation. */
128typedef struct psa_key_policy_s psa_key_policy_t;
129
130/** \def PSA_KEY_POLICY_INIT
131 *
132 * This macro returns a suitable initializer for a key policy object of type
133 * #psa_key_policy_t.
134 */
135#ifdef __DOXYGEN_ONLY__
136/* This is an example definition for documentation purposes.
137 * Implementations should define a suitable value in `crypto_struct.h`.
138 */
139#define PSA_KEY_POLICY_INIT {0}
140#endif
141
142/** Return an initial value for a key policy that forbids all usage of the key.
143 */
144static psa_key_policy_t psa_key_policy_init(void);
145
146/** \brief Set the standard fields of a policy structure.
147 *
148 * Note that this function does not make any consistency check of the
149 * parameters. The values are only checked when applying the policy to
150 * a key slot with psa_set_key_policy().
151 *
152 * \param[in,out] policy The key policy to modify. It must have been
153 * initialized as per the documentation for
154 * #psa_key_policy_t.
155 * \param usage The permitted uses for the key.
156 * \param alg The algorithm that the key may be used for.
157 */
158void psa_key_policy_set_usage(psa_key_policy_t *policy,
159 psa_key_usage_t usage,
160 psa_algorithm_t alg);
161
162/** \brief Retrieve the usage field of a policy structure.
163 *
164 * \param[in] policy The policy object to query.
165 *
166 * \return The permitted uses for a key with this policy.
167 */
168psa_key_usage_t psa_key_policy_get_usage(const psa_key_policy_t *policy);
169
170/** \brief Retrieve the algorithm field of a policy structure.
171 *
172 * \param[in] policy The policy object to query.
173 *
174 * \return The permitted algorithm for a key with this policy.
175 */
176psa_algorithm_t psa_key_policy_get_algorithm(const psa_key_policy_t *policy);
177
178/** \brief Set the usage policy on a key slot.
179 *
180 * This function must be called on an empty key slot, before importing,
181 * generating or creating a key in the slot. Changing the policy of an
182 * existing key is not permitted.
183 *
184 * Implementations may set restrictions on supported key policies
185 * depending on the key type and the key slot.
186 *
187 * \param handle Handle to the key whose policy is to be changed.
188 * \param[in] policy The policy object to query.
189 *
190 * \retval #PSA_SUCCESS
191 * Success.
192 * If the key is persistent, it is implementation-defined whether
193 * the policy has been saved to persistent storage. Implementations
194 * may defer saving the policy until the key material is created.
195 * \retval #PSA_ERROR_INVALID_HANDLE
David Saadab4ecc272019-02-14 13:48:10 +0200196 * \retval #PSA_ERROR_ALREADY_EXISTS
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100197 * \retval #PSA_ERROR_NOT_SUPPORTED
198 * \retval #PSA_ERROR_INVALID_ARGUMENT
199 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
200 * \retval #PSA_ERROR_HARDWARE_FAILURE
201 * \retval #PSA_ERROR_TAMPERING_DETECTED
202 * \retval #PSA_ERROR_BAD_STATE
203 * The library has not been previously initialized by psa_crypto_init().
204 * It is implementation-dependent whether a failure to initialize
205 * results in this error code.
206 */
207psa_status_t psa_set_key_policy(psa_key_handle_t handle,
208 const psa_key_policy_t *policy);
209
210/** \brief Get the usage policy for a key slot.
211 *
212 * \param handle Handle to the key slot whose policy is being queried.
213 * \param[out] policy On success, the key's policy.
214 *
215 * \retval #PSA_SUCCESS
216 * \retval #PSA_ERROR_INVALID_HANDLE
217 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
218 * \retval #PSA_ERROR_HARDWARE_FAILURE
219 * \retval #PSA_ERROR_TAMPERING_DETECTED
220 * \retval #PSA_ERROR_BAD_STATE
221 * The library has not been previously initialized by psa_crypto_init().
222 * It is implementation-dependent whether a failure to initialize
223 * results in this error code.
224 */
225psa_status_t psa_get_key_policy(psa_key_handle_t handle,
226 psa_key_policy_t *policy);
227
228/**@}*/
229
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100230/** \defgroup key_management Key management
231 * @{
232 */
233
Gilles Peskineae32aac2018-11-30 14:39:32 +0100234/** \brief Retrieve the lifetime of an open key.
Gilles Peskine3cac8c42018-11-30 14:07:45 +0100235 *
Gilles Peskineae32aac2018-11-30 14:39:32 +0100236 * \param handle Handle to query.
Gilles Peskine3cac8c42018-11-30 14:07:45 +0100237 * \param[out] lifetime On success, the lifetime value.
238 *
239 * \retval #PSA_SUCCESS
240 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +0100241 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine3cac8c42018-11-30 14:07:45 +0100242 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
243 * \retval #PSA_ERROR_HARDWARE_FAILURE
244 * \retval #PSA_ERROR_TAMPERING_DETECTED
245 * \retval #PSA_ERROR_BAD_STATE
246 * The library has not been previously initialized by psa_crypto_init().
247 * It is implementation-dependent whether a failure to initialize
248 * results in this error code.
249 */
Gilles Peskineae32aac2018-11-30 14:39:32 +0100250psa_status_t psa_get_key_lifetime(psa_key_handle_t handle,
Gilles Peskine3cac8c42018-11-30 14:07:45 +0100251 psa_key_lifetime_t *lifetime);
252
Gilles Peskine3cac8c42018-11-30 14:07:45 +0100253
Gilles Peskinef535eb22018-11-30 14:08:36 +0100254/** Allocate a key slot for a transient key, i.e. a key which is only stored
255 * in volatile memory.
256 *
257 * The allocated key slot and its handle remain valid until the
258 * application calls psa_close_key() or psa_destroy_key() or until the
259 * application terminates.
260 *
Gilles Peskinef535eb22018-11-30 14:08:36 +0100261 * \param[out] handle On success, a handle to a volatile key slot.
262 *
263 * \retval #PSA_SUCCESS
264 * Success. The application can now use the value of `*handle`
265 * to access the newly allocated key slot.
266 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
267 * There was not enough memory, or the maximum number of key slots
268 * has been reached.
Gilles Peskinef535eb22018-11-30 14:08:36 +0100269 */
Gilles Peskined40c1fb2019-01-19 12:20:52 +0100270psa_status_t psa_allocate_key(psa_key_handle_t *handle);
Gilles Peskinef535eb22018-11-30 14:08:36 +0100271
272/** Open a handle to an existing persistent key.
273 *
274 * Open a handle to a key which was previously created with psa_create_key().
275 *
276 * \param lifetime The lifetime of the key. This designates a storage
277 * area where the key material is stored. This must not
278 * be #PSA_KEY_LIFETIME_VOLATILE.
279 * \param id The persistent identifier of the key.
280 * \param[out] handle On success, a handle to a key slot which contains
281 * the data and metadata loaded from the specified
282 * persistent location.
283 *
284 * \retval #PSA_SUCCESS
285 * Success. The application can now use the value of `*handle`
286 * to access the newly allocated key slot.
287 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
David Saadab4ecc272019-02-14 13:48:10 +0200288 * \retval #PSA_ERROR_DOES_NOT_EXIST
Gilles Peskinef535eb22018-11-30 14:08:36 +0100289 * \retval #PSA_ERROR_INVALID_ARGUMENT
290 * \p lifetime is invalid, for example #PSA_KEY_LIFETIME_VOLATILE.
291 * \retval #PSA_ERROR_INVALID_ARGUMENT
292 * \p id is invalid for the specified lifetime.
293 * \retval #PSA_ERROR_NOT_SUPPORTED
294 * \p lifetime is not supported.
295 * \retval #PSA_ERROR_NOT_PERMITTED
296 * The specified key exists, but the application does not have the
297 * permission to access it. Note that this specification does not
298 * define any way to create such a key, but it may be possible
299 * through implementation-specific means.
300 */
301psa_status_t psa_open_key(psa_key_lifetime_t lifetime,
302 psa_key_id_t id,
303 psa_key_handle_t *handle);
304
305/** Create a new persistent key slot.
306 *
307 * Create a new persistent key slot and return a handle to it. The handle
308 * remains valid until the application calls psa_close_key() or terminates.
309 * The application can open the key again with psa_open_key() until it
310 * removes the key by calling psa_destroy_key().
311 *
312 * \param lifetime The lifetime of the key. This designates a storage
313 * area where the key material is stored. This must not
314 * be #PSA_KEY_LIFETIME_VOLATILE.
315 * \param id The persistent identifier of the key.
Gilles Peskinef535eb22018-11-30 14:08:36 +0100316 * \param[out] handle On success, a handle to the newly created key slot.
317 * When key material is later created in this key slot,
318 * it will be saved to the specified persistent location.
319 *
320 * \retval #PSA_SUCCESS
321 * Success. The application can now use the value of `*handle`
322 * to access the newly allocated key slot.
323 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
324 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
David Saadab4ecc272019-02-14 13:48:10 +0200325 * \retval #PSA_ERROR_ALREADY_EXISTS
Gilles Peskinef535eb22018-11-30 14:08:36 +0100326 * There is already a key with the identifier \p id in the storage
327 * area designated by \p lifetime.
328 * \retval #PSA_ERROR_INVALID_ARGUMENT
329 * \p lifetime is invalid, for example #PSA_KEY_LIFETIME_VOLATILE.
330 * \retval #PSA_ERROR_INVALID_ARGUMENT
331 * \p id is invalid for the specified lifetime.
332 * \retval #PSA_ERROR_NOT_SUPPORTED
333 * \p lifetime is not supported.
334 * \retval #PSA_ERROR_NOT_PERMITTED
335 * \p lifetime is valid, but the application does not have the
336 * permission to create a key there.
337 */
338psa_status_t psa_create_key(psa_key_lifetime_t lifetime,
339 psa_key_id_t id,
Gilles Peskinef535eb22018-11-30 14:08:36 +0100340 psa_key_handle_t *handle);
341
342/** Close a key handle.
343 *
344 * If the handle designates a volatile key, destroy the key material and
345 * free all associated resources, just like psa_destroy_key().
346 *
347 * If the handle designates a persistent key, free all resources associated
348 * with the key in volatile memory. The key slot in persistent storage is
349 * not affected and can be opened again later with psa_open_key().
350 *
Gilles Peskine5f25dd02019-01-14 18:24:53 +0100351 * If the key is currently in use in a multipart operation,
352 * the multipart operation is aborted.
353 *
Gilles Peskinef535eb22018-11-30 14:08:36 +0100354 * \param handle The key handle to close.
355 *
356 * \retval #PSA_SUCCESS
357 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskineae32aac2018-11-30 14:39:32 +0100358 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
Gilles Peskinef535eb22018-11-30 14:08:36 +0100359 */
360psa_status_t psa_close_key(psa_key_handle_t handle);
361
Gilles Peskine3cac8c42018-11-30 14:07:45 +0100362/**@}*/
363
364/** \defgroup import_export Key import and export
365 * @{
366 */
367
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100368/**
369 * \brief Import a key in binary format.
370 *
Gilles Peskinef5b9fa12018-03-07 16:40:18 +0100371 * This function supports any output from psa_export_key(). Refer to the
Gilles Peskinef7933932018-10-31 14:07:52 +0100372 * documentation of psa_export_public_key() for the format of public keys
373 * and to the documentation of psa_export_key() for the format for
374 * other key types.
375 *
376 * This specification supports a single format for each key type.
377 * Implementations may support other formats as long as the standard
378 * format is supported. Implementations that support other formats
379 * should ensure that the formats are clearly unambiguous so as to
380 * minimize the risk that an invalid input is accidentally interpreted
381 * according to a different format.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100382 *
Gilles Peskineae32aac2018-11-30 14:39:32 +0100383 * \param handle Handle to the slot where the key will be stored.
Gilles Peskined40c1fb2019-01-19 12:20:52 +0100384 * It must have been obtained by calling
385 * psa_allocate_key() or psa_create_key() and must
386 * not contain key material yet.
Gilles Peskinef7933932018-10-31 14:07:52 +0100387 * \param type Key type (a \c PSA_KEY_TYPE_XXX value). On a successful
388 * import, the key slot will contain a key of this type.
389 * \param[in] data Buffer containing the key data. The content of this
390 * buffer is interpreted according to \p type. It must
391 * contain the format described in the documentation
392 * of psa_export_key() or psa_export_public_key() for
393 * the chosen type.
Gilles Peskinefa4070c2018-07-12 19:23:03 +0200394 * \param data_length Size of the \p data buffer in bytes.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100395 *
Gilles Peskine28538492018-07-11 17:34:00 +0200396 * \retval #PSA_SUCCESS
Gilles Peskine308b91d2018-02-08 09:47:44 +0100397 * Success.
Gilles Peskine23fd2bd2018-12-11 15:51:32 +0100398 * If the key is persistent, the key material and the key's metadata
399 * have been saved to persistent storage.
Gilles Peskineae32aac2018-11-30 14:39:32 +0100400 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine28538492018-07-11 17:34:00 +0200401 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskine65eb8582018-04-19 08:28:58 +0200402 * The key type or key size is not supported, either by the
403 * implementation in general or in this particular slot.
Gilles Peskine28538492018-07-11 17:34:00 +0200404 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine308b91d2018-02-08 09:47:44 +0100405 * The key slot is invalid,
406 * or the key data is not correctly formatted.
David Saadab4ecc272019-02-14 13:48:10 +0200407 * \retval #PSA_ERROR_ALREADY_EXISTS
Gilles Peskine65eb8582018-04-19 08:28:58 +0200408 * There is already a key in the specified slot.
Gilles Peskine28538492018-07-11 17:34:00 +0200409 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
410 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
411 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
Darryl Greend49a4992018-06-18 17:27:26 +0100412 * \retval #PSA_ERROR_STORAGE_FAILURE
Gilles Peskine28538492018-07-11 17:34:00 +0200413 * \retval #PSA_ERROR_HARDWARE_FAILURE
414 * \retval #PSA_ERROR_TAMPERING_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +0300415 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +0300416 * The library has not been previously initialized by psa_crypto_init().
417 * It is implementation-dependent whether a failure to initialize
418 * results in this error code.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100419 */
Gilles Peskineae32aac2018-11-30 14:39:32 +0100420psa_status_t psa_import_key(psa_key_handle_t handle,
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100421 psa_key_type_t type,
422 const uint8_t *data,
423 size_t data_length);
424
425/**
Gilles Peskineae32aac2018-11-30 14:39:32 +0100426 * \brief Destroy a key.
Gilles Peskine154bd952018-04-19 08:38:16 +0200427 *
428 * This function destroys the content of the key slot from both volatile
429 * memory and, if applicable, non-volatile storage. Implementations shall
430 * make a best effort to ensure that any previous content of the slot is
431 * unrecoverable.
432 *
Gilles Peskineae32aac2018-11-30 14:39:32 +0100433 * This function also erases any metadata such as policies and frees all
434 * resources associated with the key.
Gilles Peskine154bd952018-04-19 08:38:16 +0200435 *
Gilles Peskine5f25dd02019-01-14 18:24:53 +0100436 * If the key is currently in use in a multipart operation,
437 * the multipart operation is aborted.
438 *
Gilles Peskineae32aac2018-11-30 14:39:32 +0100439 * \param handle Handle to the key slot to erase.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100440 *
Gilles Peskine28538492018-07-11 17:34:00 +0200441 * \retval #PSA_SUCCESS
Gilles Peskine65eb8582018-04-19 08:28:58 +0200442 * The slot's content, if any, has been erased.
Gilles Peskine28538492018-07-11 17:34:00 +0200443 * \retval #PSA_ERROR_NOT_PERMITTED
Gilles Peskine65eb8582018-04-19 08:28:58 +0200444 * The slot holds content and cannot be erased because it is
445 * read-only, either due to a policy or due to physical restrictions.
Gilles Peskineae32aac2018-11-30 14:39:32 +0100446 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine28538492018-07-11 17:34:00 +0200447 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
Gilles Peskine65eb8582018-04-19 08:28:58 +0200448 * There was an failure in communication with the cryptoprocessor.
449 * The key material may still be present in the cryptoprocessor.
Gilles Peskine28538492018-07-11 17:34:00 +0200450 * \retval #PSA_ERROR_STORAGE_FAILURE
Gilles Peskine65eb8582018-04-19 08:28:58 +0200451 * The storage is corrupted. Implementations shall make a best effort
452 * to erase key material even in this stage, however applications
453 * should be aware that it may be impossible to guarantee that the
454 * key material is not recoverable in such cases.
Gilles Peskine28538492018-07-11 17:34:00 +0200455 * \retval #PSA_ERROR_TAMPERING_DETECTED
Gilles Peskine65eb8582018-04-19 08:28:58 +0200456 * An unexpected condition which is not a storage corruption or
457 * a communication failure occurred. The cryptoprocessor may have
458 * been compromised.
itayzafrir90d8c7a2018-09-12 11:44:52 +0300459 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +0300460 * The library has not been previously initialized by psa_crypto_init().
461 * It is implementation-dependent whether a failure to initialize
462 * results in this error code.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100463 */
Gilles Peskineae32aac2018-11-30 14:39:32 +0100464psa_status_t psa_destroy_key(psa_key_handle_t handle);
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100465
466/**
467 * \brief Get basic metadata about a key.
468 *
Gilles Peskineae32aac2018-11-30 14:39:32 +0100469 * \param handle Handle to the key slot to query.
Gilles Peskineedd11a12018-07-12 01:08:58 +0200470 * \param[out] type On success, the key type (a \c PSA_KEY_TYPE_XXX value).
Gilles Peskine308b91d2018-02-08 09:47:44 +0100471 * This may be a null pointer, in which case the key type
472 * is not written.
Gilles Peskineedd11a12018-07-12 01:08:58 +0200473 * \param[out] bits On success, the key size in bits.
Gilles Peskine9a1ba0d2018-03-21 20:49:16 +0100474 * This may be a null pointer, in which case the key size
Gilles Peskine308b91d2018-02-08 09:47:44 +0100475 * is not written.
476 *
Gilles Peskine28538492018-07-11 17:34:00 +0200477 * \retval #PSA_SUCCESS
Gilles Peskineae32aac2018-11-30 14:39:32 +0100478 * \retval #PSA_ERROR_INVALID_HANDLE
David Saadab4ecc272019-02-14 13:48:10 +0200479 * \retval #PSA_ERROR_DOES_NOT_EXIST
Gilles Peskineae32aac2018-11-30 14:39:32 +0100480 * The handle is to a key slot which does not contain key material yet.
Gilles Peskine28538492018-07-11 17:34:00 +0200481 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
482 * \retval #PSA_ERROR_HARDWARE_FAILURE
483 * \retval #PSA_ERROR_TAMPERING_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +0300484 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +0300485 * The library has not been previously initialized by psa_crypto_init().
486 * It is implementation-dependent whether a failure to initialize
487 * results in this error code.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100488 */
Gilles Peskineae32aac2018-11-30 14:39:32 +0100489psa_status_t psa_get_key_information(psa_key_handle_t handle,
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100490 psa_key_type_t *type,
491 size_t *bits);
492
493/**
Jaeden Amero283dfd12019-01-11 12:06:22 +0000494 * \brief Set domain parameters for a key.
495 *
496 * Some key types require additional domain parameters to be set before import
497 * or generation of the key. The domain parameters can be set with this
498 * function or, for key generation, through the \c extra parameter of
499 * psa_generate_key().
500 *
501 * The format for the required domain parameters varies by the key type.
Jaeden Amero1308fb52019-01-11 13:50:43 +0000502 * - For DSA public keys (#PSA_KEY_TYPE_DSA_PUBLIC_KEY),
503 * the `Dss-Parms` format as defined by RFC 3279 &sect;2.3.2.
504 * ```
505 * Dss-Parms ::= SEQUENCE {
506 * p INTEGER,
507 * q INTEGER,
508 * g INTEGER
509 * }
510 * ```
Jaeden Amero8851c402019-01-11 14:20:03 +0000511 * - For Diffie-Hellman key exchange keys (#PSA_KEY_TYPE_DH_PUBLIC_KEY), the
512 * `DomainParameters` format as defined by RFC 3279 &sect;2.3.3.
513 * ```
514 * DomainParameters ::= SEQUENCE {
515 * p INTEGER, -- odd prime, p=jq +1
516 * g INTEGER, -- generator, g
517 * q INTEGER, -- factor of p-1
518 * j INTEGER OPTIONAL, -- subgroup factor
519 * validationParms ValidationParms OPTIONAL
520 * }
521 * ValidationParms ::= SEQUENCE {
522 * seed BIT STRING,
523 * pgenCounter INTEGER
524 * }
525 * ```
Jaeden Amero283dfd12019-01-11 12:06:22 +0000526 *
Gilles Peskine3a74e002019-01-18 17:11:25 +0100527 * \param handle Handle to the slot where the key will be stored.
528 * This must be a valid slot for a key of the chosen
529 * type: it must have been obtained by calling
530 * psa_allocate_key() or psa_create_key() with the
531 * correct \p type and with a maximum size that is
532 * compatible with \p data. It must not contain
533 * key material yet.
534 * \param type Key type (a \c PSA_KEY_TYPE_XXX value). When
535 * subsequently creating key material into \p handle,
536 * the type must be compatible.
Jaeden Amero283dfd12019-01-11 12:06:22 +0000537 * \param[in] data Buffer containing the key domain parameters. The content
538 * of this buffer is interpreted according to \p type. of
539 * psa_export_key() or psa_export_public_key() for the
540 * chosen type.
541 * \param data_length Size of the \p data buffer in bytes.
542 *
543 * \retval #PSA_SUCCESS
544 * \retval #PSA_ERROR_INVALID_HANDLE
545 * \retval #PSA_ERROR_OCCUPIED_SLOT
546 * There is already a key in the specified slot.
547 * \retval #PSA_ERROR_INVALID_ARGUMENT
548 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
549 * \retval #PSA_ERROR_HARDWARE_FAILURE
550 * \retval #PSA_ERROR_TAMPERING_DETECTED
551 * \retval #PSA_ERROR_BAD_STATE
552 * The library has not been previously initialized by psa_crypto_init().
553 * It is implementation-dependent whether a failure to initialize
554 * results in this error code.
555 */
556psa_status_t psa_set_key_domain_parameters(psa_key_handle_t handle,
Gilles Peskine3a74e002019-01-18 17:11:25 +0100557 psa_key_type_t type,
Jaeden Amero283dfd12019-01-11 12:06:22 +0000558 const uint8_t *data,
559 size_t data_length);
560
561/**
562 * \brief Get domain parameters for a key.
563 *
564 * Get the domain parameters for a key with this function, if any. The format
565 * of the domain parameters written to \p data is specified in the
566 * documentation for psa_set_key_domain_parameters().
567 *
568 * \param handle Handle to the key to get domain parameters from.
569 * \param[out] data On success, the key domain parameters.
570 * \param data_size Size of the \p data buffer in bytes.
571 * \param[out] data_length On success, the number of bytes
572 * that make up the key domain parameters data.
573 *
574 * \retval #PSA_SUCCESS
575 * \retval #PSA_ERROR_INVALID_HANDLE
576 * \retval #PSA_ERROR_EMPTY_SLOT
577 * There is no key in the specified slot.
578 * \retval #PSA_ERROR_INVALID_ARGUMENT
579 * \retval #PSA_ERROR_NOT_SUPPORTED
580 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
581 * \retval #PSA_ERROR_HARDWARE_FAILURE
582 * \retval #PSA_ERROR_TAMPERING_DETECTED
583 * \retval #PSA_ERROR_BAD_STATE
584 * The library has not been previously initialized by psa_crypto_init().
585 * It is implementation-dependent whether a failure to initialize
586 * results in this error code.
587 */
588psa_status_t psa_get_key_domain_parameters(psa_key_handle_t handle,
589 uint8_t *data,
590 size_t data_size,
591 size_t *data_length);
592
593/**
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100594 * \brief Export a key in binary format.
595 *
596 * The output of this function can be passed to psa_import_key() to
597 * create an equivalent object.
598 *
Gilles Peskinef7933932018-10-31 14:07:52 +0100599 * If the implementation of psa_import_key() supports other formats
600 * beyond the format specified here, the output from psa_export_key()
601 * must use the representation specified here, not the original
602 * representation.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100603 *
Gilles Peskine308b91d2018-02-08 09:47:44 +0100604 * For standard key types, the output format is as follows:
605 *
606 * - For symmetric keys (including MAC keys), the format is the
607 * raw bytes of the key.
608 * - For DES, the key data consists of 8 bytes. The parity bits must be
609 * correct.
610 * - For Triple-DES, the format is the concatenation of the
611 * two or three DES keys.
Gilles Peskine92b30732018-03-03 21:29:30 +0100612 * - For RSA key pairs (#PSA_KEY_TYPE_RSA_KEYPAIR), the format
Gilles Peskine4e1e9be2018-08-10 18:57:40 +0200613 * is the non-encrypted DER encoding of the representation defined by
614 * PKCS\#1 (RFC 8017) as `RSAPrivateKey`, version 0.
615 * ```
616 * RSAPrivateKey ::= SEQUENCE {
Gilles Peskine4f6c77b2018-08-11 01:17:53 +0200617 * version INTEGER, -- must be 0
Gilles Peskine4e1e9be2018-08-10 18:57:40 +0200618 * modulus INTEGER, -- n
619 * publicExponent INTEGER, -- e
620 * privateExponent INTEGER, -- d
621 * prime1 INTEGER, -- p
622 * prime2 INTEGER, -- q
623 * exponent1 INTEGER, -- d mod (p-1)
624 * exponent2 INTEGER, -- d mod (q-1)
625 * coefficient INTEGER, -- (inverse of q) mod p
626 * }
627 * ```
Jaeden Amero1308fb52019-01-11 13:50:43 +0000628 * - For DSA private keys (#PSA_KEY_TYPE_DSA_KEYPAIR), the format is the
629 * representation of the private key `x` as a big-endian byte string. The
630 * length of the byte string is the private key size in bytes (leading zeroes
631 * are not stripped).
Gilles Peskine4e1e9be2018-08-10 18:57:40 +0200632 * - For elliptic curve key pairs (key types for which
Gilles Peskinef76aa772018-10-29 19:24:33 +0100633 * #PSA_KEY_TYPE_IS_ECC_KEYPAIR is true), the format is
Gilles Peskine6c6a0232018-11-15 17:44:43 +0100634 * a representation of the private value as a `ceiling(m/8)`-byte string
635 * where `m` is the bit size associated with the curve, i.e. the bit size
636 * of the order of the curve's coordinate field. This byte string is
637 * in little-endian order for Montgomery curves (curve types
638 * `PSA_ECC_CURVE_CURVEXXX`), and in big-endian order for Weierstrass
639 * curves (curve types `PSA_ECC_CURVE_SECTXXX`, `PSA_ECC_CURVE_SECPXXX`
640 * and `PSA_ECC_CURVE_BRAINPOOL_PXXX`).
Gilles Peskinef76aa772018-10-29 19:24:33 +0100641 * This is the content of the `privateKey` field of the `ECPrivateKey`
642 * format defined by RFC 5915.
Jaeden Amero8851c402019-01-11 14:20:03 +0000643 * - For Diffie-Hellman key exchange key pairs (#PSA_KEY_TYPE_DH_KEYPAIR), the
644 * format is the representation of the private key `x` as a big-endian byte
645 * string. The length of the byte string is the private key size in bytes
646 * (leading zeroes are not stripped).
Gilles Peskine4e1e9be2018-08-10 18:57:40 +0200647 * - For public keys (key types for which #PSA_KEY_TYPE_IS_PUBLIC_KEY is
648 * true), the format is the same as for psa_export_public_key().
Gilles Peskine308b91d2018-02-08 09:47:44 +0100649 *
Gilles Peskineae32aac2018-11-30 14:39:32 +0100650 * \param handle Handle to the key to export.
Gilles Peskineedd11a12018-07-12 01:08:58 +0200651 * \param[out] data Buffer where the key data is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +0200652 * \param data_size Size of the \p data buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +0200653 * \param[out] data_length On success, the number of bytes
654 * that make up the key data.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100655 *
Gilles Peskine28538492018-07-11 17:34:00 +0200656 * \retval #PSA_SUCCESS
Gilles Peskineae32aac2018-11-30 14:39:32 +0100657 * \retval #PSA_ERROR_INVALID_HANDLE
David Saadab4ecc272019-02-14 13:48:10 +0200658 * \retval #PSA_ERROR_DOES_NOT_EXIST
Gilles Peskine28538492018-07-11 17:34:00 +0200659 * \retval #PSA_ERROR_NOT_PERMITTED
Darryl Green9e2d7a02018-07-24 16:33:30 +0100660 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskine1be949b2018-08-10 19:06:59 +0200661 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
662 * The size of the \p data buffer is too small. You can determine a
663 * sufficient buffer size by calling
664 * #PSA_KEY_EXPORT_MAX_SIZE(\c type, \c bits)
665 * where \c type is the key type
666 * and \c bits is the key size in bits.
Gilles Peskine28538492018-07-11 17:34:00 +0200667 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
668 * \retval #PSA_ERROR_HARDWARE_FAILURE
669 * \retval #PSA_ERROR_TAMPERING_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +0300670 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +0300671 * The library has not been previously initialized by psa_crypto_init().
672 * It is implementation-dependent whether a failure to initialize
673 * results in this error code.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100674 */
Gilles Peskineae32aac2018-11-30 14:39:32 +0100675psa_status_t psa_export_key(psa_key_handle_t handle,
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100676 uint8_t *data,
677 size_t data_size,
678 size_t *data_length);
679
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100680/**
681 * \brief Export a public key or the public part of a key pair in binary format.
682 *
683 * The output of this function can be passed to psa_import_key() to
684 * create an object that is equivalent to the public key.
685 *
Jaeden Amerod3a0c2c2019-01-11 17:15:56 +0000686 * This specification supports a single format for each key type.
687 * Implementations may support other formats as long as the standard
688 * format is supported. Implementations that support other formats
689 * should ensure that the formats are clearly unambiguous so as to
690 * minimize the risk that an invalid input is accidentally interpreted
691 * according to a different format.
692 *
Jaeden Amero6b196002019-01-10 10:23:21 +0000693 * For standard key types, the output format is as follows:
694 * - For RSA public keys (#PSA_KEY_TYPE_RSA_PUBLIC_KEY), the DER encoding of
695 * the representation defined by RFC 3279 &sect;2.3.1 as `RSAPublicKey`.
696 * ```
697 * RSAPublicKey ::= SEQUENCE {
698 * modulus INTEGER, -- n
699 * publicExponent INTEGER } -- e
700 * ```
Jaeden Amero0ae445f2019-01-10 11:42:27 +0000701 * - For elliptic curve public keys (key types for which
702 * #PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY is true), the format is the uncompressed
703 * representation defined by SEC1 &sect;2.3.3 as the content of an ECPoint.
704 * Let `m` be the bit size associated with the curve, i.e. the bit size of
705 * `q` for a curve over `F_q`. The representation consists of:
706 * - The byte 0x04;
707 * - `x_P` as a `ceiling(m/8)`-byte string, big-endian;
708 * - `y_P` as a `ceiling(m/8)`-byte string, big-endian.
Jaeden Amero1308fb52019-01-11 13:50:43 +0000709 * - For DSA public keys (#PSA_KEY_TYPE_DSA_PUBLIC_KEY), the format is the
710 * representation of the public key `y = g^x mod p` as a big-endian byte
711 * string. The length of the byte string is the length of the base prime `p`
712 * in bytes.
Jaeden Amero8851c402019-01-11 14:20:03 +0000713 * - For Diffie-Hellman key exchange public keys (#PSA_KEY_TYPE_DH_PUBLIC_KEY),
714 * the format is the representation of the public key `y = g^x mod p` as a
715 * big-endian byte string. The length of the byte string is the length of the
716 * base prime `p` in bytes.
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100717 *
Gilles Peskineae32aac2018-11-30 14:39:32 +0100718 * \param handle Handle to the key to export.
Gilles Peskineedd11a12018-07-12 01:08:58 +0200719 * \param[out] data Buffer where the key data is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +0200720 * \param data_size Size of the \p data buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +0200721 * \param[out] data_length On success, the number of bytes
722 * that make up the key data.
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100723 *
Gilles Peskine28538492018-07-11 17:34:00 +0200724 * \retval #PSA_SUCCESS
Gilles Peskineae32aac2018-11-30 14:39:32 +0100725 * \retval #PSA_ERROR_INVALID_HANDLE
David Saadab4ecc272019-02-14 13:48:10 +0200726 * \retval #PSA_ERROR_DOES_NOT_EXIST
Gilles Peskine28538492018-07-11 17:34:00 +0200727 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine1be949b2018-08-10 19:06:59 +0200728 * The key is neither a public key nor a key pair.
729 * \retval #PSA_ERROR_NOT_SUPPORTED
730 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
731 * The size of the \p data buffer is too small. You can determine a
732 * sufficient buffer size by calling
733 * #PSA_KEY_EXPORT_MAX_SIZE(#PSA_KEY_TYPE_PUBLIC_KEY_OF_KEYPAIR(\c type), \c bits)
734 * where \c type is the key type
735 * and \c bits is the key size in bits.
Gilles Peskine28538492018-07-11 17:34:00 +0200736 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
737 * \retval #PSA_ERROR_HARDWARE_FAILURE
738 * \retval #PSA_ERROR_TAMPERING_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +0300739 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +0300740 * The library has not been previously initialized by psa_crypto_init().
741 * It is implementation-dependent whether a failure to initialize
742 * results in this error code.
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100743 */
Gilles Peskineae32aac2018-11-30 14:39:32 +0100744psa_status_t psa_export_public_key(psa_key_handle_t handle,
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100745 uint8_t *data,
746 size_t data_size,
747 size_t *data_length);
748
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100749/** Make a copy of a key.
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100750 *
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100751 * Copy key material from one location to another.
Jaeden Amero70261c52019-01-04 11:47:20 +0000752 *
Gilles Peskineaec5a7f2019-02-05 20:26:09 +0100753 * This function is primarily useful to copy a key from one location
754 * to another, since it populates a key using the material from
755 * another key which may have a different lifetime.
Gilles Peskine6ac73a92018-07-12 19:47:19 +0200756 *
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100757 * In an implementation where slots have different ownerships,
Gilles Peskinebf7a98b2019-02-22 16:42:11 +0100758 * this function may be used to share a key with a different party,
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100759 * subject to implementation-defined restrictions on key sharing.
760 * In this case \p constraint would typically prevent the recipient
761 * from exporting the key.
Gilles Peskine7e198532018-03-08 07:50:30 +0100762 *
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100763 * The resulting key may only be used in a way that conforms to all
764 * three of: the policy of the source key, the policy previously set
765 * on the target, and the \p constraint parameter passed when calling
766 * this function.
767 * - The usage flags on the resulting key are the bitwise-and of the
768 * usage flags on the source policy, the previously-set target policy
769 * and the policy constraint.
770 * - If all three policies allow the same algorithm or wildcard-based
771 * algorithm policy, the resulting key has the same algorithm policy.
772 * - If one of the policies allows an algorithm and all the other policies
773 * either allow the same algorithm or a wildcard-based algorithm policy
774 * that includes this algorithm, the resulting key allows the same
775 * algorithm.
Gilles Peskine6ac73a92018-07-12 19:47:19 +0200776 *
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100777 * The effect of this function on implementation-defined metadata is
778 * implementation-defined.
Gilles Peskine6ac73a92018-07-12 19:47:19 +0200779 *
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100780 * \param source_handle The key to copy. It must be a handle to an
781 * occupied slot.
782 * \param target_handle A handle to the target slot. It must not contain
783 * key material yet.
784 * \param[in] constraint An optional policy constraint. If this parameter
785 * is non-null then the resulting key will conform
786 * to this policy in addition to the source policy
787 * and the policy already present on the target
788 * slot. If this parameter is null then the
789 * function behaves in the same way as if it was
790 * the target policy, i.e. only the source and
791 * target policies apply.
Gilles Peskine6ac73a92018-07-12 19:47:19 +0200792 *
793 * \retval #PSA_SUCCESS
Gilles Peskineae32aac2018-11-30 14:39:32 +0100794 * \retval #PSA_ERROR_INVALID_HANDLE
David Saadab4ecc272019-02-14 13:48:10 +0200795 * \retval #PSA_ERROR_ALREADY_EXISTS
Gilles Peskine3be6b7f2019-03-05 19:32:26 +0100796 * \p target_handle already contains key material.
David Saadab4ecc272019-02-14 13:48:10 +0200797 * \retval #PSA_ERROR_DOES_NOT_EXIST
Gilles Peskine3be6b7f2019-03-05 19:32:26 +0100798 * \p source_handle does not contain key material.
Gilles Peskine6ac73a92018-07-12 19:47:19 +0200799 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100800 * The policy constraints on the source, on the target and
Gilles Peskine3be6b7f2019-03-05 19:32:26 +0100801 * \p constraint are incompatible.
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100802 * \retval #PSA_ERROR_NOT_PERMITTED
803 * The source key is not exportable and its lifetime does not
804 * allow copying it to the target's lifetime.
805 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
806 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
Gilles Peskine6ac73a92018-07-12 19:47:19 +0200807 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
808 * \retval #PSA_ERROR_HARDWARE_FAILURE
809 * \retval #PSA_ERROR_TAMPERING_DETECTED
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100810 */
Gilles Peskine4cb9dde2019-01-19 13:40:11 +0100811psa_status_t psa_copy_key(psa_key_handle_t source_handle,
812 psa_key_handle_t target_handle,
813 const psa_key_policy_t *constraint);
Gilles Peskine20035e32018-02-03 22:44:14 +0100814
815/**@}*/
816
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100817/** \defgroup hash Message digests
818 * @{
819 */
820
Gilles Peskine69647a42019-01-14 20:18:12 +0100821/** Calculate the hash (digest) of a message.
822 *
823 * \note To verify the hash of a message against an
824 * expected value, use psa_hash_compare() instead.
825 *
826 * \param alg The hash algorithm to compute (\c PSA_ALG_XXX value
827 * such that #PSA_ALG_IS_HASH(\p alg) is true).
828 * \param[in] input Buffer containing the message to hash.
829 * \param input_length Size of the \p input buffer in bytes.
830 * \param[out] hash Buffer where the hash is to be written.
831 * \param hash_size Size of the \p hash buffer in bytes.
832 * \param[out] hash_length On success, the number of bytes
833 * that make up the hash value. This is always
Gilles Peskined338b912019-02-15 13:01:41 +0100834 * #PSA_HASH_SIZE(\p alg).
Gilles Peskine69647a42019-01-14 20:18:12 +0100835 *
836 * \retval #PSA_SUCCESS
837 * Success.
838 * \retval #PSA_ERROR_NOT_SUPPORTED
839 * \p alg is not supported or is not a hash algorithm.
840 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
841 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
842 * \retval #PSA_ERROR_HARDWARE_FAILURE
843 * \retval #PSA_ERROR_TAMPERING_DETECTED
844 */
845psa_status_t psa_hash_compute(psa_algorithm_t alg,
846 const uint8_t *input,
847 size_t input_length,
848 uint8_t *hash,
849 size_t hash_size,
850 size_t *hash_length);
851
852/** Calculate the hash (digest) of a message and compare it with a
853 * reference value.
854 *
855 * \param alg The hash algorithm to compute (\c PSA_ALG_XXX value
856 * such that #PSA_ALG_IS_HASH(\p alg) is true).
857 * \param[in] input Buffer containing the message to hash.
858 * \param input_length Size of the \p input buffer in bytes.
859 * \param[out] hash Buffer containing the expected hash value.
Gilles Peskinea05602d2019-01-17 15:25:52 +0100860 * \param hash_length Size of the \p hash buffer in bytes.
Gilles Peskine69647a42019-01-14 20:18:12 +0100861 *
862 * \retval #PSA_SUCCESS
863 * The expected hash is identical to the actual hash of the input.
864 * \retval #PSA_ERROR_INVALID_SIGNATURE
865 * The hash of the message was calculated successfully, but it
866 * differs from the expected hash.
867 * \retval #PSA_ERROR_NOT_SUPPORTED
868 * \p alg is not supported or is not a hash algorithm.
869 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
870 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
871 * \retval #PSA_ERROR_HARDWARE_FAILURE
872 * \retval #PSA_ERROR_TAMPERING_DETECTED
873 */
874psa_status_t psa_hash_compare(psa_algorithm_t alg,
875 const uint8_t *input,
876 size_t input_length,
877 const uint8_t *hash,
878 const size_t hash_length);
879
Gilles Peskine308b91d2018-02-08 09:47:44 +0100880/** The type of the state data structure for multipart hash operations.
881 *
Jaeden Amero6a25b412019-01-04 11:47:44 +0000882 * Before calling any function on a hash operation object, the application must
883 * initialize it by any of the following means:
884 * - Set the structure to all-bits-zero, for example:
885 * \code
886 * psa_hash_operation_t operation;
887 * memset(&operation, 0, sizeof(operation));
888 * \endcode
889 * - Initialize the structure to logical zero values, for example:
890 * \code
891 * psa_hash_operation_t operation = {0};
892 * \endcode
893 * - Initialize the structure to the initializer #PSA_HASH_OPERATION_INIT,
894 * for example:
895 * \code
896 * psa_hash_operation_t operation = PSA_HASH_OPERATION_INIT;
897 * \endcode
898 * - Assign the result of the function psa_hash_operation_init()
899 * to the structure, for example:
900 * \code
901 * psa_hash_operation_t operation;
902 * operation = psa_hash_operation_init();
903 * \endcode
904 *
Gilles Peskine92b30732018-03-03 21:29:30 +0100905 * This is an implementation-defined \c struct. Applications should not
Gilles Peskine308b91d2018-02-08 09:47:44 +0100906 * make any assumptions about the content of this structure except
907 * as directed by the documentation of a specific implementation. */
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100908typedef struct psa_hash_operation_s psa_hash_operation_t;
909
Jaeden Amero6a25b412019-01-04 11:47:44 +0000910/** \def PSA_HASH_OPERATION_INIT
911 *
912 * This macro returns a suitable initializer for a hash operation object
913 * of type #psa_hash_operation_t.
914 */
915#ifdef __DOXYGEN_ONLY__
916/* This is an example definition for documentation purposes.
917 * Implementations should define a suitable value in `crypto_struct.h`.
918 */
919#define PSA_HASH_OPERATION_INIT {0}
920#endif
921
922/** Return an initial value for a hash operation object.
923 */
924static psa_hash_operation_t psa_hash_operation_init(void);
925
Gilles Peskinef45adda2019-01-14 18:29:18 +0100926/** Set up a multipart hash operation.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100927 *
928 * The sequence of operations to calculate a hash (message digest)
929 * is as follows:
930 * -# Allocate an operation object which will be passed to all the functions
931 * listed here.
Jaeden Amero6a25b412019-01-04 11:47:44 +0000932 * -# Initialize the operation object with one of the methods described in the
933 * documentation for #psa_hash_operation_t, e.g. PSA_HASH_OPERATION_INIT.
Gilles Peskineda8191d1c2018-07-08 19:46:38 +0200934 * -# Call psa_hash_setup() to specify the algorithm.
Gilles Peskine7e4acc52018-02-16 21:24:11 +0100935 * -# Call psa_hash_update() zero, one or more times, passing a fragment
Gilles Peskine308b91d2018-02-08 09:47:44 +0100936 * of the message each time. The hash that is calculated is the hash
937 * of the concatenation of these messages in order.
938 * -# To calculate the hash, call psa_hash_finish().
939 * To compare the hash with an expected value, call psa_hash_verify().
940 *
941 * The application may call psa_hash_abort() at any time after the operation
Jaeden Amero6a25b412019-01-04 11:47:44 +0000942 * has been initialized.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100943 *
Gilles Peskineda8191d1c2018-07-08 19:46:38 +0200944 * After a successful call to psa_hash_setup(), the application must
Gilles Peskineed522972018-03-20 17:54:15 +0100945 * eventually terminate the operation. The following events terminate an
946 * operation:
Gilles Peskine308b91d2018-02-08 09:47:44 +0100947 * - A failed call to psa_hash_update().
Gilles Peskine19067982018-03-20 17:54:53 +0100948 * - A call to psa_hash_finish(), psa_hash_verify() or psa_hash_abort().
Gilles Peskine308b91d2018-02-08 09:47:44 +0100949 *
Jaeden Amero6a25b412019-01-04 11:47:44 +0000950 * \param[in,out] operation The operation object to set up. It must have
951 * been initialized as per the documentation for
952 * #psa_hash_operation_t and not yet in use.
Gilles Peskineedd11a12018-07-12 01:08:58 +0200953 * \param alg The hash algorithm to compute (\c PSA_ALG_XXX value
954 * such that #PSA_ALG_IS_HASH(\p alg) is true).
Gilles Peskine308b91d2018-02-08 09:47:44 +0100955 *
Gilles Peskine28538492018-07-11 17:34:00 +0200956 * \retval #PSA_SUCCESS
Gilles Peskine308b91d2018-02-08 09:47:44 +0100957 * Success.
Gilles Peskine28538492018-07-11 17:34:00 +0200958 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskinefa4070c2018-07-12 19:23:03 +0200959 * \p alg is not supported or is not a hash algorithm.
Gilles Peskine8e1addc2019-01-10 11:51:17 +0100960 * \retval #PSA_ERROR_BAD_STATE
961 * The operation state is not valid (already set up and not
962 * subsequently completed).
Gilles Peskine28538492018-07-11 17:34:00 +0200963 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
964 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
965 * \retval #PSA_ERROR_HARDWARE_FAILURE
966 * \retval #PSA_ERROR_TAMPERING_DETECTED
Gilles Peskine308b91d2018-02-08 09:47:44 +0100967 */
Gilles Peskineda8191d1c2018-07-08 19:46:38 +0200968psa_status_t psa_hash_setup(psa_hash_operation_t *operation,
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100969 psa_algorithm_t alg);
970
Gilles Peskine308b91d2018-02-08 09:47:44 +0100971/** Add a message fragment to a multipart hash operation.
972 *
Gilles Peskineda8191d1c2018-07-08 19:46:38 +0200973 * The application must call psa_hash_setup() before calling this function.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100974 *
975 * If this function returns an error status, the operation becomes inactive.
976 *
Gilles Peskineedd11a12018-07-12 01:08:58 +0200977 * \param[in,out] operation Active hash operation.
978 * \param[in] input Buffer containing the message fragment to hash.
Gilles Peskinefa4070c2018-07-12 19:23:03 +0200979 * \param input_length Size of the \p input buffer in bytes.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100980 *
Gilles Peskine28538492018-07-11 17:34:00 +0200981 * \retval #PSA_SUCCESS
Gilles Peskine308b91d2018-02-08 09:47:44 +0100982 * Success.
Gilles Peskine28538492018-07-11 17:34:00 +0200983 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +0100984 * The operation state is not valid (not set up, or already completed).
Gilles Peskine28538492018-07-11 17:34:00 +0200985 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
986 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
987 * \retval #PSA_ERROR_HARDWARE_FAILURE
988 * \retval #PSA_ERROR_TAMPERING_DETECTED
Gilles Peskine308b91d2018-02-08 09:47:44 +0100989 */
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100990psa_status_t psa_hash_update(psa_hash_operation_t *operation,
991 const uint8_t *input,
992 size_t input_length);
993
Gilles Peskine308b91d2018-02-08 09:47:44 +0100994/** Finish the calculation of the hash of a message.
995 *
Gilles Peskineda8191d1c2018-07-08 19:46:38 +0200996 * The application must call psa_hash_setup() before calling this function.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100997 * This function calculates the hash of the message formed by concatenating
998 * the inputs passed to preceding calls to psa_hash_update().
999 *
1000 * When this function returns, the operation becomes inactive.
1001 *
1002 * \warning Applications should not call this function if they expect
1003 * a specific value for the hash. Call psa_hash_verify() instead.
1004 * Beware that comparing integrity or authenticity data such as
1005 * hash values with a function such as \c memcmp is risky
1006 * because the time taken by the comparison may leak information
1007 * about the hashed data which could allow an attacker to guess
1008 * a valid hash and thereby bypass security controls.
1009 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001010 * \param[in,out] operation Active hash operation.
1011 * \param[out] hash Buffer where the hash is to be written.
1012 * \param hash_size Size of the \p hash buffer in bytes.
1013 * \param[out] hash_length On success, the number of bytes
1014 * that make up the hash value. This is always
Gilles Peskinebe42f312018-07-13 14:38:15 +02001015 * #PSA_HASH_SIZE(\c alg) where \c alg is the
Gilles Peskineedd11a12018-07-12 01:08:58 +02001016 * hash algorithm that is calculated.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001017 *
Gilles Peskine28538492018-07-11 17:34:00 +02001018 * \retval #PSA_SUCCESS
Gilles Peskine308b91d2018-02-08 09:47:44 +01001019 * Success.
Gilles Peskine28538492018-07-11 17:34:00 +02001020 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001021 * The operation state is not valid (not set up, or already completed).
Gilles Peskine28538492018-07-11 17:34:00 +02001022 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001023 * The size of the \p hash buffer is too small. You can determine a
Gilles Peskine7256e6c2018-07-12 00:34:26 +02001024 * sufficient buffer size by calling #PSA_HASH_SIZE(\c alg)
Gilles Peskine308b91d2018-02-08 09:47:44 +01001025 * where \c alg is the hash algorithm that is calculated.
Gilles Peskine28538492018-07-11 17:34:00 +02001026 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1027 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1028 * \retval #PSA_ERROR_HARDWARE_FAILURE
1029 * \retval #PSA_ERROR_TAMPERING_DETECTED
Gilles Peskine308b91d2018-02-08 09:47:44 +01001030 */
Gilles Peskine9ef733f2018-02-07 21:05:37 +01001031psa_status_t psa_hash_finish(psa_hash_operation_t *operation,
1032 uint8_t *hash,
1033 size_t hash_size,
1034 size_t *hash_length);
1035
Gilles Peskine308b91d2018-02-08 09:47:44 +01001036/** Finish the calculation of the hash of a message and compare it with
1037 * an expected value.
1038 *
Gilles Peskineda8191d1c2018-07-08 19:46:38 +02001039 * The application must call psa_hash_setup() before calling this function.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001040 * This function calculates the hash of the message formed by concatenating
1041 * the inputs passed to preceding calls to psa_hash_update(). It then
1042 * compares the calculated hash with the expected hash passed as a
1043 * parameter to this function.
1044 *
1045 * When this function returns, the operation becomes inactive.
1046 *
Gilles Peskine19067982018-03-20 17:54:53 +01001047 * \note Implementations shall make the best effort to ensure that the
Gilles Peskine308b91d2018-02-08 09:47:44 +01001048 * comparison between the actual hash and the expected hash is performed
1049 * in constant time.
1050 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001051 * \param[in,out] operation Active hash operation.
1052 * \param[in] hash Buffer containing the expected hash value.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001053 * \param hash_length Size of the \p hash buffer in bytes.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001054 *
Gilles Peskine28538492018-07-11 17:34:00 +02001055 * \retval #PSA_SUCCESS
Gilles Peskine308b91d2018-02-08 09:47:44 +01001056 * The expected hash is identical to the actual hash of the message.
Gilles Peskine28538492018-07-11 17:34:00 +02001057 * \retval #PSA_ERROR_INVALID_SIGNATURE
Gilles Peskine308b91d2018-02-08 09:47:44 +01001058 * The hash of the message was calculated successfully, but it
1059 * differs from the expected hash.
Gilles Peskine28538492018-07-11 17:34:00 +02001060 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001061 * The operation state is not valid (not set up, or already completed).
Gilles Peskine28538492018-07-11 17:34:00 +02001062 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1063 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1064 * \retval #PSA_ERROR_HARDWARE_FAILURE
1065 * \retval #PSA_ERROR_TAMPERING_DETECTED
Gilles Peskine308b91d2018-02-08 09:47:44 +01001066 */
Gilles Peskine9ef733f2018-02-07 21:05:37 +01001067psa_status_t psa_hash_verify(psa_hash_operation_t *operation,
1068 const uint8_t *hash,
1069 size_t hash_length);
1070
Gilles Peskine308b91d2018-02-08 09:47:44 +01001071/** Abort a hash operation.
1072 *
Gilles Peskine308b91d2018-02-08 09:47:44 +01001073 * Aborting an operation frees all associated resources except for the
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001074 * \p operation structure itself. Once aborted, the operation object
1075 * can be reused for another operation by calling
1076 * psa_hash_setup() again.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001077 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001078 * You may call this function any time after the operation object has
1079 * been initialized by any of the following methods:
1080 * - A call to psa_hash_setup(), whether it succeeds or not.
1081 * - Initializing the \c struct to all-bits-zero.
1082 * - Initializing the \c struct to logical zeros, e.g.
1083 * `psa_hash_operation_t operation = {0}`.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001084 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001085 * In particular, calling psa_hash_abort() after the operation has been
1086 * terminated by a call to psa_hash_abort(), psa_hash_finish() or
1087 * psa_hash_verify() is safe and has no effect.
1088 *
1089 * \param[in,out] operation Initialized hash operation.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001090 *
Gilles Peskine28538492018-07-11 17:34:00 +02001091 * \retval #PSA_SUCCESS
1092 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001093 * \p operation is not an active hash operation.
Gilles Peskine28538492018-07-11 17:34:00 +02001094 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1095 * \retval #PSA_ERROR_HARDWARE_FAILURE
1096 * \retval #PSA_ERROR_TAMPERING_DETECTED
Gilles Peskine308b91d2018-02-08 09:47:44 +01001097 */
1098psa_status_t psa_hash_abort(psa_hash_operation_t *operation);
Gilles Peskine9ef733f2018-02-07 21:05:37 +01001099
Gilles Peskineebb2c3e2019-01-19 12:03:41 +01001100/** Clone a hash operation.
1101 *
Gilles Peskinee43aa392019-01-21 14:50:37 +01001102 * This function copies the state of an ongoing hash operation to
1103 * a new operation object. In other words, this function is equivalent
1104 * to calling psa_hash_setup() on \p target_operation with the same
1105 * algorithm that \p source_operation was set up for, then
1106 * psa_hash_update() on \p target_operation with the same input that
1107 * that was passed to \p source_operation. After this function returns, the
1108 * two objects are independent, i.e. subsequent calls involving one of
1109 * the objects do not affect the other object.
1110 *
Gilles Peskineebb2c3e2019-01-19 12:03:41 +01001111 * \param[in] source_operation The active hash operation to clone.
1112 * \param[in,out] target_operation The operation object to set up.
1113 * It must be initialized but not active.
1114 *
1115 * \retval #PSA_SUCCESS
1116 * \retval #PSA_ERROR_BAD_STATE
1117 * \p source_operation is not an active hash operation.
1118 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinee43aa392019-01-21 14:50:37 +01001119 * \p target_operation is active.
Gilles Peskineebb2c3e2019-01-19 12:03:41 +01001120 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1121 * \retval #PSA_ERROR_HARDWARE_FAILURE
1122 * \retval #PSA_ERROR_TAMPERING_DETECTED
1123 */
1124psa_status_t psa_hash_clone(const psa_hash_operation_t *source_operation,
1125 psa_hash_operation_t *target_operation);
1126
Gilles Peskine9ef733f2018-02-07 21:05:37 +01001127/**@}*/
1128
Gilles Peskine8c9def32018-02-08 10:02:12 +01001129/** \defgroup MAC Message authentication codes
1130 * @{
1131 */
1132
Gilles Peskine69647a42019-01-14 20:18:12 +01001133/** Calculate the MAC (message authentication code) of a message.
1134 *
1135 * \note To verify the MAC of a message against an
1136 * expected value, use psa_mac_verify() instead.
1137 * Beware that comparing integrity or authenticity data such as
1138 * MAC values with a function such as \c memcmp is risky
1139 * because the time taken by the comparison may leak information
1140 * about the MAC value which could allow an attacker to guess
1141 * a valid MAC and thereby bypass security controls.
1142 *
1143 * \param handle Handle to the key to use for the operation.
1144 * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
Gilles Peskine63f79302019-02-15 13:01:17 +01001145 * such that #PSA_ALG_IS_MAC(\p alg) is true).
Gilles Peskine69647a42019-01-14 20:18:12 +01001146 * \param[in] input Buffer containing the input message.
1147 * \param input_length Size of the \p input buffer in bytes.
1148 * \param[out] mac Buffer where the MAC value is to be written.
1149 * \param mac_size Size of the \p mac buffer in bytes.
1150 * \param[out] mac_length On success, the number of bytes
Gilles Peskined338b912019-02-15 13:01:41 +01001151 * that make up the MAC value.
Gilles Peskine69647a42019-01-14 20:18:12 +01001152 *
1153 * \retval #PSA_SUCCESS
1154 * Success.
1155 * \retval #PSA_ERROR_INVALID_HANDLE
1156 * \retval #PSA_ERROR_EMPTY_SLOT
1157 * \retval #PSA_ERROR_NOT_PERMITTED
1158 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001159 * \p handle is not compatible with \p alg.
Gilles Peskine69647a42019-01-14 20:18:12 +01001160 * \retval #PSA_ERROR_NOT_SUPPORTED
1161 * \p alg is not supported or is not a MAC algorithm.
1162 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1163 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1164 * \retval #PSA_ERROR_HARDWARE_FAILURE
1165 * \retval #PSA_ERROR_TAMPERING_DETECTED
1166 * \retval #PSA_ERROR_BAD_STATE
1167 * The library has not been previously initialized by psa_crypto_init().
1168 * It is implementation-dependent whether a failure to initialize
1169 * results in this error code.
1170 */
1171psa_status_t psa_mac_compute(psa_key_handle_t handle,
1172 psa_algorithm_t alg,
1173 const uint8_t *input,
1174 size_t input_length,
1175 uint8_t *mac,
1176 size_t mac_size,
1177 size_t *mac_length);
1178
1179/** Calculate the MAC of a message and compare it with a reference value.
1180 *
1181 * \param handle Handle to the key to use for the operation.
1182 * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
Gilles Peskine63f79302019-02-15 13:01:17 +01001183 * such that #PSA_ALG_IS_MAC(\p alg) is true).
Gilles Peskine69647a42019-01-14 20:18:12 +01001184 * \param[in] input Buffer containing the input message.
1185 * \param input_length Size of the \p input buffer in bytes.
1186 * \param[out] mac Buffer containing the expected MAC value.
1187 * \param mac_length Size of the \p mac buffer in bytes.
1188 *
1189 * \retval #PSA_SUCCESS
1190 * The expected MAC is identical to the actual MAC of the input.
1191 * \retval #PSA_ERROR_INVALID_SIGNATURE
1192 * The MAC of the message was calculated successfully, but it
1193 * differs from the expected value.
1194 * \retval #PSA_ERROR_INVALID_HANDLE
1195 * \retval #PSA_ERROR_EMPTY_SLOT
1196 * \retval #PSA_ERROR_NOT_PERMITTED
1197 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001198 * \p handle is not compatible with \p alg.
Gilles Peskine69647a42019-01-14 20:18:12 +01001199 * \retval #PSA_ERROR_NOT_SUPPORTED
1200 * \p alg is not supported or is not a MAC algorithm.
1201 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1202 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1203 * \retval #PSA_ERROR_HARDWARE_FAILURE
1204 * \retval #PSA_ERROR_TAMPERING_DETECTED
1205 */
Gilles Peskinea05602d2019-01-17 15:25:52 +01001206psa_status_t psa_mac_verify(psa_key_handle_t handle,
1207 psa_algorithm_t alg,
Gilles Peskine69647a42019-01-14 20:18:12 +01001208 const uint8_t *input,
1209 size_t input_length,
1210 const uint8_t *mac,
1211 const size_t mac_length);
1212
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001213/** The type of the state data structure for multipart MAC operations.
1214 *
Jaeden Amero769ce272019-01-04 11:48:03 +00001215 * Before calling any function on a MAC operation object, the application must
1216 * initialize it by any of the following means:
1217 * - Set the structure to all-bits-zero, for example:
1218 * \code
1219 * psa_mac_operation_t operation;
1220 * memset(&operation, 0, sizeof(operation));
1221 * \endcode
1222 * - Initialize the structure to logical zero values, for example:
1223 * \code
1224 * psa_mac_operation_t operation = {0};
1225 * \endcode
1226 * - Initialize the structure to the initializer #PSA_MAC_OPERATION_INIT,
1227 * for example:
1228 * \code
1229 * psa_mac_operation_t operation = PSA_MAC_OPERATION_INIT;
1230 * \endcode
1231 * - Assign the result of the function psa_mac_operation_init()
1232 * to the structure, for example:
1233 * \code
1234 * psa_mac_operation_t operation;
1235 * operation = psa_mac_operation_init();
1236 * \endcode
1237 *
Gilles Peskine92b30732018-03-03 21:29:30 +01001238 * This is an implementation-defined \c struct. Applications should not
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001239 * make any assumptions about the content of this structure except
1240 * as directed by the documentation of a specific implementation. */
Gilles Peskine8c9def32018-02-08 10:02:12 +01001241typedef struct psa_mac_operation_s psa_mac_operation_t;
1242
Jaeden Amero769ce272019-01-04 11:48:03 +00001243/** \def PSA_MAC_OPERATION_INIT
1244 *
1245 * This macro returns a suitable initializer for a MAC operation object of type
1246 * #psa_mac_operation_t.
1247 */
1248#ifdef __DOXYGEN_ONLY__
1249/* This is an example definition for documentation purposes.
1250 * Implementations should define a suitable value in `crypto_struct.h`.
1251 */
1252#define PSA_MAC_OPERATION_INIT {0}
1253#endif
1254
1255/** Return an initial value for a MAC operation object.
1256 */
1257static psa_mac_operation_t psa_mac_operation_init(void);
1258
Gilles Peskinef45adda2019-01-14 18:29:18 +01001259/** Set up a multipart MAC calculation operation.
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001260 *
Gilles Peskine89167cb2018-07-08 20:12:23 +02001261 * This function sets up the calculation of the MAC
1262 * (message authentication code) of a byte string.
1263 * To verify the MAC of a message against an
1264 * expected value, use psa_mac_verify_setup() instead.
1265 *
1266 * The sequence of operations to calculate a MAC is as follows:
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001267 * -# Allocate an operation object which will be passed to all the functions
1268 * listed here.
Jaeden Amero769ce272019-01-04 11:48:03 +00001269 * -# Initialize the operation object with one of the methods described in the
1270 * documentation for #psa_mac_operation_t, e.g. PSA_MAC_OPERATION_INIT.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001271 * -# Call psa_mac_sign_setup() to specify the algorithm and key.
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001272 * -# Call psa_mac_update() zero, one or more times, passing a fragment
1273 * of the message each time. The MAC that is calculated is the MAC
1274 * of the concatenation of these messages in order.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001275 * -# At the end of the message, call psa_mac_sign_finish() to finish
1276 * calculating the MAC value and retrieve it.
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001277 *
1278 * The application may call psa_mac_abort() at any time after the operation
Jaeden Amero769ce272019-01-04 11:48:03 +00001279 * has been initialized.
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001280 *
Gilles Peskine89167cb2018-07-08 20:12:23 +02001281 * After a successful call to psa_mac_sign_setup(), the application must
1282 * eventually terminate the operation through one of the following methods:
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001283 * - A failed call to psa_mac_update().
Gilles Peskine89167cb2018-07-08 20:12:23 +02001284 * - A call to psa_mac_sign_finish() or psa_mac_abort().
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001285 *
Jaeden Amero769ce272019-01-04 11:48:03 +00001286 * \param[in,out] operation The operation object to set up. It must have
1287 * been initialized as per the documentation for
1288 * #psa_mac_operation_t and not yet in use.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001289 * \param handle Handle to the key to use for the operation.
Gilles Peskine5f25dd02019-01-14 18:24:53 +01001290 * It must remain valid until the operation
1291 * terminates.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001292 * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
Gilles Peskine63f79302019-02-15 13:01:17 +01001293 * such that #PSA_ALG_IS_MAC(\p alg) is true).
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001294 *
Gilles Peskine28538492018-07-11 17:34:00 +02001295 * \retval #PSA_SUCCESS
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001296 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001297 * \retval #PSA_ERROR_INVALID_HANDLE
David Saadab4ecc272019-02-14 13:48:10 +02001298 * \retval #PSA_ERROR_DOES_NOT_EXIST
Gilles Peskine28538492018-07-11 17:34:00 +02001299 * \retval #PSA_ERROR_NOT_PERMITTED
1300 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001301 * \p handle is not compatible with \p alg.
Gilles Peskine28538492018-07-11 17:34:00 +02001302 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001303 * \p alg is not supported or is not a MAC algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02001304 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1305 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1306 * \retval #PSA_ERROR_HARDWARE_FAILURE
1307 * \retval #PSA_ERROR_TAMPERING_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03001308 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskine8e1addc2019-01-10 11:51:17 +01001309 * The operation state is not valid (already set up and not
1310 * subsequently completed).
1311 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03001312 * The library has not been previously initialized by psa_crypto_init().
1313 * It is implementation-dependent whether a failure to initialize
1314 * results in this error code.
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001315 */
Gilles Peskine89167cb2018-07-08 20:12:23 +02001316psa_status_t psa_mac_sign_setup(psa_mac_operation_t *operation,
Gilles Peskineae32aac2018-11-30 14:39:32 +01001317 psa_key_handle_t handle,
Gilles Peskine89167cb2018-07-08 20:12:23 +02001318 psa_algorithm_t alg);
1319
Gilles Peskinef45adda2019-01-14 18:29:18 +01001320/** Set up a multipart MAC verification operation.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001321 *
1322 * This function sets up the verification of the MAC
1323 * (message authentication code) of a byte string against an expected value.
1324 *
1325 * The sequence of operations to verify a MAC is as follows:
1326 * -# Allocate an operation object which will be passed to all the functions
1327 * listed here.
Jaeden Amero769ce272019-01-04 11:48:03 +00001328 * -# Initialize the operation object with one of the methods described in the
1329 * documentation for #psa_mac_operation_t, e.g. PSA_MAC_OPERATION_INIT.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001330 * -# Call psa_mac_verify_setup() to specify the algorithm and key.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001331 * -# Call psa_mac_update() zero, one or more times, passing a fragment
1332 * of the message each time. The MAC that is calculated is the MAC
1333 * of the concatenation of these messages in order.
1334 * -# At the end of the message, call psa_mac_verify_finish() to finish
1335 * calculating the actual MAC of the message and verify it against
1336 * the expected value.
1337 *
1338 * The application may call psa_mac_abort() at any time after the operation
Jaeden Amero769ce272019-01-04 11:48:03 +00001339 * has been initialized.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001340 *
1341 * After a successful call to psa_mac_verify_setup(), the application must
1342 * eventually terminate the operation through one of the following methods:
1343 * - A failed call to psa_mac_update().
1344 * - A call to psa_mac_verify_finish() or psa_mac_abort().
1345 *
Jaeden Amero769ce272019-01-04 11:48:03 +00001346 * \param[in,out] operation The operation object to set up. It must have
1347 * been initialized as per the documentation for
1348 * #psa_mac_operation_t and not yet in use.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001349 * \param handle Handle to the key to use for the operation.
Gilles Peskine5f25dd02019-01-14 18:24:53 +01001350 * It must remain valid until the operation
1351 * terminates.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001352 * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
1353 * such that #PSA_ALG_IS_MAC(\p alg) is true).
Gilles Peskine89167cb2018-07-08 20:12:23 +02001354 *
Gilles Peskine28538492018-07-11 17:34:00 +02001355 * \retval #PSA_SUCCESS
Gilles Peskine89167cb2018-07-08 20:12:23 +02001356 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001357 * \retval #PSA_ERROR_INVALID_HANDLE
David Saadab4ecc272019-02-14 13:48:10 +02001358 * \retval #PSA_ERROR_DOES_NOT_EXIST
Gilles Peskine28538492018-07-11 17:34:00 +02001359 * \retval #PSA_ERROR_NOT_PERMITTED
1360 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine89167cb2018-07-08 20:12:23 +02001361 * \c key is not compatible with \c alg.
Gilles Peskine28538492018-07-11 17:34:00 +02001362 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskine89167cb2018-07-08 20:12:23 +02001363 * \c alg is not supported or is not a MAC algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02001364 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1365 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1366 * \retval #PSA_ERROR_HARDWARE_FAILURE
1367 * \retval #PSA_ERROR_TAMPERING_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03001368 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskine8e1addc2019-01-10 11:51:17 +01001369 * The operation state is not valid (already set up and not
1370 * subsequently completed).
1371 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03001372 * The library has not been previously initialized by psa_crypto_init().
1373 * It is implementation-dependent whether a failure to initialize
1374 * results in this error code.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001375 */
1376psa_status_t psa_mac_verify_setup(psa_mac_operation_t *operation,
Gilles Peskineae32aac2018-11-30 14:39:32 +01001377 psa_key_handle_t handle,
Gilles Peskine89167cb2018-07-08 20:12:23 +02001378 psa_algorithm_t alg);
Gilles Peskine8c9def32018-02-08 10:02:12 +01001379
Gilles Peskinedcd14942018-07-12 00:30:52 +02001380/** Add a message fragment to a multipart MAC operation.
1381 *
1382 * The application must call psa_mac_sign_setup() or psa_mac_verify_setup()
1383 * before calling this function.
1384 *
1385 * If this function returns an error status, the operation becomes inactive.
1386 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001387 * \param[in,out] operation Active MAC operation.
1388 * \param[in] input Buffer containing the message fragment to add to
1389 * the MAC calculation.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001390 * \param input_length Size of the \p input buffer in bytes.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001391 *
1392 * \retval #PSA_SUCCESS
1393 * Success.
1394 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001395 * The operation state is not valid (not set up, or already completed).
Gilles Peskinedcd14942018-07-12 00:30:52 +02001396 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1397 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1398 * \retval #PSA_ERROR_HARDWARE_FAILURE
1399 * \retval #PSA_ERROR_TAMPERING_DETECTED
1400 */
Gilles Peskine8c9def32018-02-08 10:02:12 +01001401psa_status_t psa_mac_update(psa_mac_operation_t *operation,
1402 const uint8_t *input,
1403 size_t input_length);
1404
Gilles Peskinedcd14942018-07-12 00:30:52 +02001405/** Finish the calculation of the MAC of a message.
1406 *
1407 * The application must call psa_mac_sign_setup() before calling this function.
1408 * This function calculates the MAC of the message formed by concatenating
1409 * the inputs passed to preceding calls to psa_mac_update().
1410 *
1411 * When this function returns, the operation becomes inactive.
1412 *
1413 * \warning Applications should not call this function if they expect
1414 * a specific value for the MAC. Call psa_mac_verify_finish() instead.
1415 * Beware that comparing integrity or authenticity data such as
1416 * MAC values with a function such as \c memcmp is risky
1417 * because the time taken by the comparison may leak information
1418 * about the MAC value which could allow an attacker to guess
1419 * a valid MAC and thereby bypass security controls.
1420 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001421 * \param[in,out] operation Active MAC operation.
1422 * \param[out] mac Buffer where the MAC value is to be written.
1423 * \param mac_size Size of the \p mac buffer in bytes.
1424 * \param[out] mac_length On success, the number of bytes
1425 * that make up the MAC value. This is always
Gilles Peskinedda3bd32018-07-12 19:40:46 +02001426 * #PSA_MAC_FINAL_SIZE(\c key_type, \c key_bits, \c alg)
Gilles Peskineedd11a12018-07-12 01:08:58 +02001427 * where \c key_type and \c key_bits are the type and
Gilles Peskinedda3bd32018-07-12 19:40:46 +02001428 * bit-size respectively of the key and \c alg is the
Gilles Peskineedd11a12018-07-12 01:08:58 +02001429 * MAC algorithm that is calculated.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001430 *
1431 * \retval #PSA_SUCCESS
1432 * Success.
1433 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001434 * The operation state is not valid (not set up, or already completed).
Gilles Peskinedcd14942018-07-12 00:30:52 +02001435 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001436 * The size of the \p mac buffer is too small. You can determine a
Gilles Peskinedcd14942018-07-12 00:30:52 +02001437 * sufficient buffer size by calling PSA_MAC_FINAL_SIZE().
1438 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1439 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1440 * \retval #PSA_ERROR_HARDWARE_FAILURE
1441 * \retval #PSA_ERROR_TAMPERING_DETECTED
1442 */
Gilles Peskineacd4be32018-07-08 19:56:25 +02001443psa_status_t psa_mac_sign_finish(psa_mac_operation_t *operation,
1444 uint8_t *mac,
1445 size_t mac_size,
1446 size_t *mac_length);
Gilles Peskine8c9def32018-02-08 10:02:12 +01001447
Gilles Peskinedcd14942018-07-12 00:30:52 +02001448/** Finish the calculation of the MAC of a message and compare it with
1449 * an expected value.
1450 *
1451 * The application must call psa_mac_verify_setup() before calling this function.
1452 * This function calculates the MAC of the message formed by concatenating
1453 * the inputs passed to preceding calls to psa_mac_update(). It then
1454 * compares the calculated MAC with the expected MAC passed as a
1455 * parameter to this function.
1456 *
1457 * When this function returns, the operation becomes inactive.
1458 *
1459 * \note Implementations shall make the best effort to ensure that the
1460 * comparison between the actual MAC and the expected MAC is performed
1461 * in constant time.
1462 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001463 * \param[in,out] operation Active MAC operation.
1464 * \param[in] mac Buffer containing the expected MAC value.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001465 * \param mac_length Size of the \p mac buffer in bytes.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001466 *
1467 * \retval #PSA_SUCCESS
1468 * The expected MAC is identical to the actual MAC of the message.
1469 * \retval #PSA_ERROR_INVALID_SIGNATURE
1470 * The MAC of the message was calculated successfully, but it
1471 * differs from the expected MAC.
1472 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001473 * The operation state is not valid (not set up, or already completed).
Gilles Peskinedcd14942018-07-12 00:30:52 +02001474 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1475 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1476 * \retval #PSA_ERROR_HARDWARE_FAILURE
1477 * \retval #PSA_ERROR_TAMPERING_DETECTED
1478 */
Gilles Peskineacd4be32018-07-08 19:56:25 +02001479psa_status_t psa_mac_verify_finish(psa_mac_operation_t *operation,
1480 const uint8_t *mac,
1481 size_t mac_length);
Gilles Peskine8c9def32018-02-08 10:02:12 +01001482
Gilles Peskinedcd14942018-07-12 00:30:52 +02001483/** Abort a MAC operation.
1484 *
Gilles Peskinedcd14942018-07-12 00:30:52 +02001485 * Aborting an operation frees all associated resources except for the
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001486 * \p operation structure itself. Once aborted, the operation object
1487 * can be reused for another operation by calling
1488 * psa_mac_sign_setup() or psa_mac_verify_setup() again.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001489 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001490 * You may call this function any time after the operation object has
1491 * been initialized by any of the following methods:
1492 * - A call to psa_mac_sign_setup() or psa_mac_verify_setup(), whether
1493 * it succeeds or not.
1494 * - Initializing the \c struct to all-bits-zero.
1495 * - Initializing the \c struct to logical zeros, e.g.
1496 * `psa_mac_operation_t operation = {0}`.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001497 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001498 * In particular, calling psa_mac_abort() after the operation has been
1499 * terminated by a call to psa_mac_abort(), psa_mac_sign_finish() or
1500 * psa_mac_verify_finish() is safe and has no effect.
1501 *
1502 * \param[in,out] operation Initialized MAC operation.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001503 *
1504 * \retval #PSA_SUCCESS
1505 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001506 * \p operation is not an active MAC operation.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001507 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1508 * \retval #PSA_ERROR_HARDWARE_FAILURE
1509 * \retval #PSA_ERROR_TAMPERING_DETECTED
1510 */
Gilles Peskine8c9def32018-02-08 10:02:12 +01001511psa_status_t psa_mac_abort(psa_mac_operation_t *operation);
1512
1513/**@}*/
1514
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001515/** \defgroup cipher Symmetric ciphers
1516 * @{
1517 */
1518
Gilles Peskine69647a42019-01-14 20:18:12 +01001519/** Encrypt a message using a symmetric cipher.
1520 *
1521 * This function encrypts a message with a random IV (initialization
1522 * vector).
1523 *
1524 * \param handle Handle to the key to use for the operation.
1525 * It must remain valid until the operation
1526 * terminates.
1527 * \param alg The cipher algorithm to compute
1528 * (\c PSA_ALG_XXX value such that
1529 * #PSA_ALG_IS_CIPHER(\p alg) is true).
1530 * \param[in] input Buffer containing the message to encrypt.
1531 * \param input_length Size of the \p input buffer in bytes.
1532 * \param[out] output Buffer where the output is to be written.
1533 * The output contains the IV followed by
1534 * the ciphertext proper.
1535 * \param output_size Size of the \p output buffer in bytes.
1536 * \param[out] output_length On success, the number of bytes
1537 * that make up the output.
1538 *
1539 * \retval #PSA_SUCCESS
1540 * Success.
1541 * \retval #PSA_ERROR_INVALID_HANDLE
1542 * \retval #PSA_ERROR_EMPTY_SLOT
1543 * \retval #PSA_ERROR_NOT_PERMITTED
1544 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001545 * \p handle is not compatible with \p alg.
Gilles Peskine69647a42019-01-14 20:18:12 +01001546 * \retval #PSA_ERROR_NOT_SUPPORTED
1547 * \p alg is not supported or is not a cipher algorithm.
1548 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
1549 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1550 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1551 * \retval #PSA_ERROR_HARDWARE_FAILURE
1552 * \retval #PSA_ERROR_TAMPERING_DETECTED
1553 */
1554psa_status_t psa_cipher_encrypt(psa_key_handle_t handle,
1555 psa_algorithm_t alg,
1556 const uint8_t *input,
1557 size_t input_length,
1558 uint8_t *output,
1559 size_t output_size,
1560 size_t *output_length);
1561
1562/** Decrypt a message using a symmetric cipher.
1563 *
1564 * This function decrypts a message encrypted with a symmetric cipher.
1565 *
1566 * \param handle Handle to the key to use for the operation.
1567 * It must remain valid until the operation
1568 * terminates.
1569 * \param alg The cipher algorithm to compute
1570 * (\c PSA_ALG_XXX value such that
1571 * #PSA_ALG_IS_CIPHER(\p alg) is true).
1572 * \param[in] input Buffer containing the message to decrypt.
1573 * This consists of the IV followed by the
1574 * ciphertext proper.
1575 * \param input_length Size of the \p input buffer in bytes.
1576 * \param[out] output Buffer where the plaintext is to be written.
1577 * \param output_size Size of the \p output buffer in bytes.
1578 * \param[out] output_length On success, the number of bytes
1579 * that make up the output.
1580 *
1581 * \retval #PSA_SUCCESS
1582 * Success.
1583 * \retval #PSA_ERROR_INVALID_HANDLE
1584 * \retval #PSA_ERROR_EMPTY_SLOT
1585 * \retval #PSA_ERROR_NOT_PERMITTED
1586 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001587 * \p handle is not compatible with \p alg.
Gilles Peskine69647a42019-01-14 20:18:12 +01001588 * \retval #PSA_ERROR_NOT_SUPPORTED
1589 * \p alg is not supported or is not a cipher algorithm.
1590 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
1591 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1592 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1593 * \retval #PSA_ERROR_HARDWARE_FAILURE
1594 * \retval #PSA_ERROR_TAMPERING_DETECTED
1595 */
1596psa_status_t psa_cipher_decrypt(psa_key_handle_t handle,
1597 psa_algorithm_t alg,
1598 const uint8_t *input,
1599 size_t input_length,
1600 uint8_t *output,
1601 size_t output_size,
1602 size_t *output_length);
1603
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001604/** The type of the state data structure for multipart cipher operations.
1605 *
Jaeden Amero5bae2272019-01-04 11:48:27 +00001606 * Before calling any function on a cipher operation object, the application
1607 * must initialize it by any of the following means:
1608 * - Set the structure to all-bits-zero, for example:
1609 * \code
1610 * psa_cipher_operation_t operation;
1611 * memset(&operation, 0, sizeof(operation));
1612 * \endcode
1613 * - Initialize the structure to logical zero values, for example:
1614 * \code
1615 * psa_cipher_operation_t operation = {0};
1616 * \endcode
1617 * - Initialize the structure to the initializer #PSA_CIPHER_OPERATION_INIT,
1618 * for example:
1619 * \code
1620 * psa_cipher_operation_t operation = PSA_CIPHER_OPERATION_INIT;
1621 * \endcode
1622 * - Assign the result of the function psa_cipher_operation_init()
1623 * to the structure, for example:
1624 * \code
1625 * psa_cipher_operation_t operation;
1626 * operation = psa_cipher_operation_init();
1627 * \endcode
1628 *
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001629 * This is an implementation-defined \c struct. Applications should not
1630 * make any assumptions about the content of this structure except
1631 * as directed by the documentation of a specific implementation. */
1632typedef struct psa_cipher_operation_s psa_cipher_operation_t;
1633
Jaeden Amero5bae2272019-01-04 11:48:27 +00001634/** \def PSA_CIPHER_OPERATION_INIT
1635 *
1636 * This macro returns a suitable initializer for a cipher operation object of
1637 * type #psa_cipher_operation_t.
1638 */
1639#ifdef __DOXYGEN_ONLY__
1640/* This is an example definition for documentation purposes.
1641 * Implementations should define a suitable value in `crypto_struct.h`.
1642 */
1643#define PSA_CIPHER_OPERATION_INIT {0}
1644#endif
1645
1646/** Return an initial value for a cipher operation object.
1647 */
1648static psa_cipher_operation_t psa_cipher_operation_init(void);
1649
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001650/** Set the key for a multipart symmetric encryption operation.
1651 *
1652 * The sequence of operations to encrypt a message with a symmetric cipher
1653 * is as follows:
1654 * -# Allocate an operation object which will be passed to all the functions
1655 * listed here.
Jaeden Amero5bae2272019-01-04 11:48:27 +00001656 * -# Initialize the operation object with one of the methods described in the
1657 * documentation for #psa_cipher_operation_t, e.g.
1658 * PSA_CIPHER_OPERATION_INIT.
Gilles Peskinefe119512018-07-08 21:39:34 +02001659 * -# Call psa_cipher_encrypt_setup() to specify the algorithm and key.
itayzafrired7382f2018-08-02 14:19:33 +03001660 * -# Call either psa_cipher_generate_iv() or psa_cipher_set_iv() to
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001661 * generate or set the IV (initialization vector). You should use
itayzafrired7382f2018-08-02 14:19:33 +03001662 * psa_cipher_generate_iv() unless the protocol you are implementing
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001663 * requires a specific IV value.
1664 * -# Call psa_cipher_update() zero, one or more times, passing a fragment
1665 * of the message each time.
1666 * -# Call psa_cipher_finish().
1667 *
1668 * The application may call psa_cipher_abort() at any time after the operation
Jaeden Amero5bae2272019-01-04 11:48:27 +00001669 * has been initialized.
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001670 *
Gilles Peskinefe119512018-07-08 21:39:34 +02001671 * After a successful call to psa_cipher_encrypt_setup(), the application must
Gilles Peskineed522972018-03-20 17:54:15 +01001672 * eventually terminate the operation. The following events terminate an
1673 * operation:
Gilles Peskinef45adda2019-01-14 18:29:18 +01001674 * - A failed call to any of the \c psa_cipher_xxx functions.
Gilles Peskine19067982018-03-20 17:54:53 +01001675 * - A call to psa_cipher_finish() or psa_cipher_abort().
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001676 *
Jaeden Amero5bae2272019-01-04 11:48:27 +00001677 * \param[in,out] operation The operation object to set up. It must have
1678 * been initialized as per the documentation for
1679 * #psa_cipher_operation_t and not yet in use.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001680 * \param handle Handle to the key to use for the operation.
Gilles Peskine5f25dd02019-01-14 18:24:53 +01001681 * It must remain valid until the operation
1682 * terminates.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001683 * \param alg The cipher algorithm to compute
1684 * (\c PSA_ALG_XXX value such that
1685 * #PSA_ALG_IS_CIPHER(\p alg) is true).
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001686 *
Gilles Peskine28538492018-07-11 17:34:00 +02001687 * \retval #PSA_SUCCESS
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001688 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001689 * \retval #PSA_ERROR_INVALID_HANDLE
David Saadab4ecc272019-02-14 13:48:10 +02001690 * \retval #PSA_ERROR_DOES_NOT_EXIST
Gilles Peskine28538492018-07-11 17:34:00 +02001691 * \retval #PSA_ERROR_NOT_PERMITTED
1692 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001693 * \p handle is not compatible with \p alg.
Gilles Peskine28538492018-07-11 17:34:00 +02001694 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001695 * \p alg is not supported or is not a cipher algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02001696 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1697 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1698 * \retval #PSA_ERROR_HARDWARE_FAILURE
1699 * \retval #PSA_ERROR_TAMPERING_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03001700 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskine8e1addc2019-01-10 11:51:17 +01001701 * The operation state is not valid (already set up and not
1702 * subsequently completed).
1703 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03001704 * The library has not been previously initialized by psa_crypto_init().
1705 * It is implementation-dependent whether a failure to initialize
1706 * results in this error code.
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001707 */
Gilles Peskinefe119512018-07-08 21:39:34 +02001708psa_status_t psa_cipher_encrypt_setup(psa_cipher_operation_t *operation,
Gilles Peskineae32aac2018-11-30 14:39:32 +01001709 psa_key_handle_t handle,
Gilles Peskinefe119512018-07-08 21:39:34 +02001710 psa_algorithm_t alg);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001711
1712/** Set the key for a multipart symmetric decryption operation.
1713 *
1714 * The sequence of operations to decrypt a message with a symmetric cipher
1715 * is as follows:
1716 * -# Allocate an operation object which will be passed to all the functions
1717 * listed here.
Jaeden Amero5bae2272019-01-04 11:48:27 +00001718 * -# Initialize the operation object with one of the methods described in the
1719 * documentation for #psa_cipher_operation_t, e.g.
1720 * PSA_CIPHER_OPERATION_INIT.
Gilles Peskinefe119512018-07-08 21:39:34 +02001721 * -# Call psa_cipher_decrypt_setup() to specify the algorithm and key.
Gilles Peskinef45adda2019-01-14 18:29:18 +01001722 * -# Call psa_cipher_set_iv() with the IV (initialization vector) for the
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001723 * decryption. If the IV is prepended to the ciphertext, you can call
1724 * psa_cipher_update() on a buffer containing the IV followed by the
1725 * beginning of the message.
1726 * -# Call psa_cipher_update() zero, one or more times, passing a fragment
1727 * of the message each time.
1728 * -# Call psa_cipher_finish().
1729 *
1730 * The application may call psa_cipher_abort() at any time after the operation
Jaeden Amero5bae2272019-01-04 11:48:27 +00001731 * has been initialized.
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001732 *
Gilles Peskinefe119512018-07-08 21:39:34 +02001733 * After a successful call to psa_cipher_decrypt_setup(), the application must
Gilles Peskineed522972018-03-20 17:54:15 +01001734 * eventually terminate the operation. The following events terminate an
1735 * operation:
Gilles Peskinef45adda2019-01-14 18:29:18 +01001736 * - A failed call to any of the \c psa_cipher_xxx functions.
Gilles Peskine19067982018-03-20 17:54:53 +01001737 * - A call to psa_cipher_finish() or psa_cipher_abort().
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001738 *
Jaeden Amero5bae2272019-01-04 11:48:27 +00001739 * \param[in,out] operation The operation object to set up. It must have
1740 * been initialized as per the documentation for
1741 * #psa_cipher_operation_t and not yet in use.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001742 * \param handle Handle to the key to use for the operation.
Gilles Peskine5f25dd02019-01-14 18:24:53 +01001743 * It must remain valid until the operation
1744 * terminates.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001745 * \param alg The cipher algorithm to compute
1746 * (\c PSA_ALG_XXX value such that
1747 * #PSA_ALG_IS_CIPHER(\p alg) is true).
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001748 *
Gilles Peskine28538492018-07-11 17:34:00 +02001749 * \retval #PSA_SUCCESS
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001750 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001751 * \retval #PSA_ERROR_INVALID_HANDLE
David Saadab4ecc272019-02-14 13:48:10 +02001752 * \retval #PSA_ERROR_DOES_NOT_EXIST
Gilles Peskine28538492018-07-11 17:34:00 +02001753 * \retval #PSA_ERROR_NOT_PERMITTED
1754 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001755 * \p handle is not compatible with \p alg.
Gilles Peskine28538492018-07-11 17:34:00 +02001756 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001757 * \p alg is not supported or is not a cipher algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02001758 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1759 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1760 * \retval #PSA_ERROR_HARDWARE_FAILURE
1761 * \retval #PSA_ERROR_TAMPERING_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03001762 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskine8e1addc2019-01-10 11:51:17 +01001763 * The operation state is not valid (already set up and not
1764 * subsequently completed).
1765 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03001766 * The library has not been previously initialized by psa_crypto_init().
1767 * It is implementation-dependent whether a failure to initialize
1768 * results in this error code.
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001769 */
Gilles Peskinefe119512018-07-08 21:39:34 +02001770psa_status_t psa_cipher_decrypt_setup(psa_cipher_operation_t *operation,
Gilles Peskineae32aac2018-11-30 14:39:32 +01001771 psa_key_handle_t handle,
Gilles Peskinefe119512018-07-08 21:39:34 +02001772 psa_algorithm_t alg);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001773
Gilles Peskinedcd14942018-07-12 00:30:52 +02001774/** Generate an IV for a symmetric encryption operation.
1775 *
1776 * This function generates a random IV (initialization vector), nonce
1777 * or initial counter value for the encryption operation as appropriate
1778 * for the chosen algorithm, key type and key size.
1779 *
1780 * The application must call psa_cipher_encrypt_setup() before
1781 * calling this function.
1782 *
1783 * If this function returns an error status, the operation becomes inactive.
1784 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001785 * \param[in,out] operation Active cipher operation.
1786 * \param[out] iv Buffer where the generated IV is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001787 * \param iv_size Size of the \p iv buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001788 * \param[out] iv_length On success, the number of bytes of the
1789 * generated IV.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001790 *
1791 * \retval #PSA_SUCCESS
1792 * Success.
1793 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001794 * The operation state is not valid (not set up, or IV already set).
Gilles Peskinedcd14942018-07-12 00:30:52 +02001795 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinedda3bd32018-07-12 19:40:46 +02001796 * The size of the \p iv buffer is too small.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001797 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1798 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1799 * \retval #PSA_ERROR_HARDWARE_FAILURE
1800 * \retval #PSA_ERROR_TAMPERING_DETECTED
1801 */
Gilles Peskinefe119512018-07-08 21:39:34 +02001802psa_status_t psa_cipher_generate_iv(psa_cipher_operation_t *operation,
1803 unsigned char *iv,
1804 size_t iv_size,
1805 size_t *iv_length);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001806
Gilles Peskinedcd14942018-07-12 00:30:52 +02001807/** Set the IV for a symmetric encryption or decryption operation.
1808 *
Gilles Peskinef45adda2019-01-14 18:29:18 +01001809 * This function sets the IV (initialization vector), nonce
Gilles Peskinedcd14942018-07-12 00:30:52 +02001810 * or initial counter value for the encryption or decryption operation.
1811 *
1812 * The application must call psa_cipher_encrypt_setup() before
1813 * calling this function.
1814 *
1815 * If this function returns an error status, the operation becomes inactive.
1816 *
1817 * \note When encrypting, applications should use psa_cipher_generate_iv()
1818 * instead of this function, unless implementing a protocol that requires
1819 * a non-random IV.
1820 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001821 * \param[in,out] operation Active cipher operation.
1822 * \param[in] iv Buffer containing the IV to use.
1823 * \param iv_length Size of the IV in bytes.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001824 *
1825 * \retval #PSA_SUCCESS
1826 * Success.
1827 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001828 * The operation state is not valid (not set up, or IV already set).
Gilles Peskinedcd14942018-07-12 00:30:52 +02001829 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001830 * The size of \p iv is not acceptable for the chosen algorithm,
Gilles Peskinedcd14942018-07-12 00:30:52 +02001831 * or the chosen algorithm does not use an IV.
1832 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1833 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1834 * \retval #PSA_ERROR_HARDWARE_FAILURE
1835 * \retval #PSA_ERROR_TAMPERING_DETECTED
1836 */
Gilles Peskinefe119512018-07-08 21:39:34 +02001837psa_status_t psa_cipher_set_iv(psa_cipher_operation_t *operation,
1838 const unsigned char *iv,
1839 size_t iv_length);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001840
Gilles Peskinedcd14942018-07-12 00:30:52 +02001841/** Encrypt or decrypt a message fragment in an active cipher operation.
1842 *
Gilles Peskine9ac94262018-07-12 20:15:32 +02001843 * Before calling this function, you must:
1844 * 1. Call either psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup().
1845 * The choice of setup function determines whether this function
1846 * encrypts or decrypts its input.
1847 * 2. If the algorithm requires an IV, call psa_cipher_generate_iv()
1848 * (recommended when encrypting) or psa_cipher_set_iv().
Gilles Peskinedcd14942018-07-12 00:30:52 +02001849 *
1850 * If this function returns an error status, the operation becomes inactive.
1851 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001852 * \param[in,out] operation Active cipher operation.
1853 * \param[in] input Buffer containing the message fragment to
1854 * encrypt or decrypt.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001855 * \param input_length Size of the \p input buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001856 * \param[out] output Buffer where the output is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001857 * \param output_size Size of the \p output buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001858 * \param[out] output_length On success, the number of bytes
1859 * that make up the returned output.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001860 *
1861 * \retval #PSA_SUCCESS
1862 * Success.
1863 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001864 * The operation state is not valid (not set up, IV required but
Gilles Peskinedcd14942018-07-12 00:30:52 +02001865 * not set, or already completed).
1866 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
1867 * The size of the \p output buffer is too small.
1868 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1869 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1870 * \retval #PSA_ERROR_HARDWARE_FAILURE
1871 * \retval #PSA_ERROR_TAMPERING_DETECTED
1872 */
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001873psa_status_t psa_cipher_update(psa_cipher_operation_t *operation,
1874 const uint8_t *input,
mohammad1603503973b2018-03-12 15:59:30 +02001875 size_t input_length,
Gilles Peskine2d277862018-06-18 15:41:12 +02001876 unsigned char *output,
1877 size_t output_size,
mohammad1603503973b2018-03-12 15:59:30 +02001878 size_t *output_length);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001879
Gilles Peskinedcd14942018-07-12 00:30:52 +02001880/** Finish encrypting or decrypting a message in a cipher operation.
1881 *
1882 * The application must call psa_cipher_encrypt_setup() or
1883 * psa_cipher_decrypt_setup() before calling this function. The choice
1884 * of setup function determines whether this function encrypts or
1885 * decrypts its input.
1886 *
1887 * This function finishes the encryption or decryption of the message
1888 * formed by concatenating the inputs passed to preceding calls to
1889 * psa_cipher_update().
1890 *
1891 * When this function returns, the operation becomes inactive.
1892 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001893 * \param[in,out] operation Active cipher operation.
1894 * \param[out] output Buffer where the output is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001895 * \param output_size Size of the \p output buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001896 * \param[out] output_length On success, the number of bytes
1897 * that make up the returned output.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001898 *
1899 * \retval #PSA_SUCCESS
1900 * Success.
1901 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001902 * The operation state is not valid (not set up, IV required but
Gilles Peskinedcd14942018-07-12 00:30:52 +02001903 * not set, or already completed).
1904 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
1905 * The size of the \p output buffer is too small.
1906 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1907 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1908 * \retval #PSA_ERROR_HARDWARE_FAILURE
1909 * \retval #PSA_ERROR_TAMPERING_DETECTED
1910 */
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001911psa_status_t psa_cipher_finish(psa_cipher_operation_t *operation,
mohammad1603503973b2018-03-12 15:59:30 +02001912 uint8_t *output,
Moran Peker0071b872018-04-22 20:16:58 +03001913 size_t output_size,
mohammad1603503973b2018-03-12 15:59:30 +02001914 size_t *output_length);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001915
Gilles Peskinedcd14942018-07-12 00:30:52 +02001916/** Abort a cipher operation.
1917 *
Gilles Peskinedcd14942018-07-12 00:30:52 +02001918 * Aborting an operation frees all associated resources except for the
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001919 * \p operation structure itself. Once aborted, the operation object
1920 * can be reused for another operation by calling
1921 * psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup() again.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001922 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001923 * You may call this function any time after the operation object has
1924 * been initialized by any of the following methods:
1925 * - A call to psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup(),
1926 * whether it succeeds or not.
1927 * - Initializing the \c struct to all-bits-zero.
1928 * - Initializing the \c struct to logical zeros, e.g.
1929 * `psa_cipher_operation_t operation = {0}`.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001930 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001931 * In particular, calling psa_cipher_abort() after the operation has been
1932 * terminated by a call to psa_cipher_abort() or psa_cipher_finish()
1933 * is safe and has no effect.
1934 *
1935 * \param[in,out] operation Initialized cipher operation.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001936 *
1937 * \retval #PSA_SUCCESS
1938 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001939 * \p operation is not an active cipher operation.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001940 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1941 * \retval #PSA_ERROR_HARDWARE_FAILURE
1942 * \retval #PSA_ERROR_TAMPERING_DETECTED
1943 */
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001944psa_status_t psa_cipher_abort(psa_cipher_operation_t *operation);
1945
1946/**@}*/
1947
Gilles Peskine3b555712018-03-03 21:27:57 +01001948/** \defgroup aead Authenticated encryption with associated data (AEAD)
1949 * @{
1950 */
1951
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02001952/** Process an authenticated encryption operation.
Gilles Peskine3b555712018-03-03 21:27:57 +01001953 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01001954 * \param handle Handle to the key to use for the operation.
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02001955 * \param alg The AEAD algorithm to compute
1956 * (\c PSA_ALG_XXX value such that
Gilles Peskine7256e6c2018-07-12 00:34:26 +02001957 * #PSA_ALG_IS_AEAD(\p alg) is true).
Gilles Peskineedd11a12018-07-12 01:08:58 +02001958 * \param[in] nonce Nonce or IV to use.
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02001959 * \param nonce_length Size of the \p nonce buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001960 * \param[in] additional_data Additional data that will be authenticated
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02001961 * but not encrypted.
1962 * \param additional_data_length Size of \p additional_data in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001963 * \param[in] plaintext Data that will be authenticated and
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02001964 * encrypted.
1965 * \param plaintext_length Size of \p plaintext in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001966 * \param[out] ciphertext Output buffer for the authenticated and
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02001967 * encrypted data. The additional data is not
1968 * part of this output. For algorithms where the
1969 * encrypted data and the authentication tag
1970 * are defined as separate outputs, the
1971 * authentication tag is appended to the
1972 * encrypted data.
1973 * \param ciphertext_size Size of the \p ciphertext buffer in bytes.
1974 * This must be at least
1975 * #PSA_AEAD_ENCRYPT_OUTPUT_SIZE(\p alg,
1976 * \p plaintext_length).
Gilles Peskineedd11a12018-07-12 01:08:58 +02001977 * \param[out] ciphertext_length On success, the size of the output
Gilles Peskine4c6fdbb2019-02-08 11:22:39 +01001978 * in the \p ciphertext buffer.
Gilles Peskine3b555712018-03-03 21:27:57 +01001979 *
Gilles Peskine28538492018-07-11 17:34:00 +02001980 * \retval #PSA_SUCCESS
Gilles Peskine3b555712018-03-03 21:27:57 +01001981 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001982 * \retval #PSA_ERROR_INVALID_HANDLE
David Saadab4ecc272019-02-14 13:48:10 +02001983 * \retval #PSA_ERROR_DOES_NOT_EXIST
Gilles Peskine28538492018-07-11 17:34:00 +02001984 * \retval #PSA_ERROR_NOT_PERMITTED
1985 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01001986 * \p handle is not compatible with \p alg.
Gilles Peskine28538492018-07-11 17:34:00 +02001987 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001988 * \p alg is not supported or is not an AEAD algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02001989 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1990 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1991 * \retval #PSA_ERROR_HARDWARE_FAILURE
1992 * \retval #PSA_ERROR_TAMPERING_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03001993 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03001994 * The library has not been previously initialized by psa_crypto_init().
1995 * It is implementation-dependent whether a failure to initialize
1996 * results in this error code.
Gilles Peskine3b555712018-03-03 21:27:57 +01001997 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01001998psa_status_t psa_aead_encrypt(psa_key_handle_t handle,
Gilles Peskine9fb0e012018-07-19 15:51:49 +02001999 psa_algorithm_t alg,
2000 const uint8_t *nonce,
2001 size_t nonce_length,
2002 const uint8_t *additional_data,
2003 size_t additional_data_length,
2004 const uint8_t *plaintext,
2005 size_t plaintext_length,
2006 uint8_t *ciphertext,
2007 size_t ciphertext_size,
2008 size_t *ciphertext_length);
Gilles Peskine3b555712018-03-03 21:27:57 +01002009
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002010/** Process an authenticated decryption operation.
Gilles Peskine3b555712018-03-03 21:27:57 +01002011 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01002012 * \param handle Handle to the key to use for the operation.
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002013 * \param alg The AEAD algorithm to compute
2014 * (\c PSA_ALG_XXX value such that
Gilles Peskine7256e6c2018-07-12 00:34:26 +02002015 * #PSA_ALG_IS_AEAD(\p alg) is true).
Gilles Peskineedd11a12018-07-12 01:08:58 +02002016 * \param[in] nonce Nonce or IV to use.
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002017 * \param nonce_length Size of the \p nonce buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002018 * \param[in] additional_data Additional data that has been authenticated
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002019 * but not encrypted.
2020 * \param additional_data_length Size of \p additional_data in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002021 * \param[in] ciphertext Data that has been authenticated and
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002022 * encrypted. For algorithms where the
2023 * encrypted data and the authentication tag
2024 * are defined as separate inputs, the buffer
2025 * must contain the encrypted data followed
2026 * by the authentication tag.
2027 * \param ciphertext_length Size of \p ciphertext in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002028 * \param[out] plaintext Output buffer for the decrypted data.
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002029 * \param plaintext_size Size of the \p plaintext buffer in bytes.
2030 * This must be at least
2031 * #PSA_AEAD_DECRYPT_OUTPUT_SIZE(\p alg,
2032 * \p ciphertext_length).
Gilles Peskineedd11a12018-07-12 01:08:58 +02002033 * \param[out] plaintext_length On success, the size of the output
Gilles Peskine4c6fdbb2019-02-08 11:22:39 +01002034 * in the \p plaintext buffer.
Gilles Peskine3b555712018-03-03 21:27:57 +01002035 *
Gilles Peskine28538492018-07-11 17:34:00 +02002036 * \retval #PSA_SUCCESS
Gilles Peskine3b555712018-03-03 21:27:57 +01002037 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01002038 * \retval #PSA_ERROR_INVALID_HANDLE
David Saadab4ecc272019-02-14 13:48:10 +02002039 * \retval #PSA_ERROR_DOES_NOT_EXIST
Gilles Peskine28538492018-07-11 17:34:00 +02002040 * \retval #PSA_ERROR_INVALID_SIGNATURE
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02002041 * The ciphertext is not authentic.
Gilles Peskine28538492018-07-11 17:34:00 +02002042 * \retval #PSA_ERROR_NOT_PERMITTED
2043 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002044 * \p handle is not compatible with \p alg.
Gilles Peskine28538492018-07-11 17:34:00 +02002045 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002046 * \p alg is not supported or is not an AEAD algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02002047 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2048 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2049 * \retval #PSA_ERROR_HARDWARE_FAILURE
2050 * \retval #PSA_ERROR_TAMPERING_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03002051 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03002052 * The library has not been previously initialized by psa_crypto_init().
2053 * It is implementation-dependent whether a failure to initialize
2054 * results in this error code.
Gilles Peskine3b555712018-03-03 21:27:57 +01002055 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01002056psa_status_t psa_aead_decrypt(psa_key_handle_t handle,
Gilles Peskine9fb0e012018-07-19 15:51:49 +02002057 psa_algorithm_t alg,
2058 const uint8_t *nonce,
2059 size_t nonce_length,
2060 const uint8_t *additional_data,
2061 size_t additional_data_length,
2062 const uint8_t *ciphertext,
2063 size_t ciphertext_length,
2064 uint8_t *plaintext,
2065 size_t plaintext_size,
2066 size_t *plaintext_length);
Gilles Peskine3b555712018-03-03 21:27:57 +01002067
Gilles Peskine30a9e412019-01-14 18:36:12 +01002068/** The type of the state data structure for multipart AEAD operations.
2069 *
2070 * Before calling any function on an AEAD operation object, the application
2071 * must initialize it by any of the following means:
2072 * - Set the structure to all-bits-zero, for example:
2073 * \code
2074 * psa_aead_operation_t operation;
2075 * memset(&operation, 0, sizeof(operation));
2076 * \endcode
2077 * - Initialize the structure to logical zero values, for example:
2078 * \code
2079 * psa_aead_operation_t operation = {0};
2080 * \endcode
2081 * - Initialize the structure to the initializer #PSA_AEAD_OPERATION_INIT,
2082 * for example:
2083 * \code
2084 * psa_aead_operation_t operation = PSA_AEAD_OPERATION_INIT;
2085 * \endcode
2086 * - Assign the result of the function psa_aead_operation_init()
2087 * to the structure, for example:
2088 * \code
2089 * psa_aead_operation_t operation;
2090 * operation = psa_aead_operation_init();
2091 * \endcode
2092 *
2093 * This is an implementation-defined \c struct. Applications should not
2094 * make any assumptions about the content of this structure except
2095 * as directed by the documentation of a specific implementation. */
2096typedef struct psa_aead_operation_s psa_aead_operation_t;
2097
2098/** \def PSA_AEAD_OPERATION_INIT
2099 *
2100 * This macro returns a suitable initializer for an AEAD operation object of
2101 * type #psa_aead_operation_t.
2102 */
2103#ifdef __DOXYGEN_ONLY__
2104/* This is an example definition for documentation purposes.
2105 * Implementations should define a suitable value in `crypto_struct.h`.
2106 */
2107#define PSA_AEAD_OPERATION_INIT {0}
2108#endif
2109
2110/** Return an initial value for an AEAD operation object.
2111 */
2112static psa_aead_operation_t psa_aead_operation_init(void);
2113
2114/** Set the key for a multipart authenticated encryption operation.
2115 *
2116 * The sequence of operations to encrypt a message with authentication
2117 * is as follows:
2118 * -# Allocate an operation object which will be passed to all the functions
2119 * listed here.
2120 * -# Initialize the operation object with one of the methods described in the
2121 * documentation for #psa_aead_operation_t, e.g.
2122 * PSA_AEAD_OPERATION_INIT.
2123 * -# Call psa_aead_encrypt_setup() to specify the algorithm and key.
Gilles Peskinebc59c852019-01-17 15:26:08 +01002124 * -# If needed, call psa_aead_set_lengths() to specify the length of the
2125 * inputs to the subsequent calls to psa_aead_update_ad() and
2126 * psa_aead_update(). See the documentation of psa_aead_set_lengths()
2127 * for details.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002128 * -# Call either psa_aead_generate_nonce() or psa_aead_set_nonce() to
2129 * generate or set the nonce. You should use
2130 * psa_aead_generate_nonce() unless the protocol you are implementing
2131 * requires a specific nonce value.
2132 * -# Call psa_aead_update_ad() zero, one or more times, passing a fragment
2133 * of the non-encrypted additional authenticated data each time.
2134 * -# Call psa_aead_update() zero, one or more times, passing a fragment
Gilles Peskinea05602d2019-01-17 15:25:52 +01002135 * of the message to encrypt each time.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002136 * -# Call psa_aead_finish().
2137 *
2138 * The application may call psa_aead_abort() at any time after the operation
2139 * has been initialized.
2140 *
2141 * After a successful call to psa_aead_encrypt_setup(), the application must
2142 * eventually terminate the operation. The following events terminate an
2143 * operation:
2144 * - A failed call to any of the \c psa_aead_xxx functions.
2145 * - A call to psa_aead_finish(), psa_aead_verify() or psa_aead_abort().
2146 *
2147 * \param[in,out] operation The operation object to set up. It must have
2148 * been initialized as per the documentation for
2149 * #psa_aead_operation_t and not yet in use.
2150 * \param handle Handle to the key to use for the operation.
2151 * It must remain valid until the operation
2152 * terminates.
2153 * \param alg The AEAD algorithm to compute
2154 * (\c PSA_ALG_XXX value such that
2155 * #PSA_ALG_IS_AEAD(\p alg) is true).
2156 *
2157 * \retval #PSA_SUCCESS
2158 * Success.
2159 * \retval #PSA_ERROR_INVALID_HANDLE
2160 * \retval #PSA_ERROR_EMPTY_SLOT
2161 * \retval #PSA_ERROR_NOT_PERMITTED
2162 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002163 * \p handle is not compatible with \p alg.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002164 * \retval #PSA_ERROR_NOT_SUPPORTED
2165 * \p alg is not supported or is not an AEAD algorithm.
2166 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2167 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2168 * \retval #PSA_ERROR_HARDWARE_FAILURE
2169 * \retval #PSA_ERROR_TAMPERING_DETECTED
2170 * \retval #PSA_ERROR_BAD_STATE
2171 * The library has not been previously initialized by psa_crypto_init().
2172 * It is implementation-dependent whether a failure to initialize
2173 * results in this error code.
2174 */
2175psa_status_t psa_aead_encrypt_setup(psa_aead_operation_t *operation,
2176 psa_key_handle_t handle,
2177 psa_algorithm_t alg);
2178
2179/** Set the key for a multipart authenticated decryption operation.
2180 *
2181 * The sequence of operations to decrypt a message with authentication
2182 * is as follows:
2183 * -# Allocate an operation object which will be passed to all the functions
2184 * listed here.
2185 * -# Initialize the operation object with one of the methods described in the
2186 * documentation for #psa_aead_operation_t, e.g.
2187 * PSA_AEAD_OPERATION_INIT.
2188 * -# Call psa_aead_decrypt_setup() to specify the algorithm and key.
Gilles Peskinebc59c852019-01-17 15:26:08 +01002189 * -# If needed, call psa_aead_set_lengths() to specify the length of the
2190 * inputs to the subsequent calls to psa_aead_update_ad() and
2191 * psa_aead_update(). See the documentation of psa_aead_set_lengths()
2192 * for details.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002193 * -# Call psa_aead_set_nonce() with the nonce for the decryption.
2194 * -# Call psa_aead_update_ad() zero, one or more times, passing a fragment
2195 * of the non-encrypted additional authenticated data each time.
2196 * -# Call psa_aead_update() zero, one or more times, passing a fragment
Gilles Peskinea05602d2019-01-17 15:25:52 +01002197 * of the ciphertext to decrypt each time.
2198 * -# Call psa_aead_verify().
Gilles Peskine30a9e412019-01-14 18:36:12 +01002199 *
2200 * The application may call psa_aead_abort() at any time after the operation
2201 * has been initialized.
2202 *
2203 * After a successful call to psa_aead_decrypt_setup(), the application must
2204 * eventually terminate the operation. The following events terminate an
2205 * operation:
2206 * - A failed call to any of the \c psa_aead_xxx functions.
2207 * - A call to psa_aead_finish(), psa_aead_verify() or psa_aead_abort().
2208 *
2209 * \param[in,out] operation The operation object to set up. It must have
2210 * been initialized as per the documentation for
2211 * #psa_aead_operation_t and not yet in use.
2212 * \param handle Handle to the key to use for the operation.
2213 * It must remain valid until the operation
2214 * terminates.
2215 * \param alg The AEAD algorithm to compute
2216 * (\c PSA_ALG_XXX value such that
2217 * #PSA_ALG_IS_AEAD(\p alg) is true).
2218 *
2219 * \retval #PSA_SUCCESS
2220 * Success.
2221 * \retval #PSA_ERROR_INVALID_HANDLE
2222 * \retval #PSA_ERROR_EMPTY_SLOT
2223 * \retval #PSA_ERROR_NOT_PERMITTED
2224 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002225 * \p handle is not compatible with \p alg.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002226 * \retval #PSA_ERROR_NOT_SUPPORTED
2227 * \p alg is not supported or is not an AEAD algorithm.
2228 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2229 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2230 * \retval #PSA_ERROR_HARDWARE_FAILURE
2231 * \retval #PSA_ERROR_TAMPERING_DETECTED
2232 * \retval #PSA_ERROR_BAD_STATE
2233 * The library has not been previously initialized by psa_crypto_init().
2234 * It is implementation-dependent whether a failure to initialize
2235 * results in this error code.
2236 */
2237psa_status_t psa_aead_decrypt_setup(psa_aead_operation_t *operation,
2238 psa_key_handle_t handle,
2239 psa_algorithm_t alg);
2240
2241/** Generate a random nonce for an authenticated encryption operation.
2242 *
2243 * This function generates a random nonce for the authenticated encryption
2244 * operation with an appropriate size for the chosen algorithm, key type
2245 * and key size.
2246 *
2247 * The application must call psa_aead_encrypt_setup() before
2248 * calling this function.
2249 *
2250 * If this function returns an error status, the operation becomes inactive.
2251 *
2252 * \param[in,out] operation Active AEAD operation.
2253 * \param[out] nonce Buffer where the generated nonce is to be
2254 * written.
2255 * \param nonce_size Size of the \p nonce buffer in bytes.
2256 * \param[out] nonce_length On success, the number of bytes of the
2257 * generated nonce.
2258 *
2259 * \retval #PSA_SUCCESS
2260 * Success.
2261 * \retval #PSA_ERROR_BAD_STATE
2262 * The operation state is not valid (not set up, or nonce already set).
2263 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
2264 * The size of the \p nonce buffer is too small.
2265 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2266 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2267 * \retval #PSA_ERROR_HARDWARE_FAILURE
2268 * \retval #PSA_ERROR_TAMPERING_DETECTED
2269 */
2270psa_status_t psa_aead_generate_nonce(psa_aead_operation_t *operation,
2271 unsigned char *nonce,
2272 size_t nonce_size,
2273 size_t *nonce_length);
2274
2275/** Set the nonce for an authenticated encryption or decryption operation.
2276 *
2277 * This function sets the nonce for the authenticated
2278 * encryption or decryption operation.
2279 *
2280 * The application must call psa_aead_encrypt_setup() before
2281 * calling this function.
2282 *
2283 * If this function returns an error status, the operation becomes inactive.
2284 *
Gilles Peskinea05602d2019-01-17 15:25:52 +01002285 * \note When encrypting, applications should use psa_aead_generate_nonce()
Gilles Peskine30a9e412019-01-14 18:36:12 +01002286 * instead of this function, unless implementing a protocol that requires
2287 * a non-random IV.
2288 *
2289 * \param[in,out] operation Active AEAD operation.
Gilles Peskinea05602d2019-01-17 15:25:52 +01002290 * \param[in] nonce Buffer containing the nonce to use.
2291 * \param nonce_length Size of the nonce in bytes.
Gilles Peskine30a9e412019-01-14 18:36:12 +01002292 *
2293 * \retval #PSA_SUCCESS
2294 * Success.
2295 * \retval #PSA_ERROR_BAD_STATE
2296 * The operation state is not valid (not set up, or nonce already set).
2297 * \retval #PSA_ERROR_INVALID_ARGUMENT
2298 * The size of \p nonce is not acceptable for the chosen algorithm.
2299 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2300 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2301 * \retval #PSA_ERROR_HARDWARE_FAILURE
2302 * \retval #PSA_ERROR_TAMPERING_DETECTED
2303 */
2304psa_status_t psa_aead_set_nonce(psa_aead_operation_t *operation,
2305 const unsigned char *nonce,
2306 size_t nonce_length);
2307
Gilles Peskinebc59c852019-01-17 15:26:08 +01002308/** Declare the lengths of the message and additional data for AEAD.
2309 *
2310 * The application must call this function before calling
2311 * psa_aead_update_ad() or psa_aead_update() if the algorithm for
2312 * the operation requires it. If the algorithm does not require it,
2313 * calling this function is optional, but if this function is called
2314 * then the implementation must enforce the lengths.
2315 *
2316 * You may call this function before or after setting the nonce with
2317 * psa_aead_set_nonce() or psa_aead_generate_nonce().
2318 *
2319 * - For #PSA_ALG_CCM, calling this function is required.
2320 * - For the other AEAD algorithms defined in this specification, calling
2321 * this function is not required.
2322 * - For vendor-defined algorithm, refer to the vendor documentation.
2323 *
2324 * \param[in,out] operation Active AEAD operation.
2325 * \param ad_length Size of the non-encrypted additional
2326 * authenticated data in bytes.
2327 * \param plaintext_length Size of the plaintext to encrypt in bytes.
2328 *
2329 * \retval #PSA_SUCCESS
2330 * Success.
2331 * \retval #PSA_ERROR_BAD_STATE
2332 * The operation state is not valid (not set up, already completed,
2333 * or psa_aead_update_ad() or psa_aead_update() already called).
2334 * \retval #PSA_ERROR_INVALID_ARGUMENT
2335 * At least one of the lengths is not acceptable for the chosen
2336 * algorithm.
2337 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2338 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2339 * \retval #PSA_ERROR_HARDWARE_FAILURE
2340 * \retval #PSA_ERROR_TAMPERING_DETECTED
2341 */
2342psa_status_t psa_aead_set_lengths(psa_aead_operation_t *operation,
2343 size_t ad_length,
2344 size_t plaintext_length);
2345
Gilles Peskine30a9e412019-01-14 18:36:12 +01002346/** Pass additional data to an active AEAD operation.
2347 *
2348 * Additional data is authenticated, but not encrypted.
2349 *
2350 * You may call this function multiple times to pass successive fragments
2351 * of the additional data. You may not call this function after passing
2352 * data to encrypt or decrypt with psa_aead_update().
2353 *
2354 * Before calling this function, you must:
2355 * 1. Call either psa_aead_encrypt_setup() or psa_aead_decrypt_setup().
2356 * 2. Set the nonce with psa_aead_generate_nonce() or psa_aead_set_nonce().
2357 *
2358 * If this function returns an error status, the operation becomes inactive.
2359 *
2360 * \warning When decrypting, until psa_aead_verify() has returned #PSA_SUCCESS,
2361 * there is no guarantee that the input is valid. Therefore, until
2362 * you have called psa_aead_verify() and it has returned #PSA_SUCCESS,
2363 * treat the input as untrusted and prepare to undo any action that
2364 * depends on the input if psa_aead_verify() returns an error status.
2365 *
2366 * \param[in,out] operation Active AEAD operation.
2367 * \param[in] input Buffer containing the fragment of
2368 * additional data.
2369 * \param input_length Size of the \p input buffer in bytes.
2370 *
2371 * \retval #PSA_SUCCESS
2372 * Success.
2373 * \retval #PSA_ERROR_BAD_STATE
2374 * The operation state is not valid (not set up, nonce not set,
2375 * psa_aead_update() already called, or operation already completed).
Gilles Peskinebc59c852019-01-17 15:26:08 +01002376 * \retval #PSA_ERROR_INVALID_ARGUMENT
2377 * The total input length overflows the additional data length that
2378 * was previously specified with psa_aead_set_lengths().
Gilles Peskine30a9e412019-01-14 18:36:12 +01002379 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2380 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2381 * \retval #PSA_ERROR_HARDWARE_FAILURE
2382 * \retval #PSA_ERROR_TAMPERING_DETECTED
2383 */
2384psa_status_t psa_aead_update_ad(psa_aead_operation_t *operation,
2385 const uint8_t *input,
2386 size_t input_length);
2387
2388/** Encrypt or decrypt a message fragment in an active AEAD operation.
2389 *
2390 * Before calling this function, you must:
2391 * 1. Call either psa_aead_encrypt_setup() or psa_aead_decrypt_setup().
2392 * The choice of setup function determines whether this function
2393 * encrypts or decrypts its input.
2394 * 2. Set the nonce with psa_aead_generate_nonce() or psa_aead_set_nonce().
2395 * 3. Call psa_aead_update_ad() to pass all the additional data.
2396 *
2397 * If this function returns an error status, the operation becomes inactive.
2398 *
2399 * \warning When decrypting, until psa_aead_verify() has returned #PSA_SUCCESS,
2400 * there is no guarantee that the input is valid. Therefore, until
2401 * you have called psa_aead_verify() and it has returned #PSA_SUCCESS:
2402 * - Do not use the output in any way other than storing it in a
2403 * confidential location. If you take any action that depends
2404 * on the tentative decrypted data, this action will need to be
2405 * undone if the input turns out not to be valid. Furthermore,
2406 * if an adversary can observe that this action took place
2407 * (for example through timing), they may be able to use this
2408 * fact as an oracle to decrypt any message encrypted with the
2409 * same key.
2410 * - In particular, do not copy the output anywhere but to a
2411 * memory or storage space that you have exclusive access to.
2412 *
2413 * \param[in,out] operation Active AEAD operation.
2414 * \param[in] input Buffer containing the message fragment to
2415 * encrypt or decrypt.
2416 * \param input_length Size of the \p input buffer in bytes.
2417 * \param[out] output Buffer where the output is to be written.
2418 * \param output_size Size of the \p output buffer in bytes.
2419 * \param[out] output_length On success, the number of bytes
2420 * that make up the returned output.
2421 *
2422 * \retval #PSA_SUCCESS
2423 * Success.
2424 * \retval #PSA_ERROR_BAD_STATE
2425 * The operation state is not valid (not set up, nonce not set
2426 * or already completed).
2427 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
2428 * The size of the \p output buffer is too small.
Gilles Peskinebc59c852019-01-17 15:26:08 +01002429 * \retval #PSA_ERROR_INVALID_ARGUMENT
2430 * The total length of input to psa_aead_update_ad() so far is
2431 * less than the additional data length that was previously
2432 * specified with psa_aead_set_lengths().
2433 * \retval #PSA_ERROR_INVALID_ARGUMENT
2434 * The total input length overflows the plaintext length that
2435 * was previously specified with psa_aead_set_lengths().
Gilles Peskine30a9e412019-01-14 18:36:12 +01002436 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2437 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2438 * \retval #PSA_ERROR_HARDWARE_FAILURE
2439 * \retval #PSA_ERROR_TAMPERING_DETECTED
2440 */
2441psa_status_t psa_aead_update(psa_aead_operation_t *operation,
2442 const uint8_t *input,
2443 size_t input_length,
2444 unsigned char *output,
2445 size_t output_size,
2446 size_t *output_length);
2447
2448/** Finish encrypting a message in an AEAD operation.
2449 *
2450 * The operation must have been set up with psa_aead_encrypt_setup().
2451 *
2452 * This function finishes the authentication of the additional data
2453 * formed by concatenating the inputs passed to preceding calls to
2454 * psa_aead_update_ad() with the plaintext formed by concatenating the
2455 * inputs passed to preceding calls to psa_aead_update().
2456 *
2457 * This function has two output buffers:
2458 * - \p ciphertext contains trailing ciphertext that was buffered from
2459 * preceding calls to psa_aead_update(). For all standard AEAD algorithms,
2460 * psa_aead_update() does not buffer any output and therefore \p ciphertext
2461 * will not contain any output and can be a 0-sized buffer.
2462 * - \p tag contains the authentication tag. Its length is always
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002463 * #PSA_AEAD_TAG_LENGTH(\c alg) where \c alg is the AEAD algorithm
Gilles Peskine30a9e412019-01-14 18:36:12 +01002464 * that the operation performs.
2465 *
2466 * When this function returns, the operation becomes inactive.
2467 *
2468 * \param[in,out] operation Active AEAD operation.
2469 * \param[out] ciphertext Buffer where the last part of the ciphertext
2470 * is to be written.
2471 * \param ciphertext_size Size of the \p ciphertext buffer in bytes.
2472 * \param[out] ciphertext_length On success, the number of bytes of
2473 * returned ciphertext.
2474 * \param[out] tag Buffer where the authentication tag is
2475 * to be written.
2476 * \param tag_size Size of the \p tag buffer in bytes.
2477 * \param[out] tag_length On success, the number of bytes
2478 * that make up the returned tag.
2479 *
2480 * \retval #PSA_SUCCESS
2481 * Success.
2482 * \retval #PSA_ERROR_BAD_STATE
2483 * The operation state is not valid (not set up, nonce not set,
2484 * decryption, or already completed).
2485 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002486 * The size of the \p ciphertext or \p tag buffer is too small.
Gilles Peskinebc59c852019-01-17 15:26:08 +01002487 * \retval #PSA_ERROR_INVALID_ARGUMENT
2488 * The total length of input to psa_aead_update_ad() so far is
2489 * less than the additional data length that was previously
2490 * specified with psa_aead_set_lengths().
2491 * \retval #PSA_ERROR_INVALID_ARGUMENT
2492 * The total length of input to psa_aead_update() so far is
2493 * less than the plaintext length that was previously
2494 * specified with psa_aead_set_lengths().
Gilles Peskine30a9e412019-01-14 18:36:12 +01002495 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2496 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2497 * \retval #PSA_ERROR_HARDWARE_FAILURE
2498 * \retval #PSA_ERROR_TAMPERING_DETECTED
2499 */
2500psa_status_t psa_aead_finish(psa_aead_operation_t *operation,
Gilles Peskinea05602d2019-01-17 15:25:52 +01002501 uint8_t *ciphertext,
2502 size_t ciphertext_size,
2503 size_t *ciphertext_length,
Gilles Peskine30a9e412019-01-14 18:36:12 +01002504 uint8_t *tag,
2505 size_t tag_size,
2506 size_t *tag_length);
2507
2508/** Finish authenticating and decrypting a message in an AEAD operation.
2509 *
2510 * The operation must have been set up with psa_aead_decrypt_setup().
2511 *
2512 * This function finishes the authentication of the additional data
2513 * formed by concatenating the inputs passed to preceding calls to
2514 * psa_aead_update_ad() with the ciphertext formed by concatenating the
2515 * inputs passed to preceding calls to psa_aead_update().
2516 *
2517 * When this function returns, the operation becomes inactive.
2518 *
2519 * \param[in,out] operation Active AEAD operation.
2520 * \param[in] tag Buffer containing the authentication tag.
2521 * \param tag_length Size of the \p tag buffer in bytes.
2522 *
2523 * \retval #PSA_SUCCESS
2524 * Success.
2525 * \retval #PSA_ERROR_BAD_STATE
2526 * The operation state is not valid (not set up, nonce not set,
2527 * encryption, or already completed).
Gilles Peskinebc59c852019-01-17 15:26:08 +01002528 * \retval #PSA_ERROR_INVALID_ARGUMENT
2529 * The total length of input to psa_aead_update_ad() so far is
2530 * less than the additional data length that was previously
2531 * specified with psa_aead_set_lengths().
2532 * \retval #PSA_ERROR_INVALID_ARGUMENT
2533 * The total length of input to psa_aead_update() so far is
2534 * less than the plaintext length that was previously
2535 * specified with psa_aead_set_lengths().
Gilles Peskine30a9e412019-01-14 18:36:12 +01002536 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2537 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2538 * \retval #PSA_ERROR_HARDWARE_FAILURE
2539 * \retval #PSA_ERROR_TAMPERING_DETECTED
2540 */
2541psa_status_t psa_aead_verify(psa_aead_operation_t *operation,
2542 const uint8_t *tag,
2543 size_t tag_length);
2544
2545/** Abort an AEAD operation.
2546 *
2547 * Aborting an operation frees all associated resources except for the
2548 * \p operation structure itself. Once aborted, the operation object
2549 * can be reused for another operation by calling
2550 * psa_aead_encrypt_setup() or psa_aead_decrypt_setup() again.
2551 *
2552 * You may call this function any time after the operation object has
2553 * been initialized by any of the following methods:
2554 * - A call to psa_aead_encrypt_setup() or psa_aead_decrypt_setup(),
2555 * whether it succeeds or not.
2556 * - Initializing the \c struct to all-bits-zero.
2557 * - Initializing the \c struct to logical zeros, e.g.
2558 * `psa_aead_operation_t operation = {0}`.
2559 *
2560 * In particular, calling psa_aead_abort() after the operation has been
2561 * terminated by a call to psa_aead_abort() or psa_aead_finish()
2562 * is safe and has no effect.
2563 *
2564 * \param[in,out] operation Initialized AEAD operation.
2565 *
2566 * \retval #PSA_SUCCESS
2567 * \retval #PSA_ERROR_BAD_STATE
2568 * \p operation is not an active AEAD operation.
2569 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2570 * \retval #PSA_ERROR_HARDWARE_FAILURE
2571 * \retval #PSA_ERROR_TAMPERING_DETECTED
2572 */
2573psa_status_t psa_aead_abort(psa_aead_operation_t *operation);
2574
Gilles Peskine3b555712018-03-03 21:27:57 +01002575/**@}*/
2576
Gilles Peskine20035e32018-02-03 22:44:14 +01002577/** \defgroup asymmetric Asymmetric cryptography
2578 * @{
2579 */
2580
2581/**
2582 * \brief Sign a hash or short message with a private key.
2583 *
Gilles Peskine08bac712018-06-26 16:14:46 +02002584 * Note that to perform a hash-and-sign signature algorithm, you must
Gilles Peskineda8191d1c2018-07-08 19:46:38 +02002585 * first calculate the hash by calling psa_hash_setup(), psa_hash_update()
Gilles Peskine08bac712018-06-26 16:14:46 +02002586 * and psa_hash_finish(). Then pass the resulting hash as the \p hash
2587 * parameter to this function. You can use #PSA_ALG_SIGN_GET_HASH(\p alg)
2588 * to determine the hash algorithm to use.
2589 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01002590 * \param handle Handle to the key to use for the operation.
2591 * It must be an asymmetric key pair.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002592 * \param alg A signature algorithm that is compatible with
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002593 * the type of \p handle.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002594 * \param[in] hash The hash or message to sign.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002595 * \param hash_length Size of the \p hash buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002596 * \param[out] signature Buffer where the signature is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002597 * \param signature_size Size of the \p signature buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002598 * \param[out] signature_length On success, the number of bytes
2599 * that make up the returned signature value.
Gilles Peskine308b91d2018-02-08 09:47:44 +01002600 *
Gilles Peskine28538492018-07-11 17:34:00 +02002601 * \retval #PSA_SUCCESS
2602 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002603 * The size of the \p signature buffer is too small. You can
Gilles Peskine308b91d2018-02-08 09:47:44 +01002604 * determine a sufficient buffer size by calling
Gilles Peskine7256e6c2018-07-12 00:34:26 +02002605 * #PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
Gilles Peskine308b91d2018-02-08 09:47:44 +01002606 * where \c key_type and \c key_bits are the type and bit-size
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002607 * respectively of \p handle.
Gilles Peskine28538492018-07-11 17:34:00 +02002608 * \retval #PSA_ERROR_NOT_SUPPORTED
2609 * \retval #PSA_ERROR_INVALID_ARGUMENT
2610 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2611 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2612 * \retval #PSA_ERROR_HARDWARE_FAILURE
2613 * \retval #PSA_ERROR_TAMPERING_DETECTED
2614 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
itayzafrir90d8c7a2018-09-12 11:44:52 +03002615 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03002616 * The library has not been previously initialized by psa_crypto_init().
2617 * It is implementation-dependent whether a failure to initialize
2618 * results in this error code.
Gilles Peskine20035e32018-02-03 22:44:14 +01002619 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01002620psa_status_t psa_asymmetric_sign(psa_key_handle_t handle,
Gilles Peskine20035e32018-02-03 22:44:14 +01002621 psa_algorithm_t alg,
2622 const uint8_t *hash,
2623 size_t hash_length,
Gilles Peskine20035e32018-02-03 22:44:14 +01002624 uint8_t *signature,
2625 size_t signature_size,
2626 size_t *signature_length);
2627
2628/**
2629 * \brief Verify the signature a hash or short message using a public key.
2630 *
Gilles Peskine08bac712018-06-26 16:14:46 +02002631 * Note that to perform a hash-and-sign signature algorithm, you must
Gilles Peskineda8191d1c2018-07-08 19:46:38 +02002632 * first calculate the hash by calling psa_hash_setup(), psa_hash_update()
Gilles Peskine08bac712018-06-26 16:14:46 +02002633 * and psa_hash_finish(). Then pass the resulting hash as the \p hash
2634 * parameter to this function. You can use #PSA_ALG_SIGN_GET_HASH(\p alg)
2635 * to determine the hash algorithm to use.
2636 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01002637 * \param handle Handle to the key to use for the operation.
2638 * It must be a public key or an asymmetric key pair.
Gilles Peskine308b91d2018-02-08 09:47:44 +01002639 * \param alg A signature algorithm that is compatible with
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002640 * the type of \p handle.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002641 * \param[in] hash The hash or message whose signature is to be
Gilles Peskine08bac712018-06-26 16:14:46 +02002642 * verified.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002643 * \param hash_length Size of the \p hash buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002644 * \param[in] signature Buffer containing the signature to verify.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002645 * \param signature_length Size of the \p signature buffer in bytes.
Gilles Peskine308b91d2018-02-08 09:47:44 +01002646 *
Gilles Peskine28538492018-07-11 17:34:00 +02002647 * \retval #PSA_SUCCESS
Gilles Peskine308b91d2018-02-08 09:47:44 +01002648 * The signature is valid.
Gilles Peskine28538492018-07-11 17:34:00 +02002649 * \retval #PSA_ERROR_INVALID_SIGNATURE
Gilles Peskine308b91d2018-02-08 09:47:44 +01002650 * The calculation was perfomed successfully, but the passed
2651 * signature is not a valid signature.
Gilles Peskine28538492018-07-11 17:34:00 +02002652 * \retval #PSA_ERROR_NOT_SUPPORTED
2653 * \retval #PSA_ERROR_INVALID_ARGUMENT
2654 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2655 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2656 * \retval #PSA_ERROR_HARDWARE_FAILURE
2657 * \retval #PSA_ERROR_TAMPERING_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03002658 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03002659 * The library has not been previously initialized by psa_crypto_init().
2660 * It is implementation-dependent whether a failure to initialize
2661 * results in this error code.
Gilles Peskine20035e32018-02-03 22:44:14 +01002662 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01002663psa_status_t psa_asymmetric_verify(psa_key_handle_t handle,
Gilles Peskine20035e32018-02-03 22:44:14 +01002664 psa_algorithm_t alg,
2665 const uint8_t *hash,
2666 size_t hash_length,
Gilles Peskinee9191ff2018-06-27 14:58:41 +02002667 const uint8_t *signature,
Gilles Peskine526fab02018-06-27 18:19:40 +02002668 size_t signature_length);
Gilles Peskine20035e32018-02-03 22:44:14 +01002669
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002670/**
2671 * \brief Encrypt a short message with a public key.
2672 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01002673 * \param handle Handle to the key to use for the operation.
2674 * It must be a public key or an asymmetric
2675 * key pair.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002676 * \param alg An asymmetric encryption algorithm that is
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002677 * compatible with the type of \p handle.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002678 * \param[in] input The message to encrypt.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002679 * \param input_length Size of the \p input buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002680 * \param[in] salt A salt or label, if supported by the
2681 * encryption algorithm.
2682 * If the algorithm does not support a
2683 * salt, pass \c NULL.
2684 * If the algorithm supports an optional
2685 * salt and you do not want to pass a salt,
2686 * pass \c NULL.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002687 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02002688 * - For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is
2689 * supported.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002690 * \param salt_length Size of the \p salt buffer in bytes.
2691 * If \p salt is \c NULL, pass 0.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002692 * \param[out] output Buffer where the encrypted message is to
2693 * be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002694 * \param output_size Size of the \p output buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002695 * \param[out] output_length On success, the number of bytes
2696 * that make up the returned output.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002697 *
Gilles Peskine28538492018-07-11 17:34:00 +02002698 * \retval #PSA_SUCCESS
2699 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002700 * The size of the \p output buffer is too small. You can
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002701 * determine a sufficient buffer size by calling
Gilles Peskine7256e6c2018-07-12 00:34:26 +02002702 * #PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002703 * where \c key_type and \c key_bits are the type and bit-size
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002704 * respectively of \p handle.
Gilles Peskine28538492018-07-11 17:34:00 +02002705 * \retval #PSA_ERROR_NOT_SUPPORTED
2706 * \retval #PSA_ERROR_INVALID_ARGUMENT
2707 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2708 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2709 * \retval #PSA_ERROR_HARDWARE_FAILURE
2710 * \retval #PSA_ERROR_TAMPERING_DETECTED
2711 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
itayzafrir90d8c7a2018-09-12 11:44:52 +03002712 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03002713 * The library has not been previously initialized by psa_crypto_init().
2714 * It is implementation-dependent whether a failure to initialize
2715 * results in this error code.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002716 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01002717psa_status_t psa_asymmetric_encrypt(psa_key_handle_t handle,
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002718 psa_algorithm_t alg,
2719 const uint8_t *input,
2720 size_t input_length,
2721 const uint8_t *salt,
2722 size_t salt_length,
2723 uint8_t *output,
2724 size_t output_size,
2725 size_t *output_length);
2726
2727/**
2728 * \brief Decrypt a short message with a private key.
2729 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01002730 * \param handle Handle to the key to use for the operation.
2731 * It must be an asymmetric key pair.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002732 * \param alg An asymmetric encryption algorithm that is
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002733 * compatible with the type of \p handle.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002734 * \param[in] input The message to decrypt.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002735 * \param input_length Size of the \p input buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002736 * \param[in] salt A salt or label, if supported by the
2737 * encryption algorithm.
2738 * If the algorithm does not support a
2739 * salt, pass \c NULL.
2740 * If the algorithm supports an optional
2741 * salt and you do not want to pass a salt,
2742 * pass \c NULL.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002743 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02002744 * - For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is
2745 * supported.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002746 * \param salt_length Size of the \p salt buffer in bytes.
2747 * If \p salt is \c NULL, pass 0.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002748 * \param[out] output Buffer where the decrypted message is to
2749 * be written.
2750 * \param output_size Size of the \c output buffer in bytes.
2751 * \param[out] output_length On success, the number of bytes
2752 * that make up the returned output.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002753 *
Gilles Peskine28538492018-07-11 17:34:00 +02002754 * \retval #PSA_SUCCESS
2755 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002756 * The size of the \p output buffer is too small. You can
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002757 * determine a sufficient buffer size by calling
Gilles Peskinedda3bd32018-07-12 19:40:46 +02002758 * #PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002759 * where \c key_type and \c key_bits are the type and bit-size
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01002760 * respectively of \p handle.
Gilles Peskine28538492018-07-11 17:34:00 +02002761 * \retval #PSA_ERROR_NOT_SUPPORTED
2762 * \retval #PSA_ERROR_INVALID_ARGUMENT
2763 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2764 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2765 * \retval #PSA_ERROR_HARDWARE_FAILURE
2766 * \retval #PSA_ERROR_TAMPERING_DETECTED
2767 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
2768 * \retval #PSA_ERROR_INVALID_PADDING
itayzafrir90d8c7a2018-09-12 11:44:52 +03002769 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03002770 * The library has not been previously initialized by psa_crypto_init().
2771 * It is implementation-dependent whether a failure to initialize
2772 * results in this error code.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002773 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01002774psa_status_t psa_asymmetric_decrypt(psa_key_handle_t handle,
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002775 psa_algorithm_t alg,
2776 const uint8_t *input,
2777 size_t input_length,
2778 const uint8_t *salt,
2779 size_t salt_length,
2780 uint8_t *output,
2781 size_t output_size,
2782 size_t *output_length);
2783
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +01002784/**@}*/
2785
Gilles Peskineedd76872018-07-20 17:42:05 +02002786/** \defgroup generators Generators
Gilles Peskineeab56e42018-07-12 17:12:33 +02002787 * @{
2788 */
2789
2790/** The type of the state data structure for generators.
2791 *
2792 * Before calling any function on a generator, the application must
2793 * initialize it by any of the following means:
2794 * - Set the structure to all-bits-zero, for example:
2795 * \code
2796 * psa_crypto_generator_t generator;
2797 * memset(&generator, 0, sizeof(generator));
2798 * \endcode
2799 * - Initialize the structure to logical zero values, for example:
2800 * \code
2801 * psa_crypto_generator_t generator = {0};
2802 * \endcode
2803 * - Initialize the structure to the initializer #PSA_CRYPTO_GENERATOR_INIT,
2804 * for example:
2805 * \code
2806 * psa_crypto_generator_t generator = PSA_CRYPTO_GENERATOR_INIT;
2807 * \endcode
2808 * - Assign the result of the function psa_crypto_generator_init()
2809 * to the structure, for example:
2810 * \code
2811 * psa_crypto_generator_t generator;
2812 * generator = psa_crypto_generator_init();
2813 * \endcode
2814 *
2815 * This is an implementation-defined \c struct. Applications should not
2816 * make any assumptions about the content of this structure except
2817 * as directed by the documentation of a specific implementation.
2818 */
2819typedef struct psa_crypto_generator_s psa_crypto_generator_t;
2820
2821/** \def PSA_CRYPTO_GENERATOR_INIT
2822 *
2823 * This macro returns a suitable initializer for a generator object
2824 * of type #psa_crypto_generator_t.
2825 */
2826#ifdef __DOXYGEN_ONLY__
2827/* This is an example definition for documentation purposes.
2828 * Implementations should define a suitable value in `crypto_struct.h`.
2829 */
2830#define PSA_CRYPTO_GENERATOR_INIT {0}
2831#endif
2832
2833/** Return an initial value for a generator object.
2834 */
2835static psa_crypto_generator_t psa_crypto_generator_init(void);
2836
2837/** Retrieve the current capacity of a generator.
2838 *
2839 * The capacity of a generator is the maximum number of bytes that it can
2840 * return. Reading *N* bytes from a generator reduces its capacity by *N*.
2841 *
2842 * \param[in] generator The generator to query.
2843 * \param[out] capacity On success, the capacity of the generator.
2844 *
Gilles Peskine644cd5f2018-12-11 16:47:35 +01002845 * \retval #PSA_SUCCESS
2846 * \retval #PSA_ERROR_BAD_STATE
2847 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
Gilles Peskineeab56e42018-07-12 17:12:33 +02002848 */
2849psa_status_t psa_get_generator_capacity(const psa_crypto_generator_t *generator,
2850 size_t *capacity);
2851
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01002852/** Set the maximum capacity of a generator.
2853 *
2854 * \param[in,out] generator The generator object to modify.
2855 * \param capacity The new capacity of the generator.
2856 * It must be less or equal to the generator's
2857 * current capacity.
2858 *
2859 * \retval #PSA_SUCCESS
2860 * \retval #PSA_ERROR_INVALID_ARGUMENT
2861 * \p capacity is larger than the generator's current capacity.
2862 * \retval #PSA_ERROR_BAD_STATE
2863 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2864 */
2865psa_status_t psa_set_generator_capacity(psa_crypto_generator_t *generator,
2866 size_t capacity);
2867
Gilles Peskineeab56e42018-07-12 17:12:33 +02002868/** Read some data from a generator.
2869 *
2870 * This function reads and returns a sequence of bytes from a generator.
2871 * The data that is read is discarded from the generator. The generator's
2872 * capacity is decreased by the number of bytes read.
2873 *
2874 * \param[in,out] generator The generator object to read from.
2875 * \param[out] output Buffer where the generator output will be
2876 * written.
2877 * \param output_length Number of bytes to output.
2878 *
Gilles Peskine644cd5f2018-12-11 16:47:35 +01002879 * \retval #PSA_SUCCESS
David Saadab4ecc272019-02-14 13:48:10 +02002880 * \retval #PSA_ERROR_INSUFFICIENT_DATA
Gilles Peskineeab56e42018-07-12 17:12:33 +02002881 * There were fewer than \p output_length bytes
2882 * in the generator. Note that in this case, no
2883 * output is written to the output buffer.
2884 * The generator's capacity is set to 0, thus
2885 * subsequent calls to this function will not
2886 * succeed, even with a smaller output buffer.
Gilles Peskine644cd5f2018-12-11 16:47:35 +01002887 * \retval #PSA_ERROR_BAD_STATE
2888 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2889 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2890 * \retval #PSA_ERROR_HARDWARE_FAILURE
2891 * \retval #PSA_ERROR_TAMPERING_DETECTED
Gilles Peskineeab56e42018-07-12 17:12:33 +02002892 */
2893psa_status_t psa_generator_read(psa_crypto_generator_t *generator,
2894 uint8_t *output,
2895 size_t output_length);
2896
Gilles Peskinefa4486d2019-03-11 17:30:31 +01002897/** Generate a key deterministically from data read from a generator.
Gilles Peskineeab56e42018-07-12 17:12:33 +02002898 *
Gilles Peskinefa4486d2019-03-11 17:30:31 +01002899 * This function uses the output of a generator to derive a key.
2900 * How much output it consumes and how the key is derived depends on the
2901 * key type.
Gilles Peskineeab56e42018-07-12 17:12:33 +02002902 *
Gilles Peskinefa4486d2019-03-11 17:30:31 +01002903 * - For key types for which the key is an arbitrary sequence of bytes
2904 * of a given size,
2905 * this function is functionally equivalent to calling #psa_generator_read
2906 * and passing the resulting output to #psa_import_key.
2907 * However, this function has a security benefit:
2908 * if the implementation provides an isolation boundary then
2909 * the key material is not exposed outside the isolation boundary.
2910 * As a consequence, for these key types, this function always consumes
2911 * exactly (\p bits / 8) bytes from the generator.
2912 * The following key types defined in this specification follow this scheme:
2913 *
2914 * - #PSA_KEY_TYPE_AES;
Gilles Peskinefa4486d2019-03-11 17:30:31 +01002915 * - #PSA_KEY_TYPE_ARC4;
2916 * - #PSA_KEY_TYPE_CAMELLIA;
Gilles Peskinefa4486d2019-03-11 17:30:31 +01002917 * - #PSA_KEY_TYPE_DERIVE;
2918 * - #PSA_KEY_TYPE_HMAC.
2919 *
2920 * - For ECC keys on a Montgomery elliptic curve
2921 * (#PSA_KEY_TYPE_ECC_KEYPAIR(\c curve) where \c curve designates a
2922 * Montgomery curve), this function always draws a byte string whose
2923 * length is determined by the curve, and sets the mandatory bits
2924 * accordingly. That is:
2925 *
2926 * - #PSA_ECC_CURVE_CURVE25519: draw a 32-byte string
2927 * and process it as specified in RFC 7748 &sect;5.
2928 * - #PSA_ECC_CURVE_CURVE448: draw a 56-byte string
2929 * and process it as specified in RFC 7748 &sect;5.
2930 *
2931 * - For key types for which the key is represented by a single sequence of
2932 * \p bits bits with constraints as to which bit sequences are acceptable,
2933 * this function draws a byte string of length (\p bits / 8) bytes rounded
2934 * up to the nearest whole number of bytes. If the resulting byte string
2935 * is acceptable, it becomes the key, otherwise the drawn bytes are discarded.
2936 * This process is repeated until an acceptable byte string is drawn.
2937 * The byte string drawn from the generator is interpreted as specified
2938 * for the output produced by psa_export_key().
2939 * The following key types defined in this specification follow this scheme:
2940 *
Gilles Peskine2de2c0d2019-03-11 17:59:16 +01002941 * - #PSA_KEY_TYPE_DES.
2942 * Force-set the parity bits, but discard forbidden weak keys.
2943 * For 2-key and 3-key triple-DES, the three keys are generated
2944 * successively (for example, for 3-key triple-DES,
2945 * if the first 8 bytes specify a weak key and the next 8 bytes do not,
2946 * discard the first 8 bytes, use the next 8 bytes as the first key,
2947 * and continue reading output from the generator to derive the other
2948 * two keys).
2949 * - Finite-field Diffie-Hellman keys (#PSA_KEY_TYPE_DH_KEYPAIR),
2950 * DSA keys (#PSA_KEY_TYPE_DSA_KEYPAIR), and
2951 * ECC keys on a Weierstrass elliptic curve
2952 * (#PSA_KEY_TYPE_ECC_KEYPAIR(\c curve) where \c curve designates a
2953 * Weierstrass curve).
2954 * For these key types, interpret the byte string as integer
2955 * in big-endian order. Discard it if it is not in the range
2956 * [0, *N* - 2] where *N* is the boundary of the private key domain
2957 * (the prime *p* for Diffie-Hellman, the subprime *q* for DSA,
Gilles Peskine55799712019-03-12 11:50:26 +01002958 * or the order of the curve's base point for ECC).
Gilles Peskine2de2c0d2019-03-11 17:59:16 +01002959 * Add 1 to the resulting integer and use this as the private key *x*.
Gilles Peskine55799712019-03-12 11:50:26 +01002960 * This method allows compliance to NIST standards, specifically
2961 * the methods titled "key-pair generation by testing candidates"
Gilles Peskine2de2c0d2019-03-11 17:59:16 +01002962 * in NIST SP 800-56A &sect;5.6.1.1.4 for Diffie-Hellman,
2963 * in FIPS 186-4 &sect;B.1.2 for DSA, and
2964 * in NIST SP 800-56A &sect;5.6.1.2.2 or
2965 * FIPS 186-4 &sect;B.4.2 for elliptic curve keys.
Gilles Peskinefa4486d2019-03-11 17:30:31 +01002966 *
2967 * - For other key types, including #PSA_KEY_TYPE_RSA_KEYPAIR,
2968 * the way in which the generator output is consumed is
2969 * implementation-defined.
2970 *
2971 * In all cases, the data that is read is discarded from the generator.
2972 * The generator's capacity is decreased by the number of bytes read.
Gilles Peskineeab56e42018-07-12 17:12:33 +02002973 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01002974 * \param handle Handle to the slot where the key will be stored.
Gilles Peskined40c1fb2019-01-19 12:20:52 +01002975 * It must have been obtained by calling
2976 * psa_allocate_key() or psa_create_key() and must
2977 * not contain key material yet.
Gilles Peskineeab56e42018-07-12 17:12:33 +02002978 * \param type Key type (a \c PSA_KEY_TYPE_XXX value).
Gilles Peskineee67dd62019-03-12 13:23:17 +01002979 * This must be a secret key type or a key pair type.
Gilles Peskineeab56e42018-07-12 17:12:33 +02002980 * \param bits Key size in bits.
2981 * \param[in,out] generator The generator object to read from.
2982 *
Gilles Peskine644cd5f2018-12-11 16:47:35 +01002983 * \retval #PSA_SUCCESS
Gilles Peskineeab56e42018-07-12 17:12:33 +02002984 * Success.
Gilles Peskine23fd2bd2018-12-11 15:51:32 +01002985 * If the key is persistent, the key material and the key's metadata
2986 * have been saved to persistent storage.
David Saadab4ecc272019-02-14 13:48:10 +02002987 * \retval #PSA_ERROR_INSUFFICIENT_DATA
Gilles Peskinefa4486d2019-03-11 17:30:31 +01002988 * There was not enough data to create the desired key.
2989 * Note that in this case, no output is written to the output buffer.
2990 * The generator's capacity is set to 0, thus subsequent calls to
2991 * this function will not succeed, even with a smaller output buffer.
Gilles Peskine644cd5f2018-12-11 16:47:35 +01002992 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskineeab56e42018-07-12 17:12:33 +02002993 * The key type or key size is not supported, either by the
2994 * implementation in general or in this particular slot.
Gilles Peskine644cd5f2018-12-11 16:47:35 +01002995 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskineae32aac2018-11-30 14:39:32 +01002996 * \retval #PSA_ERROR_INVALID_HANDLE
David Saadab4ecc272019-02-14 13:48:10 +02002997 * \retval #PSA_ERROR_ALREADY_EXISTS
Gilles Peskineeab56e42018-07-12 17:12:33 +02002998 * There is already a key in the specified slot.
Gilles Peskine644cd5f2018-12-11 16:47:35 +01002999 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3000 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
3001 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3002 * \retval #PSA_ERROR_HARDWARE_FAILURE
3003 * \retval #PSA_ERROR_TAMPERING_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03003004 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03003005 * The library has not been previously initialized by psa_crypto_init().
3006 * It is implementation-dependent whether a failure to initialize
3007 * results in this error code.
Gilles Peskineeab56e42018-07-12 17:12:33 +02003008 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01003009psa_status_t psa_generator_import_key(psa_key_handle_t handle,
Gilles Peskineeab56e42018-07-12 17:12:33 +02003010 psa_key_type_t type,
3011 size_t bits,
3012 psa_crypto_generator_t *generator);
3013
3014/** Abort a generator.
3015 *
3016 * Once a generator has been aborted, its capacity is zero.
3017 * Aborting a generator frees all associated resources except for the
3018 * \c generator structure itself.
3019 *
3020 * This function may be called at any time as long as the generator
3021 * object has been initialized to #PSA_CRYPTO_GENERATOR_INIT, to
3022 * psa_crypto_generator_init() or a zero value. In particular, it is valid
3023 * to call psa_generator_abort() twice, or to call psa_generator_abort()
3024 * on a generator that has not been set up.
3025 *
3026 * Once aborted, the generator object may be called.
3027 *
3028 * \param[in,out] generator The generator to abort.
3029 *
Gilles Peskine644cd5f2018-12-11 16:47:35 +01003030 * \retval #PSA_SUCCESS
3031 * \retval #PSA_ERROR_BAD_STATE
3032 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3033 * \retval #PSA_ERROR_HARDWARE_FAILURE
3034 * \retval #PSA_ERROR_TAMPERING_DETECTED
Gilles Peskineeab56e42018-07-12 17:12:33 +02003035 */
3036psa_status_t psa_generator_abort(psa_crypto_generator_t *generator);
3037
Gilles Peskine8feb3a82018-09-18 12:06:11 +02003038/** Use the maximum possible capacity for a generator.
3039 *
3040 * Use this value as the capacity argument when setting up a generator
3041 * to indicate that the generator should have the maximum possible capacity.
3042 * The value of the maximum possible capacity depends on the generator
3043 * algorithm.
3044 */
3045#define PSA_GENERATOR_UNBRIDLED_CAPACITY ((size_t)(-1))
3046
Gilles Peskineeab56e42018-07-12 17:12:33 +02003047/**@}*/
3048
Gilles Peskineea0fb492018-07-12 17:17:20 +02003049/** \defgroup derivation Key derivation
3050 * @{
3051 */
3052
3053/** Set up a key derivation operation.
3054 *
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01003055 * A key derivation algorithm takes some inputs and uses them to create
3056 * a byte generator which can be used to produce keys and other
3057 * cryptographic material.
Gilles Peskineea0fb492018-07-12 17:17:20 +02003058 *
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01003059 * To use a generator for key derivation:
3060 * - Start with an initialized object of type #psa_crypto_generator_t.
3061 * - Call psa_key_derivation_setup() to select the algorithm.
3062 * - Provide the inputs for the key derivation by calling
3063 * psa_key_derivation_input_bytes() or psa_key_derivation_input_key()
3064 * as appropriate. Which inputs are needed, in what order, and whether
3065 * they may be keys and if so of what type depends on the algorithm.
3066 * - Optionally set the generator's maximum capacity with
3067 * psa_set_generator_capacity(). You may do this before, in the middle of
3068 * or after providing inputs. For some algorithms, this step is mandatory
3069 * because the output depends on the maximum capacity.
3070 * - Generate output with psa_generator_read() or
3071 * psa_generator_import_key(). Successive calls to these functions
3072 * use successive output bytes from the generator.
3073 * - Clean up the generator object with psa_generator_abort().
Gilles Peskineea0fb492018-07-12 17:17:20 +02003074 *
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01003075 * \param[in,out] generator The generator object to set up. It must
3076 * have been initialized but not set up yet.
Gilles Peskineea0fb492018-07-12 17:17:20 +02003077 * \param alg The key derivation algorithm to compute
3078 * (\c PSA_ALG_XXX value such that
3079 * #PSA_ALG_IS_KEY_DERIVATION(\p alg) is true).
Gilles Peskineea0fb492018-07-12 17:17:20 +02003080 *
3081 * \retval #PSA_SUCCESS
3082 * Success.
Gilles Peskineea0fb492018-07-12 17:17:20 +02003083 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01003084 * \c alg is not a key derivation algorithm.
Gilles Peskineea0fb492018-07-12 17:17:20 +02003085 * \retval #PSA_ERROR_NOT_SUPPORTED
3086 * \c alg is not supported or is not a key derivation algorithm.
3087 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3088 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3089 * \retval #PSA_ERROR_HARDWARE_FAILURE
3090 * \retval #PSA_ERROR_TAMPERING_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03003091 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01003092 */
3093psa_status_t psa_key_derivation_setup(psa_crypto_generator_t *generator,
3094 psa_algorithm_t alg);
3095
Gilles Peskine6cdfdb72019-01-08 10:31:27 +01003096/** Provide an input for key derivation or key agreement.
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01003097 *
Gilles Peskine6cdfdb72019-01-08 10:31:27 +01003098 * Which inputs are required and in what order depends on the algorithm.
3099 * Refer to the documentation of each key derivation or key agreement
3100 * algorithm for information.
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01003101 *
Gilles Peskine6cdfdb72019-01-08 10:31:27 +01003102 * This function passes direct inputs. Some inputs must be passed as keys
3103 * using psa_key_derivation_input_key() instead of this function. Refer to
3104 * the documentation of individual step types for information.
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01003105 *
3106 * \param[in,out] generator The generator object to use. It must
3107 * have been set up with
3108 * psa_key_derivation_setup() and must not
3109 * have produced any output yet.
3110 * \param step Which step the input data is for.
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01003111 * \param[in] data Input data to use.
3112 * \param data_length Size of the \p data buffer in bytes.
3113 *
3114 * \retval #PSA_SUCCESS
3115 * Success.
3116 * \retval #PSA_ERROR_INVALID_ARGUMENT
3117 * \c step is not compatible with the generator's algorithm.
Gilles Peskine6cdfdb72019-01-08 10:31:27 +01003118 * \retval #PSA_ERROR_INVALID_ARGUMENT
3119 * \c step does not allow direct inputs.
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01003120 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3121 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3122 * \retval #PSA_ERROR_HARDWARE_FAILURE
3123 * \retval #PSA_ERROR_TAMPERING_DETECTED
3124 * \retval #PSA_ERROR_BAD_STATE
3125 * The value of \p step is not valid given the state of \p generator.
3126 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03003127 * The library has not been previously initialized by psa_crypto_init().
3128 * It is implementation-dependent whether a failure to initialize
3129 * results in this error code.
Gilles Peskineea0fb492018-07-12 17:17:20 +02003130 */
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01003131psa_status_t psa_key_derivation_input_bytes(psa_crypto_generator_t *generator,
3132 psa_key_derivation_step_t step,
3133 const uint8_t *data,
3134 size_t data_length);
Gilles Peskineea0fb492018-07-12 17:17:20 +02003135
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01003136/** Provide an input for key derivation in the form of a key.
3137 *
Gilles Peskine6cdfdb72019-01-08 10:31:27 +01003138 * Which inputs are required and in what order depends on the algorithm.
3139 * Refer to the documentation of each key derivation or key agreement
3140 * algorithm for information.
3141 *
3142 * This function passes key inputs. Some inputs must be passed as keys
3143 * of the appropriate type using this function, while others must be
3144 * passed as direct inputs using psa_key_derivation_input_bytes(). Refer to
3145 * the documentation of individual step types for information.
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01003146 *
3147 * \param[in,out] generator The generator object to use. It must
3148 * have been set up with
3149 * psa_key_derivation_setup() and must not
3150 * have produced any output yet.
3151 * \param step Which step the input data is for.
Gilles Peskine6cdfdb72019-01-08 10:31:27 +01003152 * \param handle Handle to the key. It must have an
3153 * appropriate type for \p step and must
3154 * allow the usage #PSA_KEY_USAGE_DERIVE.
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01003155 *
3156 * \retval #PSA_SUCCESS
3157 * Success.
3158 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine31351842019-04-09 12:00:00 +02003159 * \retval #PSA_ERROR_DOES_NOT_EXIST
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01003160 * \retval #PSA_ERROR_NOT_PERMITTED
3161 * \retval #PSA_ERROR_INVALID_ARGUMENT
3162 * \c step is not compatible with the generator's algorithm.
Gilles Peskine6cdfdb72019-01-08 10:31:27 +01003163 * \retval #PSA_ERROR_INVALID_ARGUMENT
3164 * \c step does not allow key inputs.
Gilles Peskineb70a0fd2019-01-07 22:59:38 +01003165 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3166 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3167 * \retval #PSA_ERROR_HARDWARE_FAILURE
3168 * \retval #PSA_ERROR_TAMPERING_DETECTED
3169 * \retval #PSA_ERROR_BAD_STATE
3170 * The value of \p step is not valid given the state of \p generator.
3171 * \retval #PSA_ERROR_BAD_STATE
3172 * The library has not been previously initialized by psa_crypto_init().
3173 * It is implementation-dependent whether a failure to initialize
3174 * results in this error code.
3175 */
3176psa_status_t psa_key_derivation_input_key(psa_crypto_generator_t *generator,
3177 psa_key_derivation_step_t step,
3178 psa_key_handle_t handle);
3179
Gilles Peskine969c5d62019-01-16 15:53:06 +01003180/** Perform a key agreement and use the shared secret as input to a key
3181 * derivation.
Gilles Peskine01d718c2018-09-18 12:01:02 +02003182 *
3183 * A key agreement algorithm takes two inputs: a private key \p private_key
3184 * a public key \p peer_key.
Gilles Peskine969c5d62019-01-16 15:53:06 +01003185 * The result of this function is passed as input to a key derivation.
3186 * The output of this key derivation can be extracted by reading from the
3187 * resulting generator to produce keys and other cryptographic material.
Gilles Peskine01d718c2018-09-18 12:01:02 +02003188 *
Gilles Peskine969c5d62019-01-16 15:53:06 +01003189 * \param[in,out] generator The generator object to use. It must
3190 * have been set up with
3191 * psa_key_derivation_setup() with a
Gilles Peskine6843c292019-01-18 16:44:49 +01003192 * key agreement and derivation algorithm
3193 * \c alg (\c PSA_ALG_XXX value such that
Gilles Peskine3be6b7f2019-03-05 19:32:26 +01003194 * #PSA_ALG_IS_KEY_AGREEMENT(\c alg) is true
3195 * and #PSA_ALG_IS_RAW_KEY_AGREEMENT(\c alg)
Gilles Peskine6843c292019-01-18 16:44:49 +01003196 * is false).
Gilles Peskine969c5d62019-01-16 15:53:06 +01003197 * The generator must be ready for an
3198 * input of the type given by \p step.
3199 * \param step Which step the input data is for.
Gilles Peskineae32aac2018-11-30 14:39:32 +01003200 * \param private_key Handle to the private key to use.
Jaeden Amero8afbff82019-01-14 16:56:20 +00003201 * \param[in] peer_key Public key of the peer. The peer key must be in the
3202 * same format that psa_import_key() accepts for the
3203 * public key type corresponding to the type of
3204 * private_key. That is, this function performs the
3205 * equivalent of
Gilles Peskine47e79fb2019-02-08 11:24:59 +01003206 * #psa_import_key(`internal_public_key_handle`,
3207 * #PSA_KEY_TYPE_PUBLIC_KEY_OF_KEYPAIR(`private_key_type`),
3208 * `peer_key`, `peer_key_length`) where
Jaeden Amero8afbff82019-01-14 16:56:20 +00003209 * `private_key_type` is the type of `private_key`.
3210 * For example, for EC keys, this means that peer_key
3211 * is interpreted as a point on the curve that the
3212 * private key is on. The standard formats for public
3213 * keys are documented in the documentation of
3214 * psa_export_public_key().
Gilles Peskine01d718c2018-09-18 12:01:02 +02003215 * \param peer_key_length Size of \p peer_key in bytes.
Gilles Peskine01d718c2018-09-18 12:01:02 +02003216 *
3217 * \retval #PSA_SUCCESS
3218 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01003219 * \retval #PSA_ERROR_INVALID_HANDLE
David Saadab4ecc272019-02-14 13:48:10 +02003220 * \retval #PSA_ERROR_DOES_NOT_EXIST
Gilles Peskine01d718c2018-09-18 12:01:02 +02003221 * \retval #PSA_ERROR_NOT_PERMITTED
3222 * \retval #PSA_ERROR_INVALID_ARGUMENT
3223 * \c private_key is not compatible with \c alg,
3224 * or \p peer_key is not valid for \c alg or not compatible with
3225 * \c private_key.
3226 * \retval #PSA_ERROR_NOT_SUPPORTED
3227 * \c alg is not supported or is not a key derivation algorithm.
3228 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3229 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3230 * \retval #PSA_ERROR_HARDWARE_FAILURE
3231 * \retval #PSA_ERROR_TAMPERING_DETECTED
3232 */
3233psa_status_t psa_key_agreement(psa_crypto_generator_t *generator,
Gilles Peskine969c5d62019-01-16 15:53:06 +01003234 psa_key_derivation_step_t step,
Gilles Peskineae32aac2018-11-30 14:39:32 +01003235 psa_key_handle_t private_key,
Gilles Peskine01d718c2018-09-18 12:01:02 +02003236 const uint8_t *peer_key,
Gilles Peskine969c5d62019-01-16 15:53:06 +01003237 size_t peer_key_length);
Gilles Peskine01d718c2018-09-18 12:01:02 +02003238
Gilles Peskine769c7a62019-01-18 16:42:29 +01003239/** Perform a key agreement and use the shared secret as input to a key
3240 * derivation.
3241 *
3242 * A key agreement algorithm takes two inputs: a private key \p private_key
3243 * a public key \p peer_key.
3244 *
3245 * \warning The raw result of a key agreement algorithm such as finite-field
3246 * Diffie-Hellman or elliptic curve Diffie-Hellman has biases and should
3247 * not be used directly as key material. It should instead be passed as
3248 * input to a key derivation algorithm. To chain a key agreement with
3249 * a key derivation, use psa_key_agreement() and other functions from
3250 * the key derivation and generator interface.
3251 *
Gilles Peskine47e79fb2019-02-08 11:24:59 +01003252 * \param alg The key agreement algorithm to compute
3253 * (\c PSA_ALG_XXX value such that
3254 * #PSA_ALG_IS_RAW_KEY_AGREEMENT(\p alg)
3255 * is true).
Gilles Peskine769c7a62019-01-18 16:42:29 +01003256 * \param private_key Handle to the private key to use.
3257 * \param[in] peer_key Public key of the peer. It must be
3258 * in the same format that psa_import_key()
3259 * accepts. The standard formats for public
3260 * keys are documented in the documentation
3261 * of psa_export_public_key().
3262 * \param peer_key_length Size of \p peer_key in bytes.
3263 * \param[out] output Buffer where the decrypted message is to
3264 * be written.
3265 * \param output_size Size of the \c output buffer in bytes.
3266 * \param[out] output_length On success, the number of bytes
3267 * that make up the returned output.
3268 *
3269 * \retval #PSA_SUCCESS
3270 * Success.
3271 * \retval #PSA_ERROR_INVALID_HANDLE
3272 * \retval #PSA_ERROR_EMPTY_SLOT
3273 * \retval #PSA_ERROR_NOT_PERMITTED
3274 * \retval #PSA_ERROR_INVALID_ARGUMENT
3275 * \p alg is not a key agreement algorithm
3276 * \retval #PSA_ERROR_INVALID_ARGUMENT
3277 * \p private_key is not compatible with \p alg,
3278 * or \p peer_key is not valid for \p alg or not compatible with
3279 * \p private_key.
3280 * \retval #PSA_ERROR_NOT_SUPPORTED
3281 * \p alg is not a supported key agreement algorithm.
3282 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
3283 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3284 * \retval #PSA_ERROR_HARDWARE_FAILURE
3285 * \retval #PSA_ERROR_TAMPERING_DETECTED
3286 */
3287psa_status_t psa_key_agreement_raw_shared_secret(psa_algorithm_t alg,
3288 psa_key_handle_t private_key,
3289 const uint8_t *peer_key,
3290 size_t peer_key_length,
3291 uint8_t *output,
3292 size_t output_size,
3293 size_t *output_length);
Gilles Peskine4c317f42018-07-12 01:24:09 +02003294
3295/**@}*/
Gilles Peskine9e7dc712018-03-28 14:18:50 +02003296
3297/** \defgroup random Random generation
3298 * @{
Gilles Peskine4e69d7a2018-06-19 20:19:14 +02003299 */
3300
3301/**
3302 * \brief Generate random bytes.
3303 *
Gilles Peskine53d991e2018-07-12 01:14:59 +02003304 * \warning This function **can** fail! Callers MUST check the return status
Gilles Peskine4e69d7a2018-06-19 20:19:14 +02003305 * and MUST NOT use the content of the output buffer if the return
Gilles Peskinefa4070c2018-07-12 19:23:03 +02003306 * status is not #PSA_SUCCESS.
Gilles Peskine3fa675c2018-07-12 01:31:03 +02003307 *
3308 * \note To generate a key, use psa_generate_key() instead.
3309 *
3310 * \param[out] output Output buffer for the generated data.
3311 * \param output_size Number of bytes to generate and output.
3312 *
Gilles Peskinefa4070c2018-07-12 19:23:03 +02003313 * \retval #PSA_SUCCESS
Gilles Peskine3fa675c2018-07-12 01:31:03 +02003314 * \retval #PSA_ERROR_NOT_SUPPORTED
3315 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
Gilles Peskinefa4070c2018-07-12 19:23:03 +02003316 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
Gilles Peskine3fa675c2018-07-12 01:31:03 +02003317 * \retval #PSA_ERROR_HARDWARE_FAILURE
3318 * \retval #PSA_ERROR_TAMPERING_DETECTED
Gilles Peskinedda3bd32018-07-12 19:40:46 +02003319 * \retval #PSA_ERROR_BAD_STATE
3320 * The library has not been previously initialized by psa_crypto_init().
3321 * It is implementation-dependent whether a failure to initialize
Gilles Peskine3fa675c2018-07-12 01:31:03 +02003322 * results in this error code.
3323 */
3324psa_status_t psa_generate_random(uint8_t *output,
Gilles Peskine53d991e2018-07-12 01:14:59 +02003325 size_t output_size);
3326
3327/** Extra parameters for RSA key generation.
Gilles Peskine9e7dc712018-03-28 14:18:50 +02003328 *
Gilles Peskine28538492018-07-11 17:34:00 +02003329 * You may pass a pointer to a structure of this type as the \c extra
3330 * parameter to psa_generate_key().
3331 */
3332typedef struct {
3333 uint32_t e; /**< Public exponent value. Default: 65537. */
3334} psa_generate_key_extra_rsa;
3335
3336/**
itayzafrir90d8c7a2018-09-12 11:44:52 +03003337 * \brief Generate a key or key pair.
itayzafrir18617092018-09-16 12:22:41 +03003338 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01003339 * \param handle Handle to the slot where the key will be stored.
Gilles Peskined40c1fb2019-01-19 12:20:52 +01003340 * It must have been obtained by calling
3341 * psa_allocate_key() or psa_create_key() and must
3342 * not contain key material yet.
Gilles Peskine9e7dc712018-03-28 14:18:50 +02003343 * \param type Key type (a \c PSA_KEY_TYPE_XXX value).
3344 * \param bits Key size in bits.
3345 * \param[in] extra Extra parameters for key generation. The
3346 * interpretation of this parameter depends on
3347 * \p type. All types support \c NULL to use
3348 * default parameters. Implementation that support
3349 * the generation of vendor-specific key types
3350 * that allow extra parameters shall document
3351 * the format of these extra parameters and
3352 * the default values. For standard parameters,
3353 * the meaning of \p extra is as follows:
3354 * - For a symmetric key type (a type such
3355 * that #PSA_KEY_TYPE_IS_ASYMMETRIC(\p type) is
Gilles Peskine53d991e2018-07-12 01:14:59 +02003356 * false), \p extra must be \c NULL.
3357 * - For an elliptic curve key type (a type
Gilles Peskine9e7dc712018-03-28 14:18:50 +02003358 * such that #PSA_KEY_TYPE_IS_ECC(\p type) is
3359 * false), \p extra must be \c NULL.
3360 * - For an RSA key (\p type is
Gilles Peskinee59236f2018-01-27 23:32:46 +01003361 * #PSA_KEY_TYPE_RSA_KEYPAIR), \p extra is an
3362 * optional #psa_generate_key_extra_rsa structure
3363 * specifying the public exponent. The
3364 * default public exponent used when \p extra
Gilles Peskine0cad07c2018-06-27 19:49:02 +02003365 * is \c NULL is 65537.
Jaeden Amero1308fb52019-01-11 13:50:43 +00003366 * - For an DSA key (\p type is
3367 * #PSA_KEY_TYPE_DSA_KEYPAIR), \p extra is an
3368 * optional structure specifying the key domain
3369 * parameters. The key domain parameters can also be
3370 * provided by psa_set_key_domain_parameters(),
3371 * which documents the format of the structure.
Jaeden Amero8851c402019-01-11 14:20:03 +00003372 * - For a DH key (\p type is
3373 * #PSA_KEY_TYPE_DH_KEYPAIR), the \p extra is an
3374 * optional structure specifying the key domain
3375 * parameters. The key domain parameters can also be
3376 * provided by psa_set_key_domain_parameters(),
3377 * which documents the format of the structure.
Gilles Peskinee59236f2018-01-27 23:32:46 +01003378 * \param extra_size Size of the buffer that \p extra
3379 * points to, in bytes. Note that if \p extra is
3380 * \c NULL then \p extra_size must be zero.
3381 *
Gilles Peskine0cad07c2018-06-27 19:49:02 +02003382 * \retval #PSA_SUCCESS
Gilles Peskine23fd2bd2018-12-11 15:51:32 +01003383 * Success.
3384 * If the key is persistent, the key material and the key's metadata
3385 * have been saved to persistent storage.
Gilles Peskineae32aac2018-11-30 14:39:32 +01003386 * \retval #PSA_ERROR_INVALID_HANDLE
David Saadab4ecc272019-02-14 13:48:10 +02003387 * \retval #PSA_ERROR_ALREADY_EXISTS
Gilles Peskineae32aac2018-11-30 14:39:32 +01003388 * There is already a key in the specified slot.
Gilles Peskine0cad07c2018-06-27 19:49:02 +02003389 * \retval #PSA_ERROR_NOT_SUPPORTED
3390 * \retval #PSA_ERROR_INVALID_ARGUMENT
3391 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
Gilles Peskine9ef733f2018-02-07 21:05:37 +01003392 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
3393 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
3394 * \retval #PSA_ERROR_HARDWARE_FAILURE
3395 * \retval #PSA_ERROR_TAMPERING_DETECTED
3396 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03003397 * The library has not been previously initialized by psa_crypto_init().
3398 * It is implementation-dependent whether a failure to initialize
3399 * results in this error code.
Gilles Peskinee59236f2018-01-27 23:32:46 +01003400 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01003401psa_status_t psa_generate_key(psa_key_handle_t handle,
Gilles Peskinee59236f2018-01-27 23:32:46 +01003402 psa_key_type_t type,
3403 size_t bits,
3404 const void *extra,
3405 size_t extra_size);
3406
3407/**@}*/
3408
3409#ifdef __cplusplus
3410}
3411#endif
3412
3413/* The file "crypto_sizes.h" contains definitions for size calculation
3414 * macros whose definitions are implementation-specific. */
3415#include "crypto_sizes.h"
3416
3417/* The file "crypto_struct.h" contains definitions for
3418 * implementation-specific structs that are declared above. */
3419#include "crypto_struct.h"
3420
3421/* The file "crypto_extra.h" contains vendor-specific definitions. This
3422 * can include vendor-defined algorithms, extra functions, etc. */
3423#include "crypto_extra.h"
3424
3425#endif /* PSA_CRYPTO_H */