blob: 40b3032104583b6ea1c751dc39e22d6863a416d6 [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
96/** \defgroup key_management Key management
97 * @{
98 */
99
Gilles Peskineae32aac2018-11-30 14:39:32 +0100100/** \brief Retrieve the lifetime of an open key.
Gilles Peskine3cac8c42018-11-30 14:07:45 +0100101 *
Gilles Peskineae32aac2018-11-30 14:39:32 +0100102 * \param handle Handle to query.
Gilles Peskine3cac8c42018-11-30 14:07:45 +0100103 * \param[out] lifetime On success, the lifetime value.
104 *
105 * \retval #PSA_SUCCESS
106 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +0100107 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine3cac8c42018-11-30 14:07:45 +0100108 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
109 * \retval #PSA_ERROR_HARDWARE_FAILURE
110 * \retval #PSA_ERROR_TAMPERING_DETECTED
111 * \retval #PSA_ERROR_BAD_STATE
112 * The library has not been previously initialized by psa_crypto_init().
113 * It is implementation-dependent whether a failure to initialize
114 * results in this error code.
115 */
Gilles Peskineae32aac2018-11-30 14:39:32 +0100116psa_status_t psa_get_key_lifetime(psa_key_handle_t handle,
Gilles Peskine3cac8c42018-11-30 14:07:45 +0100117 psa_key_lifetime_t *lifetime);
118
Gilles Peskine3cac8c42018-11-30 14:07:45 +0100119
Gilles Peskinef535eb22018-11-30 14:08:36 +0100120/** Allocate a key slot for a transient key, i.e. a key which is only stored
121 * in volatile memory.
122 *
123 * The allocated key slot and its handle remain valid until the
124 * application calls psa_close_key() or psa_destroy_key() or until the
125 * application terminates.
126 *
127 * This function takes a key type and maximum size as arguments so that
128 * the implementation can reserve a corresponding amount of memory.
129 * Implementations are not required to enforce this limit: if the application
130 * later tries to create a larger key or a key of a different type, it
131 * is implementation-defined whether this may succeed.
132 *
133 * \param type The type of key that the slot will contain.
134 * \param max_bits The maximum key size that the slot will contain.
135 * \param[out] handle On success, a handle to a volatile key slot.
136 *
137 * \retval #PSA_SUCCESS
138 * Success. The application can now use the value of `*handle`
139 * to access the newly allocated key slot.
140 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
141 * There was not enough memory, or the maximum number of key slots
142 * has been reached.
143 * \retval #PSA_ERROR_INVALID_ARGUMENT
144 * This implementation does not support this key type.
145 */
146
147psa_status_t psa_allocate_key(psa_key_type_t type,
148 size_t max_bits,
149 psa_key_handle_t *handle);
150
151/** Open a handle to an existing persistent key.
152 *
153 * Open a handle to a key which was previously created with psa_create_key().
154 *
155 * \param lifetime The lifetime of the key. This designates a storage
156 * area where the key material is stored. This must not
157 * be #PSA_KEY_LIFETIME_VOLATILE.
158 * \param id The persistent identifier of the key.
159 * \param[out] handle On success, a handle to a key slot which contains
160 * the data and metadata loaded from the specified
161 * persistent location.
162 *
163 * \retval #PSA_SUCCESS
164 * Success. The application can now use the value of `*handle`
165 * to access the newly allocated key slot.
166 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
167 * \retval #PSA_ERROR_EMPTY_SLOT
168 * \retval #PSA_ERROR_INVALID_ARGUMENT
169 * \p lifetime is invalid, for example #PSA_KEY_LIFETIME_VOLATILE.
170 * \retval #PSA_ERROR_INVALID_ARGUMENT
171 * \p id is invalid for the specified lifetime.
172 * \retval #PSA_ERROR_NOT_SUPPORTED
173 * \p lifetime is not supported.
174 * \retval #PSA_ERROR_NOT_PERMITTED
175 * The specified key exists, but the application does not have the
176 * permission to access it. Note that this specification does not
177 * define any way to create such a key, but it may be possible
178 * through implementation-specific means.
179 */
180psa_status_t psa_open_key(psa_key_lifetime_t lifetime,
181 psa_key_id_t id,
182 psa_key_handle_t *handle);
183
184/** Create a new persistent key slot.
185 *
186 * Create a new persistent key slot and return a handle to it. The handle
187 * remains valid until the application calls psa_close_key() or terminates.
188 * The application can open the key again with psa_open_key() until it
189 * removes the key by calling psa_destroy_key().
190 *
191 * \param lifetime The lifetime of the key. This designates a storage
192 * area where the key material is stored. This must not
193 * be #PSA_KEY_LIFETIME_VOLATILE.
194 * \param id The persistent identifier of the key.
195 * \param type The type of key that the slot will contain.
196 * \param max_bits The maximum key size that the slot will contain.
197 * \param[out] handle On success, a handle to the newly created key slot.
198 * When key material is later created in this key slot,
199 * it will be saved to the specified persistent location.
200 *
201 * \retval #PSA_SUCCESS
202 * Success. The application can now use the value of `*handle`
203 * to access the newly allocated key slot.
204 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
205 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
206 * \retval #PSA_ERROR_OCCUPIED_SLOT
207 * There is already a key with the identifier \p id in the storage
208 * area designated by \p lifetime.
209 * \retval #PSA_ERROR_INVALID_ARGUMENT
210 * \p lifetime is invalid, for example #PSA_KEY_LIFETIME_VOLATILE.
211 * \retval #PSA_ERROR_INVALID_ARGUMENT
212 * \p id is invalid for the specified lifetime.
213 * \retval #PSA_ERROR_NOT_SUPPORTED
214 * \p lifetime is not supported.
215 * \retval #PSA_ERROR_NOT_PERMITTED
216 * \p lifetime is valid, but the application does not have the
217 * permission to create a key there.
218 */
219psa_status_t psa_create_key(psa_key_lifetime_t lifetime,
220 psa_key_id_t id,
221 psa_key_type_t type,
222 size_t max_bits,
223 psa_key_handle_t *handle);
224
225/** Close a key handle.
226 *
227 * If the handle designates a volatile key, destroy the key material and
228 * free all associated resources, just like psa_destroy_key().
229 *
230 * If the handle designates a persistent key, free all resources associated
231 * with the key in volatile memory. The key slot in persistent storage is
232 * not affected and can be opened again later with psa_open_key().
233 *
Gilles Peskine5f25dd02019-01-14 18:24:53 +0100234 * If the key is currently in use in a multipart operation,
235 * the multipart operation is aborted.
236 *
Gilles Peskinef535eb22018-11-30 14:08:36 +0100237 * \param handle The key handle to close.
238 *
239 * \retval #PSA_SUCCESS
240 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskineae32aac2018-11-30 14:39:32 +0100241 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
Gilles Peskinef535eb22018-11-30 14:08:36 +0100242 */
243psa_status_t psa_close_key(psa_key_handle_t handle);
244
Gilles Peskine3cac8c42018-11-30 14:07:45 +0100245/**@}*/
246
247/** \defgroup import_export Key import and export
248 * @{
249 */
250
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100251/**
252 * \brief Import a key in binary format.
253 *
Gilles Peskinef5b9fa12018-03-07 16:40:18 +0100254 * This function supports any output from psa_export_key(). Refer to the
Gilles Peskinef7933932018-10-31 14:07:52 +0100255 * documentation of psa_export_public_key() for the format of public keys
256 * and to the documentation of psa_export_key() for the format for
257 * other key types.
258 *
259 * This specification supports a single format for each key type.
260 * Implementations may support other formats as long as the standard
261 * format is supported. Implementations that support other formats
262 * should ensure that the formats are clearly unambiguous so as to
263 * minimize the risk that an invalid input is accidentally interpreted
264 * according to a different format.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100265 *
Gilles Peskineae32aac2018-11-30 14:39:32 +0100266 * \param handle Handle to the slot where the key will be stored.
267 * This must be a valid slot for a key of the chosen
268 * type: it must have been obtained by calling
269 * psa_allocate_key() or psa_create_key() with the
270 * correct \p type and with a maximum size that is
271 * compatible with \p data.
Gilles Peskinef7933932018-10-31 14:07:52 +0100272 * \param type Key type (a \c PSA_KEY_TYPE_XXX value). On a successful
273 * import, the key slot will contain a key of this type.
274 * \param[in] data Buffer containing the key data. The content of this
275 * buffer is interpreted according to \p type. It must
276 * contain the format described in the documentation
277 * of psa_export_key() or psa_export_public_key() for
278 * the chosen type.
Gilles Peskinefa4070c2018-07-12 19:23:03 +0200279 * \param data_length Size of the \p data buffer in bytes.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100280 *
Gilles Peskine28538492018-07-11 17:34:00 +0200281 * \retval #PSA_SUCCESS
Gilles Peskine308b91d2018-02-08 09:47:44 +0100282 * Success.
Gilles Peskine23fd2bd2018-12-11 15:51:32 +0100283 * If the key is persistent, the key material and the key's metadata
284 * have been saved to persistent storage.
Gilles Peskineae32aac2018-11-30 14:39:32 +0100285 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine28538492018-07-11 17:34:00 +0200286 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskine65eb8582018-04-19 08:28:58 +0200287 * The key type or key size is not supported, either by the
288 * implementation in general or in this particular slot.
Gilles Peskine28538492018-07-11 17:34:00 +0200289 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine308b91d2018-02-08 09:47:44 +0100290 * The key slot is invalid,
291 * or the key data is not correctly formatted.
Gilles Peskine28538492018-07-11 17:34:00 +0200292 * \retval #PSA_ERROR_OCCUPIED_SLOT
Gilles Peskine65eb8582018-04-19 08:28:58 +0200293 * There is already a key in the specified slot.
Gilles Peskine28538492018-07-11 17:34:00 +0200294 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
295 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
296 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
Darryl Greend49a4992018-06-18 17:27:26 +0100297 * \retval #PSA_ERROR_STORAGE_FAILURE
Gilles Peskine28538492018-07-11 17:34:00 +0200298 * \retval #PSA_ERROR_HARDWARE_FAILURE
299 * \retval #PSA_ERROR_TAMPERING_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +0300300 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +0300301 * The library has not been previously initialized by psa_crypto_init().
302 * It is implementation-dependent whether a failure to initialize
303 * results in this error code.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100304 */
Gilles Peskineae32aac2018-11-30 14:39:32 +0100305psa_status_t psa_import_key(psa_key_handle_t handle,
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100306 psa_key_type_t type,
307 const uint8_t *data,
308 size_t data_length);
309
310/**
Gilles Peskineae32aac2018-11-30 14:39:32 +0100311 * \brief Destroy a key.
Gilles Peskine154bd952018-04-19 08:38:16 +0200312 *
313 * This function destroys the content of the key slot from both volatile
314 * memory and, if applicable, non-volatile storage. Implementations shall
315 * make a best effort to ensure that any previous content of the slot is
316 * unrecoverable.
317 *
Gilles Peskineae32aac2018-11-30 14:39:32 +0100318 * This function also erases any metadata such as policies and frees all
319 * resources associated with the key.
Gilles Peskine154bd952018-04-19 08:38:16 +0200320 *
Gilles Peskine5f25dd02019-01-14 18:24:53 +0100321 * If the key is currently in use in a multipart operation,
322 * the multipart operation is aborted.
323 *
Gilles Peskineae32aac2018-11-30 14:39:32 +0100324 * \param handle Handle to the key slot to erase.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100325 *
Gilles Peskine28538492018-07-11 17:34:00 +0200326 * \retval #PSA_SUCCESS
Gilles Peskine65eb8582018-04-19 08:28:58 +0200327 * The slot's content, if any, has been erased.
Gilles Peskine28538492018-07-11 17:34:00 +0200328 * \retval #PSA_ERROR_NOT_PERMITTED
Gilles Peskine65eb8582018-04-19 08:28:58 +0200329 * The slot holds content and cannot be erased because it is
330 * read-only, either due to a policy or due to physical restrictions.
Gilles Peskineae32aac2018-11-30 14:39:32 +0100331 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine28538492018-07-11 17:34:00 +0200332 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
Gilles Peskine65eb8582018-04-19 08:28:58 +0200333 * There was an failure in communication with the cryptoprocessor.
334 * The key material may still be present in the cryptoprocessor.
Gilles Peskine28538492018-07-11 17:34:00 +0200335 * \retval #PSA_ERROR_STORAGE_FAILURE
Gilles Peskine65eb8582018-04-19 08:28:58 +0200336 * The storage is corrupted. Implementations shall make a best effort
337 * to erase key material even in this stage, however applications
338 * should be aware that it may be impossible to guarantee that the
339 * key material is not recoverable in such cases.
Gilles Peskine28538492018-07-11 17:34:00 +0200340 * \retval #PSA_ERROR_TAMPERING_DETECTED
Gilles Peskine65eb8582018-04-19 08:28:58 +0200341 * An unexpected condition which is not a storage corruption or
342 * a communication failure occurred. The cryptoprocessor may have
343 * been compromised.
itayzafrir90d8c7a2018-09-12 11:44:52 +0300344 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +0300345 * The library has not been previously initialized by psa_crypto_init().
346 * It is implementation-dependent whether a failure to initialize
347 * results in this error code.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100348 */
Gilles Peskineae32aac2018-11-30 14:39:32 +0100349psa_status_t psa_destroy_key(psa_key_handle_t handle);
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100350
351/**
352 * \brief Get basic metadata about a key.
353 *
Gilles Peskineae32aac2018-11-30 14:39:32 +0100354 * \param handle Handle to the key slot to query.
Gilles Peskineedd11a12018-07-12 01:08:58 +0200355 * \param[out] type On success, the key type (a \c PSA_KEY_TYPE_XXX value).
Gilles Peskine308b91d2018-02-08 09:47:44 +0100356 * This may be a null pointer, in which case the key type
357 * is not written.
Gilles Peskineedd11a12018-07-12 01:08:58 +0200358 * \param[out] bits On success, the key size in bits.
Gilles Peskine9a1ba0d2018-03-21 20:49:16 +0100359 * This may be a null pointer, in which case the key size
Gilles Peskine308b91d2018-02-08 09:47:44 +0100360 * is not written.
361 *
Gilles Peskine28538492018-07-11 17:34:00 +0200362 * \retval #PSA_SUCCESS
Gilles Peskineae32aac2018-11-30 14:39:32 +0100363 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine28538492018-07-11 17:34:00 +0200364 * \retval #PSA_ERROR_EMPTY_SLOT
Gilles Peskineae32aac2018-11-30 14:39:32 +0100365 * The handle is to a key slot which does not contain key material yet.
Gilles Peskine28538492018-07-11 17:34:00 +0200366 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
367 * \retval #PSA_ERROR_HARDWARE_FAILURE
368 * \retval #PSA_ERROR_TAMPERING_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +0300369 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +0300370 * The library has not been previously initialized by psa_crypto_init().
371 * It is implementation-dependent whether a failure to initialize
372 * results in this error code.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100373 */
Gilles Peskineae32aac2018-11-30 14:39:32 +0100374psa_status_t psa_get_key_information(psa_key_handle_t handle,
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100375 psa_key_type_t *type,
376 size_t *bits);
377
378/**
379 * \brief Export a key in binary format.
380 *
381 * The output of this function can be passed to psa_import_key() to
382 * create an equivalent object.
383 *
Gilles Peskinef7933932018-10-31 14:07:52 +0100384 * If the implementation of psa_import_key() supports other formats
385 * beyond the format specified here, the output from psa_export_key()
386 * must use the representation specified here, not the original
387 * representation.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100388 *
Gilles Peskine308b91d2018-02-08 09:47:44 +0100389 * For standard key types, the output format is as follows:
390 *
391 * - For symmetric keys (including MAC keys), the format is the
392 * raw bytes of the key.
393 * - For DES, the key data consists of 8 bytes. The parity bits must be
394 * correct.
395 * - For Triple-DES, the format is the concatenation of the
396 * two or three DES keys.
Gilles Peskine92b30732018-03-03 21:29:30 +0100397 * - For RSA key pairs (#PSA_KEY_TYPE_RSA_KEYPAIR), the format
Gilles Peskine4e1e9be2018-08-10 18:57:40 +0200398 * is the non-encrypted DER encoding of the representation defined by
399 * PKCS\#1 (RFC 8017) as `RSAPrivateKey`, version 0.
400 * ```
401 * RSAPrivateKey ::= SEQUENCE {
Gilles Peskine4f6c77b2018-08-11 01:17:53 +0200402 * version INTEGER, -- must be 0
Gilles Peskine4e1e9be2018-08-10 18:57:40 +0200403 * modulus INTEGER, -- n
404 * publicExponent INTEGER, -- e
405 * privateExponent INTEGER, -- d
406 * prime1 INTEGER, -- p
407 * prime2 INTEGER, -- q
408 * exponent1 INTEGER, -- d mod (p-1)
409 * exponent2 INTEGER, -- d mod (q-1)
410 * coefficient INTEGER, -- (inverse of q) mod p
411 * }
412 * ```
413 * - For DSA private keys (#PSA_KEY_TYPE_DSA_KEYPAIR), the format
414 * is the non-encrypted DER encoding of the representation used by
Gilles Peskinec6290c02018-08-13 17:24:59 +0200415 * OpenSSL and OpenSSH, whose structure is described in ASN.1 as follows:
Gilles Peskine4e1e9be2018-08-10 18:57:40 +0200416 * ```
417 * DSAPrivateKey ::= SEQUENCE {
Gilles Peskine4f6c77b2018-08-11 01:17:53 +0200418 * version INTEGER, -- must be 0
Gilles Peskine4e1e9be2018-08-10 18:57:40 +0200419 * prime INTEGER, -- p
420 * subprime INTEGER, -- q
421 * generator INTEGER, -- g
422 * public INTEGER, -- y
423 * private INTEGER, -- x
424 * }
425 * ```
426 * - For elliptic curve key pairs (key types for which
Gilles Peskinef76aa772018-10-29 19:24:33 +0100427 * #PSA_KEY_TYPE_IS_ECC_KEYPAIR is true), the format is
Gilles Peskine6c6a0232018-11-15 17:44:43 +0100428 * a representation of the private value as a `ceiling(m/8)`-byte string
429 * where `m` is the bit size associated with the curve, i.e. the bit size
430 * of the order of the curve's coordinate field. This byte string is
431 * in little-endian order for Montgomery curves (curve types
432 * `PSA_ECC_CURVE_CURVEXXX`), and in big-endian order for Weierstrass
433 * curves (curve types `PSA_ECC_CURVE_SECTXXX`, `PSA_ECC_CURVE_SECPXXX`
434 * and `PSA_ECC_CURVE_BRAINPOOL_PXXX`).
Gilles Peskinef76aa772018-10-29 19:24:33 +0100435 * This is the content of the `privateKey` field of the `ECPrivateKey`
436 * format defined by RFC 5915.
Gilles Peskine4e1e9be2018-08-10 18:57:40 +0200437 * - For public keys (key types for which #PSA_KEY_TYPE_IS_PUBLIC_KEY is
438 * true), the format is the same as for psa_export_public_key().
Gilles Peskine308b91d2018-02-08 09:47:44 +0100439 *
Gilles Peskineae32aac2018-11-30 14:39:32 +0100440 * \param handle Handle to the key to export.
Gilles Peskineedd11a12018-07-12 01:08:58 +0200441 * \param[out] data Buffer where the key data is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +0200442 * \param data_size Size of the \p data buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +0200443 * \param[out] data_length On success, the number of bytes
444 * that make up the key data.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100445 *
Gilles Peskine28538492018-07-11 17:34:00 +0200446 * \retval #PSA_SUCCESS
Gilles Peskineae32aac2018-11-30 14:39:32 +0100447 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine28538492018-07-11 17:34:00 +0200448 * \retval #PSA_ERROR_EMPTY_SLOT
449 * \retval #PSA_ERROR_NOT_PERMITTED
Darryl Green9e2d7a02018-07-24 16:33:30 +0100450 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskine1be949b2018-08-10 19:06:59 +0200451 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
452 * The size of the \p data buffer is too small. You can determine a
453 * sufficient buffer size by calling
454 * #PSA_KEY_EXPORT_MAX_SIZE(\c type, \c bits)
455 * where \c type is the key type
456 * and \c bits is the key size in bits.
Gilles Peskine28538492018-07-11 17:34:00 +0200457 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
458 * \retval #PSA_ERROR_HARDWARE_FAILURE
459 * \retval #PSA_ERROR_TAMPERING_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +0300460 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +0300461 * The library has not been previously initialized by psa_crypto_init().
462 * It is implementation-dependent whether a failure to initialize
463 * results in this error code.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100464 */
Gilles Peskineae32aac2018-11-30 14:39:32 +0100465psa_status_t psa_export_key(psa_key_handle_t handle,
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100466 uint8_t *data,
467 size_t data_size,
468 size_t *data_length);
469
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100470/**
471 * \brief Export a public key or the public part of a key pair in binary format.
472 *
473 * The output of this function can be passed to psa_import_key() to
474 * create an object that is equivalent to the public key.
475 *
Gilles Peskine4e1e9be2018-08-10 18:57:40 +0200476 * The format is the DER representation defined by RFC 5280 as
477 * `SubjectPublicKeyInfo`, with the `subjectPublicKey` format
478 * specified below.
479 * ```
480 * SubjectPublicKeyInfo ::= SEQUENCE {
481 * algorithm AlgorithmIdentifier,
482 * subjectPublicKey BIT STRING }
483 * AlgorithmIdentifier ::= SEQUENCE {
484 * algorithm OBJECT IDENTIFIER,
485 * parameters ANY DEFINED BY algorithm OPTIONAL }
486 * ```
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100487 *
Gilles Peskine4e1e9be2018-08-10 18:57:40 +0200488 * - For RSA public keys (#PSA_KEY_TYPE_RSA_PUBLIC_KEY),
489 * the `subjectPublicKey` format is defined by RFC 3279 &sect;2.3.1 as
490 * `RSAPublicKey`,
491 * with the OID `rsaEncryption`,
492 * and with the parameters `NULL`.
493 * ```
494 * pkcs-1 OBJECT IDENTIFIER ::= { iso(1) member-body(2) us(840)
495 * rsadsi(113549) pkcs(1) 1 }
496 * rsaEncryption OBJECT IDENTIFIER ::= { pkcs-1 1 }
497 *
498 * RSAPublicKey ::= SEQUENCE {
499 * modulus INTEGER, -- n
500 * publicExponent INTEGER } -- e
501 * ```
502 * - For DSA public keys (#PSA_KEY_TYPE_DSA_PUBLIC_KEY),
503 * the `subjectPublicKey` format is defined by RFC 3279 &sect;2.3.2 as
504 * `DSAPublicKey`,
505 * with the OID `id-dsa`,
506 * and with the parameters `DSS-Parms`.
507 * ```
508 * id-dsa OBJECT IDENTIFIER ::= {
509 * iso(1) member-body(2) us(840) x9-57(10040) x9cm(4) 1 }
510 *
511 * Dss-Parms ::= SEQUENCE {
512 * p INTEGER,
513 * q INTEGER,
514 * g INTEGER }
515 * DSAPublicKey ::= INTEGER -- public key, Y
516 * ```
517 * - For elliptic curve public keys (key types for which
518 * #PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY is true),
519 * the `subjectPublicKey` format is defined by RFC 3279 &sect;2.3.5 as
Gilles Peskine4f6c77b2018-08-11 01:17:53 +0200520 * `ECPoint`, which contains the uncompressed
Gilles Peskine4e1e9be2018-08-10 18:57:40 +0200521 * representation defined by SEC1 &sect;2.3.3.
522 * The OID is `id-ecPublicKey`,
Gilles Peskine4f6c77b2018-08-11 01:17:53 +0200523 * and the parameters must be given as a `namedCurve` OID as specified in
Gilles Peskinec6290c02018-08-13 17:24:59 +0200524 * RFC 5480 &sect;2.1.1.1 or other applicable standards.
Gilles Peskine4e1e9be2018-08-10 18:57:40 +0200525 * ```
526 * ansi-X9-62 OBJECT IDENTIFIER ::=
527 * { iso(1) member-body(2) us(840) 10045 }
528 * id-public-key-type OBJECT IDENTIFIER ::= { ansi-X9.62 2 }
529 * id-ecPublicKey OBJECT IDENTIFIER ::= { id-publicKeyType 1 }
530 *
Gilles Peskine4f6c77b2018-08-11 01:17:53 +0200531 * ECPoint ::= ...
532 * -- first 8 bits: 0x04;
Gilles Peskine6c6a0232018-11-15 17:44:43 +0100533 * -- then x_P as a `ceiling(m/8)`-byte string, big endian;
534 * -- then y_P as a `ceiling(m/8)`-byte string, big endian;
535 * -- where `m` is the bit size associated with the curve,
Gilles Peskine7b5b4a02018-11-14 21:05:10 +0100536 * -- i.e. the bit size of `q` for a curve over `F_q`.
Gilles Peskine4e1e9be2018-08-10 18:57:40 +0200537 *
538 * EcpkParameters ::= CHOICE { -- other choices are not allowed
539 * namedCurve OBJECT IDENTIFIER }
540 * ```
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100541 *
Gilles Peskineae32aac2018-11-30 14:39:32 +0100542 * \param handle Handle to the key to export.
Gilles Peskineedd11a12018-07-12 01:08:58 +0200543 * \param[out] data Buffer where the key data is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +0200544 * \param data_size Size of the \p data buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +0200545 * \param[out] data_length On success, the number of bytes
546 * that make up the key data.
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100547 *
Gilles Peskine28538492018-07-11 17:34:00 +0200548 * \retval #PSA_SUCCESS
Gilles Peskineae32aac2018-11-30 14:39:32 +0100549 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine28538492018-07-11 17:34:00 +0200550 * \retval #PSA_ERROR_EMPTY_SLOT
551 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine1be949b2018-08-10 19:06:59 +0200552 * The key is neither a public key nor a key pair.
553 * \retval #PSA_ERROR_NOT_SUPPORTED
554 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
555 * The size of the \p data buffer is too small. You can determine a
556 * sufficient buffer size by calling
557 * #PSA_KEY_EXPORT_MAX_SIZE(#PSA_KEY_TYPE_PUBLIC_KEY_OF_KEYPAIR(\c type), \c bits)
558 * where \c type is the key type
559 * and \c bits is the key size in bits.
Gilles Peskine28538492018-07-11 17:34:00 +0200560 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
561 * \retval #PSA_ERROR_HARDWARE_FAILURE
562 * \retval #PSA_ERROR_TAMPERING_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +0300563 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +0300564 * The library has not been previously initialized by psa_crypto_init().
565 * It is implementation-dependent whether a failure to initialize
566 * results in this error code.
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100567 */
Gilles Peskineae32aac2018-11-30 14:39:32 +0100568psa_status_t psa_export_public_key(psa_key_handle_t handle,
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100569 uint8_t *data,
570 size_t data_size,
571 size_t *data_length);
572
573/**@}*/
574
575/** \defgroup policy Key policies
576 * @{
577 */
578
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100579/** The type of the key policy data structure.
580 *
Jaeden Amero70261c52019-01-04 11:47:20 +0000581 * Before calling any function on a key policy, the application must initialize
582 * it by any of the following means:
583 * - Set the structure to all-bits-zero, for example:
584 * \code
585 * psa_key_policy_t policy;
586 * memset(&policy, 0, sizeof(policy));
587 * \endcode
588 * - Initialize the structure to logical zero values, for example:
589 * \code
590 * psa_key_policy_t policy = {0};
591 * \endcode
592 * - Initialize the structure to the initializer #PSA_KEY_POLICY_INIT,
593 * for example:
594 * \code
595 * psa_key_policy_t policy = PSA_KEY_POLICY_INIT;
596 * \endcode
597 * - Assign the result of the function psa_key_policy_init()
598 * to the structure, for example:
599 * \code
600 * psa_key_policy_t policy;
601 * policy = psa_key_policy_init();
602 * \endcode
603 *
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100604 * This is an implementation-defined \c struct. Applications should not
605 * make any assumptions about the content of this structure except
606 * as directed by the documentation of a specific implementation. */
607typedef struct psa_key_policy_s psa_key_policy_t;
608
Jaeden Amero70261c52019-01-04 11:47:20 +0000609/** \def PSA_KEY_POLICY_INIT
Gilles Peskine6ac73a92018-07-12 19:47:19 +0200610 *
Jaeden Amero70261c52019-01-04 11:47:20 +0000611 * This macro returns a suitable initializer for a key policy object of type
612 * #psa_key_policy_t.
Gilles Peskine6ac73a92018-07-12 19:47:19 +0200613 */
Jaeden Amero70261c52019-01-04 11:47:20 +0000614#ifdef __DOXYGEN_ONLY__
615/* This is an example definition for documentation purposes.
616 * Implementations should define a suitable value in `crypto_struct.h`.
617 */
618#define PSA_KEY_POLICY_INIT {0}
619#endif
620
621/** Return an initial value for a key policy that forbids all usage of the key.
622 */
623static psa_key_policy_t psa_key_policy_init(void);
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100624
Gilles Peskine7e198532018-03-08 07:50:30 +0100625/** \brief Set the standard fields of a policy structure.
626 *
627 * Note that this function does not make any consistency check of the
628 * parameters. The values are only checked when applying the policy to
629 * a key slot with psa_set_key_policy().
Gilles Peskine6ac73a92018-07-12 19:47:19 +0200630 *
Jaeden Amero70261c52019-01-04 11:47:20 +0000631 * \param[in,out] policy The key policy to modify. It must have been
632 * initialized as per the documentation for
633 * #psa_key_policy_t.
634 * \param usage The permitted uses for the key.
635 * \param alg The algorithm that the key may be used for.
Gilles Peskine7e198532018-03-08 07:50:30 +0100636 */
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100637void psa_key_policy_set_usage(psa_key_policy_t *policy,
638 psa_key_usage_t usage,
639 psa_algorithm_t alg);
640
Gilles Peskine6ac73a92018-07-12 19:47:19 +0200641/** \brief Retrieve the usage field of a policy structure.
642 *
643 * \param[in] policy The policy object to query.
644 *
645 * \return The permitted uses for a key with this policy.
646 */
Gilles Peskineaa7bc472018-07-12 00:54:56 +0200647psa_key_usage_t psa_key_policy_get_usage(const psa_key_policy_t *policy);
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100648
Gilles Peskine6ac73a92018-07-12 19:47:19 +0200649/** \brief Retrieve the algorithm field of a policy structure.
650 *
651 * \param[in] policy The policy object to query.
652 *
653 * \return The permitted algorithm for a key with this policy.
654 */
Gilles Peskineaa7bc472018-07-12 00:54:56 +0200655psa_algorithm_t psa_key_policy_get_algorithm(const psa_key_policy_t *policy);
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100656
657/** \brief Set the usage policy on a key slot.
658 *
659 * This function must be called on an empty key slot, before importing,
660 * generating or creating a key in the slot. Changing the policy of an
661 * existing key is not permitted.
Gilles Peskine7e198532018-03-08 07:50:30 +0100662 *
663 * Implementations may set restrictions on supported key policies
664 * depending on the key type and the key slot.
Gilles Peskine6ac73a92018-07-12 19:47:19 +0200665 *
Gilles Peskineae32aac2018-11-30 14:39:32 +0100666 * \param handle Handle to the key whose policy is to be changed.
Gilles Peskine6ac73a92018-07-12 19:47:19 +0200667 * \param[in] policy The policy object to query.
668 *
669 * \retval #PSA_SUCCESS
Gilles Peskine23fd2bd2018-12-11 15:51:32 +0100670 * Success.
671 * If the key is persistent, it is implementation-defined whether
672 * the policy has been saved to persistent storage. Implementations
673 * may defer saving the policy until the key material is created.
Gilles Peskineae32aac2018-11-30 14:39:32 +0100674 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine6ac73a92018-07-12 19:47:19 +0200675 * \retval #PSA_ERROR_OCCUPIED_SLOT
676 * \retval #PSA_ERROR_NOT_SUPPORTED
677 * \retval #PSA_ERROR_INVALID_ARGUMENT
678 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
679 * \retval #PSA_ERROR_HARDWARE_FAILURE
680 * \retval #PSA_ERROR_TAMPERING_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +0300681 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +0300682 * The library has not been previously initialized by psa_crypto_init().
683 * It is implementation-dependent whether a failure to initialize
684 * results in this error code.
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100685 */
Gilles Peskineae32aac2018-11-30 14:39:32 +0100686psa_status_t psa_set_key_policy(psa_key_handle_t handle,
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100687 const psa_key_policy_t *policy);
688
Gilles Peskine7e198532018-03-08 07:50:30 +0100689/** \brief Get the usage policy for a key slot.
Gilles Peskine6ac73a92018-07-12 19:47:19 +0200690 *
Gilles Peskineae32aac2018-11-30 14:39:32 +0100691 * \param handle Handle to the key slot whose policy is being queried.
Gilles Peskine6ac73a92018-07-12 19:47:19 +0200692 * \param[out] policy On success, the key's policy.
693 *
694 * \retval #PSA_SUCCESS
Gilles Peskineae32aac2018-11-30 14:39:32 +0100695 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine6ac73a92018-07-12 19:47:19 +0200696 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
697 * \retval #PSA_ERROR_HARDWARE_FAILURE
698 * \retval #PSA_ERROR_TAMPERING_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +0300699 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +0300700 * The library has not been previously initialized by psa_crypto_init().
701 * It is implementation-dependent whether a failure to initialize
702 * results in this error code.
Gilles Peskine7e198532018-03-08 07:50:30 +0100703 */
Gilles Peskineae32aac2018-11-30 14:39:32 +0100704psa_status_t psa_get_key_policy(psa_key_handle_t handle,
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100705 psa_key_policy_t *policy);
Gilles Peskine20035e32018-02-03 22:44:14 +0100706
707/**@}*/
708
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100709/** \defgroup hash Message digests
710 * @{
711 */
712
Gilles Peskine69647a42019-01-14 20:18:12 +0100713/** Calculate the hash (digest) of a message.
714 *
715 * \note To verify the hash of a message against an
716 * expected value, use psa_hash_compare() instead.
717 *
718 * \param alg The hash algorithm to compute (\c PSA_ALG_XXX value
719 * such that #PSA_ALG_IS_HASH(\p alg) is true).
720 * \param[in] input Buffer containing the message to hash.
721 * \param input_length Size of the \p input buffer in bytes.
722 * \param[out] hash Buffer where the hash is to be written.
723 * \param hash_size Size of the \p hash buffer in bytes.
724 * \param[out] hash_length On success, the number of bytes
725 * that make up the hash value. This is always
726 * #PSA_HASH_SIZE(\c alg) where \c alg is the
727 * hash algorithm that is calculated.
728 *
729 * \retval #PSA_SUCCESS
730 * Success.
731 * \retval #PSA_ERROR_NOT_SUPPORTED
732 * \p alg is not supported or is not a hash algorithm.
733 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
734 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
735 * \retval #PSA_ERROR_HARDWARE_FAILURE
736 * \retval #PSA_ERROR_TAMPERING_DETECTED
737 */
738psa_status_t psa_hash_compute(psa_algorithm_t alg,
739 const uint8_t *input,
740 size_t input_length,
741 uint8_t *hash,
742 size_t hash_size,
743 size_t *hash_length);
744
745/** Calculate the hash (digest) of a message and compare it with a
746 * reference value.
747 *
748 * \param alg The hash algorithm to compute (\c PSA_ALG_XXX value
749 * such that #PSA_ALG_IS_HASH(\p alg) is true).
750 * \param[in] input Buffer containing the message to hash.
751 * \param input_length Size of the \p input buffer in bytes.
752 * \param[out] hash Buffer containing the expected hash value.
753 * \param hash_size Size of the \p hash buffer in bytes.
754 *
755 * \retval #PSA_SUCCESS
756 * The expected hash is identical to the actual hash of the input.
757 * \retval #PSA_ERROR_INVALID_SIGNATURE
758 * The hash of the message was calculated successfully, but it
759 * differs from the expected hash.
760 * \retval #PSA_ERROR_NOT_SUPPORTED
761 * \p alg is not supported or is not a hash algorithm.
762 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
763 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
764 * \retval #PSA_ERROR_HARDWARE_FAILURE
765 * \retval #PSA_ERROR_TAMPERING_DETECTED
766 */
767psa_status_t psa_hash_compare(psa_algorithm_t alg,
768 const uint8_t *input,
769 size_t input_length,
770 const uint8_t *hash,
771 const size_t hash_length);
772
Gilles Peskine308b91d2018-02-08 09:47:44 +0100773/** The type of the state data structure for multipart hash operations.
774 *
Jaeden Amero6a25b412019-01-04 11:47:44 +0000775 * Before calling any function on a hash operation object, the application must
776 * initialize it by any of the following means:
777 * - Set the structure to all-bits-zero, for example:
778 * \code
779 * psa_hash_operation_t operation;
780 * memset(&operation, 0, sizeof(operation));
781 * \endcode
782 * - Initialize the structure to logical zero values, for example:
783 * \code
784 * psa_hash_operation_t operation = {0};
785 * \endcode
786 * - Initialize the structure to the initializer #PSA_HASH_OPERATION_INIT,
787 * for example:
788 * \code
789 * psa_hash_operation_t operation = PSA_HASH_OPERATION_INIT;
790 * \endcode
791 * - Assign the result of the function psa_hash_operation_init()
792 * to the structure, for example:
793 * \code
794 * psa_hash_operation_t operation;
795 * operation = psa_hash_operation_init();
796 * \endcode
797 *
Gilles Peskine92b30732018-03-03 21:29:30 +0100798 * This is an implementation-defined \c struct. Applications should not
Gilles Peskine308b91d2018-02-08 09:47:44 +0100799 * make any assumptions about the content of this structure except
800 * as directed by the documentation of a specific implementation. */
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100801typedef struct psa_hash_operation_s psa_hash_operation_t;
802
Jaeden Amero6a25b412019-01-04 11:47:44 +0000803/** \def PSA_HASH_OPERATION_INIT
804 *
805 * This macro returns a suitable initializer for a hash operation object
806 * of type #psa_hash_operation_t.
807 */
808#ifdef __DOXYGEN_ONLY__
809/* This is an example definition for documentation purposes.
810 * Implementations should define a suitable value in `crypto_struct.h`.
811 */
812#define PSA_HASH_OPERATION_INIT {0}
813#endif
814
815/** Return an initial value for a hash operation object.
816 */
817static psa_hash_operation_t psa_hash_operation_init(void);
818
Gilles Peskinef45adda2019-01-14 18:29:18 +0100819/** Set up a multipart hash operation.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100820 *
821 * The sequence of operations to calculate a hash (message digest)
822 * is as follows:
823 * -# Allocate an operation object which will be passed to all the functions
824 * listed here.
Jaeden Amero6a25b412019-01-04 11:47:44 +0000825 * -# Initialize the operation object with one of the methods described in the
826 * documentation for #psa_hash_operation_t, e.g. PSA_HASH_OPERATION_INIT.
Gilles Peskineda8191d1c2018-07-08 19:46:38 +0200827 * -# Call psa_hash_setup() to specify the algorithm.
Gilles Peskine7e4acc52018-02-16 21:24:11 +0100828 * -# Call psa_hash_update() zero, one or more times, passing a fragment
Gilles Peskine308b91d2018-02-08 09:47:44 +0100829 * of the message each time. The hash that is calculated is the hash
830 * of the concatenation of these messages in order.
831 * -# To calculate the hash, call psa_hash_finish().
832 * To compare the hash with an expected value, call psa_hash_verify().
833 *
834 * The application may call psa_hash_abort() at any time after the operation
Jaeden Amero6a25b412019-01-04 11:47:44 +0000835 * has been initialized.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100836 *
Gilles Peskineda8191d1c2018-07-08 19:46:38 +0200837 * After a successful call to psa_hash_setup(), the application must
Gilles Peskineed522972018-03-20 17:54:15 +0100838 * eventually terminate the operation. The following events terminate an
839 * operation:
Gilles Peskine308b91d2018-02-08 09:47:44 +0100840 * - A failed call to psa_hash_update().
Gilles Peskine19067982018-03-20 17:54:53 +0100841 * - A call to psa_hash_finish(), psa_hash_verify() or psa_hash_abort().
Gilles Peskine308b91d2018-02-08 09:47:44 +0100842 *
Jaeden Amero6a25b412019-01-04 11:47:44 +0000843 * \param[in,out] operation The operation object to set up. It must have
844 * been initialized as per the documentation for
845 * #psa_hash_operation_t and not yet in use.
Gilles Peskineedd11a12018-07-12 01:08:58 +0200846 * \param alg The hash algorithm to compute (\c PSA_ALG_XXX value
847 * such that #PSA_ALG_IS_HASH(\p alg) is true).
Gilles Peskine308b91d2018-02-08 09:47:44 +0100848 *
Gilles Peskine28538492018-07-11 17:34:00 +0200849 * \retval #PSA_SUCCESS
Gilles Peskine308b91d2018-02-08 09:47:44 +0100850 * Success.
Gilles Peskine28538492018-07-11 17:34:00 +0200851 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskinefa4070c2018-07-12 19:23:03 +0200852 * \p alg is not supported or is not a hash algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +0200853 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
854 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
855 * \retval #PSA_ERROR_HARDWARE_FAILURE
856 * \retval #PSA_ERROR_TAMPERING_DETECTED
Gilles Peskine308b91d2018-02-08 09:47:44 +0100857 */
Gilles Peskineda8191d1c2018-07-08 19:46:38 +0200858psa_status_t psa_hash_setup(psa_hash_operation_t *operation,
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100859 psa_algorithm_t alg);
860
Gilles Peskine308b91d2018-02-08 09:47:44 +0100861/** Add a message fragment to a multipart hash operation.
862 *
Gilles Peskineda8191d1c2018-07-08 19:46:38 +0200863 * The application must call psa_hash_setup() before calling this function.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100864 *
865 * If this function returns an error status, the operation becomes inactive.
866 *
Gilles Peskineedd11a12018-07-12 01:08:58 +0200867 * \param[in,out] operation Active hash operation.
868 * \param[in] input Buffer containing the message fragment to hash.
Gilles Peskinefa4070c2018-07-12 19:23:03 +0200869 * \param input_length Size of the \p input buffer in bytes.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100870 *
Gilles Peskine28538492018-07-11 17:34:00 +0200871 * \retval #PSA_SUCCESS
Gilles Peskine308b91d2018-02-08 09:47:44 +0100872 * Success.
Gilles Peskine28538492018-07-11 17:34:00 +0200873 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +0100874 * The operation state is not valid (not set up, or already completed).
Gilles Peskine28538492018-07-11 17:34:00 +0200875 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
876 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
877 * \retval #PSA_ERROR_HARDWARE_FAILURE
878 * \retval #PSA_ERROR_TAMPERING_DETECTED
Gilles Peskine308b91d2018-02-08 09:47:44 +0100879 */
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100880psa_status_t psa_hash_update(psa_hash_operation_t *operation,
881 const uint8_t *input,
882 size_t input_length);
883
Gilles Peskine308b91d2018-02-08 09:47:44 +0100884/** Finish the calculation of the hash of a message.
885 *
Gilles Peskineda8191d1c2018-07-08 19:46:38 +0200886 * The application must call psa_hash_setup() before calling this function.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100887 * This function calculates the hash of the message formed by concatenating
888 * the inputs passed to preceding calls to psa_hash_update().
889 *
890 * When this function returns, the operation becomes inactive.
891 *
892 * \warning Applications should not call this function if they expect
893 * a specific value for the hash. Call psa_hash_verify() instead.
894 * Beware that comparing integrity or authenticity data such as
895 * hash values with a function such as \c memcmp is risky
896 * because the time taken by the comparison may leak information
897 * about the hashed data which could allow an attacker to guess
898 * a valid hash and thereby bypass security controls.
899 *
Gilles Peskineedd11a12018-07-12 01:08:58 +0200900 * \param[in,out] operation Active hash operation.
901 * \param[out] hash Buffer where the hash is to be written.
902 * \param hash_size Size of the \p hash buffer in bytes.
903 * \param[out] hash_length On success, the number of bytes
904 * that make up the hash value. This is always
Gilles Peskinebe42f312018-07-13 14:38:15 +0200905 * #PSA_HASH_SIZE(\c alg) where \c alg is the
Gilles Peskineedd11a12018-07-12 01:08:58 +0200906 * hash algorithm that is calculated.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100907 *
Gilles Peskine28538492018-07-11 17:34:00 +0200908 * \retval #PSA_SUCCESS
Gilles Peskine308b91d2018-02-08 09:47:44 +0100909 * Success.
Gilles Peskine28538492018-07-11 17:34:00 +0200910 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +0100911 * The operation state is not valid (not set up, or already completed).
Gilles Peskine28538492018-07-11 17:34:00 +0200912 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinefa4070c2018-07-12 19:23:03 +0200913 * The size of the \p hash buffer is too small. You can determine a
Gilles Peskine7256e6c2018-07-12 00:34:26 +0200914 * sufficient buffer size by calling #PSA_HASH_SIZE(\c alg)
Gilles Peskine308b91d2018-02-08 09:47:44 +0100915 * where \c alg is the hash algorithm that is calculated.
Gilles Peskine28538492018-07-11 17:34:00 +0200916 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
917 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
918 * \retval #PSA_ERROR_HARDWARE_FAILURE
919 * \retval #PSA_ERROR_TAMPERING_DETECTED
Gilles Peskine308b91d2018-02-08 09:47:44 +0100920 */
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100921psa_status_t psa_hash_finish(psa_hash_operation_t *operation,
922 uint8_t *hash,
923 size_t hash_size,
924 size_t *hash_length);
925
Gilles Peskine308b91d2018-02-08 09:47:44 +0100926/** Finish the calculation of the hash of a message and compare it with
927 * an expected value.
928 *
Gilles Peskineda8191d1c2018-07-08 19:46:38 +0200929 * The application must call psa_hash_setup() before calling this function.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100930 * This function calculates the hash of the message formed by concatenating
931 * the inputs passed to preceding calls to psa_hash_update(). It then
932 * compares the calculated hash with the expected hash passed as a
933 * parameter to this function.
934 *
935 * When this function returns, the operation becomes inactive.
936 *
Gilles Peskine19067982018-03-20 17:54:53 +0100937 * \note Implementations shall make the best effort to ensure that the
Gilles Peskine308b91d2018-02-08 09:47:44 +0100938 * comparison between the actual hash and the expected hash is performed
939 * in constant time.
940 *
Gilles Peskineedd11a12018-07-12 01:08:58 +0200941 * \param[in,out] operation Active hash operation.
942 * \param[in] hash Buffer containing the expected hash value.
Gilles Peskinefa4070c2018-07-12 19:23:03 +0200943 * \param hash_length Size of the \p hash buffer in bytes.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100944 *
Gilles Peskine28538492018-07-11 17:34:00 +0200945 * \retval #PSA_SUCCESS
Gilles Peskine308b91d2018-02-08 09:47:44 +0100946 * The expected hash is identical to the actual hash of the message.
Gilles Peskine28538492018-07-11 17:34:00 +0200947 * \retval #PSA_ERROR_INVALID_SIGNATURE
Gilles Peskine308b91d2018-02-08 09:47:44 +0100948 * The hash of the message was calculated successfully, but it
949 * differs from the expected hash.
Gilles Peskine28538492018-07-11 17:34:00 +0200950 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +0100951 * The operation state is not valid (not set up, or already completed).
Gilles Peskine28538492018-07-11 17:34:00 +0200952 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
953 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
954 * \retval #PSA_ERROR_HARDWARE_FAILURE
955 * \retval #PSA_ERROR_TAMPERING_DETECTED
Gilles Peskine308b91d2018-02-08 09:47:44 +0100956 */
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100957psa_status_t psa_hash_verify(psa_hash_operation_t *operation,
958 const uint8_t *hash,
959 size_t hash_length);
960
Gilles Peskine308b91d2018-02-08 09:47:44 +0100961/** Abort a hash operation.
962 *
Gilles Peskine308b91d2018-02-08 09:47:44 +0100963 * Aborting an operation frees all associated resources except for the
Gilles Peskineb82ab6f2018-07-13 15:33:43 +0200964 * \p operation structure itself. Once aborted, the operation object
965 * can be reused for another operation by calling
966 * psa_hash_setup() again.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100967 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +0200968 * You may call this function any time after the operation object has
969 * been initialized by any of the following methods:
970 * - A call to psa_hash_setup(), whether it succeeds or not.
971 * - Initializing the \c struct to all-bits-zero.
972 * - Initializing the \c struct to logical zeros, e.g.
973 * `psa_hash_operation_t operation = {0}`.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100974 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +0200975 * In particular, calling psa_hash_abort() after the operation has been
976 * terminated by a call to psa_hash_abort(), psa_hash_finish() or
977 * psa_hash_verify() is safe and has no effect.
978 *
979 * \param[in,out] operation Initialized hash operation.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100980 *
Gilles Peskine28538492018-07-11 17:34:00 +0200981 * \retval #PSA_SUCCESS
982 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinefa4070c2018-07-12 19:23:03 +0200983 * \p operation is not an active hash operation.
Gilles Peskine28538492018-07-11 17:34:00 +0200984 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
985 * \retval #PSA_ERROR_HARDWARE_FAILURE
986 * \retval #PSA_ERROR_TAMPERING_DETECTED
Gilles Peskine308b91d2018-02-08 09:47:44 +0100987 */
988psa_status_t psa_hash_abort(psa_hash_operation_t *operation);
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100989
990/**@}*/
991
Gilles Peskine8c9def32018-02-08 10:02:12 +0100992/** \defgroup MAC Message authentication codes
993 * @{
994 */
995
Gilles Peskine69647a42019-01-14 20:18:12 +0100996/** Calculate the MAC (message authentication code) of a message.
997 *
998 * \note To verify the MAC of a message against an
999 * expected value, use psa_mac_verify() instead.
1000 * Beware that comparing integrity or authenticity data such as
1001 * MAC values with a function such as \c memcmp is risky
1002 * because the time taken by the comparison may leak information
1003 * about the MAC value which could allow an attacker to guess
1004 * a valid MAC and thereby bypass security controls.
1005 *
1006 * \param handle Handle to the key to use for the operation.
1007 * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
1008 * such that #PSA_ALG_IS_MAC(alg) is true).
1009 * \param[in] input Buffer containing the input message.
1010 * \param input_length Size of the \p input buffer in bytes.
1011 * \param[out] mac Buffer where the MAC value is to be written.
1012 * \param mac_size Size of the \p mac buffer in bytes.
1013 * \param[out] mac_length On success, the number of bytes
1014 * that make up the mac value. This is always
1015 * #PSA_HASH_SIZE(\c alg) where \c alg is the
1016 * hash algorithm that is calculated.
1017 *
1018 * \retval #PSA_SUCCESS
1019 * Success.
1020 * \retval #PSA_ERROR_INVALID_HANDLE
1021 * \retval #PSA_ERROR_EMPTY_SLOT
1022 * \retval #PSA_ERROR_NOT_PERMITTED
1023 * \retval #PSA_ERROR_INVALID_ARGUMENT
1024 * \p key is not compatible with \p alg.
1025 * \retval #PSA_ERROR_NOT_SUPPORTED
1026 * \p alg is not supported or is not a MAC algorithm.
1027 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1028 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1029 * \retval #PSA_ERROR_HARDWARE_FAILURE
1030 * \retval #PSA_ERROR_TAMPERING_DETECTED
1031 * \retval #PSA_ERROR_BAD_STATE
1032 * The library has not been previously initialized by psa_crypto_init().
1033 * It is implementation-dependent whether a failure to initialize
1034 * results in this error code.
1035 */
1036psa_status_t psa_mac_compute(psa_key_handle_t handle,
1037 psa_algorithm_t alg,
1038 const uint8_t *input,
1039 size_t input_length,
1040 uint8_t *mac,
1041 size_t mac_size,
1042 size_t *mac_length);
1043
1044/** Calculate the MAC of a message and compare it with a reference value.
1045 *
1046 * \param handle Handle to the key to use for the operation.
1047 * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
1048 * such that #PSA_ALG_IS_MAC(alg) is true).
1049 * \param[in] input Buffer containing the input message.
1050 * \param input_length Size of the \p input buffer in bytes.
1051 * \param[out] mac Buffer containing the expected MAC value.
1052 * \param mac_length Size of the \p mac buffer in bytes.
1053 *
1054 * \retval #PSA_SUCCESS
1055 * The expected MAC is identical to the actual MAC of the input.
1056 * \retval #PSA_ERROR_INVALID_SIGNATURE
1057 * The MAC of the message was calculated successfully, but it
1058 * differs from the expected value.
1059 * \retval #PSA_ERROR_INVALID_HANDLE
1060 * \retval #PSA_ERROR_EMPTY_SLOT
1061 * \retval #PSA_ERROR_NOT_PERMITTED
1062 * \retval #PSA_ERROR_INVALID_ARGUMENT
1063 * \p key is not compatible with \p alg.
1064 * \retval #PSA_ERROR_NOT_SUPPORTED
1065 * \p alg is not supported or is not a MAC algorithm.
1066 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1067 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1068 * \retval #PSA_ERROR_HARDWARE_FAILURE
1069 * \retval #PSA_ERROR_TAMPERING_DETECTED
1070 */
1071psa_status_t psa_mac_verify(psa_algorithm_t alg,
1072 const uint8_t *input,
1073 size_t input_length,
1074 const uint8_t *mac,
1075 const size_t mac_length);
1076
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001077/** The type of the state data structure for multipart MAC operations.
1078 *
Jaeden Amero769ce272019-01-04 11:48:03 +00001079 * Before calling any function on a MAC operation object, the application must
1080 * initialize it by any of the following means:
1081 * - Set the structure to all-bits-zero, for example:
1082 * \code
1083 * psa_mac_operation_t operation;
1084 * memset(&operation, 0, sizeof(operation));
1085 * \endcode
1086 * - Initialize the structure to logical zero values, for example:
1087 * \code
1088 * psa_mac_operation_t operation = {0};
1089 * \endcode
1090 * - Initialize the structure to the initializer #PSA_MAC_OPERATION_INIT,
1091 * for example:
1092 * \code
1093 * psa_mac_operation_t operation = PSA_MAC_OPERATION_INIT;
1094 * \endcode
1095 * - Assign the result of the function psa_mac_operation_init()
1096 * to the structure, for example:
1097 * \code
1098 * psa_mac_operation_t operation;
1099 * operation = psa_mac_operation_init();
1100 * \endcode
1101 *
Gilles Peskine92b30732018-03-03 21:29:30 +01001102 * This is an implementation-defined \c struct. Applications should not
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001103 * make any assumptions about the content of this structure except
1104 * as directed by the documentation of a specific implementation. */
Gilles Peskine8c9def32018-02-08 10:02:12 +01001105typedef struct psa_mac_operation_s psa_mac_operation_t;
1106
Jaeden Amero769ce272019-01-04 11:48:03 +00001107/** \def PSA_MAC_OPERATION_INIT
1108 *
1109 * This macro returns a suitable initializer for a MAC operation object of type
1110 * #psa_mac_operation_t.
1111 */
1112#ifdef __DOXYGEN_ONLY__
1113/* This is an example definition for documentation purposes.
1114 * Implementations should define a suitable value in `crypto_struct.h`.
1115 */
1116#define PSA_MAC_OPERATION_INIT {0}
1117#endif
1118
1119/** Return an initial value for a MAC operation object.
1120 */
1121static psa_mac_operation_t psa_mac_operation_init(void);
1122
Gilles Peskinef45adda2019-01-14 18:29:18 +01001123/** Set up a multipart MAC calculation operation.
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001124 *
Gilles Peskine89167cb2018-07-08 20:12:23 +02001125 * This function sets up the calculation of the MAC
1126 * (message authentication code) of a byte string.
1127 * To verify the MAC of a message against an
1128 * expected value, use psa_mac_verify_setup() instead.
1129 *
1130 * The sequence of operations to calculate a MAC is as follows:
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001131 * -# Allocate an operation object which will be passed to all the functions
1132 * listed here.
Jaeden Amero769ce272019-01-04 11:48:03 +00001133 * -# Initialize the operation object with one of the methods described in the
1134 * documentation for #psa_mac_operation_t, e.g. PSA_MAC_OPERATION_INIT.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001135 * -# Call psa_mac_sign_setup() to specify the algorithm and key.
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001136 * -# Call psa_mac_update() zero, one or more times, passing a fragment
1137 * of the message each time. The MAC that is calculated is the MAC
1138 * of the concatenation of these messages in order.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001139 * -# At the end of the message, call psa_mac_sign_finish() to finish
1140 * calculating the MAC value and retrieve it.
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001141 *
1142 * The application may call psa_mac_abort() at any time after the operation
Jaeden Amero769ce272019-01-04 11:48:03 +00001143 * has been initialized.
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001144 *
Gilles Peskine89167cb2018-07-08 20:12:23 +02001145 * After a successful call to psa_mac_sign_setup(), the application must
1146 * eventually terminate the operation through one of the following methods:
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001147 * - A failed call to psa_mac_update().
Gilles Peskine89167cb2018-07-08 20:12:23 +02001148 * - A call to psa_mac_sign_finish() or psa_mac_abort().
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001149 *
Jaeden Amero769ce272019-01-04 11:48:03 +00001150 * \param[in,out] operation The operation object to set up. It must have
1151 * been initialized as per the documentation for
1152 * #psa_mac_operation_t and not yet in use.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001153 * \param handle Handle to the key to use for the operation.
Gilles Peskine5f25dd02019-01-14 18:24:53 +01001154 * It must remain valid until the operation
1155 * terminates.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001156 * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
1157 * such that #PSA_ALG_IS_MAC(alg) is true).
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001158 *
Gilles Peskine28538492018-07-11 17:34:00 +02001159 * \retval #PSA_SUCCESS
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001160 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001161 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine28538492018-07-11 17:34:00 +02001162 * \retval #PSA_ERROR_EMPTY_SLOT
1163 * \retval #PSA_ERROR_NOT_PERMITTED
1164 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001165 * \p key is not compatible with \p alg.
Gilles Peskine28538492018-07-11 17:34:00 +02001166 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001167 * \p alg is not supported or is not a MAC algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02001168 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1169 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1170 * \retval #PSA_ERROR_HARDWARE_FAILURE
1171 * \retval #PSA_ERROR_TAMPERING_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03001172 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03001173 * The library has not been previously initialized by psa_crypto_init().
1174 * It is implementation-dependent whether a failure to initialize
1175 * results in this error code.
Gilles Peskine7e4acc52018-02-16 21:24:11 +01001176 */
Gilles Peskine89167cb2018-07-08 20:12:23 +02001177psa_status_t psa_mac_sign_setup(psa_mac_operation_t *operation,
Gilles Peskineae32aac2018-11-30 14:39:32 +01001178 psa_key_handle_t handle,
Gilles Peskine89167cb2018-07-08 20:12:23 +02001179 psa_algorithm_t alg);
1180
Gilles Peskinef45adda2019-01-14 18:29:18 +01001181/** Set up a multipart MAC verification operation.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001182 *
1183 * This function sets up the verification of the MAC
1184 * (message authentication code) of a byte string against an expected value.
1185 *
1186 * The sequence of operations to verify a MAC is as follows:
1187 * -# Allocate an operation object which will be passed to all the functions
1188 * listed here.
Jaeden Amero769ce272019-01-04 11:48:03 +00001189 * -# Initialize the operation object with one of the methods described in the
1190 * documentation for #psa_mac_operation_t, e.g. PSA_MAC_OPERATION_INIT.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001191 * -# Call psa_mac_verify_setup() to specify the algorithm and key.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001192 * -# Call psa_mac_update() zero, one or more times, passing a fragment
1193 * of the message each time. The MAC that is calculated is the MAC
1194 * of the concatenation of these messages in order.
1195 * -# At the end of the message, call psa_mac_verify_finish() to finish
1196 * calculating the actual MAC of the message and verify it against
1197 * the expected value.
1198 *
1199 * The application may call psa_mac_abort() at any time after the operation
Jaeden Amero769ce272019-01-04 11:48:03 +00001200 * has been initialized.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001201 *
1202 * After a successful call to psa_mac_verify_setup(), the application must
1203 * eventually terminate the operation through one of the following methods:
1204 * - A failed call to psa_mac_update().
1205 * - A call to psa_mac_verify_finish() or psa_mac_abort().
1206 *
Jaeden Amero769ce272019-01-04 11:48:03 +00001207 * \param[in,out] operation The operation object to set up. It must have
1208 * been initialized as per the documentation for
1209 * #psa_mac_operation_t and not yet in use.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001210 * \param handle Handle to the key to use for the operation.
Gilles Peskine5f25dd02019-01-14 18:24:53 +01001211 * It must remain valid until the operation
1212 * terminates.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001213 * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
1214 * such that #PSA_ALG_IS_MAC(\p alg) is true).
Gilles Peskine89167cb2018-07-08 20:12:23 +02001215 *
Gilles Peskine28538492018-07-11 17:34:00 +02001216 * \retval #PSA_SUCCESS
Gilles Peskine89167cb2018-07-08 20:12:23 +02001217 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001218 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine28538492018-07-11 17:34:00 +02001219 * \retval #PSA_ERROR_EMPTY_SLOT
1220 * \retval #PSA_ERROR_NOT_PERMITTED
1221 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskine89167cb2018-07-08 20:12:23 +02001222 * \c key is not compatible with \c alg.
Gilles Peskine28538492018-07-11 17:34:00 +02001223 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskine89167cb2018-07-08 20:12:23 +02001224 * \c alg is not supported or is not a MAC algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02001225 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1226 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1227 * \retval #PSA_ERROR_HARDWARE_FAILURE
1228 * \retval #PSA_ERROR_TAMPERING_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03001229 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03001230 * The library has not been previously initialized by psa_crypto_init().
1231 * It is implementation-dependent whether a failure to initialize
1232 * results in this error code.
Gilles Peskine89167cb2018-07-08 20:12:23 +02001233 */
1234psa_status_t psa_mac_verify_setup(psa_mac_operation_t *operation,
Gilles Peskineae32aac2018-11-30 14:39:32 +01001235 psa_key_handle_t handle,
Gilles Peskine89167cb2018-07-08 20:12:23 +02001236 psa_algorithm_t alg);
Gilles Peskine8c9def32018-02-08 10:02:12 +01001237
Gilles Peskinedcd14942018-07-12 00:30:52 +02001238/** Add a message fragment to a multipart MAC operation.
1239 *
1240 * The application must call psa_mac_sign_setup() or psa_mac_verify_setup()
1241 * before calling this function.
1242 *
1243 * If this function returns an error status, the operation becomes inactive.
1244 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001245 * \param[in,out] operation Active MAC operation.
1246 * \param[in] input Buffer containing the message fragment to add to
1247 * the MAC calculation.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001248 * \param input_length Size of the \p input buffer in bytes.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001249 *
1250 * \retval #PSA_SUCCESS
1251 * Success.
1252 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001253 * The operation state is not valid (not set up, or already completed).
Gilles Peskinedcd14942018-07-12 00:30:52 +02001254 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1255 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1256 * \retval #PSA_ERROR_HARDWARE_FAILURE
1257 * \retval #PSA_ERROR_TAMPERING_DETECTED
1258 */
Gilles Peskine8c9def32018-02-08 10:02:12 +01001259psa_status_t psa_mac_update(psa_mac_operation_t *operation,
1260 const uint8_t *input,
1261 size_t input_length);
1262
Gilles Peskinedcd14942018-07-12 00:30:52 +02001263/** Finish the calculation of the MAC of a message.
1264 *
1265 * The application must call psa_mac_sign_setup() before calling this function.
1266 * This function calculates the MAC of the message formed by concatenating
1267 * the inputs passed to preceding calls to psa_mac_update().
1268 *
1269 * When this function returns, the operation becomes inactive.
1270 *
1271 * \warning Applications should not call this function if they expect
1272 * a specific value for the MAC. Call psa_mac_verify_finish() instead.
1273 * Beware that comparing integrity or authenticity data such as
1274 * MAC values with a function such as \c memcmp is risky
1275 * because the time taken by the comparison may leak information
1276 * about the MAC value which could allow an attacker to guess
1277 * a valid MAC and thereby bypass security controls.
1278 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001279 * \param[in,out] operation Active MAC operation.
1280 * \param[out] mac Buffer where the MAC value is to be written.
1281 * \param mac_size Size of the \p mac buffer in bytes.
1282 * \param[out] mac_length On success, the number of bytes
1283 * that make up the MAC value. This is always
Gilles Peskinedda3bd32018-07-12 19:40:46 +02001284 * #PSA_MAC_FINAL_SIZE(\c key_type, \c key_bits, \c alg)
Gilles Peskineedd11a12018-07-12 01:08:58 +02001285 * where \c key_type and \c key_bits are the type and
Gilles Peskinedda3bd32018-07-12 19:40:46 +02001286 * bit-size respectively of the key and \c alg is the
Gilles Peskineedd11a12018-07-12 01:08:58 +02001287 * MAC algorithm that is calculated.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001288 *
1289 * \retval #PSA_SUCCESS
1290 * Success.
1291 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001292 * The operation state is not valid (not set up, or already completed).
Gilles Peskinedcd14942018-07-12 00:30:52 +02001293 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001294 * The size of the \p mac buffer is too small. You can determine a
Gilles Peskinedcd14942018-07-12 00:30:52 +02001295 * sufficient buffer size by calling PSA_MAC_FINAL_SIZE().
1296 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1297 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1298 * \retval #PSA_ERROR_HARDWARE_FAILURE
1299 * \retval #PSA_ERROR_TAMPERING_DETECTED
1300 */
Gilles Peskineacd4be32018-07-08 19:56:25 +02001301psa_status_t psa_mac_sign_finish(psa_mac_operation_t *operation,
1302 uint8_t *mac,
1303 size_t mac_size,
1304 size_t *mac_length);
Gilles Peskine8c9def32018-02-08 10:02:12 +01001305
Gilles Peskinedcd14942018-07-12 00:30:52 +02001306/** Finish the calculation of the MAC of a message and compare it with
1307 * an expected value.
1308 *
1309 * The application must call psa_mac_verify_setup() before calling this function.
1310 * This function calculates the MAC of the message formed by concatenating
1311 * the inputs passed to preceding calls to psa_mac_update(). It then
1312 * compares the calculated MAC with the expected MAC passed as a
1313 * parameter to this function.
1314 *
1315 * When this function returns, the operation becomes inactive.
1316 *
1317 * \note Implementations shall make the best effort to ensure that the
1318 * comparison between the actual MAC and the expected MAC is performed
1319 * in constant time.
1320 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001321 * \param[in,out] operation Active MAC operation.
1322 * \param[in] mac Buffer containing the expected MAC value.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001323 * \param mac_length Size of the \p mac buffer in bytes.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001324 *
1325 * \retval #PSA_SUCCESS
1326 * The expected MAC is identical to the actual MAC of the message.
1327 * \retval #PSA_ERROR_INVALID_SIGNATURE
1328 * The MAC of the message was calculated successfully, but it
1329 * differs from the expected MAC.
1330 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001331 * The operation state is not valid (not set up, or already completed).
Gilles Peskinedcd14942018-07-12 00:30:52 +02001332 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1333 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1334 * \retval #PSA_ERROR_HARDWARE_FAILURE
1335 * \retval #PSA_ERROR_TAMPERING_DETECTED
1336 */
Gilles Peskineacd4be32018-07-08 19:56:25 +02001337psa_status_t psa_mac_verify_finish(psa_mac_operation_t *operation,
1338 const uint8_t *mac,
1339 size_t mac_length);
Gilles Peskine8c9def32018-02-08 10:02:12 +01001340
Gilles Peskinedcd14942018-07-12 00:30:52 +02001341/** Abort a MAC operation.
1342 *
Gilles Peskinedcd14942018-07-12 00:30:52 +02001343 * Aborting an operation frees all associated resources except for the
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001344 * \p operation structure itself. Once aborted, the operation object
1345 * can be reused for another operation by calling
1346 * psa_mac_sign_setup() or psa_mac_verify_setup() again.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001347 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001348 * You may call this function any time after the operation object has
1349 * been initialized by any of the following methods:
1350 * - A call to psa_mac_sign_setup() or psa_mac_verify_setup(), whether
1351 * it succeeds or not.
1352 * - Initializing the \c struct to all-bits-zero.
1353 * - Initializing the \c struct to logical zeros, e.g.
1354 * `psa_mac_operation_t operation = {0}`.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001355 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001356 * In particular, calling psa_mac_abort() after the operation has been
1357 * terminated by a call to psa_mac_abort(), psa_mac_sign_finish() or
1358 * psa_mac_verify_finish() is safe and has no effect.
1359 *
1360 * \param[in,out] operation Initialized MAC operation.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001361 *
1362 * \retval #PSA_SUCCESS
1363 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001364 * \p operation is not an active MAC operation.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001365 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1366 * \retval #PSA_ERROR_HARDWARE_FAILURE
1367 * \retval #PSA_ERROR_TAMPERING_DETECTED
1368 */
Gilles Peskine8c9def32018-02-08 10:02:12 +01001369psa_status_t psa_mac_abort(psa_mac_operation_t *operation);
1370
1371/**@}*/
1372
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001373/** \defgroup cipher Symmetric ciphers
1374 * @{
1375 */
1376
Gilles Peskine69647a42019-01-14 20:18:12 +01001377/** Encrypt a message using a symmetric cipher.
1378 *
1379 * This function encrypts a message with a random IV (initialization
1380 * vector).
1381 *
1382 * \param handle Handle to the key to use for the operation.
1383 * It must remain valid until the operation
1384 * terminates.
1385 * \param alg The cipher algorithm to compute
1386 * (\c PSA_ALG_XXX value such that
1387 * #PSA_ALG_IS_CIPHER(\p alg) is true).
1388 * \param[in] input Buffer containing the message to encrypt.
1389 * \param input_length Size of the \p input buffer in bytes.
1390 * \param[out] output Buffer where the output is to be written.
1391 * The output contains the IV followed by
1392 * the ciphertext proper.
1393 * \param output_size Size of the \p output buffer in bytes.
1394 * \param[out] output_length On success, the number of bytes
1395 * that make up the output.
1396 *
1397 * \retval #PSA_SUCCESS
1398 * Success.
1399 * \retval #PSA_ERROR_INVALID_HANDLE
1400 * \retval #PSA_ERROR_EMPTY_SLOT
1401 * \retval #PSA_ERROR_NOT_PERMITTED
1402 * \retval #PSA_ERROR_INVALID_ARGUMENT
1403 * \p key is not compatible with \p alg.
1404 * \retval #PSA_ERROR_NOT_SUPPORTED
1405 * \p alg is not supported or is not a cipher algorithm.
1406 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
1407 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1408 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1409 * \retval #PSA_ERROR_HARDWARE_FAILURE
1410 * \retval #PSA_ERROR_TAMPERING_DETECTED
1411 */
1412psa_status_t psa_cipher_encrypt(psa_key_handle_t handle,
1413 psa_algorithm_t alg,
1414 const uint8_t *input,
1415 size_t input_length,
1416 uint8_t *output,
1417 size_t output_size,
1418 size_t *output_length);
1419
1420/** Decrypt a message using a symmetric cipher.
1421 *
1422 * This function decrypts a message encrypted with a symmetric cipher.
1423 *
1424 * \param handle Handle to the key to use for the operation.
1425 * It must remain valid until the operation
1426 * terminates.
1427 * \param alg The cipher algorithm to compute
1428 * (\c PSA_ALG_XXX value such that
1429 * #PSA_ALG_IS_CIPHER(\p alg) is true).
1430 * \param[in] input Buffer containing the message to decrypt.
1431 * This consists of the IV followed by the
1432 * ciphertext proper.
1433 * \param input_length Size of the \p input buffer in bytes.
1434 * \param[out] output Buffer where the plaintext is to be written.
1435 * \param output_size Size of the \p output buffer in bytes.
1436 * \param[out] output_length On success, the number of bytes
1437 * that make up the output.
1438 *
1439 * \retval #PSA_SUCCESS
1440 * Success.
1441 * \retval #PSA_ERROR_INVALID_HANDLE
1442 * \retval #PSA_ERROR_EMPTY_SLOT
1443 * \retval #PSA_ERROR_NOT_PERMITTED
1444 * \retval #PSA_ERROR_INVALID_ARGUMENT
1445 * \p key is not compatible with \p alg.
1446 * \retval #PSA_ERROR_NOT_SUPPORTED
1447 * \p alg is not supported or is not a cipher algorithm.
1448 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
1449 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1450 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1451 * \retval #PSA_ERROR_HARDWARE_FAILURE
1452 * \retval #PSA_ERROR_TAMPERING_DETECTED
1453 */
1454psa_status_t psa_cipher_decrypt(psa_key_handle_t handle,
1455 psa_algorithm_t alg,
1456 const uint8_t *input,
1457 size_t input_length,
1458 uint8_t *output,
1459 size_t output_size,
1460 size_t *output_length);
1461
1462/** Calculate the MAC of a message and compare it with a reference value.
1463 *
1464 * \param handle Handle to the key to use for the operation.
1465 * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
1466 * such that #PSA_ALG_IS_MAC(alg) is true).
1467 * \param[in] input Buffer containing the input message.
1468 * \param input_length Size of the \p input buffer in bytes.
1469 * \param[out] mac Buffer containing the expected MAC value.
1470 * \param mac_length Size of the \p mac buffer in bytes.
1471 *
1472 * \retval #PSA_SUCCESS
1473 * The expected MAC is identical to the actual MAC of the input.
1474 * \retval #PSA_ERROR_INVALID_SIGNATURE
1475 * The MAC of the message was calculated successfully, but it
1476 * differs from the expected value.
1477 * \retval #PSA_ERROR_INVALID_HANDLE
1478 * \retval #PSA_ERROR_EMPTY_SLOT
1479 * \retval #PSA_ERROR_NOT_PERMITTED
1480 * \retval #PSA_ERROR_INVALID_ARGUMENT
1481 * \p key is not compatible with \p alg.
1482 * \retval #PSA_ERROR_NOT_SUPPORTED
1483 * \p alg is not supported or is not a MAC algorithm.
1484 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1485 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1486 * \retval #PSA_ERROR_HARDWARE_FAILURE
1487 * \retval #PSA_ERROR_TAMPERING_DETECTED
1488 */
1489psa_status_t psa_mac_verify(psa_algorithm_t alg,
1490 const uint8_t *input,
1491 size_t input_length,
1492 const uint8_t *mac,
1493 const size_t mac_length);
1494
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001495/** The type of the state data structure for multipart cipher operations.
1496 *
Jaeden Amero5bae2272019-01-04 11:48:27 +00001497 * Before calling any function on a cipher operation object, the application
1498 * must initialize it by any of the following means:
1499 * - Set the structure to all-bits-zero, for example:
1500 * \code
1501 * psa_cipher_operation_t operation;
1502 * memset(&operation, 0, sizeof(operation));
1503 * \endcode
1504 * - Initialize the structure to logical zero values, for example:
1505 * \code
1506 * psa_cipher_operation_t operation = {0};
1507 * \endcode
1508 * - Initialize the structure to the initializer #PSA_CIPHER_OPERATION_INIT,
1509 * for example:
1510 * \code
1511 * psa_cipher_operation_t operation = PSA_CIPHER_OPERATION_INIT;
1512 * \endcode
1513 * - Assign the result of the function psa_cipher_operation_init()
1514 * to the structure, for example:
1515 * \code
1516 * psa_cipher_operation_t operation;
1517 * operation = psa_cipher_operation_init();
1518 * \endcode
1519 *
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001520 * This is an implementation-defined \c struct. Applications should not
1521 * make any assumptions about the content of this structure except
1522 * as directed by the documentation of a specific implementation. */
1523typedef struct psa_cipher_operation_s psa_cipher_operation_t;
1524
Jaeden Amero5bae2272019-01-04 11:48:27 +00001525/** \def PSA_CIPHER_OPERATION_INIT
1526 *
1527 * This macro returns a suitable initializer for a cipher operation object of
1528 * type #psa_cipher_operation_t.
1529 */
1530#ifdef __DOXYGEN_ONLY__
1531/* This is an example definition for documentation purposes.
1532 * Implementations should define a suitable value in `crypto_struct.h`.
1533 */
1534#define PSA_CIPHER_OPERATION_INIT {0}
1535#endif
1536
1537/** Return an initial value for a cipher operation object.
1538 */
1539static psa_cipher_operation_t psa_cipher_operation_init(void);
1540
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001541/** Set the key for a multipart symmetric encryption operation.
1542 *
1543 * The sequence of operations to encrypt a message with a symmetric cipher
1544 * is as follows:
1545 * -# Allocate an operation object which will be passed to all the functions
1546 * listed here.
Jaeden Amero5bae2272019-01-04 11:48:27 +00001547 * -# Initialize the operation object with one of the methods described in the
1548 * documentation for #psa_cipher_operation_t, e.g.
1549 * PSA_CIPHER_OPERATION_INIT.
Gilles Peskinefe119512018-07-08 21:39:34 +02001550 * -# Call psa_cipher_encrypt_setup() to specify the algorithm and key.
itayzafrired7382f2018-08-02 14:19:33 +03001551 * -# Call either psa_cipher_generate_iv() or psa_cipher_set_iv() to
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001552 * generate or set the IV (initialization vector). You should use
itayzafrired7382f2018-08-02 14:19:33 +03001553 * psa_cipher_generate_iv() unless the protocol you are implementing
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001554 * requires a specific IV value.
1555 * -# Call psa_cipher_update() zero, one or more times, passing a fragment
1556 * of the message each time.
1557 * -# Call psa_cipher_finish().
1558 *
1559 * The application may call psa_cipher_abort() at any time after the operation
Jaeden Amero5bae2272019-01-04 11:48:27 +00001560 * has been initialized.
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001561 *
Gilles Peskinefe119512018-07-08 21:39:34 +02001562 * After a successful call to psa_cipher_encrypt_setup(), the application must
Gilles Peskineed522972018-03-20 17:54:15 +01001563 * eventually terminate the operation. The following events terminate an
1564 * operation:
Gilles Peskinef45adda2019-01-14 18:29:18 +01001565 * - A failed call to any of the \c psa_cipher_xxx functions.
Gilles Peskine19067982018-03-20 17:54:53 +01001566 * - A call to psa_cipher_finish() or psa_cipher_abort().
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001567 *
Jaeden Amero5bae2272019-01-04 11:48:27 +00001568 * \param[in,out] operation The operation object to set up. It must have
1569 * been initialized as per the documentation for
1570 * #psa_cipher_operation_t and not yet in use.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001571 * \param handle Handle to the key to use for the operation.
Gilles Peskine5f25dd02019-01-14 18:24:53 +01001572 * It must remain valid until the operation
1573 * terminates.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001574 * \param alg The cipher algorithm to compute
1575 * (\c PSA_ALG_XXX value such that
1576 * #PSA_ALG_IS_CIPHER(\p alg) is true).
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001577 *
Gilles Peskine28538492018-07-11 17:34:00 +02001578 * \retval #PSA_SUCCESS
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001579 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001580 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine28538492018-07-11 17:34:00 +02001581 * \retval #PSA_ERROR_EMPTY_SLOT
1582 * \retval #PSA_ERROR_NOT_PERMITTED
1583 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001584 * \p key is not compatible with \p alg.
Gilles Peskine28538492018-07-11 17:34:00 +02001585 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001586 * \p alg is not supported or is not a cipher algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02001587 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1588 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1589 * \retval #PSA_ERROR_HARDWARE_FAILURE
1590 * \retval #PSA_ERROR_TAMPERING_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03001591 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03001592 * The library has not been previously initialized by psa_crypto_init().
1593 * It is implementation-dependent whether a failure to initialize
1594 * results in this error code.
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001595 */
Gilles Peskinefe119512018-07-08 21:39:34 +02001596psa_status_t psa_cipher_encrypt_setup(psa_cipher_operation_t *operation,
Gilles Peskineae32aac2018-11-30 14:39:32 +01001597 psa_key_handle_t handle,
Gilles Peskinefe119512018-07-08 21:39:34 +02001598 psa_algorithm_t alg);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001599
1600/** Set the key for a multipart symmetric decryption operation.
1601 *
1602 * The sequence of operations to decrypt a message with a symmetric cipher
1603 * is as follows:
1604 * -# Allocate an operation object which will be passed to all the functions
1605 * listed here.
Jaeden Amero5bae2272019-01-04 11:48:27 +00001606 * -# Initialize the operation object with one of the methods described in the
1607 * documentation for #psa_cipher_operation_t, e.g.
1608 * PSA_CIPHER_OPERATION_INIT.
Gilles Peskinefe119512018-07-08 21:39:34 +02001609 * -# Call psa_cipher_decrypt_setup() to specify the algorithm and key.
Gilles Peskinef45adda2019-01-14 18:29:18 +01001610 * -# Call psa_cipher_set_iv() with the IV (initialization vector) for the
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001611 * decryption. If the IV is prepended to the ciphertext, you can call
1612 * psa_cipher_update() on a buffer containing the IV followed by the
1613 * beginning of the message.
1614 * -# Call psa_cipher_update() zero, one or more times, passing a fragment
1615 * of the message each time.
1616 * -# Call psa_cipher_finish().
1617 *
1618 * The application may call psa_cipher_abort() at any time after the operation
Jaeden Amero5bae2272019-01-04 11:48:27 +00001619 * has been initialized.
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001620 *
Gilles Peskinefe119512018-07-08 21:39:34 +02001621 * After a successful call to psa_cipher_decrypt_setup(), the application must
Gilles Peskineed522972018-03-20 17:54:15 +01001622 * eventually terminate the operation. The following events terminate an
1623 * operation:
Gilles Peskinef45adda2019-01-14 18:29:18 +01001624 * - A failed call to any of the \c psa_cipher_xxx functions.
Gilles Peskine19067982018-03-20 17:54:53 +01001625 * - A call to psa_cipher_finish() or psa_cipher_abort().
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001626 *
Jaeden Amero5bae2272019-01-04 11:48:27 +00001627 * \param[in,out] operation The operation object to set up. It must have
1628 * been initialized as per the documentation for
1629 * #psa_cipher_operation_t and not yet in use.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001630 * \param handle Handle to the key to use for the operation.
Gilles Peskine5f25dd02019-01-14 18:24:53 +01001631 * It must remain valid until the operation
1632 * terminates.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001633 * \param alg The cipher algorithm to compute
1634 * (\c PSA_ALG_XXX value such that
1635 * #PSA_ALG_IS_CIPHER(\p alg) is true).
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001636 *
Gilles Peskine28538492018-07-11 17:34:00 +02001637 * \retval #PSA_SUCCESS
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001638 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001639 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine28538492018-07-11 17:34:00 +02001640 * \retval #PSA_ERROR_EMPTY_SLOT
1641 * \retval #PSA_ERROR_NOT_PERMITTED
1642 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001643 * \p key is not compatible with \p alg.
Gilles Peskine28538492018-07-11 17:34:00 +02001644 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001645 * \p alg is not supported or is not a cipher algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02001646 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1647 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1648 * \retval #PSA_ERROR_HARDWARE_FAILURE
1649 * \retval #PSA_ERROR_TAMPERING_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03001650 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03001651 * The library has not been previously initialized by psa_crypto_init().
1652 * It is implementation-dependent whether a failure to initialize
1653 * results in this error code.
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001654 */
Gilles Peskinefe119512018-07-08 21:39:34 +02001655psa_status_t psa_cipher_decrypt_setup(psa_cipher_operation_t *operation,
Gilles Peskineae32aac2018-11-30 14:39:32 +01001656 psa_key_handle_t handle,
Gilles Peskinefe119512018-07-08 21:39:34 +02001657 psa_algorithm_t alg);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001658
Gilles Peskinedcd14942018-07-12 00:30:52 +02001659/** Generate an IV for a symmetric encryption operation.
1660 *
1661 * This function generates a random IV (initialization vector), nonce
1662 * or initial counter value for the encryption operation as appropriate
1663 * for the chosen algorithm, key type and key size.
1664 *
1665 * The application must call psa_cipher_encrypt_setup() before
1666 * calling this function.
1667 *
1668 * If this function returns an error status, the operation becomes inactive.
1669 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001670 * \param[in,out] operation Active cipher operation.
1671 * \param[out] iv Buffer where the generated IV is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001672 * \param iv_size Size of the \p iv buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001673 * \param[out] iv_length On success, the number of bytes of the
1674 * generated IV.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001675 *
1676 * \retval #PSA_SUCCESS
1677 * Success.
1678 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001679 * The operation state is not valid (not set up, or IV already set).
Gilles Peskinedcd14942018-07-12 00:30:52 +02001680 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinedda3bd32018-07-12 19:40:46 +02001681 * The size of the \p iv buffer is too small.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001682 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1683 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1684 * \retval #PSA_ERROR_HARDWARE_FAILURE
1685 * \retval #PSA_ERROR_TAMPERING_DETECTED
1686 */
Gilles Peskinefe119512018-07-08 21:39:34 +02001687psa_status_t psa_cipher_generate_iv(psa_cipher_operation_t *operation,
1688 unsigned char *iv,
1689 size_t iv_size,
1690 size_t *iv_length);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001691
Gilles Peskinedcd14942018-07-12 00:30:52 +02001692/** Set the IV for a symmetric encryption or decryption operation.
1693 *
Gilles Peskinef45adda2019-01-14 18:29:18 +01001694 * This function sets the IV (initialization vector), nonce
Gilles Peskinedcd14942018-07-12 00:30:52 +02001695 * or initial counter value for the encryption or decryption operation.
1696 *
1697 * The application must call psa_cipher_encrypt_setup() before
1698 * calling this function.
1699 *
1700 * If this function returns an error status, the operation becomes inactive.
1701 *
1702 * \note When encrypting, applications should use psa_cipher_generate_iv()
1703 * instead of this function, unless implementing a protocol that requires
1704 * a non-random IV.
1705 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001706 * \param[in,out] operation Active cipher operation.
1707 * \param[in] iv Buffer containing the IV to use.
1708 * \param iv_length Size of the IV in bytes.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001709 *
1710 * \retval #PSA_SUCCESS
1711 * Success.
1712 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001713 * The operation state is not valid (not set up, or IV already set).
Gilles Peskinedcd14942018-07-12 00:30:52 +02001714 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001715 * The size of \p iv is not acceptable for the chosen algorithm,
Gilles Peskinedcd14942018-07-12 00:30:52 +02001716 * or the chosen algorithm does not use an IV.
1717 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1718 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1719 * \retval #PSA_ERROR_HARDWARE_FAILURE
1720 * \retval #PSA_ERROR_TAMPERING_DETECTED
1721 */
Gilles Peskinefe119512018-07-08 21:39:34 +02001722psa_status_t psa_cipher_set_iv(psa_cipher_operation_t *operation,
1723 const unsigned char *iv,
1724 size_t iv_length);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001725
Gilles Peskinedcd14942018-07-12 00:30:52 +02001726/** Encrypt or decrypt a message fragment in an active cipher operation.
1727 *
Gilles Peskine9ac94262018-07-12 20:15:32 +02001728 * Before calling this function, you must:
1729 * 1. Call either psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup().
1730 * The choice of setup function determines whether this function
1731 * encrypts or decrypts its input.
1732 * 2. If the algorithm requires an IV, call psa_cipher_generate_iv()
1733 * (recommended when encrypting) or psa_cipher_set_iv().
Gilles Peskinedcd14942018-07-12 00:30:52 +02001734 *
1735 * If this function returns an error status, the operation becomes inactive.
1736 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001737 * \param[in,out] operation Active cipher operation.
1738 * \param[in] input Buffer containing the message fragment to
1739 * encrypt or decrypt.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001740 * \param input_length Size of the \p input buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001741 * \param[out] output Buffer where the output is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001742 * \param output_size Size of the \p output buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001743 * \param[out] output_length On success, the number of bytes
1744 * that make up the returned output.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001745 *
1746 * \retval #PSA_SUCCESS
1747 * Success.
1748 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001749 * The operation state is not valid (not set up, IV required but
Gilles Peskinedcd14942018-07-12 00:30:52 +02001750 * not set, or already completed).
1751 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
1752 * The size of the \p output buffer is too small.
1753 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1754 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1755 * \retval #PSA_ERROR_HARDWARE_FAILURE
1756 * \retval #PSA_ERROR_TAMPERING_DETECTED
1757 */
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001758psa_status_t psa_cipher_update(psa_cipher_operation_t *operation,
1759 const uint8_t *input,
mohammad1603503973b2018-03-12 15:59:30 +02001760 size_t input_length,
Gilles Peskine2d277862018-06-18 15:41:12 +02001761 unsigned char *output,
1762 size_t output_size,
mohammad1603503973b2018-03-12 15:59:30 +02001763 size_t *output_length);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001764
Gilles Peskinedcd14942018-07-12 00:30:52 +02001765/** Finish encrypting or decrypting a message in a cipher operation.
1766 *
1767 * The application must call psa_cipher_encrypt_setup() or
1768 * psa_cipher_decrypt_setup() before calling this function. The choice
1769 * of setup function determines whether this function encrypts or
1770 * decrypts its input.
1771 *
1772 * This function finishes the encryption or decryption of the message
1773 * formed by concatenating the inputs passed to preceding calls to
1774 * psa_cipher_update().
1775 *
1776 * When this function returns, the operation becomes inactive.
1777 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02001778 * \param[in,out] operation Active cipher operation.
1779 * \param[out] output Buffer where the output is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001780 * \param output_size Size of the \p output buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001781 * \param[out] output_length On success, the number of bytes
1782 * that make up the returned output.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001783 *
1784 * \retval #PSA_SUCCESS
1785 * Success.
1786 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinef45adda2019-01-14 18:29:18 +01001787 * The operation state is not valid (not set up, IV required but
Gilles Peskinedcd14942018-07-12 00:30:52 +02001788 * not set, or already completed).
1789 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
1790 * The size of the \p output buffer is too small.
1791 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1792 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1793 * \retval #PSA_ERROR_HARDWARE_FAILURE
1794 * \retval #PSA_ERROR_TAMPERING_DETECTED
1795 */
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001796psa_status_t psa_cipher_finish(psa_cipher_operation_t *operation,
mohammad1603503973b2018-03-12 15:59:30 +02001797 uint8_t *output,
Moran Peker0071b872018-04-22 20:16:58 +03001798 size_t output_size,
mohammad1603503973b2018-03-12 15:59:30 +02001799 size_t *output_length);
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001800
Gilles Peskinedcd14942018-07-12 00:30:52 +02001801/** Abort a cipher operation.
1802 *
Gilles Peskinedcd14942018-07-12 00:30:52 +02001803 * Aborting an operation frees all associated resources except for the
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001804 * \p operation structure itself. Once aborted, the operation object
1805 * can be reused for another operation by calling
1806 * psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup() again.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001807 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001808 * You may call this function any time after the operation object has
1809 * been initialized by any of the following methods:
1810 * - A call to psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup(),
1811 * whether it succeeds or not.
1812 * - Initializing the \c struct to all-bits-zero.
1813 * - Initializing the \c struct to logical zeros, e.g.
1814 * `psa_cipher_operation_t operation = {0}`.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001815 *
Gilles Peskineb82ab6f2018-07-13 15:33:43 +02001816 * In particular, calling psa_cipher_abort() after the operation has been
1817 * terminated by a call to psa_cipher_abort() or psa_cipher_finish()
1818 * is safe and has no effect.
1819 *
1820 * \param[in,out] operation Initialized cipher operation.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001821 *
1822 * \retval #PSA_SUCCESS
1823 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001824 * \p operation is not an active cipher operation.
Gilles Peskinedcd14942018-07-12 00:30:52 +02001825 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1826 * \retval #PSA_ERROR_HARDWARE_FAILURE
1827 * \retval #PSA_ERROR_TAMPERING_DETECTED
1828 */
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001829psa_status_t psa_cipher_abort(psa_cipher_operation_t *operation);
1830
1831/**@}*/
1832
Gilles Peskine3b555712018-03-03 21:27:57 +01001833/** \defgroup aead Authenticated encryption with associated data (AEAD)
1834 * @{
1835 */
1836
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02001837/** Process an authenticated encryption operation.
Gilles Peskine3b555712018-03-03 21:27:57 +01001838 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01001839 * \param handle Handle to the key to use for the operation.
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02001840 * \param alg The AEAD algorithm to compute
1841 * (\c PSA_ALG_XXX value such that
Gilles Peskine7256e6c2018-07-12 00:34:26 +02001842 * #PSA_ALG_IS_AEAD(\p alg) is true).
Gilles Peskineedd11a12018-07-12 01:08:58 +02001843 * \param[in] nonce Nonce or IV to use.
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02001844 * \param nonce_length Size of the \p nonce buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001845 * \param[in] additional_data Additional data that will be authenticated
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02001846 * but not encrypted.
1847 * \param additional_data_length Size of \p additional_data in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001848 * \param[in] plaintext Data that will be authenticated and
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02001849 * encrypted.
1850 * \param plaintext_length Size of \p plaintext in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001851 * \param[out] ciphertext Output buffer for the authenticated and
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02001852 * encrypted data. The additional data is not
1853 * part of this output. For algorithms where the
1854 * encrypted data and the authentication tag
1855 * are defined as separate outputs, the
1856 * authentication tag is appended to the
1857 * encrypted data.
1858 * \param ciphertext_size Size of the \p ciphertext buffer in bytes.
1859 * This must be at least
1860 * #PSA_AEAD_ENCRYPT_OUTPUT_SIZE(\p alg,
1861 * \p plaintext_length).
Gilles Peskineedd11a12018-07-12 01:08:58 +02001862 * \param[out] ciphertext_length On success, the size of the output
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02001863 * in the \b ciphertext buffer.
Gilles Peskine3b555712018-03-03 21:27:57 +01001864 *
Gilles Peskine28538492018-07-11 17:34:00 +02001865 * \retval #PSA_SUCCESS
Gilles Peskine3b555712018-03-03 21:27:57 +01001866 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001867 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine28538492018-07-11 17:34:00 +02001868 * \retval #PSA_ERROR_EMPTY_SLOT
1869 * \retval #PSA_ERROR_NOT_PERMITTED
1870 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001871 * \p key is not compatible with \p alg.
Gilles Peskine28538492018-07-11 17:34:00 +02001872 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001873 * \p alg is not supported or is not an AEAD algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02001874 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1875 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1876 * \retval #PSA_ERROR_HARDWARE_FAILURE
1877 * \retval #PSA_ERROR_TAMPERING_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03001878 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03001879 * The library has not been previously initialized by psa_crypto_init().
1880 * It is implementation-dependent whether a failure to initialize
1881 * results in this error code.
Gilles Peskine3b555712018-03-03 21:27:57 +01001882 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01001883psa_status_t psa_aead_encrypt(psa_key_handle_t handle,
Gilles Peskine9fb0e012018-07-19 15:51:49 +02001884 psa_algorithm_t alg,
1885 const uint8_t *nonce,
1886 size_t nonce_length,
1887 const uint8_t *additional_data,
1888 size_t additional_data_length,
1889 const uint8_t *plaintext,
1890 size_t plaintext_length,
1891 uint8_t *ciphertext,
1892 size_t ciphertext_size,
1893 size_t *ciphertext_length);
Gilles Peskine3b555712018-03-03 21:27:57 +01001894
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02001895/** Process an authenticated decryption operation.
Gilles Peskine3b555712018-03-03 21:27:57 +01001896 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01001897 * \param handle Handle to the key to use for the operation.
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02001898 * \param alg The AEAD algorithm to compute
1899 * (\c PSA_ALG_XXX value such that
Gilles Peskine7256e6c2018-07-12 00:34:26 +02001900 * #PSA_ALG_IS_AEAD(\p alg) is true).
Gilles Peskineedd11a12018-07-12 01:08:58 +02001901 * \param[in] nonce Nonce or IV to use.
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02001902 * \param nonce_length Size of the \p nonce buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001903 * \param[in] additional_data Additional data that has been authenticated
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02001904 * but not encrypted.
1905 * \param additional_data_length Size of \p additional_data in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001906 * \param[in] ciphertext Data that has been authenticated and
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02001907 * encrypted. For algorithms where the
1908 * encrypted data and the authentication tag
1909 * are defined as separate inputs, the buffer
1910 * must contain the encrypted data followed
1911 * by the authentication tag.
1912 * \param ciphertext_length Size of \p ciphertext in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02001913 * \param[out] plaintext Output buffer for the decrypted data.
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02001914 * \param plaintext_size Size of the \p plaintext buffer in bytes.
1915 * This must be at least
1916 * #PSA_AEAD_DECRYPT_OUTPUT_SIZE(\p alg,
1917 * \p ciphertext_length).
Gilles Peskineedd11a12018-07-12 01:08:58 +02001918 * \param[out] plaintext_length On success, the size of the output
mohammad1603fb5b9cb2018-06-06 13:44:27 +03001919 * in the \b plaintext buffer.
Gilles Peskine3b555712018-03-03 21:27:57 +01001920 *
Gilles Peskine28538492018-07-11 17:34:00 +02001921 * \retval #PSA_SUCCESS
Gilles Peskine3b555712018-03-03 21:27:57 +01001922 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01001923 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine28538492018-07-11 17:34:00 +02001924 * \retval #PSA_ERROR_EMPTY_SLOT
1925 * \retval #PSA_ERROR_INVALID_SIGNATURE
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02001926 * The ciphertext is not authentic.
Gilles Peskine28538492018-07-11 17:34:00 +02001927 * \retval #PSA_ERROR_NOT_PERMITTED
1928 * \retval #PSA_ERROR_INVALID_ARGUMENT
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001929 * \p key is not compatible with \p alg.
Gilles Peskine28538492018-07-11 17:34:00 +02001930 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskinefa4070c2018-07-12 19:23:03 +02001931 * \p alg is not supported or is not an AEAD algorithm.
Gilles Peskine28538492018-07-11 17:34:00 +02001932 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
1933 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
1934 * \retval #PSA_ERROR_HARDWARE_FAILURE
1935 * \retval #PSA_ERROR_TAMPERING_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03001936 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03001937 * The library has not been previously initialized by psa_crypto_init().
1938 * It is implementation-dependent whether a failure to initialize
1939 * results in this error code.
Gilles Peskine3b555712018-03-03 21:27:57 +01001940 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01001941psa_status_t psa_aead_decrypt(psa_key_handle_t handle,
Gilles Peskine9fb0e012018-07-19 15:51:49 +02001942 psa_algorithm_t alg,
1943 const uint8_t *nonce,
1944 size_t nonce_length,
1945 const uint8_t *additional_data,
1946 size_t additional_data_length,
1947 const uint8_t *ciphertext,
1948 size_t ciphertext_length,
1949 uint8_t *plaintext,
1950 size_t plaintext_size,
1951 size_t *plaintext_length);
Gilles Peskine3b555712018-03-03 21:27:57 +01001952
Gilles Peskine30a9e412019-01-14 18:36:12 +01001953/** The type of the state data structure for multipart AEAD operations.
1954 *
1955 * Before calling any function on an AEAD operation object, the application
1956 * must initialize it by any of the following means:
1957 * - Set the structure to all-bits-zero, for example:
1958 * \code
1959 * psa_aead_operation_t operation;
1960 * memset(&operation, 0, sizeof(operation));
1961 * \endcode
1962 * - Initialize the structure to logical zero values, for example:
1963 * \code
1964 * psa_aead_operation_t operation = {0};
1965 * \endcode
1966 * - Initialize the structure to the initializer #PSA_AEAD_OPERATION_INIT,
1967 * for example:
1968 * \code
1969 * psa_aead_operation_t operation = PSA_AEAD_OPERATION_INIT;
1970 * \endcode
1971 * - Assign the result of the function psa_aead_operation_init()
1972 * to the structure, for example:
1973 * \code
1974 * psa_aead_operation_t operation;
1975 * operation = psa_aead_operation_init();
1976 * \endcode
1977 *
1978 * This is an implementation-defined \c struct. Applications should not
1979 * make any assumptions about the content of this structure except
1980 * as directed by the documentation of a specific implementation. */
1981typedef struct psa_aead_operation_s psa_aead_operation_t;
1982
1983/** \def PSA_AEAD_OPERATION_INIT
1984 *
1985 * This macro returns a suitable initializer for an AEAD operation object of
1986 * type #psa_aead_operation_t.
1987 */
1988#ifdef __DOXYGEN_ONLY__
1989/* This is an example definition for documentation purposes.
1990 * Implementations should define a suitable value in `crypto_struct.h`.
1991 */
1992#define PSA_AEAD_OPERATION_INIT {0}
1993#endif
1994
1995/** Return an initial value for an AEAD operation object.
1996 */
1997static psa_aead_operation_t psa_aead_operation_init(void);
1998
1999/** Set the key for a multipart authenticated encryption operation.
2000 *
2001 * The sequence of operations to encrypt a message with authentication
2002 * is as follows:
2003 * -# Allocate an operation object which will be passed to all the functions
2004 * listed here.
2005 * -# Initialize the operation object with one of the methods described in the
2006 * documentation for #psa_aead_operation_t, e.g.
2007 * PSA_AEAD_OPERATION_INIT.
2008 * -# Call psa_aead_encrypt_setup() to specify the algorithm and key.
2009 * -# Call either psa_aead_generate_nonce() or psa_aead_set_nonce() to
2010 * generate or set the nonce. You should use
2011 * psa_aead_generate_nonce() unless the protocol you are implementing
2012 * requires a specific nonce value.
2013 * -# Call psa_aead_update_ad() zero, one or more times, passing a fragment
2014 * of the non-encrypted additional authenticated data each time.
2015 * -# Call psa_aead_update() zero, one or more times, passing a fragment
2016 * of the message each time.
2017 * -# Call psa_aead_finish().
2018 *
2019 * The application may call psa_aead_abort() at any time after the operation
2020 * has been initialized.
2021 *
2022 * After a successful call to psa_aead_encrypt_setup(), the application must
2023 * eventually terminate the operation. The following events terminate an
2024 * operation:
2025 * - A failed call to any of the \c psa_aead_xxx functions.
2026 * - A call to psa_aead_finish(), psa_aead_verify() or psa_aead_abort().
2027 *
2028 * \param[in,out] operation The operation object to set up. It must have
2029 * been initialized as per the documentation for
2030 * #psa_aead_operation_t and not yet in use.
2031 * \param handle Handle to the key to use for the operation.
2032 * It must remain valid until the operation
2033 * terminates.
2034 * \param alg The AEAD algorithm to compute
2035 * (\c PSA_ALG_XXX value such that
2036 * #PSA_ALG_IS_AEAD(\p alg) is true).
2037 *
2038 * \retval #PSA_SUCCESS
2039 * Success.
2040 * \retval #PSA_ERROR_INVALID_HANDLE
2041 * \retval #PSA_ERROR_EMPTY_SLOT
2042 * \retval #PSA_ERROR_NOT_PERMITTED
2043 * \retval #PSA_ERROR_INVALID_ARGUMENT
2044 * \p key is not compatible with \p alg.
2045 * \retval #PSA_ERROR_NOT_SUPPORTED
2046 * \p alg is not supported or is not an AEAD algorithm.
2047 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2048 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2049 * \retval #PSA_ERROR_HARDWARE_FAILURE
2050 * \retval #PSA_ERROR_TAMPERING_DETECTED
2051 * \retval #PSA_ERROR_BAD_STATE
2052 * 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.
2055 */
2056psa_status_t psa_aead_encrypt_setup(psa_aead_operation_t *operation,
2057 psa_key_handle_t handle,
2058 psa_algorithm_t alg);
2059
2060/** Set the key for a multipart authenticated decryption operation.
2061 *
2062 * The sequence of operations to decrypt a message with authentication
2063 * is as follows:
2064 * -# Allocate an operation object which will be passed to all the functions
2065 * listed here.
2066 * -# Initialize the operation object with one of the methods described in the
2067 * documentation for #psa_aead_operation_t, e.g.
2068 * PSA_AEAD_OPERATION_INIT.
2069 * -# Call psa_aead_decrypt_setup() to specify the algorithm and key.
2070 * -# Call psa_aead_set_nonce() with the nonce for the decryption.
2071 * -# Call psa_aead_update_ad() zero, one or more times, passing a fragment
2072 * of the non-encrypted additional authenticated data each time.
2073 * -# Call psa_aead_update() zero, one or more times, passing a fragment
2074 * of the message each time.
2075 * -# Call psa_aead_finish().
2076 *
2077 * The application may call psa_aead_abort() at any time after the operation
2078 * has been initialized.
2079 *
2080 * After a successful call to psa_aead_decrypt_setup(), the application must
2081 * eventually terminate the operation. The following events terminate an
2082 * operation:
2083 * - A failed call to any of the \c psa_aead_xxx functions.
2084 * - A call to psa_aead_finish(), psa_aead_verify() or psa_aead_abort().
2085 *
2086 * \param[in,out] operation The operation object to set up. It must have
2087 * been initialized as per the documentation for
2088 * #psa_aead_operation_t and not yet in use.
2089 * \param handle Handle to the key to use for the operation.
2090 * It must remain valid until the operation
2091 * terminates.
2092 * \param alg The AEAD algorithm to compute
2093 * (\c PSA_ALG_XXX value such that
2094 * #PSA_ALG_IS_AEAD(\p alg) is true).
2095 *
2096 * \retval #PSA_SUCCESS
2097 * Success.
2098 * \retval #PSA_ERROR_INVALID_HANDLE
2099 * \retval #PSA_ERROR_EMPTY_SLOT
2100 * \retval #PSA_ERROR_NOT_PERMITTED
2101 * \retval #PSA_ERROR_INVALID_ARGUMENT
2102 * \p key is not compatible with \p alg.
2103 * \retval #PSA_ERROR_NOT_SUPPORTED
2104 * \p alg is not supported or is not an AEAD algorithm.
2105 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2106 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2107 * \retval #PSA_ERROR_HARDWARE_FAILURE
2108 * \retval #PSA_ERROR_TAMPERING_DETECTED
2109 * \retval #PSA_ERROR_BAD_STATE
2110 * The library has not been previously initialized by psa_crypto_init().
2111 * It is implementation-dependent whether a failure to initialize
2112 * results in this error code.
2113 */
2114psa_status_t psa_aead_decrypt_setup(psa_aead_operation_t *operation,
2115 psa_key_handle_t handle,
2116 psa_algorithm_t alg);
2117
2118/** Generate a random nonce for an authenticated encryption operation.
2119 *
2120 * This function generates a random nonce for the authenticated encryption
2121 * operation with an appropriate size for the chosen algorithm, key type
2122 * and key size.
2123 *
2124 * The application must call psa_aead_encrypt_setup() before
2125 * calling this function.
2126 *
2127 * If this function returns an error status, the operation becomes inactive.
2128 *
2129 * \param[in,out] operation Active AEAD operation.
2130 * \param[out] nonce Buffer where the generated nonce is to be
2131 * written.
2132 * \param nonce_size Size of the \p nonce buffer in bytes.
2133 * \param[out] nonce_length On success, the number of bytes of the
2134 * generated nonce.
2135 *
2136 * \retval #PSA_SUCCESS
2137 * Success.
2138 * \retval #PSA_ERROR_BAD_STATE
2139 * The operation state is not valid (not set up, or nonce already set).
2140 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
2141 * The size of the \p nonce buffer is too small.
2142 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2143 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2144 * \retval #PSA_ERROR_HARDWARE_FAILURE
2145 * \retval #PSA_ERROR_TAMPERING_DETECTED
2146 */
2147psa_status_t psa_aead_generate_nonce(psa_aead_operation_t *operation,
2148 unsigned char *nonce,
2149 size_t nonce_size,
2150 size_t *nonce_length);
2151
2152/** Set the nonce for an authenticated encryption or decryption operation.
2153 *
2154 * This function sets the nonce for the authenticated
2155 * encryption or decryption operation.
2156 *
2157 * The application must call psa_aead_encrypt_setup() before
2158 * calling this function.
2159 *
2160 * If this function returns an error status, the operation becomes inactive.
2161 *
2162 * \note When encrypting, applications should use psa_aead_generate_iv()
2163 * instead of this function, unless implementing a protocol that requires
2164 * a non-random IV.
2165 *
2166 * \param[in,out] operation Active AEAD operation.
2167 * \param[in] iv Buffer containing the nonce to use.
2168 * \param iv_length Size of the nonce in bytes.
2169 *
2170 * \retval #PSA_SUCCESS
2171 * Success.
2172 * \retval #PSA_ERROR_BAD_STATE
2173 * The operation state is not valid (not set up, or nonce already set).
2174 * \retval #PSA_ERROR_INVALID_ARGUMENT
2175 * The size of \p nonce is not acceptable for the chosen algorithm.
2176 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2177 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2178 * \retval #PSA_ERROR_HARDWARE_FAILURE
2179 * \retval #PSA_ERROR_TAMPERING_DETECTED
2180 */
2181psa_status_t psa_aead_set_nonce(psa_aead_operation_t *operation,
2182 const unsigned char *nonce,
2183 size_t nonce_length);
2184
2185/** Pass additional data to an active AEAD operation.
2186 *
2187 * Additional data is authenticated, but not encrypted.
2188 *
2189 * You may call this function multiple times to pass successive fragments
2190 * of the additional data. You may not call this function after passing
2191 * data to encrypt or decrypt with psa_aead_update().
2192 *
2193 * Before calling this function, you must:
2194 * 1. Call either psa_aead_encrypt_setup() or psa_aead_decrypt_setup().
2195 * 2. Set the nonce with psa_aead_generate_nonce() or psa_aead_set_nonce().
2196 *
2197 * If this function returns an error status, the operation becomes inactive.
2198 *
2199 * \warning When decrypting, until psa_aead_verify() has returned #PSA_SUCCESS,
2200 * there is no guarantee that the input is valid. Therefore, until
2201 * you have called psa_aead_verify() and it has returned #PSA_SUCCESS,
2202 * treat the input as untrusted and prepare to undo any action that
2203 * depends on the input if psa_aead_verify() returns an error status.
2204 *
2205 * \param[in,out] operation Active AEAD operation.
2206 * \param[in] input Buffer containing the fragment of
2207 * additional data.
2208 * \param input_length Size of the \p input buffer in bytes.
2209 *
2210 * \retval #PSA_SUCCESS
2211 * Success.
2212 * \retval #PSA_ERROR_BAD_STATE
2213 * The operation state is not valid (not set up, nonce not set,
2214 * psa_aead_update() already called, or operation already completed).
2215 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2216 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2217 * \retval #PSA_ERROR_HARDWARE_FAILURE
2218 * \retval #PSA_ERROR_TAMPERING_DETECTED
2219 */
2220psa_status_t psa_aead_update_ad(psa_aead_operation_t *operation,
2221 const uint8_t *input,
2222 size_t input_length);
2223
2224/** Encrypt or decrypt a message fragment in an active AEAD operation.
2225 *
2226 * Before calling this function, you must:
2227 * 1. Call either psa_aead_encrypt_setup() or psa_aead_decrypt_setup().
2228 * The choice of setup function determines whether this function
2229 * encrypts or decrypts its input.
2230 * 2. Set the nonce with psa_aead_generate_nonce() or psa_aead_set_nonce().
2231 * 3. Call psa_aead_update_ad() to pass all the additional data.
2232 *
2233 * If this function returns an error status, the operation becomes inactive.
2234 *
2235 * \warning When decrypting, until psa_aead_verify() has returned #PSA_SUCCESS,
2236 * there is no guarantee that the input is valid. Therefore, until
2237 * you have called psa_aead_verify() and it has returned #PSA_SUCCESS:
2238 * - Do not use the output in any way other than storing it in a
2239 * confidential location. If you take any action that depends
2240 * on the tentative decrypted data, this action will need to be
2241 * undone if the input turns out not to be valid. Furthermore,
2242 * if an adversary can observe that this action took place
2243 * (for example through timing), they may be able to use this
2244 * fact as an oracle to decrypt any message encrypted with the
2245 * same key.
2246 * - In particular, do not copy the output anywhere but to a
2247 * memory or storage space that you have exclusive access to.
2248 *
2249 * \param[in,out] operation Active AEAD operation.
2250 * \param[in] input Buffer containing the message fragment to
2251 * encrypt or decrypt.
2252 * \param input_length Size of the \p input buffer in bytes.
2253 * \param[out] output Buffer where the output is to be written.
2254 * \param output_size Size of the \p output buffer in bytes.
2255 * \param[out] output_length On success, the number of bytes
2256 * that make up the returned output.
2257 *
2258 * \retval #PSA_SUCCESS
2259 * Success.
2260 * \retval #PSA_ERROR_BAD_STATE
2261 * The operation state is not valid (not set up, nonce not set
2262 * or already completed).
2263 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
2264 * The size of the \p output 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_update(psa_aead_operation_t *operation,
2271 const uint8_t *input,
2272 size_t input_length,
2273 unsigned char *output,
2274 size_t output_size,
2275 size_t *output_length);
2276
2277/** Finish encrypting a message in an AEAD operation.
2278 *
2279 * The operation must have been set up with psa_aead_encrypt_setup().
2280 *
2281 * This function finishes the authentication of the additional data
2282 * formed by concatenating the inputs passed to preceding calls to
2283 * psa_aead_update_ad() with the plaintext formed by concatenating the
2284 * inputs passed to preceding calls to psa_aead_update().
2285 *
2286 * This function has two output buffers:
2287 * - \p ciphertext contains trailing ciphertext that was buffered from
2288 * preceding calls to psa_aead_update(). For all standard AEAD algorithms,
2289 * psa_aead_update() does not buffer any output and therefore \p ciphertext
2290 * will not contain any output and can be a 0-sized buffer.
2291 * - \p tag contains the authentication tag. Its length is always
2292 * #PSA_AEAD_TAG_LENGTH(\p alg) where \p alg is the AEAD algorithm
2293 * that the operation performs.
2294 *
2295 * When this function returns, the operation becomes inactive.
2296 *
2297 * \param[in,out] operation Active AEAD operation.
2298 * \param[out] ciphertext Buffer where the last part of the ciphertext
2299 * is to be written.
2300 * \param ciphertext_size Size of the \p ciphertext buffer in bytes.
2301 * \param[out] ciphertext_length On success, the number of bytes of
2302 * returned ciphertext.
2303 * \param[out] tag Buffer where the authentication tag is
2304 * to be written.
2305 * \param tag_size Size of the \p tag buffer in bytes.
2306 * \param[out] tag_length On success, the number of bytes
2307 * that make up the returned tag.
2308 *
2309 * \retval #PSA_SUCCESS
2310 * Success.
2311 * \retval #PSA_ERROR_BAD_STATE
2312 * The operation state is not valid (not set up, nonce not set,
2313 * decryption, or already completed).
2314 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
2315 * The size of the \p output buffer is too small.
2316 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2317 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2318 * \retval #PSA_ERROR_HARDWARE_FAILURE
2319 * \retval #PSA_ERROR_TAMPERING_DETECTED
2320 */
2321psa_status_t psa_aead_finish(psa_aead_operation_t *operation,
2322 uint8_t *output,
2323 size_t output_size,
2324 size_t *output_length,
2325 uint8_t *tag,
2326 size_t tag_size,
2327 size_t *tag_length);
2328
2329/** Finish authenticating and decrypting a message in an AEAD operation.
2330 *
2331 * The operation must have been set up with psa_aead_decrypt_setup().
2332 *
2333 * This function finishes the authentication of the additional data
2334 * formed by concatenating the inputs passed to preceding calls to
2335 * psa_aead_update_ad() with the ciphertext formed by concatenating the
2336 * inputs passed to preceding calls to psa_aead_update().
2337 *
2338 * When this function returns, the operation becomes inactive.
2339 *
2340 * \param[in,out] operation Active AEAD operation.
2341 * \param[in] tag Buffer containing the authentication tag.
2342 * \param tag_length Size of the \p tag buffer in bytes.
2343 *
2344 * \retval #PSA_SUCCESS
2345 * Success.
2346 * \retval #PSA_ERROR_BAD_STATE
2347 * The operation state is not valid (not set up, nonce not set,
2348 * encryption, or already completed).
2349 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
2350 * The size of the \p output buffer is too small.
2351 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2352 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2353 * \retval #PSA_ERROR_HARDWARE_FAILURE
2354 * \retval #PSA_ERROR_TAMPERING_DETECTED
2355 */
2356psa_status_t psa_aead_verify(psa_aead_operation_t *operation,
2357 const uint8_t *tag,
2358 size_t tag_length);
2359
2360/** Abort an AEAD operation.
2361 *
2362 * Aborting an operation frees all associated resources except for the
2363 * \p operation structure itself. Once aborted, the operation object
2364 * can be reused for another operation by calling
2365 * psa_aead_encrypt_setup() or psa_aead_decrypt_setup() again.
2366 *
2367 * You may call this function any time after the operation object has
2368 * been initialized by any of the following methods:
2369 * - A call to psa_aead_encrypt_setup() or psa_aead_decrypt_setup(),
2370 * whether it succeeds or not.
2371 * - Initializing the \c struct to all-bits-zero.
2372 * - Initializing the \c struct to logical zeros, e.g.
2373 * `psa_aead_operation_t operation = {0}`.
2374 *
2375 * In particular, calling psa_aead_abort() after the operation has been
2376 * terminated by a call to psa_aead_abort() or psa_aead_finish()
2377 * is safe and has no effect.
2378 *
2379 * \param[in,out] operation Initialized AEAD operation.
2380 *
2381 * \retval #PSA_SUCCESS
2382 * \retval #PSA_ERROR_BAD_STATE
2383 * \p operation is not an active AEAD operation.
2384 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2385 * \retval #PSA_ERROR_HARDWARE_FAILURE
2386 * \retval #PSA_ERROR_TAMPERING_DETECTED
2387 */
2388psa_status_t psa_aead_abort(psa_aead_operation_t *operation);
2389
Gilles Peskine3b555712018-03-03 21:27:57 +01002390/**@}*/
2391
Gilles Peskine20035e32018-02-03 22:44:14 +01002392/** \defgroup asymmetric Asymmetric cryptography
2393 * @{
2394 */
2395
2396/**
2397 * \brief Sign a hash or short message with a private key.
2398 *
Gilles Peskine08bac712018-06-26 16:14:46 +02002399 * Note that to perform a hash-and-sign signature algorithm, you must
Gilles Peskineda8191d1c2018-07-08 19:46:38 +02002400 * first calculate the hash by calling psa_hash_setup(), psa_hash_update()
Gilles Peskine08bac712018-06-26 16:14:46 +02002401 * and psa_hash_finish(). Then pass the resulting hash as the \p hash
2402 * parameter to this function. You can use #PSA_ALG_SIGN_GET_HASH(\p alg)
2403 * to determine the hash algorithm to use.
2404 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01002405 * \param handle Handle to the key to use for the operation.
2406 * It must be an asymmetric key pair.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002407 * \param alg A signature algorithm that is compatible with
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002408 * the type of \p key.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002409 * \param[in] hash The hash or message to sign.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002410 * \param hash_length Size of the \p hash buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002411 * \param[out] signature Buffer where the signature is to be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002412 * \param signature_size Size of the \p signature buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002413 * \param[out] signature_length On success, the number of bytes
2414 * that make up the returned signature value.
Gilles Peskine308b91d2018-02-08 09:47:44 +01002415 *
Gilles Peskine28538492018-07-11 17:34:00 +02002416 * \retval #PSA_SUCCESS
2417 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002418 * The size of the \p signature buffer is too small. You can
Gilles Peskine308b91d2018-02-08 09:47:44 +01002419 * determine a sufficient buffer size by calling
Gilles Peskine7256e6c2018-07-12 00:34:26 +02002420 * #PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
Gilles Peskine308b91d2018-02-08 09:47:44 +01002421 * where \c key_type and \c key_bits are the type and bit-size
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002422 * respectively of \p key.
Gilles Peskine28538492018-07-11 17:34:00 +02002423 * \retval #PSA_ERROR_NOT_SUPPORTED
2424 * \retval #PSA_ERROR_INVALID_ARGUMENT
2425 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2426 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2427 * \retval #PSA_ERROR_HARDWARE_FAILURE
2428 * \retval #PSA_ERROR_TAMPERING_DETECTED
2429 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
itayzafrir90d8c7a2018-09-12 11:44:52 +03002430 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03002431 * The library has not been previously initialized by psa_crypto_init().
2432 * It is implementation-dependent whether a failure to initialize
2433 * results in this error code.
Gilles Peskine20035e32018-02-03 22:44:14 +01002434 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01002435psa_status_t psa_asymmetric_sign(psa_key_handle_t handle,
Gilles Peskine20035e32018-02-03 22:44:14 +01002436 psa_algorithm_t alg,
2437 const uint8_t *hash,
2438 size_t hash_length,
Gilles Peskine20035e32018-02-03 22:44:14 +01002439 uint8_t *signature,
2440 size_t signature_size,
2441 size_t *signature_length);
2442
2443/**
2444 * \brief Verify the signature a hash or short message using a public key.
2445 *
Gilles Peskine08bac712018-06-26 16:14:46 +02002446 * Note that to perform a hash-and-sign signature algorithm, you must
Gilles Peskineda8191d1c2018-07-08 19:46:38 +02002447 * first calculate the hash by calling psa_hash_setup(), psa_hash_update()
Gilles Peskine08bac712018-06-26 16:14:46 +02002448 * and psa_hash_finish(). Then pass the resulting hash as the \p hash
2449 * parameter to this function. You can use #PSA_ALG_SIGN_GET_HASH(\p alg)
2450 * to determine the hash algorithm to use.
2451 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01002452 * \param handle Handle to the key to use for the operation.
2453 * It must be a public key or an asymmetric key pair.
Gilles Peskine308b91d2018-02-08 09:47:44 +01002454 * \param alg A signature algorithm that is compatible with
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002455 * the type of \p key.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002456 * \param[in] hash The hash or message whose signature is to be
Gilles Peskine08bac712018-06-26 16:14:46 +02002457 * verified.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002458 * \param hash_length Size of the \p hash buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002459 * \param[in] signature Buffer containing the signature to verify.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002460 * \param signature_length Size of the \p signature buffer in bytes.
Gilles Peskine308b91d2018-02-08 09:47:44 +01002461 *
Gilles Peskine28538492018-07-11 17:34:00 +02002462 * \retval #PSA_SUCCESS
Gilles Peskine308b91d2018-02-08 09:47:44 +01002463 * The signature is valid.
Gilles Peskine28538492018-07-11 17:34:00 +02002464 * \retval #PSA_ERROR_INVALID_SIGNATURE
Gilles Peskine308b91d2018-02-08 09:47:44 +01002465 * The calculation was perfomed successfully, but the passed
2466 * signature is not a valid signature.
Gilles Peskine28538492018-07-11 17:34:00 +02002467 * \retval #PSA_ERROR_NOT_SUPPORTED
2468 * \retval #PSA_ERROR_INVALID_ARGUMENT
2469 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2470 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2471 * \retval #PSA_ERROR_HARDWARE_FAILURE
2472 * \retval #PSA_ERROR_TAMPERING_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03002473 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03002474 * The library has not been previously initialized by psa_crypto_init().
2475 * It is implementation-dependent whether a failure to initialize
2476 * results in this error code.
Gilles Peskine20035e32018-02-03 22:44:14 +01002477 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01002478psa_status_t psa_asymmetric_verify(psa_key_handle_t handle,
Gilles Peskine20035e32018-02-03 22:44:14 +01002479 psa_algorithm_t alg,
2480 const uint8_t *hash,
2481 size_t hash_length,
Gilles Peskinee9191ff2018-06-27 14:58:41 +02002482 const uint8_t *signature,
Gilles Peskine526fab02018-06-27 18:19:40 +02002483 size_t signature_length);
Gilles Peskine20035e32018-02-03 22:44:14 +01002484
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002485/**
2486 * \brief Encrypt a short message with a public key.
2487 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01002488 * \param handle Handle to the key to use for the operation.
2489 * It must be a public key or an asymmetric
2490 * key pair.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002491 * \param alg An asymmetric encryption algorithm that is
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002492 * compatible with the type of \p key.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002493 * \param[in] input The message to encrypt.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002494 * \param input_length Size of the \p input buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002495 * \param[in] salt A salt or label, if supported by the
2496 * encryption algorithm.
2497 * If the algorithm does not support a
2498 * salt, pass \c NULL.
2499 * If the algorithm supports an optional
2500 * salt and you do not want to pass a salt,
2501 * pass \c NULL.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002502 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02002503 * - For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is
2504 * supported.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002505 * \param salt_length Size of the \p salt buffer in bytes.
2506 * If \p salt is \c NULL, pass 0.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002507 * \param[out] output Buffer where the encrypted message is to
2508 * be written.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002509 * \param output_size Size of the \p output buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002510 * \param[out] output_length On success, the number of bytes
2511 * that make up the returned output.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002512 *
Gilles Peskine28538492018-07-11 17:34:00 +02002513 * \retval #PSA_SUCCESS
2514 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002515 * The size of the \p output buffer is too small. You can
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002516 * determine a sufficient buffer size by calling
Gilles Peskine7256e6c2018-07-12 00:34:26 +02002517 * #PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002518 * where \c key_type and \c key_bits are the type and bit-size
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002519 * respectively of \p key.
Gilles Peskine28538492018-07-11 17:34:00 +02002520 * \retval #PSA_ERROR_NOT_SUPPORTED
2521 * \retval #PSA_ERROR_INVALID_ARGUMENT
2522 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2523 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2524 * \retval #PSA_ERROR_HARDWARE_FAILURE
2525 * \retval #PSA_ERROR_TAMPERING_DETECTED
2526 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
itayzafrir90d8c7a2018-09-12 11:44:52 +03002527 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03002528 * The library has not been previously initialized by psa_crypto_init().
2529 * It is implementation-dependent whether a failure to initialize
2530 * results in this error code.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002531 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01002532psa_status_t psa_asymmetric_encrypt(psa_key_handle_t handle,
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002533 psa_algorithm_t alg,
2534 const uint8_t *input,
2535 size_t input_length,
2536 const uint8_t *salt,
2537 size_t salt_length,
2538 uint8_t *output,
2539 size_t output_size,
2540 size_t *output_length);
2541
2542/**
2543 * \brief Decrypt a short message with a private key.
2544 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01002545 * \param handle Handle to the key to use for the operation.
2546 * It must be an asymmetric key pair.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002547 * \param alg An asymmetric encryption algorithm that is
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002548 * compatible with the type of \p key.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002549 * \param[in] input The message to decrypt.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002550 * \param input_length Size of the \p input buffer in bytes.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002551 * \param[in] salt A salt or label, if supported by the
2552 * encryption algorithm.
2553 * If the algorithm does not support a
2554 * salt, pass \c NULL.
2555 * If the algorithm supports an optional
2556 * salt and you do not want to pass a salt,
2557 * pass \c NULL.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002558 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02002559 * - For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is
2560 * supported.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002561 * \param salt_length Size of the \p salt buffer in bytes.
2562 * If \p salt is \c NULL, pass 0.
Gilles Peskineedd11a12018-07-12 01:08:58 +02002563 * \param[out] output Buffer where the decrypted message is to
2564 * be written.
2565 * \param output_size Size of the \c output buffer in bytes.
2566 * \param[out] output_length On success, the number of bytes
2567 * that make up the returned output.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002568 *
Gilles Peskine28538492018-07-11 17:34:00 +02002569 * \retval #PSA_SUCCESS
2570 * \retval #PSA_ERROR_BUFFER_TOO_SMALL
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002571 * The size of the \p output buffer is too small. You can
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002572 * determine a sufficient buffer size by calling
Gilles Peskinedda3bd32018-07-12 19:40:46 +02002573 * #PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002574 * where \c key_type and \c key_bits are the type and bit-size
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002575 * respectively of \p key.
Gilles Peskine28538492018-07-11 17:34:00 +02002576 * \retval #PSA_ERROR_NOT_SUPPORTED
2577 * \retval #PSA_ERROR_INVALID_ARGUMENT
2578 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2579 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2580 * \retval #PSA_ERROR_HARDWARE_FAILURE
2581 * \retval #PSA_ERROR_TAMPERING_DETECTED
2582 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
2583 * \retval #PSA_ERROR_INVALID_PADDING
itayzafrir90d8c7a2018-09-12 11:44:52 +03002584 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03002585 * The library has not been previously initialized by psa_crypto_init().
2586 * It is implementation-dependent whether a failure to initialize
2587 * results in this error code.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002588 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01002589psa_status_t psa_asymmetric_decrypt(psa_key_handle_t handle,
Gilles Peskine6944f9a2018-03-28 14:18:39 +02002590 psa_algorithm_t alg,
2591 const uint8_t *input,
2592 size_t input_length,
2593 const uint8_t *salt,
2594 size_t salt_length,
2595 uint8_t *output,
2596 size_t output_size,
2597 size_t *output_length);
2598
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +01002599/**@}*/
2600
Gilles Peskineedd76872018-07-20 17:42:05 +02002601/** \defgroup generators Generators
Gilles Peskineeab56e42018-07-12 17:12:33 +02002602 * @{
2603 */
2604
2605/** The type of the state data structure for generators.
2606 *
2607 * Before calling any function on a generator, the application must
2608 * initialize it by any of the following means:
2609 * - Set the structure to all-bits-zero, for example:
2610 * \code
2611 * psa_crypto_generator_t generator;
2612 * memset(&generator, 0, sizeof(generator));
2613 * \endcode
2614 * - Initialize the structure to logical zero values, for example:
2615 * \code
2616 * psa_crypto_generator_t generator = {0};
2617 * \endcode
2618 * - Initialize the structure to the initializer #PSA_CRYPTO_GENERATOR_INIT,
2619 * for example:
2620 * \code
2621 * psa_crypto_generator_t generator = PSA_CRYPTO_GENERATOR_INIT;
2622 * \endcode
2623 * - Assign the result of the function psa_crypto_generator_init()
2624 * to the structure, for example:
2625 * \code
2626 * psa_crypto_generator_t generator;
2627 * generator = psa_crypto_generator_init();
2628 * \endcode
2629 *
2630 * This is an implementation-defined \c struct. Applications should not
2631 * make any assumptions about the content of this structure except
2632 * as directed by the documentation of a specific implementation.
2633 */
2634typedef struct psa_crypto_generator_s psa_crypto_generator_t;
2635
2636/** \def PSA_CRYPTO_GENERATOR_INIT
2637 *
2638 * This macro returns a suitable initializer for a generator object
2639 * of type #psa_crypto_generator_t.
2640 */
2641#ifdef __DOXYGEN_ONLY__
2642/* This is an example definition for documentation purposes.
2643 * Implementations should define a suitable value in `crypto_struct.h`.
2644 */
2645#define PSA_CRYPTO_GENERATOR_INIT {0}
2646#endif
2647
2648/** Return an initial value for a generator object.
2649 */
2650static psa_crypto_generator_t psa_crypto_generator_init(void);
2651
2652/** Retrieve the current capacity of a generator.
2653 *
2654 * The capacity of a generator is the maximum number of bytes that it can
2655 * return. Reading *N* bytes from a generator reduces its capacity by *N*.
2656 *
2657 * \param[in] generator The generator to query.
2658 * \param[out] capacity On success, the capacity of the generator.
2659 *
Gilles Peskine644cd5f2018-12-11 16:47:35 +01002660 * \retval #PSA_SUCCESS
2661 * \retval #PSA_ERROR_BAD_STATE
2662 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
Gilles Peskineeab56e42018-07-12 17:12:33 +02002663 */
2664psa_status_t psa_get_generator_capacity(const psa_crypto_generator_t *generator,
2665 size_t *capacity);
2666
2667/** Read some data from a generator.
2668 *
2669 * This function reads and returns a sequence of bytes from a generator.
2670 * The data that is read is discarded from the generator. The generator's
2671 * capacity is decreased by the number of bytes read.
2672 *
2673 * \param[in,out] generator The generator object to read from.
2674 * \param[out] output Buffer where the generator output will be
2675 * written.
2676 * \param output_length Number of bytes to output.
2677 *
Gilles Peskine644cd5f2018-12-11 16:47:35 +01002678 * \retval #PSA_SUCCESS
2679 * \retval #PSA_ERROR_INSUFFICIENT_CAPACITY
Gilles Peskineeab56e42018-07-12 17:12:33 +02002680 * There were fewer than \p output_length bytes
2681 * in the generator. Note that in this case, no
2682 * output is written to the output buffer.
2683 * The generator's capacity is set to 0, thus
2684 * subsequent calls to this function will not
2685 * succeed, even with a smaller output buffer.
Gilles Peskine644cd5f2018-12-11 16:47:35 +01002686 * \retval #PSA_ERROR_BAD_STATE
2687 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2688 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2689 * \retval #PSA_ERROR_HARDWARE_FAILURE
2690 * \retval #PSA_ERROR_TAMPERING_DETECTED
Gilles Peskineeab56e42018-07-12 17:12:33 +02002691 */
2692psa_status_t psa_generator_read(psa_crypto_generator_t *generator,
2693 uint8_t *output,
2694 size_t output_length);
2695
2696/** Create a symmetric key from data read from a generator.
2697 *
2698 * This function reads a sequence of bytes from a generator and imports
2699 * these bytes as a key.
2700 * The data that is read is discarded from the generator. The generator's
2701 * capacity is decreased by the number of bytes read.
2702 *
2703 * This function is equivalent to calling #psa_generator_read and
2704 * passing the resulting output to #psa_import_key, but
2705 * if the implementation provides an isolation boundary then
2706 * the key material is not exposed outside the isolation boundary.
2707 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01002708 * \param handle Handle to the slot where the key will be stored.
2709 * This must be a valid slot for a key of the chosen
2710 * type: it must have been obtained by calling
2711 * psa_allocate_key() or psa_create_key() with the
2712 * correct \p type and with a maximum size that is
2713 * compatible with \p bits.
2714 * It must not contain any key material yet.
Gilles Peskineeab56e42018-07-12 17:12:33 +02002715 * \param type Key type (a \c PSA_KEY_TYPE_XXX value).
2716 * This must be a symmetric key type.
2717 * \param bits Key size in bits.
2718 * \param[in,out] generator The generator object to read from.
2719 *
Gilles Peskine644cd5f2018-12-11 16:47:35 +01002720 * \retval #PSA_SUCCESS
Gilles Peskineeab56e42018-07-12 17:12:33 +02002721 * Success.
Gilles Peskine23fd2bd2018-12-11 15:51:32 +01002722 * If the key is persistent, the key material and the key's metadata
2723 * have been saved to persistent storage.
Gilles Peskine644cd5f2018-12-11 16:47:35 +01002724 * \retval #PSA_ERROR_INSUFFICIENT_CAPACITY
Gilles Peskineeab56e42018-07-12 17:12:33 +02002725 * There were fewer than \p output_length bytes
2726 * in the generator. Note that in this case, no
2727 * output is written to the output buffer.
2728 * The generator's capacity is set to 0, thus
2729 * subsequent calls to this function will not
2730 * succeed, even with a smaller output buffer.
Gilles Peskine644cd5f2018-12-11 16:47:35 +01002731 * \retval #PSA_ERROR_NOT_SUPPORTED
Gilles Peskineeab56e42018-07-12 17:12:33 +02002732 * The key type or key size is not supported, either by the
2733 * implementation in general or in this particular slot.
Gilles Peskine644cd5f2018-12-11 16:47:35 +01002734 * \retval #PSA_ERROR_BAD_STATE
Gilles Peskineae32aac2018-11-30 14:39:32 +01002735 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine644cd5f2018-12-11 16:47:35 +01002736 * \retval #PSA_ERROR_OCCUPIED_SLOT
Gilles Peskineeab56e42018-07-12 17:12:33 +02002737 * There is already a key in the specified slot.
Gilles Peskine644cd5f2018-12-11 16:47:35 +01002738 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2739 * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
2740 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2741 * \retval #PSA_ERROR_HARDWARE_FAILURE
2742 * \retval #PSA_ERROR_TAMPERING_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03002743 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03002744 * The library has not been previously initialized by psa_crypto_init().
2745 * It is implementation-dependent whether a failure to initialize
2746 * results in this error code.
Gilles Peskineeab56e42018-07-12 17:12:33 +02002747 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01002748psa_status_t psa_generator_import_key(psa_key_handle_t handle,
Gilles Peskineeab56e42018-07-12 17:12:33 +02002749 psa_key_type_t type,
2750 size_t bits,
2751 psa_crypto_generator_t *generator);
2752
2753/** Abort a generator.
2754 *
2755 * Once a generator has been aborted, its capacity is zero.
2756 * Aborting a generator frees all associated resources except for the
2757 * \c generator structure itself.
2758 *
2759 * This function may be called at any time as long as the generator
2760 * object has been initialized to #PSA_CRYPTO_GENERATOR_INIT, to
2761 * psa_crypto_generator_init() or a zero value. In particular, it is valid
2762 * to call psa_generator_abort() twice, or to call psa_generator_abort()
2763 * on a generator that has not been set up.
2764 *
2765 * Once aborted, the generator object may be called.
2766 *
2767 * \param[in,out] generator The generator to abort.
2768 *
Gilles Peskine644cd5f2018-12-11 16:47:35 +01002769 * \retval #PSA_SUCCESS
2770 * \retval #PSA_ERROR_BAD_STATE
2771 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2772 * \retval #PSA_ERROR_HARDWARE_FAILURE
2773 * \retval #PSA_ERROR_TAMPERING_DETECTED
Gilles Peskineeab56e42018-07-12 17:12:33 +02002774 */
2775psa_status_t psa_generator_abort(psa_crypto_generator_t *generator);
2776
Gilles Peskine8feb3a82018-09-18 12:06:11 +02002777/** Use the maximum possible capacity for a generator.
2778 *
2779 * Use this value as the capacity argument when setting up a generator
2780 * to indicate that the generator should have the maximum possible capacity.
2781 * The value of the maximum possible capacity depends on the generator
2782 * algorithm.
2783 */
2784#define PSA_GENERATOR_UNBRIDLED_CAPACITY ((size_t)(-1))
2785
Gilles Peskineeab56e42018-07-12 17:12:33 +02002786/**@}*/
2787
Gilles Peskineea0fb492018-07-12 17:17:20 +02002788/** \defgroup derivation Key derivation
2789 * @{
2790 */
2791
2792/** Set up a key derivation operation.
2793 *
2794 * A key derivation algorithm takes three inputs: a secret input \p key and
2795 * two non-secret inputs \p label and p salt.
2796 * The result of this function is a byte generator which can
2797 * be used to produce keys and other cryptographic material.
2798 *
2799 * The role of \p label and \p salt is as follows:
Gilles Peskinebef7f142018-07-12 17:22:21 +02002800 * - For HKDF (#PSA_ALG_HKDF), \p salt is the salt used in the "extract" step
2801 * and \p label is the info string used in the "expand" step.
Gilles Peskineea0fb492018-07-12 17:17:20 +02002802 *
Jaeden Amero9e919c62019-01-07 15:41:50 +00002803 * \param[in,out] generator The generator object to set up. It must have
2804 * been initialized as per the documentation for
2805 * #psa_crypto_generator_t and not yet in use.
Gilles Peskineae32aac2018-11-30 14:39:32 +01002806 * \param handle Handle to the secret key.
Gilles Peskineea0fb492018-07-12 17:17:20 +02002807 * \param alg The key derivation algorithm to compute
2808 * (\c PSA_ALG_XXX value such that
2809 * #PSA_ALG_IS_KEY_DERIVATION(\p alg) is true).
2810 * \param[in] salt Salt to use.
2811 * \param salt_length Size of the \p salt buffer in bytes.
2812 * \param[in] label Label to use.
2813 * \param label_length Size of the \p label buffer in bytes.
2814 * \param capacity The maximum number of bytes that the
2815 * generator will be able to provide.
2816 *
2817 * \retval #PSA_SUCCESS
2818 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01002819 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskineea0fb492018-07-12 17:17:20 +02002820 * \retval #PSA_ERROR_EMPTY_SLOT
2821 * \retval #PSA_ERROR_NOT_PERMITTED
2822 * \retval #PSA_ERROR_INVALID_ARGUMENT
2823 * \c key is not compatible with \c alg,
2824 * or \p capacity is too large for the specified algorithm and key.
2825 * \retval #PSA_ERROR_NOT_SUPPORTED
2826 * \c alg is not supported or is not a key derivation algorithm.
2827 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2828 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2829 * \retval #PSA_ERROR_HARDWARE_FAILURE
2830 * \retval #PSA_ERROR_TAMPERING_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03002831 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03002832 * The library has not been previously initialized by psa_crypto_init().
2833 * It is implementation-dependent whether a failure to initialize
2834 * results in this error code.
Gilles Peskineea0fb492018-07-12 17:17:20 +02002835 */
2836psa_status_t psa_key_derivation(psa_crypto_generator_t *generator,
Gilles Peskineae32aac2018-11-30 14:39:32 +01002837 psa_key_handle_t handle,
Gilles Peskineea0fb492018-07-12 17:17:20 +02002838 psa_algorithm_t alg,
2839 const uint8_t *salt,
2840 size_t salt_length,
2841 const uint8_t *label,
2842 size_t label_length,
2843 size_t capacity);
2844
Gilles Peskine01d718c2018-09-18 12:01:02 +02002845/** Set up a key agreement operation.
2846 *
2847 * A key agreement algorithm takes two inputs: a private key \p private_key
2848 * a public key \p peer_key.
2849 * The result of this function is a byte generator which can
2850 * be used to produce keys and other cryptographic material.
2851 *
Gilles Peskine211a4362018-10-25 22:22:31 +02002852 * The resulting generator always has the maximum capacity permitted by
2853 * the algorithm.
2854 *
Jaeden Amero9e919c62019-01-07 15:41:50 +00002855 * \param[in,out] generator The generator object to set up. It must have
2856 * been initialized as per the documentation for
2857 * #psa_crypto_generator_t and not yet in use.
Gilles Peskineae32aac2018-11-30 14:39:32 +01002858 * \param private_key Handle to the private key to use.
Gilles Peskined171e782018-11-15 17:46:21 +01002859 * \param[in] peer_key Public key of the peer. It must be
2860 * in the same format that psa_import_key()
2861 * accepts. The standard formats for public
2862 * keys are documented in the documentation
2863 * of psa_export_public_key().
Gilles Peskine01d718c2018-09-18 12:01:02 +02002864 * \param peer_key_length Size of \p peer_key in bytes.
2865 * \param alg The key agreement algorithm to compute
2866 * (\c PSA_ALG_XXX value such that
2867 * #PSA_ALG_IS_KEY_AGREEMENT(\p alg) is true).
2868 *
2869 * \retval #PSA_SUCCESS
2870 * Success.
Gilles Peskineae32aac2018-11-30 14:39:32 +01002871 * \retval #PSA_ERROR_INVALID_HANDLE
Gilles Peskine01d718c2018-09-18 12:01:02 +02002872 * \retval #PSA_ERROR_EMPTY_SLOT
2873 * \retval #PSA_ERROR_NOT_PERMITTED
2874 * \retval #PSA_ERROR_INVALID_ARGUMENT
2875 * \c private_key is not compatible with \c alg,
2876 * or \p peer_key is not valid for \c alg or not compatible with
2877 * \c private_key.
2878 * \retval #PSA_ERROR_NOT_SUPPORTED
2879 * \c alg is not supported or is not a key derivation algorithm.
2880 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2881 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2882 * \retval #PSA_ERROR_HARDWARE_FAILURE
2883 * \retval #PSA_ERROR_TAMPERING_DETECTED
2884 */
2885psa_status_t psa_key_agreement(psa_crypto_generator_t *generator,
Gilles Peskineae32aac2018-11-30 14:39:32 +01002886 psa_key_handle_t private_key,
Gilles Peskine01d718c2018-09-18 12:01:02 +02002887 const uint8_t *peer_key,
2888 size_t peer_key_length,
2889 psa_algorithm_t alg);
2890
Gilles Peskineea0fb492018-07-12 17:17:20 +02002891/**@}*/
2892
Gilles Peskineedd76872018-07-20 17:42:05 +02002893/** \defgroup random Random generation
Gilles Peskine9e7dc712018-03-28 14:18:50 +02002894 * @{
2895 */
2896
2897/**
2898 * \brief Generate random bytes.
2899 *
2900 * \warning This function **can** fail! Callers MUST check the return status
2901 * and MUST NOT use the content of the output buffer if the return
2902 * status is not #PSA_SUCCESS.
2903 *
2904 * \note To generate a key, use psa_generate_key() instead.
2905 *
Gilles Peskineedd11a12018-07-12 01:08:58 +02002906 * \param[out] output Output buffer for the generated data.
Gilles Peskine9e7dc712018-03-28 14:18:50 +02002907 * \param output_size Number of bytes to generate and output.
2908 *
Gilles Peskine28538492018-07-11 17:34:00 +02002909 * \retval #PSA_SUCCESS
2910 * \retval #PSA_ERROR_NOT_SUPPORTED
2911 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
2912 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2913 * \retval #PSA_ERROR_HARDWARE_FAILURE
2914 * \retval #PSA_ERROR_TAMPERING_DETECTED
itayzafrir0adf0fc2018-09-06 16:24:41 +03002915 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03002916 * The library has not been previously initialized by psa_crypto_init().
2917 * It is implementation-dependent whether a failure to initialize
2918 * results in this error code.
Gilles Peskine9e7dc712018-03-28 14:18:50 +02002919 */
2920psa_status_t psa_generate_random(uint8_t *output,
2921 size_t output_size);
2922
Gilles Peskine4c317f42018-07-12 01:24:09 +02002923/** Extra parameters for RSA key generation.
2924 *
Gilles Peskinebe42f312018-07-13 14:38:15 +02002925 * You may pass a pointer to a structure of this type as the \c extra
Gilles Peskine4c317f42018-07-12 01:24:09 +02002926 * parameter to psa_generate_key().
2927 */
2928typedef struct {
Gilles Peskineedd76872018-07-20 17:42:05 +02002929 uint32_t e; /**< Public exponent value. Default: 65537. */
Gilles Peskine4c317f42018-07-12 01:24:09 +02002930} psa_generate_key_extra_rsa;
2931
Gilles Peskine9e7dc712018-03-28 14:18:50 +02002932/**
2933 * \brief Generate a key or key pair.
2934 *
Gilles Peskineae32aac2018-11-30 14:39:32 +01002935 * \param handle Handle to the slot where the key will be stored.
2936 * This must be a valid slot for a key of the chosen
2937 * type: it must have been obtained by calling
2938 * psa_allocate_key() or psa_create_key() with the
2939 * correct \p type and with a maximum size that is
2940 * compatible with \p bits.
2941 * It must not contain any key material yet.
Gilles Peskine4e69d7a2018-06-19 20:19:14 +02002942 * \param type Key type (a \c PSA_KEY_TYPE_XXX value).
2943 * \param bits Key size in bits.
Gilles Peskine53d991e2018-07-12 01:14:59 +02002944 * \param[in] extra Extra parameters for key generation. The
Gilles Peskine4e69d7a2018-06-19 20:19:14 +02002945 * interpretation of this parameter depends on
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002946 * \p type. All types support \c NULL to use
Gilles Peskine3fa675c2018-07-12 01:31:03 +02002947 * default parameters. Implementation that support
2948 * the generation of vendor-specific key types
2949 * that allow extra parameters shall document
2950 * the format of these extra parameters and
2951 * the default values. For standard parameters,
2952 * the meaning of \p extra is as follows:
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002953 * - For a symmetric key type (a type such
Gilles Peskine3fa675c2018-07-12 01:31:03 +02002954 * that #PSA_KEY_TYPE_IS_ASYMMETRIC(\p type) is
2955 * false), \p extra must be \c NULL.
Gilles Peskinefa4070c2018-07-12 19:23:03 +02002956 * - For an elliptic curve key type (a type
Gilles Peskine3fa675c2018-07-12 01:31:03 +02002957 * such that #PSA_KEY_TYPE_IS_ECC(\p type) is
2958 * false), \p extra must be \c NULL.
Gilles Peskinedda3bd32018-07-12 19:40:46 +02002959 * - For an RSA key (\p type is
2960 * #PSA_KEY_TYPE_RSA_KEYPAIR), \p extra is an
2961 * optional #psa_generate_key_extra_rsa structure
Gilles Peskine3fa675c2018-07-12 01:31:03 +02002962 * specifying the public exponent. The
2963 * default public exponent used when \p extra
2964 * is \c NULL is 65537.
Gilles Peskine53d991e2018-07-12 01:14:59 +02002965 * \param extra_size Size of the buffer that \p extra
2966 * points to, in bytes. Note that if \p extra is
2967 * \c NULL then \p extra_size must be zero.
Gilles Peskine9e7dc712018-03-28 14:18:50 +02002968 *
Gilles Peskine28538492018-07-11 17:34:00 +02002969 * \retval #PSA_SUCCESS
Gilles Peskine23fd2bd2018-12-11 15:51:32 +01002970 * Success.
2971 * If the key is persistent, the key material and the key's metadata
2972 * have been saved to persistent storage.
Gilles Peskineae32aac2018-11-30 14:39:32 +01002973 * \retval #PSA_ERROR_INVALID_HANDLE
2974 * \retval #PSA_ERROR_OCCUPIED_SLOT
2975 * There is already a key in the specified slot.
Gilles Peskine28538492018-07-11 17:34:00 +02002976 * \retval #PSA_ERROR_NOT_SUPPORTED
2977 * \retval #PSA_ERROR_INVALID_ARGUMENT
2978 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
2979 * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
2980 * \retval #PSA_ERROR_COMMUNICATION_FAILURE
2981 * \retval #PSA_ERROR_HARDWARE_FAILURE
2982 * \retval #PSA_ERROR_TAMPERING_DETECTED
itayzafrir90d8c7a2018-09-12 11:44:52 +03002983 * \retval #PSA_ERROR_BAD_STATE
itayzafrir18617092018-09-16 12:22:41 +03002984 * The library has not been previously initialized by psa_crypto_init().
2985 * It is implementation-dependent whether a failure to initialize
2986 * results in this error code.
Gilles Peskine9e7dc712018-03-28 14:18:50 +02002987 */
Gilles Peskineae32aac2018-11-30 14:39:32 +01002988psa_status_t psa_generate_key(psa_key_handle_t handle,
Gilles Peskine9e7dc712018-03-28 14:18:50 +02002989 psa_key_type_t type,
2990 size_t bits,
Gilles Peskine53d991e2018-07-12 01:14:59 +02002991 const void *extra,
2992 size_t extra_size);
Gilles Peskine9e7dc712018-03-28 14:18:50 +02002993
2994/**@}*/
2995
Gilles Peskinee59236f2018-01-27 23:32:46 +01002996#ifdef __cplusplus
2997}
2998#endif
2999
Gilles Peskine0cad07c2018-06-27 19:49:02 +02003000/* The file "crypto_sizes.h" contains definitions for size calculation
3001 * macros whose definitions are implementation-specific. */
3002#include "crypto_sizes.h"
3003
Gilles Peskine9ef733f2018-02-07 21:05:37 +01003004/* The file "crypto_struct.h" contains definitions for
3005 * implementation-specific structs that are declared above. */
3006#include "crypto_struct.h"
3007
3008/* The file "crypto_extra.h" contains vendor-specific definitions. This
3009 * can include vendor-defined algorithms, extra functions, etc. */
Gilles Peskinee59236f2018-01-27 23:32:46 +01003010#include "crypto_extra.h"
3011
3012#endif /* PSA_CRYPTO_H */