crypto_struct_spe.h

00001 /**
00002  * \file psa/crypto_struct.h
00003  *
00004  * \brief PSA cryptography module: Mbed TLS structured type implementations
00005  *
00006  * \note This file may not be included directly. Applications must
00007  * include psa/crypto.h.
00008  *
00009  * This file contains the definitions of some data structures with
00010  * implementation-specific definitions.
00011  *
00012  * In implementations with isolation between the application and the
00013  * cryptography module, it is expected that the front-end and the back-end
00014  * would have different versions of this file.
00015  *
00016  * <h3>Design notes about multipart operation structures</h3>
00017  *
00018  * Each multipart operation structure contains a `psa_algorithm_t alg`
00019  * field which indicates which specific algorithm the structure is for.
00020  * When the structure is not in use, `alg` is 0. Most of the structure
00021  * consists of a union which is discriminated by `alg`.
00022  *
00023  * Note that when `alg` is 0, the content of other fields is undefined.
00024  * In particular, it is not guaranteed that a freshly-initialized structure
00025  * is all-zero: we initialize structures to something like `{0, 0}`, which
00026  * is only guaranteed to initializes the first member of the union;
00027  * GCC and Clang initialize the whole structure to 0 (at the time of writing),
00028  * but MSVC and CompCert don't.
00029  *
00030  * In Mbed Crypto, multipart operation structures live independently from
00031  * the key. This allows Mbed Crypto to free the key objects when destroying
00032  * a key slot. If a multipart operation needs to remember the key after
00033  * the setup function returns, the operation structure needs to contain a
00034  * copy of the key.
00035  */
00036 /*
00037  *  Copyright (C) 2018, ARM Limited, All Rights Reserved
00038  *  SPDX-License-Identifier: Apache-2.0
00039  *
00040  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00041  *  not use this file except in compliance with the License.
00042  *  You may obtain a copy of the License at
00043  *
00044  *  http://www.apache.org/licenses/LICENSE-2.0
00045  *
00046  *  Unless required by applicable law or agreed to in writing, software
00047  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00048  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00049  *  See the License for the specific language governing permissions and
00050  *  limitations under the License.
00051  *
00052  *  This file is part of mbed TLS (https://tls.mbed.org)
00053  */
00054 
00055 #ifndef PSA_CRYPTO_STRUCT_H
00056 #define PSA_CRYPTO_STRUCT_H
00057 
00058 #ifdef __cplusplus
00059 extern "C" {
00060 #endif
00061 
00062 /* Include the Mbed TLS configuration file, the way Mbed TLS does it
00063  * in each of its header files. */
00064 #if !defined(MBEDTLS_CONFIG_FILE)
00065 #include "mbedtls/config.h"
00066 #else
00067 #include MBEDTLS_CONFIG_FILE
00068 #endif
00069 
00070 #include "mbedtls/cipher.h"
00071 #include "mbedtls/cmac.h"
00072 #include "mbedtls/gcm.h"
00073 #include "mbedtls/md.h"
00074 #include "mbedtls/md2.h"
00075 #include "mbedtls/md4.h"
00076 #include "mbedtls/md5.h"
00077 #include "mbedtls/ripemd160.h"
00078 #include "mbedtls/sha1.h"
00079 #include "mbedtls/sha256.h"
00080 #include "mbedtls/sha512.h"
00081 
00082 struct psa_hash_operation_s
00083 {
00084     psa_algorithm_t alg;
00085     union
00086     {
00087         unsigned dummy; /* Make the union non-empty even with no supported algorithms. */
00088 #if defined(MBEDTLS_MD2_C)
00089         mbedtls_md2_context md2;
00090 #endif
00091 #if defined(MBEDTLS_MD4_C)
00092         mbedtls_md4_context md4;
00093 #endif
00094 #if defined(MBEDTLS_MD5_C)
00095         mbedtls_md5_context md5;
00096 #endif
00097 #if defined(MBEDTLS_RIPEMD160_C)
00098         mbedtls_ripemd160_context ripemd160;
00099 #endif
00100 #if defined(MBEDTLS_SHA1_C)
00101         mbedtls_sha1_context sha1;
00102 #endif
00103 #if defined(MBEDTLS_SHA256_C)
00104         mbedtls_sha256_context sha256;
00105 #endif
00106 #if defined(MBEDTLS_SHA512_C)
00107         mbedtls_sha512_context sha512;
00108 #endif
00109     } ctx;
00110 };
00111 
00112 #define PSA_HASH_OPERATION_INIT {0, {0}}
00113 static inline struct psa_hash_operation_s psa_hash_operation_init( void )
00114 {
00115     const struct psa_hash_operation_s v = PSA_HASH_OPERATION_INIT;
00116     return( v );
00117 }
00118 
00119 #if defined(MBEDTLS_MD_C)
00120 typedef struct
00121 {
00122         /** The hash context. */
00123         struct psa_hash_operation_s hash_ctx;
00124         /** The HMAC part of the context. */
00125         uint8_t opad[PSA_HMAC_MAX_HASH_BLOCK_SIZE];
00126 } psa_hmac_internal_data;
00127 #endif /* MBEDTLS_MD_C */
00128 
00129 struct psa_mac_operation_s
00130 {
00131     psa_algorithm_t alg;
00132     unsigned int key_set : 1;
00133     unsigned int iv_required : 1;
00134     unsigned int iv_set : 1;
00135     unsigned int has_input : 1;
00136     unsigned int is_sign : 1;
00137     uint8_t mac_size;
00138     union
00139     {
00140         unsigned dummy; /* Make the union non-empty even with no supported algorithms. */
00141 #if defined(MBEDTLS_MD_C)
00142         psa_hmac_internal_data hmac;
00143 #endif
00144 #if defined(MBEDTLS_CMAC_C)
00145         mbedtls_cipher_context_t cmac;
00146 #endif
00147     } ctx;
00148 };
00149 
00150 #define PSA_MAC_OPERATION_INIT {0, 0, 0, 0, 0, 0, 0, {0}}
00151 static inline struct psa_mac_operation_s psa_mac_operation_init( void )
00152 {
00153     const struct psa_mac_operation_s v = PSA_MAC_OPERATION_INIT;
00154     return( v );
00155 }
00156 
00157 struct psa_cipher_operation_s
00158 {
00159     psa_algorithm_t alg;
00160     unsigned int key_set : 1;
00161     unsigned int iv_required : 1;
00162     unsigned int iv_set : 1;
00163     uint8_t iv_size;
00164     uint8_t block_size;
00165     union
00166     {
00167         unsigned dummy; /* Enable easier initializing of the union. */
00168         mbedtls_cipher_context_t cipher;
00169     } ctx;
00170 };
00171 
00172 #define PSA_CIPHER_OPERATION_INIT {0, 0, 0, 0, 0, 0, {0}}
00173 static inline struct psa_cipher_operation_s psa_cipher_operation_init( void )
00174 {
00175     const struct psa_cipher_operation_s v = PSA_CIPHER_OPERATION_INIT;
00176     return( v );
00177 }
00178 
00179 struct psa_aead_operation_s
00180 {
00181     psa_algorithm_t alg;
00182     unsigned int key_set : 1;
00183     unsigned int iv_set : 1;
00184     uint8_t iv_size;
00185     uint8_t block_size;
00186     union
00187     {
00188         unsigned dummy; /* Enable easier initializing of the union. */
00189         mbedtls_cipher_context_t cipher;
00190     } ctx;
00191 };
00192 
00193 #define PSA_AEAD_OPERATION_INIT {0, 0, 0, 0, 0, {0}}
00194 static inline struct psa_aead_operation_s psa_aead_operation_init( void )
00195 {
00196     const struct psa_aead_operation_s v = PSA_AEAD_OPERATION_INIT;
00197     return( v );
00198 }
00199 
00200 #if defined(MBEDTLS_MD_C)
00201 typedef struct
00202 {
00203     uint8_t *info;
00204     size_t info_length;
00205     psa_hmac_internal_data hmac;
00206     uint8_t prk[PSA_HASH_MAX_SIZE];
00207     uint8_t output_block[PSA_HASH_MAX_SIZE];
00208 #if PSA_HASH_MAX_SIZE > 0xff
00209 #error "PSA_HASH_MAX_SIZE does not fit in uint8_t"
00210 #endif
00211     uint8_t offset_in_block;
00212     uint8_t block_number;
00213     unsigned int state : 2;
00214     unsigned int info_set : 1;
00215 } psa_hkdf_key_derivation_t;
00216 #endif /* MBEDTLS_MD_C */
00217 
00218 #if defined(MBEDTLS_MD_C)
00219 typedef enum
00220 {
00221     TLS12_PRF_STATE_INIT,       /* no input provided */
00222     TLS12_PRF_STATE_SEED_SET,   /* seed has been set */
00223     TLS12_PRF_STATE_KEY_SET,    /* key has been set */
00224     TLS12_PRF_STATE_LABEL_SET,  /* label has been set */
00225     TLS12_PRF_STATE_OUTPUT      /* output has been started */
00226 } psa_tls12_prf_key_derivation_state_t;
00227 
00228 typedef struct psa_tls12_prf_key_derivation_s
00229 {
00230 #if PSA_HASH_MAX_SIZE > 0xff
00231 #error "PSA_HASH_MAX_SIZE does not fit in uint8_t"
00232 #endif
00233 
00234     /* Indicates how many bytes in the current HMAC block have
00235      * not yet been read by the user. */
00236     uint8_t left_in_block;
00237 
00238     /* The 1-based number of the block. */
00239     uint8_t block_number;
00240 
00241     psa_tls12_prf_key_derivation_state_t state;
00242 
00243     uint8_t *seed;
00244     size_t seed_length;
00245     uint8_t *label;
00246     size_t label_length;
00247     psa_hmac_internal_data hmac;
00248     uint8_t Ai[PSA_HASH_MAX_SIZE];
00249 
00250     /* `HMAC_hash( prk, A(i) + seed )` in the notation of RFC 5246, Sect. 5. */
00251     uint8_t output_block[PSA_HASH_MAX_SIZE];
00252 } psa_tls12_prf_key_derivation_t;
00253 #endif /* MBEDTLS_MD_C */
00254 
00255 struct psa_key_derivation_s
00256 {
00257     psa_algorithm_t alg;
00258     unsigned int can_output_key : 1;
00259     size_t capacity;
00260     union
00261     {
00262         /* Make the union non-empty even with no supported algorithms. */
00263         uint8_t dummy;
00264 #if defined(MBEDTLS_MD_C)
00265         psa_hkdf_key_derivation_t hkdf;
00266         psa_tls12_prf_key_derivation_t tls12_prf;
00267 #endif
00268     } ctx;
00269 };
00270 
00271 /* This only zeroes out the first byte in the union, the rest is unspecified. */
00272 #define PSA_KEY_DERIVATION_OPERATION_INIT {0, 0, 0, {0}}
00273 static inline struct psa_key_derivation_s psa_key_derivation_operation_init( void )
00274 {
00275     const struct psa_key_derivation_s v = PSA_KEY_DERIVATION_OPERATION_INIT;
00276     return( v );
00277 }
00278 
00279 struct psa_key_policy_s
00280 {
00281     psa_key_usage_t usage;
00282     psa_algorithm_t alg;
00283     psa_algorithm_t alg2;
00284 };
00285 typedef struct psa_key_policy_s psa_key_policy_t;
00286 
00287 #define PSA_KEY_POLICY_INIT {0, 0, 0}
00288 static inline struct psa_key_policy_s psa_key_policy_init( void )
00289 {
00290     const struct psa_key_policy_s v = PSA_KEY_POLICY_INIT;
00291     return( v );
00292 }
00293 
00294 /* The type used internally for key sizes.
00295  * Public interfaces use size_t, but internally we use a smaller type. */
00296 typedef uint16_t psa_key_bits_t;
00297 /* The maximum value of the type used to represent bit-sizes.
00298  * This is used to mark an invalid key size. */
00299 #define PSA_KEY_BITS_TOO_LARGE ( (psa_key_bits_t) ( -1 ) )
00300 /* The maximum size of a key in bits.
00301  * Currently defined as the maximum that can be represented, rounded down
00302  * to a whole number of bytes.
00303  * This is an uncast value so that it can be used in preprocessor
00304  * conditionals. */
00305 #define PSA_MAX_KEY_BITS 0xfff8
00306 
00307 /** A mask of flags that can be stored in key attributes.
00308  *
00309  * This type is also used internally to store flags in slots. Internal
00310  * flags are defined in library/psa_crypto_core.h. Internal flags may have
00311  * the same value as external flags if they are properly handled during
00312  * key creation and in psa_get_key_attributes.
00313  */
00314 typedef uint16_t psa_key_attributes_flag_t;
00315 
00316 #define MBEDTLS_PSA_KA_FLAG_HAS_SLOT_NUMBER     \
00317     ( (psa_key_attributes_flag_t) 0x0001 )
00318 
00319 /* A mask of key attribute flags used externally only.
00320  * Only meant for internal checks inside the library. */
00321 #define MBEDTLS_PSA_KA_MASK_EXTERNAL_ONLY (      \
00322         MBEDTLS_PSA_KA_FLAG_HAS_SLOT_NUMBER |    \
00323         0 )
00324 
00325 /* A mask of key attribute flags used both internally and externally.
00326  * Currently there aren't any. */
00327 #define MBEDTLS_PSA_KA_MASK_DUAL_USE (          \
00328         0 )
00329 
00330 typedef struct
00331 {
00332     psa_key_type_t type;
00333     psa_key_lifetime_t lifetime;
00334     psa_key_id_t id;
00335     psa_key_policy_t policy;
00336     psa_key_bits_t bits;
00337     psa_key_attributes_flag_t flags;
00338 } psa_core_key_attributes_t;
00339 
00340 /* The server must be able to interpret the attributes as specified by the
00341  * client. The server works with the psa_key_id_t encoding the key owner, but
00342  * the client works with the psa_key_id_t not containing the key owner (pure
00343  * psa_app_key_id_t. */
00344 typedef struct
00345 {
00346     psa_key_type_t type;
00347     psa_key_lifetime_t lifetime;
00348     psa_app_key_id_t id;
00349     psa_key_policy_t policy;
00350     psa_key_bits_t bits;
00351     uint16_t flags;
00352 } psa_client_core_key_attributes_t;
00353 
00354 #define PSA_CORE_KEY_ATTRIBUTES_INIT {0, 0, PSA_KEY_ID_INIT, PSA_KEY_POLICY_INIT, 0, 0}
00355 
00356 struct psa_key_attributes_s
00357 {
00358     psa_core_key_attributes_t core;
00359 #if defined(MBEDTLS_PSA_CRYPTO_SE_C)
00360     psa_key_slot_number_t slot_number;
00361 #endif /* MBEDTLS_PSA_CRYPTO_SE_C */
00362     void *domain_parameters;
00363     size_t domain_parameters_size;
00364 };
00365 
00366 #if defined(MBEDTLS_PSA_CRYPTO_SE_C)
00367 #define PSA_KEY_ATTRIBUTES_INIT {PSA_CORE_KEY_ATTRIBUTES_INIT, 0, NULL, 0}
00368 #else
00369 #define PSA_KEY_ATTRIBUTES_INIT {PSA_CORE_KEY_ATTRIBUTES_INIT, NULL, 0}
00370 #endif
00371 typedef struct psa_client_key_attributes_s
00372 {
00373     psa_client_core_key_attributes_t core;
00374     void *domain_parameters;
00375     size_t domain_parameters_size;
00376 } psa_client_key_attributes_t;
00377 
00378 static inline struct psa_key_attributes_s psa_key_attributes_init( void )
00379 {
00380     const struct psa_key_attributes_s v = PSA_KEY_ATTRIBUTES_INIT;
00381     return( v );
00382 }
00383 
00384 static void psa_core_attributes_to_client(
00385     const psa_core_key_attributes_t *server,
00386     psa_client_core_key_attributes_t *client)
00387 {
00388     client->type = server->type;
00389     client->lifetime = server->lifetime;
00390     client->id = server->id.key_id;
00391     client->policy = server->policy;
00392     client->bits = server->bits;
00393     client->flags = server->flags;
00394 }
00395 
00396 static void psa_core_attributes_to_server(
00397     const psa_client_core_key_attributes_t *client,
00398     psa_key_owner_id_t owner,
00399     psa_core_key_attributes_t *server)
00400 {
00401     server->type = client->type;
00402     server->lifetime = client->lifetime;
00403     server->id.key_id = client->id;
00404     server->id.owner = owner;
00405     server->policy = client->policy;
00406     server->bits = client->bits;
00407     server->flags = client->flags;
00408 }
00409 
00410 static inline void psa_set_key_id(psa_key_attributes_t *attributes,
00411                                   psa_key_id_t id)
00412 {
00413     attributes->core.id = id;
00414     if( attributes->core.lifetime == PSA_KEY_LIFETIME_VOLATILE )
00415         attributes->core.lifetime = PSA_KEY_LIFETIME_PERSISTENT;
00416 }
00417 
00418 static inline psa_key_id_t psa_get_key_id(
00419     const psa_key_attributes_t *attributes)
00420 {
00421     return( attributes->core.id );
00422 }
00423 
00424 static inline void psa_set_key_lifetime(psa_key_attributes_t *attributes,
00425                                         psa_key_lifetime_t lifetime)
00426 {
00427     attributes->core.lifetime = lifetime;
00428     if( lifetime == PSA_KEY_LIFETIME_VOLATILE )
00429     {
00430 #ifdef MBEDTLS_PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER
00431         attributes->core.id.key_id = 0;
00432         attributes->core.id.owner = 0;
00433 #else
00434         attributes->core.id = 0;
00435 #endif
00436     }
00437 }
00438 
00439 static inline psa_key_lifetime_t psa_get_key_lifetime(
00440     const psa_key_attributes_t *attributes)
00441 {
00442     return( attributes->core.lifetime );
00443 }
00444 
00445 static inline void psa_set_key_usage_flags(psa_key_attributes_t *attributes,
00446                                            psa_key_usage_t usage_flags)
00447 {
00448     attributes->core.policy.usage = usage_flags;
00449 }
00450 
00451 static inline psa_key_usage_t psa_get_key_usage_flags(
00452     const psa_key_attributes_t *attributes)
00453 {
00454     return( attributes->core.policy.usage );
00455 }
00456 
00457 static inline void psa_set_key_algorithm(psa_key_attributes_t *attributes,
00458                                          psa_algorithm_t alg)
00459 {
00460     attributes->core.policy.alg = alg;
00461 }
00462 
00463 static inline psa_algorithm_t psa_get_key_algorithm(
00464     const psa_key_attributes_t *attributes)
00465 {
00466     return( attributes->core.policy.alg );
00467 }
00468 
00469 /* This function is declared in crypto_extra.h, which comes after this
00470  * header file, but we need the function here, so repeat the declaration. */
00471 psa_status_t psa_set_key_domain_parameters(psa_key_attributes_t *attributes,
00472                                            psa_key_type_t type,
00473                                            const uint8_t *data,
00474                                            size_t data_length);
00475 
00476 static inline void psa_set_key_type(psa_key_attributes_t *attributes,
00477                                     psa_key_type_t type)
00478 {
00479     if( attributes->domain_parameters == NULL )
00480     {
00481         /* Common case: quick path */
00482         attributes->core.type = type;
00483     }
00484     else
00485     {
00486         /* Call the bigger function to free the old domain paramteres.
00487          * Ignore any errors which may arise due to type requiring
00488          * non-default domain parameters, since this function can't
00489          * report errors. */
00490         (void) psa_set_key_domain_parameters( attributes, type, NULL, 0 );
00491     }
00492 }
00493 
00494 static inline psa_key_type_t psa_get_key_type(
00495     const psa_key_attributes_t *attributes)
00496 {
00497     return( attributes->core.type );
00498 }
00499 
00500 static inline void psa_set_key_bits(psa_key_attributes_t *attributes,
00501                                     size_t bits)
00502 {
00503     if( bits > PSA_MAX_KEY_BITS )
00504         attributes->core.bits = PSA_KEY_BITS_TOO_LARGE;
00505     else
00506         attributes->core.bits = (psa_key_bits_t) bits;
00507 }
00508 
00509 static inline size_t psa_get_key_bits(
00510     const psa_key_attributes_t *attributes)
00511 {
00512     return( attributes->core.bits );
00513 }
00514 
00515 #ifdef __cplusplus
00516 }
00517 #endif
00518 
00519 #endif /* PSA_CRYPTO_STRUCT_H */