Kenji Arai
/
mbed-os_TYBLE16
Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
Dependents: TYBLE16_simple_data_logger TYBLE16_MP3_Air
Embed:
(wiki syntax)
Show/hide line numbers
crypto_values.h
Go to the documentation of this file.
00001 /** 00002 * \file psa/crypto_values.h 00003 * 00004 * \brief PSA cryptography module: macros to build and analyze integer values. 00005 * 00006 * \note This file may not be included directly. Applications must 00007 * include psa/crypto.h. Drivers must include the appropriate driver 00008 * header file. 00009 * 00010 * This file contains portable definitions of macros to build and analyze 00011 * values of integral types that encode properties of cryptographic keys, 00012 * designations of cryptographic algorithms, and error codes returned by 00013 * the library. 00014 * 00015 * This header file only defines preprocessor macros. 00016 */ 00017 /* 00018 * Copyright (C) 2018, ARM Limited, All Rights Reserved 00019 * SPDX-License-Identifier: Apache-2.0 00020 * 00021 * Licensed under the Apache License, Version 2.0 (the "License"); you may 00022 * not use this file except in compliance with the License. 00023 * You may obtain a copy of the License at 00024 * 00025 * http://www.apache.org/licenses/LICENSE-2.0 00026 * 00027 * Unless required by applicable law or agreed to in writing, software 00028 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 00029 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00030 * See the License for the specific language governing permissions and 00031 * limitations under the License. 00032 * 00033 * This file is part of mbed TLS (https://tls.mbed.org) 00034 */ 00035 00036 #ifndef PSA_CRYPTO_VALUES_H 00037 #define PSA_CRYPTO_VALUES_H 00038 00039 /** \defgroup error Error codes 00040 * @{ 00041 */ 00042 00043 /* PSA error codes */ 00044 00045 /** The action was completed successfully. */ 00046 #define PSA_SUCCESS ((psa_status_t)0) 00047 00048 /** An error occurred that does not correspond to any defined 00049 * failure cause. 00050 * 00051 * Implementations may use this error code if none of the other standard 00052 * error codes are applicable. */ 00053 #define PSA_ERROR_GENERIC_ERROR ((psa_status_t)-132) 00054 00055 /** The requested operation or a parameter is not supported 00056 * by this implementation. 00057 * 00058 * Implementations should return this error code when an enumeration 00059 * parameter such as a key type, algorithm, etc. is not recognized. 00060 * If a combination of parameters is recognized and identified as 00061 * not valid, return #PSA_ERROR_INVALID_ARGUMENT instead. */ 00062 #define PSA_ERROR_NOT_SUPPORTED ((psa_status_t)-134) 00063 00064 /** The requested action is denied by a policy. 00065 * 00066 * Implementations should return this error code when the parameters 00067 * are recognized as valid and supported, and a policy explicitly 00068 * denies the requested operation. 00069 * 00070 * If a subset of the parameters of a function call identify a 00071 * forbidden operation, and another subset of the parameters are 00072 * not valid or not supported, it is unspecified whether the function 00073 * returns #PSA_ERROR_NOT_PERMITTED, #PSA_ERROR_NOT_SUPPORTED or 00074 * #PSA_ERROR_INVALID_ARGUMENT. */ 00075 #define PSA_ERROR_NOT_PERMITTED ((psa_status_t)-133) 00076 00077 /** An output buffer is too small. 00078 * 00079 * Applications can call the \c PSA_xxx_SIZE macro listed in the function 00080 * description to determine a sufficient buffer size. 00081 * 00082 * Implementations should preferably return this error code only 00083 * in cases when performing the operation with a larger output 00084 * buffer would succeed. However implementations may return this 00085 * error if a function has invalid or unsupported parameters in addition 00086 * to the parameters that determine the necessary output buffer size. */ 00087 #define PSA_ERROR_BUFFER_TOO_SMALL ((psa_status_t)-138) 00088 00089 /** Asking for an item that already exists 00090 * 00091 * Implementations should return this error, when attempting 00092 * to write an item (like a key) that already exists. */ 00093 #define PSA_ERROR_ALREADY_EXISTS ((psa_status_t)-139) 00094 00095 /** Asking for an item that doesn't exist 00096 * 00097 * Implementations should return this error, if a requested item (like 00098 * a key) does not exist. */ 00099 #define PSA_ERROR_DOES_NOT_EXIST ((psa_status_t)-140) 00100 00101 /** The requested action cannot be performed in the current state. 00102 * 00103 * Multipart operations return this error when one of the 00104 * functions is called out of sequence. Refer to the function 00105 * descriptions for permitted sequencing of functions. 00106 * 00107 * Implementations shall not return this error code to indicate 00108 * that a key either exists or not, 00109 * but shall instead return #PSA_ERROR_ALREADY_EXISTS or #PSA_ERROR_DOES_NOT_EXIST 00110 * as applicable. 00111 * 00112 * Implementations shall not return this error code to indicate that a 00113 * key handle is invalid, but shall return #PSA_ERROR_INVALID_HANDLE 00114 * instead. */ 00115 #define PSA_ERROR_BAD_STATE ((psa_status_t)-137) 00116 00117 /** The parameters passed to the function are invalid. 00118 * 00119 * Implementations may return this error any time a parameter or 00120 * combination of parameters are recognized as invalid. 00121 * 00122 * Implementations shall not return this error code to indicate that a 00123 * key handle is invalid, but shall return #PSA_ERROR_INVALID_HANDLE 00124 * instead. 00125 */ 00126 #define PSA_ERROR_INVALID_ARGUMENT ((psa_status_t)-135) 00127 00128 /** There is not enough runtime memory. 00129 * 00130 * If the action is carried out across multiple security realms, this 00131 * error can refer to available memory in any of the security realms. */ 00132 #define PSA_ERROR_INSUFFICIENT_MEMORY ((psa_status_t)-141) 00133 00134 /** There is not enough persistent storage. 00135 * 00136 * Functions that modify the key storage return this error code if 00137 * there is insufficient storage space on the host media. In addition, 00138 * many functions that do not otherwise access storage may return this 00139 * error code if the implementation requires a mandatory log entry for 00140 * the requested action and the log storage space is full. */ 00141 #define PSA_ERROR_INSUFFICIENT_STORAGE ((psa_status_t)-142) 00142 00143 /** There was a communication failure inside the implementation. 00144 * 00145 * This can indicate a communication failure between the application 00146 * and an external cryptoprocessor or between the cryptoprocessor and 00147 * an external volatile or persistent memory. A communication failure 00148 * may be transient or permanent depending on the cause. 00149 * 00150 * \warning If a function returns this error, it is undetermined 00151 * whether the requested action has completed or not. Implementations 00152 * should return #PSA_SUCCESS on successful completion whenever 00153 * possible, however functions may return #PSA_ERROR_COMMUNICATION_FAILURE 00154 * if the requested action was completed successfully in an external 00155 * cryptoprocessor but there was a breakdown of communication before 00156 * the cryptoprocessor could report the status to the application. 00157 */ 00158 #define PSA_ERROR_COMMUNICATION_FAILURE ((psa_status_t)-145) 00159 00160 /** There was a storage failure that may have led to data loss. 00161 * 00162 * This error indicates that some persistent storage is corrupted. 00163 * It should not be used for a corruption of volatile memory 00164 * (use #PSA_ERROR_CORRUPTION_DETECTED), for a communication error 00165 * between the cryptoprocessor and its external storage (use 00166 * #PSA_ERROR_COMMUNICATION_FAILURE), or when the storage is 00167 * in a valid state but is full (use #PSA_ERROR_INSUFFICIENT_STORAGE). 00168 * 00169 * Note that a storage failure does not indicate that any data that was 00170 * previously read is invalid. However this previously read data may no 00171 * longer be readable from storage. 00172 * 00173 * When a storage failure occurs, it is no longer possible to ensure 00174 * the global integrity of the keystore. Depending on the global 00175 * integrity guarantees offered by the implementation, access to other 00176 * data may or may not fail even if the data is still readable but 00177 * its integrity cannot be guaranteed. 00178 * 00179 * Implementations should only use this error code to report a 00180 * permanent storage corruption. However application writers should 00181 * keep in mind that transient errors while reading the storage may be 00182 * reported using this error code. */ 00183 #define PSA_ERROR_STORAGE_FAILURE ((psa_status_t)-146) 00184 00185 /** A hardware failure was detected. 00186 * 00187 * A hardware failure may be transient or permanent depending on the 00188 * cause. */ 00189 #define PSA_ERROR_HARDWARE_FAILURE ((psa_status_t)-147) 00190 00191 /** A tampering attempt was detected. 00192 * 00193 * If an application receives this error code, there is no guarantee 00194 * that previously accessed or computed data was correct and remains 00195 * confidential. Applications should not perform any security function 00196 * and should enter a safe failure state. 00197 * 00198 * Implementations may return this error code if they detect an invalid 00199 * state that cannot happen during normal operation and that indicates 00200 * that the implementation's security guarantees no longer hold. Depending 00201 * on the implementation architecture and on its security and safety goals, 00202 * the implementation may forcibly terminate the application. 00203 * 00204 * This error code is intended as a last resort when a security breach 00205 * is detected and it is unsure whether the keystore data is still 00206 * protected. Implementations shall only return this error code 00207 * to report an alarm from a tampering detector, to indicate that 00208 * the confidentiality of stored data can no longer be guaranteed, 00209 * or to indicate that the integrity of previously returned data is now 00210 * considered compromised. Implementations shall not use this error code 00211 * to indicate a hardware failure that merely makes it impossible to 00212 * perform the requested operation (use #PSA_ERROR_COMMUNICATION_FAILURE, 00213 * #PSA_ERROR_STORAGE_FAILURE, #PSA_ERROR_HARDWARE_FAILURE, 00214 * #PSA_ERROR_INSUFFICIENT_ENTROPY or other applicable error code 00215 * instead). 00216 * 00217 * This error indicates an attack against the application. Implementations 00218 * shall not return this error code as a consequence of the behavior of 00219 * the application itself. */ 00220 #define PSA_ERROR_CORRUPTION_DETECTED ((psa_status_t)-151) 00221 00222 /** There is not enough entropy to generate random data needed 00223 * for the requested action. 00224 * 00225 * This error indicates a failure of a hardware random generator. 00226 * Application writers should note that this error can be returned not 00227 * only by functions whose purpose is to generate random data, such 00228 * as key, IV or nonce generation, but also by functions that execute 00229 * an algorithm with a randomized result, as well as functions that 00230 * use randomization of intermediate computations as a countermeasure 00231 * to certain attacks. 00232 * 00233 * Implementations should avoid returning this error after psa_crypto_init() 00234 * has succeeded. Implementations should generate sufficient 00235 * entropy during initialization and subsequently use a cryptographically 00236 * secure pseudorandom generator (PRNG). However implementations may return 00237 * this error at any time if a policy requires the PRNG to be reseeded 00238 * during normal operation. */ 00239 #define PSA_ERROR_INSUFFICIENT_ENTROPY ((psa_status_t)-148) 00240 00241 /** The signature, MAC or hash is incorrect. 00242 * 00243 * Verification functions return this error if the verification 00244 * calculations completed successfully, and the value to be verified 00245 * was determined to be incorrect. 00246 * 00247 * If the value to verify has an invalid size, implementations may return 00248 * either #PSA_ERROR_INVALID_ARGUMENT or #PSA_ERROR_INVALID_SIGNATURE. */ 00249 #define PSA_ERROR_INVALID_SIGNATURE ((psa_status_t)-149) 00250 00251 /** The decrypted padding is incorrect. 00252 * 00253 * \warning In some protocols, when decrypting data, it is essential that 00254 * the behavior of the application does not depend on whether the padding 00255 * is correct, down to precise timing. Applications should prefer 00256 * protocols that use authenticated encryption rather than plain 00257 * encryption. If the application must perform a decryption of 00258 * unauthenticated data, the application writer should take care not 00259 * to reveal whether the padding is invalid. 00260 * 00261 * Implementations should strive to make valid and invalid padding 00262 * as close as possible to indistinguishable to an external observer. 00263 * In particular, the timing of a decryption operation should not 00264 * depend on the validity of the padding. */ 00265 #define PSA_ERROR_INVALID_PADDING ((psa_status_t)-150) 00266 00267 /** Return this error when there's insufficient data when attempting 00268 * to read from a resource. */ 00269 #define PSA_ERROR_INSUFFICIENT_DATA ((psa_status_t)-143) 00270 00271 /** The key handle is not valid. See also :ref:\`key-handles\`. 00272 */ 00273 #define PSA_ERROR_INVALID_HANDLE ((psa_status_t)-136) 00274 00275 /**@}*/ 00276 00277 /** \defgroup crypto_types Key and algorithm types 00278 * @{ 00279 */ 00280 00281 /** An invalid key type value. 00282 * 00283 * Zero is not the encoding of any key type. 00284 */ 00285 #define PSA_KEY_TYPE_NONE ((psa_key_type_t)0x00000000) 00286 00287 /** Vendor-defined key type flag. 00288 * 00289 * Key types defined by this standard will never have the 00290 * #PSA_KEY_TYPE_VENDOR_FLAG bit set. Vendors who define additional key types 00291 * must use an encoding with the #PSA_KEY_TYPE_VENDOR_FLAG bit set and should 00292 * respect the bitwise structure used by standard encodings whenever practical. 00293 */ 00294 #define PSA_KEY_TYPE_VENDOR_FLAG ((psa_key_type_t)0x80000000) 00295 00296 #define PSA_KEY_TYPE_CATEGORY_MASK ((psa_key_type_t)0x70000000) 00297 #define PSA_KEY_TYPE_CATEGORY_SYMMETRIC ((psa_key_type_t)0x40000000) 00298 #define PSA_KEY_TYPE_CATEGORY_RAW ((psa_key_type_t)0x50000000) 00299 #define PSA_KEY_TYPE_CATEGORY_PUBLIC_KEY ((psa_key_type_t)0x60000000) 00300 #define PSA_KEY_TYPE_CATEGORY_KEY_PAIR ((psa_key_type_t)0x70000000) 00301 00302 #define PSA_KEY_TYPE_CATEGORY_FLAG_PAIR ((psa_key_type_t)0x10000000) 00303 00304 /** Whether a key type is vendor-defined. 00305 * 00306 * See also #PSA_KEY_TYPE_VENDOR_FLAG. 00307 */ 00308 #define PSA_KEY_TYPE_IS_VENDOR_DEFINED(type) \ 00309 (((type) & PSA_KEY_TYPE_VENDOR_FLAG) != 0) 00310 00311 /** Whether a key type is an unstructured array of bytes. 00312 * 00313 * This encompasses both symmetric keys and non-key data. 00314 */ 00315 #define PSA_KEY_TYPE_IS_UNSTRUCTURED(type) \ 00316 (((type) & PSA_KEY_TYPE_CATEGORY_MASK & ~(psa_key_type_t)0x10000000) == \ 00317 PSA_KEY_TYPE_CATEGORY_SYMMETRIC) 00318 00319 /** Whether a key type is asymmetric: either a key pair or a public key. */ 00320 #define PSA_KEY_TYPE_IS_ASYMMETRIC(type) \ 00321 (((type) & PSA_KEY_TYPE_CATEGORY_MASK \ 00322 & ~PSA_KEY_TYPE_CATEGORY_FLAG_PAIR) == \ 00323 PSA_KEY_TYPE_CATEGORY_PUBLIC_KEY) 00324 /** Whether a key type is the public part of a key pair. */ 00325 #define PSA_KEY_TYPE_IS_PUBLIC_KEY(type) \ 00326 (((type) & PSA_KEY_TYPE_CATEGORY_MASK) == PSA_KEY_TYPE_CATEGORY_PUBLIC_KEY) 00327 /** Whether a key type is a key pair containing a private part and a public 00328 * part. */ 00329 #define PSA_KEY_TYPE_IS_KEY_PAIR(type) \ 00330 (((type) & PSA_KEY_TYPE_CATEGORY_MASK) == PSA_KEY_TYPE_CATEGORY_KEY_PAIR) 00331 /** The key pair type corresponding to a public key type. 00332 * 00333 * You may also pass a key pair type as \p type, it will be left unchanged. 00334 * 00335 * \param type A public key type or key pair type. 00336 * 00337 * \return The corresponding key pair type. 00338 * If \p type is not a public key or a key pair, 00339 * the return value is undefined. 00340 */ 00341 #define PSA_KEY_TYPE_KEY_PAIR_OF_PUBLIC_KEY(type) \ 00342 ((type) | PSA_KEY_TYPE_CATEGORY_FLAG_PAIR) 00343 /** The public key type corresponding to a key pair type. 00344 * 00345 * You may also pass a key pair type as \p type, it will be left unchanged. 00346 * 00347 * \param type A public key type or key pair type. 00348 * 00349 * \return The corresponding public key type. 00350 * If \p type is not a public key or a key pair, 00351 * the return value is undefined. 00352 */ 00353 #define PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) \ 00354 ((type) & ~PSA_KEY_TYPE_CATEGORY_FLAG_PAIR) 00355 00356 /** Raw data. 00357 * 00358 * A "key" of this type cannot be used for any cryptographic operation. 00359 * Applications may use this type to store arbitrary data in the keystore. */ 00360 #define PSA_KEY_TYPE_RAW_DATA ((psa_key_type_t)0x50000001) 00361 00362 /** HMAC key. 00363 * 00364 * The key policy determines which underlying hash algorithm the key can be 00365 * used for. 00366 * 00367 * HMAC keys should generally have the same size as the underlying hash. 00368 * This size can be calculated with #PSA_HASH_SIZE(\c alg) where 00369 * \c alg is the HMAC algorithm or the underlying hash algorithm. */ 00370 #define PSA_KEY_TYPE_HMAC ((psa_key_type_t)0x51000000) 00371 00372 /** A secret for key derivation. 00373 * 00374 * The key policy determines which key derivation algorithm the key 00375 * can be used for. 00376 */ 00377 #define PSA_KEY_TYPE_DERIVE ((psa_key_type_t)0x52000000) 00378 00379 /** Key for a cipher, AEAD or MAC algorithm based on the AES block cipher. 00380 * 00381 * The size of the key can be 16 bytes (AES-128), 24 bytes (AES-192) or 00382 * 32 bytes (AES-256). 00383 */ 00384 #define PSA_KEY_TYPE_AES ((psa_key_type_t)0x40000001) 00385 00386 /** Key for a cipher or MAC algorithm based on DES or 3DES (Triple-DES). 00387 * 00388 * The size of the key can be 8 bytes (single DES), 16 bytes (2-key 3DES) or 00389 * 24 bytes (3-key 3DES). 00390 * 00391 * Note that single DES and 2-key 3DES are weak and strongly 00392 * deprecated and should only be used to decrypt legacy data. 3-key 3DES 00393 * is weak and deprecated and should only be used in legacy protocols. 00394 */ 00395 #define PSA_KEY_TYPE_DES ((psa_key_type_t)0x40000002) 00396 00397 /** Key for a cipher, AEAD or MAC algorithm based on the 00398 * Camellia block cipher. */ 00399 #define PSA_KEY_TYPE_CAMELLIA ((psa_key_type_t)0x40000003) 00400 00401 /** Key for the RC4 stream cipher. 00402 * 00403 * Note that RC4 is weak and deprecated and should only be used in 00404 * legacy protocols. */ 00405 #define PSA_KEY_TYPE_ARC4 ((psa_key_type_t)0x40000004) 00406 00407 /** Key for the ChaCha20 stream cipher or the Chacha20-Poly1305 AEAD algorithm. 00408 * 00409 * ChaCha20 and the ChaCha20_Poly1305 construction are defined in RFC 7539. 00410 * 00411 * Implementations must support 12-byte nonces, may support 8-byte nonces, 00412 * and should reject other sizes. 00413 */ 00414 #define PSA_KEY_TYPE_CHACHA20 ((psa_key_type_t)0x40000005) 00415 00416 /** RSA public key. */ 00417 #define PSA_KEY_TYPE_RSA_PUBLIC_KEY ((psa_key_type_t)0x60010000) 00418 /** RSA key pair (private and public key). */ 00419 #define PSA_KEY_TYPE_RSA_KEY_PAIR ((psa_key_type_t)0x70010000) 00420 /** Whether a key type is an RSA key (pair or public-only). */ 00421 #define PSA_KEY_TYPE_IS_RSA(type) \ 00422 (PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) == PSA_KEY_TYPE_RSA_PUBLIC_KEY) 00423 00424 #define PSA_KEY_TYPE_ECC_PUBLIC_KEY_BASE ((psa_key_type_t)0x60030000) 00425 #define PSA_KEY_TYPE_ECC_KEY_PAIR_BASE ((psa_key_type_t)0x70030000) 00426 #define PSA_KEY_TYPE_ECC_CURVE_MASK ((psa_key_type_t)0x0000ffff) 00427 /** Elliptic curve key pair. 00428 * 00429 * \param curve A value of type ::psa_ecc_curve_t that identifies the 00430 * ECC curve to be used. 00431 */ 00432 #define PSA_KEY_TYPE_ECC_KEY_PAIR(curve) \ 00433 (PSA_KEY_TYPE_ECC_KEY_PAIR_BASE | (curve)) 00434 /** Elliptic curve public key. 00435 * 00436 * \param curve A value of type ::psa_ecc_curve_t that identifies the 00437 * ECC curve to be used. 00438 */ 00439 #define PSA_KEY_TYPE_ECC_PUBLIC_KEY(curve) \ 00440 (PSA_KEY_TYPE_ECC_PUBLIC_KEY_BASE | (curve)) 00441 00442 /** Whether a key type is an elliptic curve key (pair or public-only). */ 00443 #define PSA_KEY_TYPE_IS_ECC(type) \ 00444 ((PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) & \ 00445 ~PSA_KEY_TYPE_ECC_CURVE_MASK) == PSA_KEY_TYPE_ECC_PUBLIC_KEY_BASE) 00446 /** Whether a key type is an elliptic curve key pair. */ 00447 #define PSA_KEY_TYPE_IS_ECC_KEY_PAIR(type) \ 00448 (((type) & ~PSA_KEY_TYPE_ECC_CURVE_MASK) == \ 00449 PSA_KEY_TYPE_ECC_KEY_PAIR_BASE) 00450 /** Whether a key type is an elliptic curve public key. */ 00451 #define PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY(type) \ 00452 (((type) & ~PSA_KEY_TYPE_ECC_CURVE_MASK) == \ 00453 PSA_KEY_TYPE_ECC_PUBLIC_KEY_BASE) 00454 00455 /** Extract the curve from an elliptic curve key type. */ 00456 #define PSA_KEY_TYPE_GET_CURVE(type) \ 00457 ((psa_ecc_curve_t) (PSA_KEY_TYPE_IS_ECC(type) ? \ 00458 ((type) & PSA_KEY_TYPE_ECC_CURVE_MASK) : \ 00459 0)) 00460 00461 /* The encoding of curve identifiers is currently aligned with the 00462 * TLS Supported Groups Registry (formerly known as the 00463 * TLS EC Named Curve Registry) 00464 * https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-8 00465 * The values are defined by RFC 8422 and RFC 7027. */ 00466 #define PSA_ECC_CURVE_SECT163K1 ((psa_ecc_curve_t) 0x0001) 00467 #define PSA_ECC_CURVE_SECT163R1 ((psa_ecc_curve_t) 0x0002) 00468 #define PSA_ECC_CURVE_SECT163R2 ((psa_ecc_curve_t) 0x0003) 00469 #define PSA_ECC_CURVE_SECT193R1 ((psa_ecc_curve_t) 0x0004) 00470 #define PSA_ECC_CURVE_SECT193R2 ((psa_ecc_curve_t) 0x0005) 00471 #define PSA_ECC_CURVE_SECT233K1 ((psa_ecc_curve_t) 0x0006) 00472 #define PSA_ECC_CURVE_SECT233R1 ((psa_ecc_curve_t) 0x0007) 00473 #define PSA_ECC_CURVE_SECT239K1 ((psa_ecc_curve_t) 0x0008) 00474 #define PSA_ECC_CURVE_SECT283K1 ((psa_ecc_curve_t) 0x0009) 00475 #define PSA_ECC_CURVE_SECT283R1 ((psa_ecc_curve_t) 0x000a) 00476 #define PSA_ECC_CURVE_SECT409K1 ((psa_ecc_curve_t) 0x000b) 00477 #define PSA_ECC_CURVE_SECT409R1 ((psa_ecc_curve_t) 0x000c) 00478 #define PSA_ECC_CURVE_SECT571K1 ((psa_ecc_curve_t) 0x000d) 00479 #define PSA_ECC_CURVE_SECT571R1 ((psa_ecc_curve_t) 0x000e) 00480 #define PSA_ECC_CURVE_SECP160K1 ((psa_ecc_curve_t) 0x000f) 00481 #define PSA_ECC_CURVE_SECP160R1 ((psa_ecc_curve_t) 0x0010) 00482 #define PSA_ECC_CURVE_SECP160R2 ((psa_ecc_curve_t) 0x0011) 00483 #define PSA_ECC_CURVE_SECP192K1 ((psa_ecc_curve_t) 0x0012) 00484 #define PSA_ECC_CURVE_SECP192R1 ((psa_ecc_curve_t) 0x0013) 00485 #define PSA_ECC_CURVE_SECP224K1 ((psa_ecc_curve_t) 0x0014) 00486 #define PSA_ECC_CURVE_SECP224R1 ((psa_ecc_curve_t) 0x0015) 00487 #define PSA_ECC_CURVE_SECP256K1 ((psa_ecc_curve_t) 0x0016) 00488 #define PSA_ECC_CURVE_SECP256R1 ((psa_ecc_curve_t) 0x0017) 00489 #define PSA_ECC_CURVE_SECP384R1 ((psa_ecc_curve_t) 0x0018) 00490 #define PSA_ECC_CURVE_SECP521R1 ((psa_ecc_curve_t) 0x0019) 00491 #define PSA_ECC_CURVE_BRAINPOOL_P256R1 ((psa_ecc_curve_t) 0x001a) 00492 #define PSA_ECC_CURVE_BRAINPOOL_P384R1 ((psa_ecc_curve_t) 0x001b) 00493 #define PSA_ECC_CURVE_BRAINPOOL_P512R1 ((psa_ecc_curve_t) 0x001c) 00494 /** Curve25519. 00495 * 00496 * This is the curve defined in Bernstein et al., 00497 * _Curve25519: new Diffie-Hellman speed records_, LNCS 3958, 2006. 00498 * The algorithm #PSA_ALG_ECDH performs X25519 when used with this curve. 00499 */ 00500 #define PSA_ECC_CURVE_CURVE25519 ((psa_ecc_curve_t) 0x001d) 00501 /** Curve448 00502 * 00503 * This is the curve defined in Hamburg, 00504 * _Ed448-Goldilocks, a new elliptic curve_, NIST ECC Workshop, 2015. 00505 * The algorithm #PSA_ALG_ECDH performs X448 when used with this curve. 00506 */ 00507 #define PSA_ECC_CURVE_CURVE448 ((psa_ecc_curve_t) 0x001e) 00508 00509 /** Minimum value for a vendor-defined ECC curve identifier 00510 * 00511 * The range for vendor-defined curve identifiers is a subset of the IANA 00512 * registry private use range, `0xfe00` - `0xfeff`. 00513 */ 00514 #define PSA_ECC_CURVE_VENDOR_MIN ((psa_ecc_curve_t) 0xfe00) 00515 /** Maximum value for a vendor-defined ECC curve identifier 00516 * 00517 * The range for vendor-defined curve identifiers is a subset of the IANA 00518 * registry private use range, `0xfe00` - `0xfeff`. 00519 */ 00520 #define PSA_ECC_CURVE_VENDOR_MAX ((psa_ecc_curve_t) 0xfe7f) 00521 00522 #define PSA_KEY_TYPE_DH_PUBLIC_KEY_BASE ((psa_key_type_t)0x60040000) 00523 #define PSA_KEY_TYPE_DH_KEY_PAIR_BASE ((psa_key_type_t)0x70040000) 00524 #define PSA_KEY_TYPE_DH_GROUP_MASK ((psa_key_type_t)0x0000ffff) 00525 /** Diffie-Hellman key pair. 00526 * 00527 * \param group A value of type ::psa_dh_group_t that identifies the 00528 * Diffie-Hellman group to be used. 00529 */ 00530 #define PSA_KEY_TYPE_DH_KEY_PAIR(group) \ 00531 (PSA_KEY_TYPE_DH_KEY_PAIR_BASE | (group)) 00532 /** Diffie-Hellman public key. 00533 * 00534 * \param group A value of type ::psa_dh_group_t that identifies the 00535 * Diffie-Hellman group to be used. 00536 */ 00537 #define PSA_KEY_TYPE_DH_PUBLIC_KEY(group) \ 00538 (PSA_KEY_TYPE_DH_PUBLIC_KEY_BASE | (group)) 00539 00540 /** Whether a key type is a Diffie-Hellman key (pair or public-only). */ 00541 #define PSA_KEY_TYPE_IS_DH(type) \ 00542 ((PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) & \ 00543 ~PSA_KEY_TYPE_DH_GROUP_MASK) == PSA_KEY_TYPE_DH_PUBLIC_KEY_BASE) 00544 /** Whether a key type is a Diffie-Hellman key pair. */ 00545 #define PSA_KEY_TYPE_IS_DH_KEY_PAIR(type) \ 00546 (((type) & ~PSA_KEY_TYPE_DH_GROUP_MASK) == \ 00547 PSA_KEY_TYPE_DH_KEY_PAIR_BASE) 00548 /** Whether a key type is a Diffie-Hellman public key. */ 00549 #define PSA_KEY_TYPE_IS_DH_PUBLIC_KEY(type) \ 00550 (((type) & ~PSA_KEY_TYPE_DH_GROUP_MASK) == \ 00551 PSA_KEY_TYPE_DH_PUBLIC_KEY_BASE) 00552 00553 /** Extract the group from a Diffie-Hellman key type. */ 00554 #define PSA_KEY_TYPE_GET_GROUP(type) \ 00555 ((psa_dh_group_t) (PSA_KEY_TYPE_IS_DH(type) ? \ 00556 ((type) & PSA_KEY_TYPE_DH_GROUP_MASK) : \ 00557 0)) 00558 00559 /* The encoding of group identifiers is currently aligned with the 00560 * TLS Supported Groups Registry (formerly known as the 00561 * TLS EC Named Curve Registry) 00562 * https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-8 00563 * The values are defined by RFC 7919. */ 00564 #define PSA_DH_GROUP_FFDHE2048 ((psa_dh_group_t) 0x0100) 00565 #define PSA_DH_GROUP_FFDHE3072 ((psa_dh_group_t) 0x0101) 00566 #define PSA_DH_GROUP_FFDHE4096 ((psa_dh_group_t) 0x0102) 00567 #define PSA_DH_GROUP_FFDHE6144 ((psa_dh_group_t) 0x0103) 00568 #define PSA_DH_GROUP_FFDHE8192 ((psa_dh_group_t) 0x0104) 00569 00570 /** Minimum value for a vendor-defined Diffie Hellman group identifier 00571 * 00572 * The range for vendor-defined group identifiers is a subset of the IANA 00573 * registry private use range, `0x01fc` - `0x01ff`. 00574 */ 00575 #define PSA_DH_GROUP_VENDOR_MIN ((psa_dh_group_t) 0x01fc) 00576 /** Maximum value for a vendor-defined Diffie Hellman group identifier 00577 * 00578 * The range for vendor-defined group identifiers is a subset of the IANA 00579 * registry private use range, `0x01fc` - `0x01ff`. 00580 */ 00581 #define PSA_DH_GROUP_VENDOR_MAX ((psa_dh_group_t) 0x01fd) 00582 00583 /** The block size of a block cipher. 00584 * 00585 * \param type A cipher key type (value of type #psa_key_type_t). 00586 * 00587 * \return The block size for a block cipher, or 1 for a stream cipher. 00588 * The return value is undefined if \p type is not a supported 00589 * cipher key type. 00590 * 00591 * \note It is possible to build stream cipher algorithms on top of a block 00592 * cipher, for example CTR mode (#PSA_ALG_CTR). 00593 * This macro only takes the key type into account, so it cannot be 00594 * used to determine the size of the data that #psa_cipher_update() 00595 * might buffer for future processing in general. 00596 * 00597 * \note This macro returns a compile-time constant if its argument is one. 00598 * 00599 * \warning This macro may evaluate its argument multiple times. 00600 */ 00601 #define PSA_BLOCK_CIPHER_BLOCK_SIZE(type) \ 00602 ( \ 00603 (type) == PSA_KEY_TYPE_AES ? 16 : \ 00604 (type) == PSA_KEY_TYPE_DES ? 8 : \ 00605 (type) == PSA_KEY_TYPE_CAMELLIA ? 16 : \ 00606 (type) == PSA_KEY_TYPE_ARC4 ? 1 : \ 00607 0) 00608 00609 /** Vendor-defined algorithm flag. 00610 * 00611 * Algorithms defined by this standard will never have the #PSA_ALG_VENDOR_FLAG 00612 * bit set. Vendors who define additional algorithms must use an encoding with 00613 * the #PSA_ALG_VENDOR_FLAG bit set and should respect the bitwise structure 00614 * used by standard encodings whenever practical. 00615 */ 00616 #define PSA_ALG_VENDOR_FLAG ((psa_algorithm_t)0x80000000) 00617 00618 #define PSA_ALG_CATEGORY_MASK ((psa_algorithm_t)0x7f000000) 00619 #define PSA_ALG_CATEGORY_HASH ((psa_algorithm_t)0x01000000) 00620 #define PSA_ALG_CATEGORY_MAC ((psa_algorithm_t)0x02000000) 00621 #define PSA_ALG_CATEGORY_CIPHER ((psa_algorithm_t)0x04000000) 00622 #define PSA_ALG_CATEGORY_AEAD ((psa_algorithm_t)0x06000000) 00623 #define PSA_ALG_CATEGORY_SIGN ((psa_algorithm_t)0x10000000) 00624 #define PSA_ALG_CATEGORY_ASYMMETRIC_ENCRYPTION ((psa_algorithm_t)0x12000000) 00625 #define PSA_ALG_CATEGORY_KEY_DERIVATION ((psa_algorithm_t)0x20000000) 00626 #define PSA_ALG_CATEGORY_KEY_AGREEMENT ((psa_algorithm_t)0x30000000) 00627 00628 /** Whether an algorithm is vendor-defined. 00629 * 00630 * See also #PSA_ALG_VENDOR_FLAG. 00631 */ 00632 #define PSA_ALG_IS_VENDOR_DEFINED(alg) \ 00633 (((alg) & PSA_ALG_VENDOR_FLAG) != 0) 00634 00635 /** Whether the specified algorithm is a hash algorithm. 00636 * 00637 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 00638 * 00639 * \return 1 if \p alg is a hash algorithm, 0 otherwise. 00640 * This macro may return either 0 or 1 if \p alg is not a supported 00641 * algorithm identifier. 00642 */ 00643 #define PSA_ALG_IS_HASH(alg) \ 00644 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_HASH) 00645 00646 /** Whether the specified algorithm is a MAC algorithm. 00647 * 00648 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 00649 * 00650 * \return 1 if \p alg is a MAC algorithm, 0 otherwise. 00651 * This macro may return either 0 or 1 if \p alg is not a supported 00652 * algorithm identifier. 00653 */ 00654 #define PSA_ALG_IS_MAC(alg) \ 00655 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_MAC) 00656 00657 /** Whether the specified algorithm is a symmetric cipher algorithm. 00658 * 00659 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 00660 * 00661 * \return 1 if \p alg is a symmetric cipher algorithm, 0 otherwise. 00662 * This macro may return either 0 or 1 if \p alg is not a supported 00663 * algorithm identifier. 00664 */ 00665 #define PSA_ALG_IS_CIPHER(alg) \ 00666 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_CIPHER) 00667 00668 /** Whether the specified algorithm is an authenticated encryption 00669 * with associated data (AEAD) algorithm. 00670 * 00671 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 00672 * 00673 * \return 1 if \p alg is an AEAD algorithm, 0 otherwise. 00674 * This macro may return either 0 or 1 if \p alg is not a supported 00675 * algorithm identifier. 00676 */ 00677 #define PSA_ALG_IS_AEAD(alg) \ 00678 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_AEAD) 00679 00680 /** Whether the specified algorithm is a public-key signature algorithm. 00681 * 00682 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 00683 * 00684 * \return 1 if \p alg is a public-key signature algorithm, 0 otherwise. 00685 * This macro may return either 0 or 1 if \p alg is not a supported 00686 * algorithm identifier. 00687 */ 00688 #define PSA_ALG_IS_SIGN(alg) \ 00689 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_SIGN) 00690 00691 /** Whether the specified algorithm is a public-key encryption algorithm. 00692 * 00693 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 00694 * 00695 * \return 1 if \p alg is a public-key encryption algorithm, 0 otherwise. 00696 * This macro may return either 0 or 1 if \p alg is not a supported 00697 * algorithm identifier. 00698 */ 00699 #define PSA_ALG_IS_ASYMMETRIC_ENCRYPTION(alg) \ 00700 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_ASYMMETRIC_ENCRYPTION) 00701 00702 /** Whether the specified algorithm is a key agreement algorithm. 00703 * 00704 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 00705 * 00706 * \return 1 if \p alg is a key agreement algorithm, 0 otherwise. 00707 * This macro may return either 0 or 1 if \p alg is not a supported 00708 * algorithm identifier. 00709 */ 00710 #define PSA_ALG_IS_KEY_AGREEMENT(alg) \ 00711 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_KEY_AGREEMENT) 00712 00713 /** Whether the specified algorithm is a key derivation algorithm. 00714 * 00715 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 00716 * 00717 * \return 1 if \p alg is a key derivation algorithm, 0 otherwise. 00718 * This macro may return either 0 or 1 if \p alg is not a supported 00719 * algorithm identifier. 00720 */ 00721 #define PSA_ALG_IS_KEY_DERIVATION(alg) \ 00722 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_KEY_DERIVATION) 00723 00724 #define PSA_ALG_HASH_MASK ((psa_algorithm_t)0x000000ff) 00725 /** MD2 */ 00726 #define PSA_ALG_MD2 ((psa_algorithm_t)0x01000001) 00727 /** MD4 */ 00728 #define PSA_ALG_MD4 ((psa_algorithm_t)0x01000002) 00729 /** MD5 */ 00730 #define PSA_ALG_MD5 ((psa_algorithm_t)0x01000003) 00731 /** PSA_ALG_RIPEMD160 */ 00732 #define PSA_ALG_RIPEMD160 ((psa_algorithm_t)0x01000004) 00733 /** SHA1 */ 00734 #define PSA_ALG_SHA_1 ((psa_algorithm_t)0x01000005) 00735 /** SHA2-224 */ 00736 #define PSA_ALG_SHA_224 ((psa_algorithm_t)0x01000008) 00737 /** SHA2-256 */ 00738 #define PSA_ALG_SHA_256 ((psa_algorithm_t)0x01000009) 00739 /** SHA2-384 */ 00740 #define PSA_ALG_SHA_384 ((psa_algorithm_t)0x0100000a) 00741 /** SHA2-512 */ 00742 #define PSA_ALG_SHA_512 ((psa_algorithm_t)0x0100000b) 00743 /** SHA2-512/224 */ 00744 #define PSA_ALG_SHA_512_224 ((psa_algorithm_t)0x0100000c) 00745 /** SHA2-512/256 */ 00746 #define PSA_ALG_SHA_512_256 ((psa_algorithm_t)0x0100000d) 00747 /** SHA3-224 */ 00748 #define PSA_ALG_SHA3_224 ((psa_algorithm_t)0x01000010) 00749 /** SHA3-256 */ 00750 #define PSA_ALG_SHA3_256 ((psa_algorithm_t)0x01000011) 00751 /** SHA3-384 */ 00752 #define PSA_ALG_SHA3_384 ((psa_algorithm_t)0x01000012) 00753 /** SHA3-512 */ 00754 #define PSA_ALG_SHA3_512 ((psa_algorithm_t)0x01000013) 00755 00756 /** In a hash-and-sign algorithm policy, allow any hash algorithm. 00757 * 00758 * This value may be used to form the algorithm usage field of a policy 00759 * for a signature algorithm that is parametrized by a hash. The key 00760 * may then be used to perform operations using the same signature 00761 * algorithm parametrized with any supported hash. 00762 * 00763 * That is, suppose that `PSA_xxx_SIGNATURE` is one of the following macros: 00764 * - #PSA_ALG_RSA_PKCS1V15_SIGN, #PSA_ALG_RSA_PSS, 00765 * - #PSA_ALG_ECDSA, #PSA_ALG_DETERMINISTIC_ECDSA. 00766 * Then you may create and use a key as follows: 00767 * - Set the key usage field using #PSA_ALG_ANY_HASH, for example: 00768 * ``` 00769 * psa_set_key_usage_flags(&attributes, PSA_KEY_USAGE_SIGN); // or VERIFY 00770 * psa_set_key_algorithm(&attributes, PSA_xxx_SIGNATURE(PSA_ALG_ANY_HASH)); 00771 * ``` 00772 * - Import or generate key material. 00773 * - Call psa_asymmetric_sign() or psa_asymmetric_verify(), passing 00774 * an algorithm built from `PSA_xxx_SIGNATURE` and a specific hash. Each 00775 * call to sign or verify a message may use a different hash. 00776 * ``` 00777 * psa_asymmetric_sign(handle, PSA_xxx_SIGNATURE(PSA_ALG_SHA_256), ...); 00778 * psa_asymmetric_sign(handle, PSA_xxx_SIGNATURE(PSA_ALG_SHA_512), ...); 00779 * psa_asymmetric_sign(handle, PSA_xxx_SIGNATURE(PSA_ALG_SHA3_256), ...); 00780 * ``` 00781 * 00782 * This value may not be used to build other algorithms that are 00783 * parametrized over a hash. For any valid use of this macro to build 00784 * an algorithm \c alg, #PSA_ALG_IS_HASH_AND_SIGN(\c alg) is true. 00785 * 00786 * This value may not be used to build an algorithm specification to 00787 * perform an operation. It is only valid to build policies. 00788 */ 00789 #define PSA_ALG_ANY_HASH ((psa_algorithm_t)0x010000ff) 00790 00791 #define PSA_ALG_MAC_SUBCATEGORY_MASK ((psa_algorithm_t)0x00c00000) 00792 #define PSA_ALG_HMAC_BASE ((psa_algorithm_t)0x02800000) 00793 /** Macro to build an HMAC algorithm. 00794 * 00795 * For example, #PSA_ALG_HMAC(#PSA_ALG_SHA_256) is HMAC-SHA-256. 00796 * 00797 * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that 00798 * #PSA_ALG_IS_HASH(\p hash_alg) is true). 00799 * 00800 * \return The corresponding HMAC algorithm. 00801 * \return Unspecified if \p hash_alg is not a supported 00802 * hash algorithm. 00803 */ 00804 #define PSA_ALG_HMAC(hash_alg) \ 00805 (PSA_ALG_HMAC_BASE | ((hash_alg) & PSA_ALG_HASH_MASK)) 00806 00807 #define PSA_ALG_HMAC_GET_HASH(hmac_alg) \ 00808 (PSA_ALG_CATEGORY_HASH | ((hmac_alg) & PSA_ALG_HASH_MASK)) 00809 00810 /** Whether the specified algorithm is an HMAC algorithm. 00811 * 00812 * HMAC is a family of MAC algorithms that are based on a hash function. 00813 * 00814 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 00815 * 00816 * \return 1 if \p alg is an HMAC algorithm, 0 otherwise. 00817 * This macro may return either 0 or 1 if \p alg is not a supported 00818 * algorithm identifier. 00819 */ 00820 #define PSA_ALG_IS_HMAC(alg) \ 00821 (((alg) & (PSA_ALG_CATEGORY_MASK | PSA_ALG_MAC_SUBCATEGORY_MASK)) == \ 00822 PSA_ALG_HMAC_BASE) 00823 00824 /* In the encoding of a MAC algorithm, the bits corresponding to 00825 * PSA_ALG_MAC_TRUNCATION_MASK encode the length to which the MAC is 00826 * truncated. As an exception, the value 0 means the untruncated algorithm, 00827 * whatever its length is. The length is encoded in 6 bits, so it can 00828 * reach up to 63; the largest MAC is 64 bytes so its trivial truncation 00829 * to full length is correctly encoded as 0 and any non-trivial truncation 00830 * is correctly encoded as a value between 1 and 63. */ 00831 #define PSA_ALG_MAC_TRUNCATION_MASK ((psa_algorithm_t)0x00003f00) 00832 #define PSA_MAC_TRUNCATION_OFFSET 8 00833 00834 /** Macro to build a truncated MAC algorithm. 00835 * 00836 * A truncated MAC algorithm is identical to the corresponding MAC 00837 * algorithm except that the MAC value for the truncated algorithm 00838 * consists of only the first \p mac_length bytes of the MAC value 00839 * for the untruncated algorithm. 00840 * 00841 * \note This macro may allow constructing algorithm identifiers that 00842 * are not valid, either because the specified length is larger 00843 * than the untruncated MAC or because the specified length is 00844 * smaller than permitted by the implementation. 00845 * 00846 * \note It is implementation-defined whether a truncated MAC that 00847 * is truncated to the same length as the MAC of the untruncated 00848 * algorithm is considered identical to the untruncated algorithm 00849 * for policy comparison purposes. 00850 * 00851 * \param mac_alg A MAC algorithm identifier (value of type 00852 * #psa_algorithm_t such that #PSA_ALG_IS_MAC(\p alg) 00853 * is true). This may be a truncated or untruncated 00854 * MAC algorithm. 00855 * \param mac_length Desired length of the truncated MAC in bytes. 00856 * This must be at most the full length of the MAC 00857 * and must be at least an implementation-specified 00858 * minimum. The implementation-specified minimum 00859 * shall not be zero. 00860 * 00861 * \return The corresponding MAC algorithm with the specified 00862 * length. 00863 * \return Unspecified if \p alg is not a supported 00864 * MAC algorithm or if \p mac_length is too small or 00865 * too large for the specified MAC algorithm. 00866 */ 00867 #define PSA_ALG_TRUNCATED_MAC(mac_alg, mac_length) \ 00868 (((mac_alg) & ~PSA_ALG_MAC_TRUNCATION_MASK) | \ 00869 ((mac_length) << PSA_MAC_TRUNCATION_OFFSET & PSA_ALG_MAC_TRUNCATION_MASK)) 00870 00871 /** Macro to build the base MAC algorithm corresponding to a truncated 00872 * MAC algorithm. 00873 * 00874 * \param mac_alg A MAC algorithm identifier (value of type 00875 * #psa_algorithm_t such that #PSA_ALG_IS_MAC(\p alg) 00876 * is true). This may be a truncated or untruncated 00877 * MAC algorithm. 00878 * 00879 * \return The corresponding base MAC algorithm. 00880 * \return Unspecified if \p alg is not a supported 00881 * MAC algorithm. 00882 */ 00883 #define PSA_ALG_FULL_LENGTH_MAC(mac_alg) \ 00884 ((mac_alg) & ~PSA_ALG_MAC_TRUNCATION_MASK) 00885 00886 /** Length to which a MAC algorithm is truncated. 00887 * 00888 * \param mac_alg A MAC algorithm identifier (value of type 00889 * #psa_algorithm_t such that #PSA_ALG_IS_MAC(\p alg) 00890 * is true). 00891 * 00892 * \return Length of the truncated MAC in bytes. 00893 * \return 0 if \p alg is a non-truncated MAC algorithm. 00894 * \return Unspecified if \p alg is not a supported 00895 * MAC algorithm. 00896 */ 00897 #define PSA_MAC_TRUNCATED_LENGTH(mac_alg) \ 00898 (((mac_alg) & PSA_ALG_MAC_TRUNCATION_MASK) >> PSA_MAC_TRUNCATION_OFFSET) 00899 00900 #define PSA_ALG_CIPHER_MAC_BASE ((psa_algorithm_t)0x02c00000) 00901 /** The CBC-MAC construction over a block cipher 00902 * 00903 * \warning CBC-MAC is insecure in many cases. 00904 * A more secure mode, such as #PSA_ALG_CMAC, is recommended. 00905 */ 00906 #define PSA_ALG_CBC_MAC ((psa_algorithm_t)0x02c00001) 00907 /** The CMAC construction over a block cipher */ 00908 #define PSA_ALG_CMAC ((psa_algorithm_t)0x02c00002) 00909 00910 /** Whether the specified algorithm is a MAC algorithm based on a block cipher. 00911 * 00912 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 00913 * 00914 * \return 1 if \p alg is a MAC algorithm based on a block cipher, 0 otherwise. 00915 * This macro may return either 0 or 1 if \p alg is not a supported 00916 * algorithm identifier. 00917 */ 00918 #define PSA_ALG_IS_BLOCK_CIPHER_MAC(alg) \ 00919 (((alg) & (PSA_ALG_CATEGORY_MASK | PSA_ALG_MAC_SUBCATEGORY_MASK)) == \ 00920 PSA_ALG_CIPHER_MAC_BASE) 00921 00922 #define PSA_ALG_CIPHER_STREAM_FLAG ((psa_algorithm_t)0x00800000) 00923 #define PSA_ALG_CIPHER_FROM_BLOCK_FLAG ((psa_algorithm_t)0x00400000) 00924 00925 /** Whether the specified algorithm is a stream cipher. 00926 * 00927 * A stream cipher is a symmetric cipher that encrypts or decrypts messages 00928 * by applying a bitwise-xor with a stream of bytes that is generated 00929 * from a key. 00930 * 00931 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 00932 * 00933 * \return 1 if \p alg is a stream cipher algorithm, 0 otherwise. 00934 * This macro may return either 0 or 1 if \p alg is not a supported 00935 * algorithm identifier or if it is not a symmetric cipher algorithm. 00936 */ 00937 #define PSA_ALG_IS_STREAM_CIPHER(alg) \ 00938 (((alg) & (PSA_ALG_CATEGORY_MASK | PSA_ALG_CIPHER_STREAM_FLAG)) == \ 00939 (PSA_ALG_CATEGORY_CIPHER | PSA_ALG_CIPHER_STREAM_FLAG)) 00940 00941 /** The ARC4 stream cipher algorithm. 00942 */ 00943 #define PSA_ALG_ARC4 ((psa_algorithm_t)0x04800001) 00944 00945 /** The ChaCha20 stream cipher. 00946 * 00947 * ChaCha20 is defined in RFC 7539. 00948 * 00949 * The nonce size for psa_cipher_set_iv() or psa_cipher_generate_iv() 00950 * must be 12. 00951 * 00952 * The initial block counter is always 0. 00953 * 00954 */ 00955 #define PSA_ALG_CHACHA20 ((psa_algorithm_t)0x04800005) 00956 00957 /** The CTR stream cipher mode. 00958 * 00959 * CTR is a stream cipher which is built from a block cipher. 00960 * The underlying block cipher is determined by the key type. 00961 * For example, to use AES-128-CTR, use this algorithm with 00962 * a key of type #PSA_KEY_TYPE_AES and a length of 128 bits (16 bytes). 00963 */ 00964 #define PSA_ALG_CTR ((psa_algorithm_t)0x04c00001) 00965 00966 /** The CFB stream cipher mode. 00967 * 00968 * The underlying block cipher is determined by the key type. 00969 */ 00970 #define PSA_ALG_CFB ((psa_algorithm_t)0x04c00002) 00971 00972 /** The OFB stream cipher mode. 00973 * 00974 * The underlying block cipher is determined by the key type. 00975 */ 00976 #define PSA_ALG_OFB ((psa_algorithm_t)0x04c00003) 00977 00978 /** The XTS cipher mode. 00979 * 00980 * XTS is a cipher mode which is built from a block cipher. It requires at 00981 * least one full block of input, but beyond this minimum the input 00982 * does not need to be a whole number of blocks. 00983 */ 00984 #define PSA_ALG_XTS ((psa_algorithm_t)0x044000ff) 00985 00986 /** The CBC block cipher chaining mode, with no padding. 00987 * 00988 * The underlying block cipher is determined by the key type. 00989 * 00990 * This symmetric cipher mode can only be used with messages whose lengths 00991 * are whole number of blocks for the chosen block cipher. 00992 */ 00993 #define PSA_ALG_CBC_NO_PADDING ((psa_algorithm_t)0x04600100) 00994 00995 /** The CBC block cipher chaining mode with PKCS#7 padding. 00996 * 00997 * The underlying block cipher is determined by the key type. 00998 * 00999 * This is the padding method defined by PKCS#7 (RFC 2315) §10.3. 01000 */ 01001 #define PSA_ALG_CBC_PKCS7 ((psa_algorithm_t)0x04600101) 01002 01003 #define PSA_ALG_AEAD_FROM_BLOCK_FLAG ((psa_algorithm_t)0x00400000) 01004 01005 /** Whether the specified algorithm is an AEAD mode on a block cipher. 01006 * 01007 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 01008 * 01009 * \return 1 if \p alg is an AEAD algorithm which is an AEAD mode based on 01010 * a block cipher, 0 otherwise. 01011 * This macro may return either 0 or 1 if \p alg is not a supported 01012 * algorithm identifier. 01013 */ 01014 #define PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER(alg) \ 01015 (((alg) & (PSA_ALG_CATEGORY_MASK | PSA_ALG_AEAD_FROM_BLOCK_FLAG)) == \ 01016 (PSA_ALG_CATEGORY_AEAD | PSA_ALG_AEAD_FROM_BLOCK_FLAG)) 01017 01018 /** The CCM authenticated encryption algorithm. 01019 * 01020 * The underlying block cipher is determined by the key type. 01021 */ 01022 #define PSA_ALG_CCM ((psa_algorithm_t)0x06401001) 01023 01024 /** The GCM authenticated encryption algorithm. 01025 * 01026 * The underlying block cipher is determined by the key type. 01027 */ 01028 #define PSA_ALG_GCM ((psa_algorithm_t)0x06401002) 01029 01030 /** The Chacha20-Poly1305 AEAD algorithm. 01031 * 01032 * The ChaCha20_Poly1305 construction is defined in RFC 7539. 01033 * 01034 * Implementations must support 12-byte nonces, may support 8-byte nonces, 01035 * and should reject other sizes. 01036 * 01037 * Implementations must support 16-byte tags and should reject other sizes. 01038 */ 01039 #define PSA_ALG_CHACHA20_POLY1305 ((psa_algorithm_t)0x06001005) 01040 01041 /* In the encoding of a AEAD algorithm, the bits corresponding to 01042 * PSA_ALG_AEAD_TAG_LENGTH_MASK encode the length of the AEAD tag. 01043 * The constants for default lengths follow this encoding. 01044 */ 01045 #define PSA_ALG_AEAD_TAG_LENGTH_MASK ((psa_algorithm_t)0x00003f00) 01046 #define PSA_AEAD_TAG_LENGTH_OFFSET 8 01047 01048 /** Macro to build a shortened AEAD algorithm. 01049 * 01050 * A shortened AEAD algorithm is similar to the corresponding AEAD 01051 * algorithm, but has an authentication tag that consists of fewer bytes. 01052 * Depending on the algorithm, the tag length may affect the calculation 01053 * of the ciphertext. 01054 * 01055 * \param aead_alg An AEAD algorithm identifier (value of type 01056 * #psa_algorithm_t such that #PSA_ALG_IS_AEAD(\p alg) 01057 * is true). 01058 * \param tag_length Desired length of the authentication tag in bytes. 01059 * 01060 * \return The corresponding AEAD algorithm with the specified 01061 * length. 01062 * \return Unspecified if \p alg is not a supported 01063 * AEAD algorithm or if \p tag_length is not valid 01064 * for the specified AEAD algorithm. 01065 */ 01066 #define PSA_ALG_AEAD_WITH_TAG_LENGTH(aead_alg, tag_length) \ 01067 (((aead_alg) & ~PSA_ALG_AEAD_TAG_LENGTH_MASK) | \ 01068 ((tag_length) << PSA_AEAD_TAG_LENGTH_OFFSET & \ 01069 PSA_ALG_AEAD_TAG_LENGTH_MASK)) 01070 01071 /** Calculate the corresponding AEAD algorithm with the default tag length. 01072 * 01073 * \param aead_alg An AEAD algorithm (\c PSA_ALG_XXX value such that 01074 * #PSA_ALG_IS_AEAD(\p alg) is true). 01075 * 01076 * \return The corresponding AEAD algorithm with the default 01077 * tag length for that algorithm. 01078 */ 01079 #define PSA_ALG_AEAD_WITH_DEFAULT_TAG_LENGTH(aead_alg) \ 01080 ( \ 01081 PSA_ALG_AEAD_WITH_DEFAULT_TAG_LENGTH_CASE(aead_alg, PSA_ALG_CCM) \ 01082 PSA_ALG_AEAD_WITH_DEFAULT_TAG_LENGTH_CASE(aead_alg, PSA_ALG_GCM) \ 01083 PSA_ALG_AEAD_WITH_DEFAULT_TAG_LENGTH_CASE(aead_alg, PSA_ALG_CHACHA20_POLY1305) \ 01084 0) 01085 #define PSA_ALG_AEAD_WITH_DEFAULT_TAG_LENGTH_CASE(aead_alg, ref) \ 01086 PSA_ALG_AEAD_WITH_TAG_LENGTH(aead_alg, 0) == \ 01087 PSA_ALG_AEAD_WITH_TAG_LENGTH(ref, 0) ? \ 01088 ref : 01089 01090 #define PSA_ALG_RSA_PKCS1V15_SIGN_BASE ((psa_algorithm_t)0x10020000) 01091 /** RSA PKCS#1 v1.5 signature with hashing. 01092 * 01093 * This is the signature scheme defined by RFC 8017 01094 * (PKCS#1: RSA Cryptography Specifications) under the name 01095 * RSASSA-PKCS1-v1_5. 01096 * 01097 * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that 01098 * #PSA_ALG_IS_HASH(\p hash_alg) is true). 01099 * This includes #PSA_ALG_ANY_HASH 01100 * when specifying the algorithm in a usage policy. 01101 * 01102 * \return The corresponding RSA PKCS#1 v1.5 signature algorithm. 01103 * \return Unspecified if \p hash_alg is not a supported 01104 * hash algorithm. 01105 */ 01106 #define PSA_ALG_RSA_PKCS1V15_SIGN(hash_alg) \ 01107 (PSA_ALG_RSA_PKCS1V15_SIGN_BASE | ((hash_alg) & PSA_ALG_HASH_MASK)) 01108 /** Raw PKCS#1 v1.5 signature. 01109 * 01110 * The input to this algorithm is the DigestInfo structure used by 01111 * RFC 8017 (PKCS#1: RSA Cryptography Specifications), §9.2 01112 * steps 3–6. 01113 */ 01114 #define PSA_ALG_RSA_PKCS1V15_SIGN_RAW PSA_ALG_RSA_PKCS1V15_SIGN_BASE 01115 #define PSA_ALG_IS_RSA_PKCS1V15_SIGN(alg) \ 01116 (((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_RSA_PKCS1V15_SIGN_BASE) 01117 01118 #define PSA_ALG_RSA_PSS_BASE ((psa_algorithm_t)0x10030000) 01119 /** RSA PSS signature with hashing. 01120 * 01121 * This is the signature scheme defined by RFC 8017 01122 * (PKCS#1: RSA Cryptography Specifications) under the name 01123 * RSASSA-PSS, with the message generation function MGF1, and with 01124 * a salt length equal to the length of the hash. The specified 01125 * hash algorithm is used to hash the input message, to create the 01126 * salted hash, and for the mask generation. 01127 * 01128 * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that 01129 * #PSA_ALG_IS_HASH(\p hash_alg) is true). 01130 * This includes #PSA_ALG_ANY_HASH 01131 * when specifying the algorithm in a usage policy. 01132 * 01133 * \return The corresponding RSA PSS signature algorithm. 01134 * \return Unspecified if \p hash_alg is not a supported 01135 * hash algorithm. 01136 */ 01137 #define PSA_ALG_RSA_PSS(hash_alg) \ 01138 (PSA_ALG_RSA_PSS_BASE | ((hash_alg) & PSA_ALG_HASH_MASK)) 01139 #define PSA_ALG_IS_RSA_PSS(alg) \ 01140 (((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_RSA_PSS_BASE) 01141 01142 #define PSA_ALG_ECDSA_BASE ((psa_algorithm_t)0x10060000) 01143 /** ECDSA signature with hashing. 01144 * 01145 * This is the ECDSA signature scheme defined by ANSI X9.62, 01146 * with a random per-message secret number (*k*). 01147 * 01148 * The representation of the signature as a byte string consists of 01149 * the concatentation of the signature values *r* and *s*. Each of 01150 * *r* and *s* is encoded as an *N*-octet string, where *N* is the length 01151 * of the base point of the curve in octets. Each value is represented 01152 * in big-endian order (most significant octet first). 01153 * 01154 * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that 01155 * #PSA_ALG_IS_HASH(\p hash_alg) is true). 01156 * This includes #PSA_ALG_ANY_HASH 01157 * when specifying the algorithm in a usage policy. 01158 * 01159 * \return The corresponding ECDSA signature algorithm. 01160 * \return Unspecified if \p hash_alg is not a supported 01161 * hash algorithm. 01162 */ 01163 #define PSA_ALG_ECDSA(hash_alg) \ 01164 (PSA_ALG_ECDSA_BASE | ((hash_alg) & PSA_ALG_HASH_MASK)) 01165 /** ECDSA signature without hashing. 01166 * 01167 * This is the same signature scheme as #PSA_ALG_ECDSA(), but 01168 * without specifying a hash algorithm. This algorithm may only be 01169 * used to sign or verify a sequence of bytes that should be an 01170 * already-calculated hash. Note that the input is padded with 01171 * zeros on the left or truncated on the left as required to fit 01172 * the curve size. 01173 */ 01174 #define PSA_ALG_ECDSA_ANY PSA_ALG_ECDSA_BASE 01175 #define PSA_ALG_DETERMINISTIC_ECDSA_BASE ((psa_algorithm_t)0x10070000) 01176 /** Deterministic ECDSA signature with hashing. 01177 * 01178 * This is the deterministic ECDSA signature scheme defined by RFC 6979. 01179 * 01180 * The representation of a signature is the same as with #PSA_ALG_ECDSA(). 01181 * 01182 * Note that when this algorithm is used for verification, signatures 01183 * made with randomized ECDSA (#PSA_ALG_ECDSA(\p hash_alg)) with the 01184 * same private key are accepted. In other words, 01185 * #PSA_ALG_DETERMINISTIC_ECDSA(\p hash_alg) differs from 01186 * #PSA_ALG_ECDSA(\p hash_alg) only for signature, not for verification. 01187 * 01188 * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that 01189 * #PSA_ALG_IS_HASH(\p hash_alg) is true). 01190 * This includes #PSA_ALG_ANY_HASH 01191 * when specifying the algorithm in a usage policy. 01192 * 01193 * \return The corresponding deterministic ECDSA signature 01194 * algorithm. 01195 * \return Unspecified if \p hash_alg is not a supported 01196 * hash algorithm. 01197 */ 01198 #define PSA_ALG_DETERMINISTIC_ECDSA(hash_alg) \ 01199 (PSA_ALG_DETERMINISTIC_ECDSA_BASE | ((hash_alg) & PSA_ALG_HASH_MASK)) 01200 #define PSA_ALG_IS_ECDSA(alg) \ 01201 (((alg) & ~PSA_ALG_HASH_MASK & ~PSA_ALG_DSA_DETERMINISTIC_FLAG) == \ 01202 PSA_ALG_ECDSA_BASE) 01203 #define PSA_ALG_ECDSA_IS_DETERMINISTIC(alg) \ 01204 (((alg) & PSA_ALG_DSA_DETERMINISTIC_FLAG) != 0) 01205 #define PSA_ALG_IS_DETERMINISTIC_ECDSA(alg) \ 01206 (PSA_ALG_IS_ECDSA(alg) && PSA_ALG_ECDSA_IS_DETERMINISTIC(alg)) 01207 #define PSA_ALG_IS_RANDOMIZED_ECDSA(alg) \ 01208 (PSA_ALG_IS_ECDSA(alg) && !PSA_ALG_ECDSA_IS_DETERMINISTIC(alg)) 01209 01210 /** Whether the specified algorithm is a hash-and-sign algorithm. 01211 * 01212 * Hash-and-sign algorithms are public-key signature algorithms structured 01213 * in two parts: first the calculation of a hash in a way that does not 01214 * depend on the key, then the calculation of a signature from the 01215 * hash value and the key. 01216 * 01217 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 01218 * 01219 * \return 1 if \p alg is a hash-and-sign algorithm, 0 otherwise. 01220 * This macro may return either 0 or 1 if \p alg is not a supported 01221 * algorithm identifier. 01222 */ 01223 #define PSA_ALG_IS_HASH_AND_SIGN(alg) \ 01224 (PSA_ALG_IS_RSA_PSS(alg) || PSA_ALG_IS_RSA_PKCS1V15_SIGN(alg) || \ 01225 PSA_ALG_IS_ECDSA(alg)) 01226 01227 /** Get the hash used by a hash-and-sign signature algorithm. 01228 * 01229 * A hash-and-sign algorithm is a signature algorithm which is 01230 * composed of two phases: first a hashing phase which does not use 01231 * the key and produces a hash of the input message, then a signing 01232 * phase which only uses the hash and the key and not the message 01233 * itself. 01234 * 01235 * \param alg A signature algorithm (\c PSA_ALG_XXX value such that 01236 * #PSA_ALG_IS_SIGN(\p alg) is true). 01237 * 01238 * \return The underlying hash algorithm if \p alg is a hash-and-sign 01239 * algorithm. 01240 * \return 0 if \p alg is a signature algorithm that does not 01241 * follow the hash-and-sign structure. 01242 * \return Unspecified if \p alg is not a signature algorithm or 01243 * if it is not supported by the implementation. 01244 */ 01245 #define PSA_ALG_SIGN_GET_HASH(alg) \ 01246 (PSA_ALG_IS_HASH_AND_SIGN(alg) ? \ 01247 ((alg) & PSA_ALG_HASH_MASK) == 0 ? /*"raw" algorithm*/ 0 : \ 01248 ((alg) & PSA_ALG_HASH_MASK) | PSA_ALG_CATEGORY_HASH : \ 01249 0) 01250 01251 /** RSA PKCS#1 v1.5 encryption. 01252 */ 01253 #define PSA_ALG_RSA_PKCS1V15_CRYPT ((psa_algorithm_t)0x12020000) 01254 01255 #define PSA_ALG_RSA_OAEP_BASE ((psa_algorithm_t)0x12030000) 01256 /** RSA OAEP encryption. 01257 * 01258 * This is the encryption scheme defined by RFC 8017 01259 * (PKCS#1: RSA Cryptography Specifications) under the name 01260 * RSAES-OAEP, with the message generation function MGF1. 01261 * 01262 * \param hash_alg The hash algorithm (\c PSA_ALG_XXX value such that 01263 * #PSA_ALG_IS_HASH(\p hash_alg) is true) to use 01264 * for MGF1. 01265 * 01266 * \return The corresponding RSA OAEP signature algorithm. 01267 * \return Unspecified if \p hash_alg is not a supported 01268 * hash algorithm. 01269 */ 01270 #define PSA_ALG_RSA_OAEP(hash_alg) \ 01271 (PSA_ALG_RSA_OAEP_BASE | ((hash_alg) & PSA_ALG_HASH_MASK)) 01272 #define PSA_ALG_IS_RSA_OAEP(alg) \ 01273 (((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_RSA_OAEP_BASE) 01274 #define PSA_ALG_RSA_OAEP_GET_HASH(alg) \ 01275 (PSA_ALG_IS_RSA_OAEP(alg) ? \ 01276 ((alg) & PSA_ALG_HASH_MASK) | PSA_ALG_CATEGORY_HASH : \ 01277 0) 01278 01279 #define PSA_ALG_HKDF_BASE ((psa_algorithm_t)0x20000100) 01280 /** Macro to build an HKDF algorithm. 01281 * 01282 * For example, `PSA_ALG_HKDF(PSA_ALG_SHA256)` is HKDF using HMAC-SHA-256. 01283 * 01284 * This key derivation algorithm uses the following inputs: 01285 * - #PSA_KEY_DERIVATION_INPUT_SALT is the salt used in the "extract" step. 01286 * It is optional; if omitted, the derivation uses an empty salt. 01287 * - #PSA_KEY_DERIVATION_INPUT_SECRET is the secret key used in the "extract" step. 01288 * - #PSA_KEY_DERIVATION_INPUT_INFO is the info string used in the "expand" step. 01289 * You must pass #PSA_KEY_DERIVATION_INPUT_SALT before #PSA_KEY_DERIVATION_INPUT_SECRET. 01290 * You may pass #PSA_KEY_DERIVATION_INPUT_INFO at any time after steup and before 01291 * starting to generate output. 01292 * 01293 * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that 01294 * #PSA_ALG_IS_HASH(\p hash_alg) is true). 01295 * 01296 * \return The corresponding HKDF algorithm. 01297 * \return Unspecified if \p hash_alg is not a supported 01298 * hash algorithm. 01299 */ 01300 #define PSA_ALG_HKDF(hash_alg) \ 01301 (PSA_ALG_HKDF_BASE | ((hash_alg) & PSA_ALG_HASH_MASK)) 01302 /** Whether the specified algorithm is an HKDF algorithm. 01303 * 01304 * HKDF is a family of key derivation algorithms that are based on a hash 01305 * function and the HMAC construction. 01306 * 01307 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 01308 * 01309 * \return 1 if \c alg is an HKDF algorithm, 0 otherwise. 01310 * This macro may return either 0 or 1 if \c alg is not a supported 01311 * key derivation algorithm identifier. 01312 */ 01313 #define PSA_ALG_IS_HKDF(alg) \ 01314 (((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_HKDF_BASE) 01315 #define PSA_ALG_HKDF_GET_HASH(hkdf_alg) \ 01316 (PSA_ALG_CATEGORY_HASH | ((hkdf_alg) & PSA_ALG_HASH_MASK)) 01317 01318 #define PSA_ALG_TLS12_PRF_BASE ((psa_algorithm_t)0x20000200) 01319 /** Macro to build a TLS-1.2 PRF algorithm. 01320 * 01321 * TLS 1.2 uses a custom pseudorandom function (PRF) for key schedule, 01322 * specified in Section 5 of RFC 5246. It is based on HMAC and can be 01323 * used with either SHA-256 or SHA-384. 01324 * 01325 * This key derivation algorithm uses the following inputs, which must be 01326 * passed in the order given here: 01327 * - #PSA_KEY_DERIVATION_INPUT_SEED is the seed. 01328 * - #PSA_KEY_DERIVATION_INPUT_SECRET is the secret key. 01329 * - #PSA_KEY_DERIVATION_INPUT_LABEL is the label. 01330 * 01331 * For the application to TLS-1.2 key expansion, the seed is the 01332 * concatenation of ServerHello.Random + ClientHello.Random, 01333 * and the label is "key expansion". 01334 * 01335 * For example, `PSA_ALG_TLS12_PRF(PSA_ALG_SHA256)` represents the 01336 * TLS 1.2 PRF using HMAC-SHA-256. 01337 * 01338 * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that 01339 * #PSA_ALG_IS_HASH(\p hash_alg) is true). 01340 * 01341 * \return The corresponding TLS-1.2 PRF algorithm. 01342 * \return Unspecified if \p hash_alg is not a supported 01343 * hash algorithm. 01344 */ 01345 #define PSA_ALG_TLS12_PRF(hash_alg) \ 01346 (PSA_ALG_TLS12_PRF_BASE | ((hash_alg) & PSA_ALG_HASH_MASK)) 01347 01348 /** Whether the specified algorithm is a TLS-1.2 PRF algorithm. 01349 * 01350 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 01351 * 01352 * \return 1 if \c alg is a TLS-1.2 PRF algorithm, 0 otherwise. 01353 * This macro may return either 0 or 1 if \c alg is not a supported 01354 * key derivation algorithm identifier. 01355 */ 01356 #define PSA_ALG_IS_TLS12_PRF(alg) \ 01357 (((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_TLS12_PRF_BASE) 01358 #define PSA_ALG_TLS12_PRF_GET_HASH(hkdf_alg) \ 01359 (PSA_ALG_CATEGORY_HASH | ((hkdf_alg) & PSA_ALG_HASH_MASK)) 01360 01361 #define PSA_ALG_TLS12_PSK_TO_MS_BASE ((psa_algorithm_t)0x20000300) 01362 /** Macro to build a TLS-1.2 PSK-to-MasterSecret algorithm. 01363 * 01364 * In a pure-PSK handshake in TLS 1.2, the master secret is derived 01365 * from the PreSharedKey (PSK) through the application of padding 01366 * (RFC 4279, Section 2) and the TLS-1.2 PRF (RFC 5246, Section 5). 01367 * The latter is based on HMAC and can be used with either SHA-256 01368 * or SHA-384. 01369 * 01370 * This key derivation algorithm uses the following inputs, which must be 01371 * passed in the order given here: 01372 * - #PSA_KEY_DERIVATION_INPUT_SEED is the seed. 01373 * - #PSA_KEY_DERIVATION_INPUT_SECRET is the secret key. 01374 * - #PSA_KEY_DERIVATION_INPUT_LABEL is the label. 01375 * 01376 * For the application to TLS-1.2, the seed (which is 01377 * forwarded to the TLS-1.2 PRF) is the concatenation of the 01378 * ClientHello.Random + ServerHello.Random, 01379 * and the label is "master secret" or "extended master secret". 01380 * 01381 * For example, `PSA_ALG_TLS12_PSK_TO_MS(PSA_ALG_SHA256)` represents the 01382 * TLS-1.2 PSK to MasterSecret derivation PRF using HMAC-SHA-256. 01383 * 01384 * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that 01385 * #PSA_ALG_IS_HASH(\p hash_alg) is true). 01386 * 01387 * \return The corresponding TLS-1.2 PSK to MS algorithm. 01388 * \return Unspecified if \p hash_alg is not a supported 01389 * hash algorithm. 01390 */ 01391 #define PSA_ALG_TLS12_PSK_TO_MS(hash_alg) \ 01392 (PSA_ALG_TLS12_PSK_TO_MS_BASE | ((hash_alg) & PSA_ALG_HASH_MASK)) 01393 01394 /** Whether the specified algorithm is a TLS-1.2 PSK to MS algorithm. 01395 * 01396 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 01397 * 01398 * \return 1 if \c alg is a TLS-1.2 PSK to MS algorithm, 0 otherwise. 01399 * This macro may return either 0 or 1 if \c alg is not a supported 01400 * key derivation algorithm identifier. 01401 */ 01402 #define PSA_ALG_IS_TLS12_PSK_TO_MS(alg) \ 01403 (((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_TLS12_PSK_TO_MS_BASE) 01404 #define PSA_ALG_TLS12_PSK_TO_MS_GET_HASH(hkdf_alg) \ 01405 (PSA_ALG_CATEGORY_HASH | ((hkdf_alg) & PSA_ALG_HASH_MASK)) 01406 01407 #define PSA_ALG_KEY_DERIVATION_MASK ((psa_algorithm_t)0x0803ffff) 01408 #define PSA_ALG_KEY_AGREEMENT_MASK ((psa_algorithm_t)0x10fc0000) 01409 01410 /** Macro to build a combined algorithm that chains a key agreement with 01411 * a key derivation. 01412 * 01413 * \param ka_alg A key agreement algorithm (\c PSA_ALG_XXX value such 01414 * that #PSA_ALG_IS_KEY_AGREEMENT(\p ka_alg) is true). 01415 * \param kdf_alg A key derivation algorithm (\c PSA_ALG_XXX value such 01416 * that #PSA_ALG_IS_KEY_DERIVATION(\p kdf_alg) is true). 01417 * 01418 * \return The corresponding key agreement and derivation 01419 * algorithm. 01420 * \return Unspecified if \p ka_alg is not a supported 01421 * key agreement algorithm or \p kdf_alg is not a 01422 * supported key derivation algorithm. 01423 */ 01424 #define PSA_ALG_KEY_AGREEMENT(ka_alg, kdf_alg) \ 01425 ((ka_alg) | (kdf_alg)) 01426 01427 #define PSA_ALG_KEY_AGREEMENT_GET_KDF(alg) \ 01428 (((alg) & PSA_ALG_KEY_DERIVATION_MASK) | PSA_ALG_CATEGORY_KEY_DERIVATION) 01429 01430 #define PSA_ALG_KEY_AGREEMENT_GET_BASE(alg) \ 01431 (((alg) & PSA_ALG_KEY_AGREEMENT_MASK) | PSA_ALG_CATEGORY_KEY_AGREEMENT) 01432 01433 /** Whether the specified algorithm is a raw key agreement algorithm. 01434 * 01435 * A raw key agreement algorithm is one that does not specify 01436 * a key derivation function. 01437 * Usually, raw key agreement algorithms are constructed directly with 01438 * a \c PSA_ALG_xxx macro while non-raw key agreement algorithms are 01439 * constructed with PSA_ALG_KEY_AGREEMENT(). 01440 * 01441 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 01442 * 01443 * \return 1 if \p alg is a raw key agreement algorithm, 0 otherwise. 01444 * This macro may return either 0 or 1 if \p alg is not a supported 01445 * algorithm identifier. 01446 */ 01447 #define PSA_ALG_IS_RAW_KEY_AGREEMENT(alg) \ 01448 (PSA_ALG_IS_KEY_AGREEMENT(alg) && \ 01449 PSA_ALG_KEY_AGREEMENT_GET_KDF(alg) == PSA_ALG_CATEGORY_KEY_DERIVATION) 01450 01451 #define PSA_ALG_IS_KEY_DERIVATION_OR_AGREEMENT(alg) \ 01452 ((PSA_ALG_IS_KEY_DERIVATION(alg) || PSA_ALG_IS_KEY_AGREEMENT(alg))) 01453 01454 /** The finite-field Diffie-Hellman (DH) key agreement algorithm. 01455 * 01456 * The shared secret produced by key agreement is 01457 * `g^{ab}` in big-endian format. 01458 * It is `ceiling(m / 8)` bytes long where `m` is the size of the prime `p` 01459 * in bits. 01460 */ 01461 #define PSA_ALG_FFDH ((psa_algorithm_t)0x30100000) 01462 01463 /** Whether the specified algorithm is a finite field Diffie-Hellman algorithm. 01464 * 01465 * This includes the raw finite field Diffie-Hellman algorithm as well as 01466 * finite-field Diffie-Hellman followed by any supporter key derivation 01467 * algorithm. 01468 * 01469 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 01470 * 01471 * \return 1 if \c alg is a finite field Diffie-Hellman algorithm, 0 otherwise. 01472 * This macro may return either 0 or 1 if \c alg is not a supported 01473 * key agreement algorithm identifier. 01474 */ 01475 #define PSA_ALG_IS_FFDH(alg) \ 01476 (PSA_ALG_KEY_AGREEMENT_GET_BASE(alg) == PSA_ALG_FFDH) 01477 01478 /** The elliptic curve Diffie-Hellman (ECDH) key agreement algorithm. 01479 * 01480 * The shared secret produced by key agreement is the x-coordinate of 01481 * the shared secret point. It is always `ceiling(m / 8)` bytes long where 01482 * `m` is the bit size associated with the curve, i.e. the bit size of the 01483 * order of the curve's coordinate field. When `m` is not a multiple of 8, 01484 * the byte containing the most significant bit of the shared secret 01485 * is padded with zero bits. The byte order is either little-endian 01486 * or big-endian depending on the curve type. 01487 * 01488 * - For Montgomery curves (curve types `PSA_ECC_CURVE_CURVEXXX`), 01489 * the shared secret is the x-coordinate of `d_A Q_B = d_B Q_A` 01490 * in little-endian byte order. 01491 * The bit size is 448 for Curve448 and 255 for Curve25519. 01492 * - For Weierstrass curves over prime fields (curve types 01493 * `PSA_ECC_CURVE_SECPXXX` and `PSA_ECC_CURVE_BRAINPOOL_PXXX`), 01494 * the shared secret is the x-coordinate of `d_A Q_B = d_B Q_A` 01495 * in big-endian byte order. 01496 * The bit size is `m = ceiling(log_2(p))` for the field `F_p`. 01497 * - For Weierstrass curves over binary fields (curve types 01498 * `PSA_ECC_CURVE_SECTXXX`), 01499 * the shared secret is the x-coordinate of `d_A Q_B = d_B Q_A` 01500 * in big-endian byte order. 01501 * The bit size is `m` for the field `F_{2^m}`. 01502 */ 01503 #define PSA_ALG_ECDH ((psa_algorithm_t)0x30200000) 01504 01505 /** Whether the specified algorithm is an elliptic curve Diffie-Hellman 01506 * algorithm. 01507 * 01508 * This includes the raw elliptic curve Diffie-Hellman algorithm as well as 01509 * elliptic curve Diffie-Hellman followed by any supporter key derivation 01510 * algorithm. 01511 * 01512 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 01513 * 01514 * \return 1 if \c alg is an elliptic curve Diffie-Hellman algorithm, 01515 * 0 otherwise. 01516 * This macro may return either 0 or 1 if \c alg is not a supported 01517 * key agreement algorithm identifier. 01518 */ 01519 #define PSA_ALG_IS_ECDH(alg) \ 01520 (PSA_ALG_KEY_AGREEMENT_GET_BASE(alg) == PSA_ALG_ECDH) 01521 01522 /** Whether the specified algorithm encoding is a wildcard. 01523 * 01524 * Wildcard values may only be used to set the usage algorithm field in 01525 * a policy, not to perform an operation. 01526 * 01527 * \param alg An algorithm identifier (value of type #psa_algorithm_t). 01528 * 01529 * \return 1 if \c alg is a wildcard algorithm encoding. 01530 * \return 0 if \c alg is a non-wildcard algorithm encoding (suitable for 01531 * an operation). 01532 * \return This macro may return either 0 or 1 if \c alg is not a supported 01533 * algorithm identifier. 01534 */ 01535 #define PSA_ALG_IS_WILDCARD(alg) \ 01536 (PSA_ALG_IS_HASH_AND_SIGN(alg) ? \ 01537 PSA_ALG_SIGN_GET_HASH(alg) == PSA_ALG_ANY_HASH : \ 01538 (alg) == PSA_ALG_ANY_HASH) 01539 01540 /**@}*/ 01541 01542 /** \defgroup key_lifetimes Key lifetimes 01543 * @{ 01544 */ 01545 01546 /** A volatile key only exists as long as the handle to it is not closed. 01547 * The key material is guaranteed to be erased on a power reset. 01548 */ 01549 #define PSA_KEY_LIFETIME_VOLATILE ((psa_key_lifetime_t)0x00000000) 01550 01551 /** The default storage area for persistent keys. 01552 * 01553 * A persistent key remains in storage until it is explicitly destroyed or 01554 * until the corresponding storage area is wiped. This specification does 01555 * not define any mechanism to wipe a storage area, but implementations may 01556 * provide their own mechanism (for example to perform a factory reset, 01557 * to prepare for device refurbishment, or to uninstall an application). 01558 * 01559 * This lifetime value is the default storage area for the calling 01560 * application. Implementations may offer other storage areas designated 01561 * by other lifetime values as implementation-specific extensions. 01562 */ 01563 #define PSA_KEY_LIFETIME_PERSISTENT ((psa_key_lifetime_t)0x00000001) 01564 01565 /** The minimum value for a key identifier chosen by the application. 01566 */ 01567 #define PSA_KEY_ID_USER_MIN ((psa_app_key_id_t)0x00000001) 01568 /** The maximum value for a key identifier chosen by the application. 01569 */ 01570 #define PSA_KEY_ID_USER_MAX ((psa_app_key_id_t)0x3fffffff) 01571 /** The minimum value for a key identifier chosen by the implementation. 01572 */ 01573 #define PSA_KEY_ID_VENDOR_MIN ((psa_app_key_id_t)0x40000000) 01574 /** The maximum value for a key identifier chosen by the implementation. 01575 */ 01576 #define PSA_KEY_ID_VENDOR_MAX ((psa_app_key_id_t)0x7fffffff) 01577 01578 /**@}*/ 01579 01580 /** \defgroup policy Key policies 01581 * @{ 01582 */ 01583 01584 /** Whether the key may be exported. 01585 * 01586 * A public key or the public part of a key pair may always be exported 01587 * regardless of the value of this permission flag. 01588 * 01589 * If a key does not have export permission, implementations shall not 01590 * allow the key to be exported in plain form from the cryptoprocessor, 01591 * whether through psa_export_key() or through a proprietary interface. 01592 * The key may however be exportable in a wrapped form, i.e. in a form 01593 * where it is encrypted by another key. 01594 */ 01595 #define PSA_KEY_USAGE_EXPORT ((psa_key_usage_t)0x00000001) 01596 01597 /** Whether the key may be copied. 01598 * 01599 * This flag allows the use of psa_copy_key() to make a copy of the key 01600 * with the same policy or a more restrictive policy. 01601 * 01602 * For lifetimes for which the key is located in a secure element which 01603 * enforce the non-exportability of keys, copying a key outside the secure 01604 * element also requires the usage flag #PSA_KEY_USAGE_EXPORT. 01605 * Copying the key inside the secure element is permitted with just 01606 * #PSA_KEY_USAGE_COPY if the secure element supports it. 01607 * For keys with the lifetime #PSA_KEY_LIFETIME_VOLATILE or 01608 * #PSA_KEY_LIFETIME_PERSISTENT, the usage flag #PSA_KEY_USAGE_COPY 01609 * is sufficient to permit the copy. 01610 */ 01611 #define PSA_KEY_USAGE_COPY ((psa_key_usage_t)0x00000002) 01612 01613 /** Whether the key may be used to encrypt a message. 01614 * 01615 * This flag allows the key to be used for a symmetric encryption operation, 01616 * for an AEAD encryption-and-authentication operation, 01617 * or for an asymmetric encryption operation, 01618 * if otherwise permitted by the key's type and policy. 01619 * 01620 * For a key pair, this concerns the public key. 01621 */ 01622 #define PSA_KEY_USAGE_ENCRYPT ((psa_key_usage_t)0x00000100) 01623 01624 /** Whether the key may be used to decrypt a message. 01625 * 01626 * This flag allows the key to be used for a symmetric decryption operation, 01627 * for an AEAD decryption-and-verification operation, 01628 * or for an asymmetric decryption operation, 01629 * if otherwise permitted by the key's type and policy. 01630 * 01631 * For a key pair, this concerns the private key. 01632 */ 01633 #define PSA_KEY_USAGE_DECRYPT ((psa_key_usage_t)0x00000200) 01634 01635 /** Whether the key may be used to sign a message. 01636 * 01637 * This flag allows the key to be used for a MAC calculation operation 01638 * or for an asymmetric signature operation, 01639 * if otherwise permitted by the key's type and policy. 01640 * 01641 * For a key pair, this concerns the private key. 01642 */ 01643 #define PSA_KEY_USAGE_SIGN ((psa_key_usage_t)0x00000400) 01644 01645 /** Whether the key may be used to verify a message signature. 01646 * 01647 * This flag allows the key to be used for a MAC verification operation 01648 * or for an asymmetric signature verification operation, 01649 * if otherwise permitted by by the key's type and policy. 01650 * 01651 * For a key pair, this concerns the public key. 01652 */ 01653 #define PSA_KEY_USAGE_VERIFY ((psa_key_usage_t)0x00000800) 01654 01655 /** Whether the key may be used to derive other keys. 01656 */ 01657 #define PSA_KEY_USAGE_DERIVE ((psa_key_usage_t)0x00001000) 01658 01659 /**@}*/ 01660 01661 /** \defgroup derivation Key derivation 01662 * @{ 01663 */ 01664 01665 /** A secret input for key derivation. 01666 * 01667 * This should be a key of type #PSA_KEY_TYPE_DERIVE 01668 * (passed to psa_key_derivation_input_key()) 01669 * or the shared secret resulting from a key agreement 01670 * (obtained via psa_key_derivation_key_agreement()). 01671 * 01672 * The secret can also be a direct input (passed to 01673 * key_derivation_input_bytes()). In this case, the derivation operation 01674 * may not be used to derive keys: the operation will only allow 01675 * psa_key_derivation_output_bytes(), not psa_key_derivation_output_key(). 01676 */ 01677 #define PSA_KEY_DERIVATION_INPUT_SECRET ((psa_key_derivation_step_t)0x0101) 01678 01679 /** A label for key derivation. 01680 * 01681 * This should be a direct input. 01682 * It can also be a key of type #PSA_KEY_TYPE_RAW_DATA. 01683 */ 01684 #define PSA_KEY_DERIVATION_INPUT_LABEL ((psa_key_derivation_step_t)0x0201) 01685 01686 /** A salt for key derivation. 01687 * 01688 * This should be a direct input. 01689 * It can also be a key of type #PSA_KEY_TYPE_RAW_DATA. 01690 */ 01691 #define PSA_KEY_DERIVATION_INPUT_SALT ((psa_key_derivation_step_t)0x0202) 01692 01693 /** An information string for key derivation. 01694 * 01695 * This should be a direct input. 01696 * It can also be a key of type #PSA_KEY_TYPE_RAW_DATA. 01697 */ 01698 #define PSA_KEY_DERIVATION_INPUT_INFO ((psa_key_derivation_step_t)0x0203) 01699 01700 /** A seed for key derivation. 01701 * 01702 * This should be a direct input. 01703 * It can also be a key of type #PSA_KEY_TYPE_RAW_DATA. 01704 */ 01705 #define PSA_KEY_DERIVATION_INPUT_SEED ((psa_key_derivation_step_t)0x0204) 01706 01707 /**@}*/ 01708 01709 #endif /* PSA_CRYPTO_VALUES_H */
Generated on Tue Jul 12 2022 13:54:14 by
1.7.2