1 /** 2 * \file psa/crypto_types.h 3 * 4 * \brief PSA cryptography module: type aliases. 5 * 6 * \note This file may not be included directly. Applications must 7 * include psa/crypto.h. Drivers must include the appropriate driver 8 * header file. 9 * 10 * This file contains portable definitions of integral types for properties 11 * of cryptographic keys, designations of cryptographic algorithms, and 12 * error codes returned by the library. 13 * 14 * This header file does not declare any function. 15 */ 16 /* 17 * Copyright The Mbed TLS Contributors 18 * SPDX-License-Identifier: Apache-2.0 19 * 20 * Licensed under the Apache License, Version 2.0 (the "License"); you may 21 * not use this file except in compliance with the License. 22 * You may obtain a copy of the License at 23 * 24 * http://www.apache.org/licenses/LICENSE-2.0 25 * 26 * Unless required by applicable law or agreed to in writing, software 27 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 28 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 29 * See the License for the specific language governing permissions and 30 * limitations under the License. 31 */ 32 33 #ifndef PSA_CRYPTO_TYPES_H 34 #define PSA_CRYPTO_TYPES_H 35 #include "mbedtls/private_access.h" 36 37 #include "crypto_platform.h" 38 39 /* If MBEDTLS_PSA_CRYPTO_C is defined, make sure MBEDTLS_PSA_CRYPTO_CLIENT 40 * is defined as well to include all PSA code. 41 */ 42 #if defined(MBEDTLS_PSA_CRYPTO_C) 43 #define MBEDTLS_PSA_CRYPTO_CLIENT 44 #endif /* MBEDTLS_PSA_CRYPTO_C */ 45 46 #include <stdint.h> 47 48 /** \defgroup error Error codes 49 * @{ 50 */ 51 52 /** 53 * \brief Function return status. 54 * 55 * This is either #PSA_SUCCESS (which is zero), indicating success, 56 * or a small negative value indicating that an error occurred. Errors are 57 * encoded as one of the \c PSA_ERROR_xxx values defined here. */ 58 /* If #PSA_SUCCESS is already defined, it means that #psa_status_t 59 * is also defined in an external header, so prevent its multiple 60 * definition. 61 */ 62 #ifndef PSA_SUCCESS 63 typedef int32_t psa_status_t; 64 #endif 65 66 /**@}*/ 67 68 /** \defgroup crypto_types Key and algorithm types 69 * @{ 70 */ 71 72 /** \brief Encoding of a key type. 73 */ 74 typedef uint16_t psa_key_type_t; 75 76 /** The type of PSA elliptic curve family identifiers. 77 * 78 * The curve identifier is required to create an ECC key using the 79 * PSA_KEY_TYPE_ECC_KEY_PAIR() or PSA_KEY_TYPE_ECC_PUBLIC_KEY() 80 * macros. 81 * 82 * Values defined by this standard will never be in the range 0x80-0xff. 83 * Vendors who define additional families must use an encoding in this range. 84 */ 85 typedef uint8_t psa_ecc_family_t; 86 87 /** The type of PSA Diffie-Hellman group family identifiers. 88 * 89 * The group identifier is required to create an Diffie-Hellman key using the 90 * PSA_KEY_TYPE_DH_KEY_PAIR() or PSA_KEY_TYPE_DH_PUBLIC_KEY() 91 * macros. 92 * 93 * Values defined by this standard will never be in the range 0x80-0xff. 94 * Vendors who define additional families must use an encoding in this range. 95 */ 96 typedef uint8_t psa_dh_family_t; 97 98 /** \brief Encoding of a cryptographic algorithm. 99 * 100 * For algorithms that can be applied to multiple key types, this type 101 * does not encode the key type. For example, for symmetric ciphers 102 * based on a block cipher, #psa_algorithm_t encodes the block cipher 103 * mode and the padding mode while the block cipher itself is encoded 104 * via #psa_key_type_t. 105 */ 106 typedef uint32_t psa_algorithm_t; 107 108 /**@}*/ 109 110 /** \defgroup key_lifetimes Key lifetimes 111 * @{ 112 */ 113 114 /** Encoding of key lifetimes. 115 * 116 * The lifetime of a key indicates where it is stored and what system actions 117 * may create and destroy it. 118 * 119 * Lifetime values have the following structure: 120 * - Bits 0-7 (#PSA_KEY_LIFETIME_GET_PERSISTENCE(\c lifetime)): 121 * persistence level. This value indicates what device management 122 * actions can cause it to be destroyed. In particular, it indicates 123 * whether the key is _volatile_ or _persistent_. 124 * See ::psa_key_persistence_t for more information. 125 * - Bits 8-31 (#PSA_KEY_LIFETIME_GET_LOCATION(\c lifetime)): 126 * location indicator. This value indicates which part of the system 127 * has access to the key material and can perform operations using the key. 128 * See ::psa_key_location_t for more information. 129 * 130 * Volatile keys are automatically destroyed when the application instance 131 * terminates or on a power reset of the device. Persistent keys are 132 * preserved until the application explicitly destroys them or until an 133 * integration-specific device management event occurs (for example, 134 * a factory reset). 135 * 136 * Persistent keys have a key identifier of type #mbedtls_svc_key_id_t. 137 * This identifier remains valid throughout the lifetime of the key, 138 * even if the application instance that created the key terminates. 139 * The application can call psa_open_key() to open a persistent key that 140 * it created previously. 141 * 142 * The default lifetime of a key is #PSA_KEY_LIFETIME_VOLATILE. The lifetime 143 * #PSA_KEY_LIFETIME_PERSISTENT is supported if persistent storage is 144 * available. Other lifetime values may be supported depending on the 145 * library configuration. 146 */ 147 typedef uint32_t psa_key_lifetime_t; 148 149 /** Encoding of key persistence levels. 150 * 151 * What distinguishes different persistence levels is what device management 152 * events may cause keys to be destroyed. _Volatile_ keys are destroyed 153 * by a power reset. Persistent keys may be destroyed by events such as 154 * a transfer of ownership or a factory reset. What management events 155 * actually affect persistent keys at different levels is outside the 156 * scope of the PSA Cryptography specification. 157 * 158 * The PSA Cryptography specification defines the following values of 159 * persistence levels: 160 * - \c 0 = #PSA_KEY_PERSISTENCE_VOLATILE: volatile key. 161 * A volatile key is automatically destroyed by the implementation when 162 * the application instance terminates. In particular, a volatile key 163 * is automatically destroyed on a power reset of the device. 164 * - \c 1 = #PSA_KEY_PERSISTENCE_DEFAULT: 165 * persistent key with a default lifetime. 166 * - \c 2-254: currently not supported by Mbed TLS. 167 * - \c 255 = #PSA_KEY_PERSISTENCE_READ_ONLY: 168 * read-only or write-once key. 169 * A key with this persistence level cannot be destroyed. 170 * Mbed TLS does not currently offer a way to create such keys, but 171 * integrations of Mbed TLS can use it for built-in keys that the 172 * application cannot modify (for example, a hardware unique key (HUK)). 173 * 174 * \note Key persistence levels are 8-bit values. Key management 175 * interfaces operate on lifetimes (type ::psa_key_lifetime_t) which 176 * encode the persistence as the lower 8 bits of a 32-bit value. 177 */ 178 typedef uint8_t psa_key_persistence_t; 179 180 /** Encoding of key location indicators. 181 * 182 * If an integration of Mbed TLS can make calls to external 183 * cryptoprocessors such as secure elements, the location of a key 184 * indicates which secure element performs the operations on the key. 185 * Depending on the design of the secure element, the key 186 * material may be stored either in the secure element, or 187 * in wrapped (encrypted) form alongside the key metadata in the 188 * primary local storage. 189 * 190 * The PSA Cryptography API specification defines the following values of 191 * location indicators: 192 * - \c 0: primary local storage. 193 * This location is always available. 194 * The primary local storage is typically the same storage area that 195 * contains the key metadata. 196 * - \c 1: primary secure element. 197 * Integrations of Mbed TLS should support this value if there is a secure 198 * element attached to the operating environment. 199 * As a guideline, secure elements may provide higher resistance against 200 * side channel and physical attacks than the primary local storage, but may 201 * have restrictions on supported key types, sizes, policies and operations 202 * and may have different performance characteristics. 203 * - \c 2-0x7fffff: other locations defined by a PSA specification. 204 * The PSA Cryptography API does not currently assign any meaning to these 205 * locations, but future versions of that specification or other PSA 206 * specifications may do so. 207 * - \c 0x800000-0xffffff: vendor-defined locations. 208 * No PSA specification will assign a meaning to locations in this range. 209 * 210 * \note Key location indicators are 24-bit values. Key management 211 * interfaces operate on lifetimes (type ::psa_key_lifetime_t) which 212 * encode the location as the upper 24 bits of a 32-bit value. 213 */ 214 typedef uint32_t psa_key_location_t; 215 216 /** Encoding of identifiers of persistent keys. 217 * 218 * - Applications may freely choose key identifiers in the range 219 * #PSA_KEY_ID_USER_MIN to #PSA_KEY_ID_USER_MAX. 220 * - The implementation may define additional key identifiers in the range 221 * #PSA_KEY_ID_VENDOR_MIN to #PSA_KEY_ID_VENDOR_MAX. 222 * - 0 is reserved as an invalid key identifier. 223 * - Key identifiers outside these ranges are reserved for future use. 224 */ 225 typedef uint32_t psa_key_id_t; 226 227 #if !defined(MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER) 228 typedef psa_key_id_t mbedtls_svc_key_id_t; 229 230 #else /* MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER */ 231 /* Implementation-specific: The Mbed Cryptography library can be built as 232 * part of a multi-client service that exposes the PSA Cryptograpy API in each 233 * client and encodes the client identity in the key identifier argument of 234 * functions such as psa_open_key(). 235 */ 236 typedef struct 237 { 238 psa_key_id_t MBEDTLS_PRIVATE(key_id); 239 mbedtls_key_owner_id_t MBEDTLS_PRIVATE(owner); 240 } mbedtls_svc_key_id_t; 241 242 #endif /* !MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER */ 243 244 /**@}*/ 245 246 /** \defgroup policy Key policies 247 * @{ 248 */ 249 250 /** \brief Encoding of permitted usage on a key. */ 251 typedef uint32_t psa_key_usage_t; 252 253 /**@}*/ 254 255 /** \defgroup attributes Key attributes 256 * @{ 257 */ 258 259 /** The type of a structure containing key attributes. 260 * 261 * This is an opaque structure that can represent the metadata of a key 262 * object. Metadata that can be stored in attributes includes: 263 * - The location of the key in storage, indicated by its key identifier 264 * and its lifetime. 265 * - The key's policy, comprising usage flags and a specification of 266 * the permitted algorithm(s). 267 * - Information about the key itself: the key type and its size. 268 * - Additional implementation-defined attributes. 269 * 270 * The actual key material is not considered an attribute of a key. 271 * Key attributes do not contain information that is generally considered 272 * highly confidential. 273 * 274 * An attribute structure works like a simple data structure where each function 275 * `psa_set_key_xxx` sets a field and the corresponding function 276 * `psa_get_key_xxx` retrieves the value of the corresponding field. 277 * However, a future version of the library may report values that are 278 * equivalent to the original one, but have a different encoding. Invalid 279 * values may be mapped to different, also invalid values. 280 * 281 * An attribute structure may contain references to auxiliary resources, 282 * for example pointers to allocated memory or indirect references to 283 * pre-calculated values. In order to free such resources, the application 284 * must call psa_reset_key_attributes(). As an exception, calling 285 * psa_reset_key_attributes() on an attribute structure is optional if 286 * the structure has only been modified by the following functions 287 * since it was initialized or last reset with psa_reset_key_attributes(): 288 * - psa_set_key_id() 289 * - psa_set_key_lifetime() 290 * - psa_set_key_type() 291 * - psa_set_key_bits() 292 * - psa_set_key_usage_flags() 293 * - psa_set_key_algorithm() 294 * 295 * Before calling any function on a key attribute structure, the application 296 * must initialize it by any of the following means: 297 * - Set the structure to all-bits-zero, for example: 298 * \code 299 * psa_key_attributes_t attributes; 300 * memset(&attributes, 0, sizeof(attributes)); 301 * \endcode 302 * - Initialize the structure to logical zero values, for example: 303 * \code 304 * psa_key_attributes_t attributes = {0}; 305 * \endcode 306 * - Initialize the structure to the initializer #PSA_KEY_ATTRIBUTES_INIT, 307 * for example: 308 * \code 309 * psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT; 310 * \endcode 311 * - Assign the result of the function psa_key_attributes_init() 312 * to the structure, for example: 313 * \code 314 * psa_key_attributes_t attributes; 315 * attributes = psa_key_attributes_init(); 316 * \endcode 317 * 318 * A freshly initialized attribute structure contains the following 319 * values: 320 * 321 * - lifetime: #PSA_KEY_LIFETIME_VOLATILE. 322 * - key identifier: 0 (which is not a valid key identifier). 323 * - type: \c 0 (meaning that the type is unspecified). 324 * - key size: \c 0 (meaning that the size is unspecified). 325 * - usage flags: \c 0 (which allows no usage except exporting a public key). 326 * - algorithm: \c 0 (which allows no cryptographic usage, but allows 327 * exporting). 328 * 329 * A typical sequence to create a key is as follows: 330 * -# Create and initialize an attribute structure. 331 * -# If the key is persistent, call psa_set_key_id(). 332 * Also call psa_set_key_lifetime() to place the key in a non-default 333 * location. 334 * -# Set the key policy with psa_set_key_usage_flags() and 335 * psa_set_key_algorithm(). 336 * -# Set the key type with psa_set_key_type(). 337 * Skip this step if copying an existing key with psa_copy_key(). 338 * -# When generating a random key with psa_generate_key() or deriving a key 339 * with psa_key_derivation_output_key(), set the desired key size with 340 * psa_set_key_bits(). 341 * -# Call a key creation function: psa_import_key(), psa_generate_key(), 342 * psa_key_derivation_output_key() or psa_copy_key(). This function reads 343 * the attribute structure, creates a key with these attributes, and 344 * outputs a key identifier to the newly created key. 345 * -# The attribute structure is now no longer necessary. 346 * You may call psa_reset_key_attributes(), although this is optional 347 * with the workflow presented here because the attributes currently 348 * defined in this specification do not require any additional resources 349 * beyond the structure itself. 350 * 351 * A typical sequence to query a key's attributes is as follows: 352 * -# Call psa_get_key_attributes(). 353 * -# Call `psa_get_key_xxx` functions to retrieve the attribute(s) that 354 * you are interested in. 355 * -# Call psa_reset_key_attributes() to free any resources that may be 356 * used by the attribute structure. 357 * 358 * Once a key has been created, it is impossible to change its attributes. 359 */ 360 typedef struct psa_key_attributes_s psa_key_attributes_t; 361 362 363 #ifndef __DOXYGEN_ONLY__ 364 #if defined(MBEDTLS_PSA_CRYPTO_SE_C) 365 /* Mbed Crypto defines this type in crypto_types.h because it is also 366 * visible to applications through an implementation-specific extension. 367 * For the PSA Cryptography specification, this type is only visible 368 * via crypto_se_driver.h. */ 369 typedef uint64_t psa_key_slot_number_t; 370 #endif /* MBEDTLS_PSA_CRYPTO_SE_C */ 371 #endif /* !__DOXYGEN_ONLY__ */ 372 373 /**@}*/ 374 375 /** \defgroup derivation Key derivation 376 * @{ 377 */ 378 379 /** \brief Encoding of the step of a key derivation. */ 380 typedef uint16_t psa_key_derivation_step_t; 381 382 /**@}*/ 383 384 #endif /* PSA_CRYPTO_TYPES_H */ 385