crypto_struct.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 #define PSA_CORE_KEY_ATTRIBUTES_INIT {0, 0, PSA_KEY_ID_INIT, PSA_KEY_POLICY_INIT, 0, 0}
00341 
00342 struct psa_key_attributes_s
00343 {
00344     psa_core_key_attributes_t core;
00345 #if defined(MBEDTLS_PSA_CRYPTO_SE_C)
00346     psa_key_slot_number_t slot_number;
00347 #endif /* MBEDTLS_PSA_CRYPTO_SE_C */
00348     void *domain_parameters;
00349     size_t domain_parameters_size;
00350 };
00351 
00352 #if defined(MBEDTLS_PSA_CRYPTO_SE_C)
00353 #define PSA_KEY_ATTRIBUTES_INIT {PSA_CORE_KEY_ATTRIBUTES_INIT, 0, NULL, 0}
00354 #else
00355 #define PSA_KEY_ATTRIBUTES_INIT {PSA_CORE_KEY_ATTRIBUTES_INIT, NULL, 0}
00356 #endif
00357 
00358 static inline struct psa_key_attributes_s psa_key_attributes_init( void )
00359 {
00360     const struct psa_key_attributes_s v = PSA_KEY_ATTRIBUTES_INIT;
00361     return( v );
00362 }
00363 
00364 static inline void psa_set_key_id(psa_key_attributes_t *attributes,
00365                                   psa_key_id_t id)
00366 {
00367     attributes->core.id = id;
00368     if( attributes->core.lifetime == PSA_KEY_LIFETIME_VOLATILE )
00369         attributes->core.lifetime = PSA_KEY_LIFETIME_PERSISTENT;
00370 }
00371 
00372 static inline psa_key_id_t psa_get_key_id(
00373     const psa_key_attributes_t *attributes)
00374 {
00375     return( attributes->core.id );
00376 }
00377 
00378 static inline void psa_set_key_lifetime(psa_key_attributes_t *attributes,
00379                                         psa_key_lifetime_t lifetime)
00380 {
00381     attributes->core.lifetime = lifetime;
00382     if( lifetime == PSA_KEY_LIFETIME_VOLATILE )
00383     {
00384 #ifdef MBEDTLS_PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER
00385         attributes->core.id.key_id = 0;
00386         attributes->core.id.owner = 0;
00387 #else
00388         attributes->core.id = 0;
00389 #endif
00390     }
00391 }
00392 
00393 static inline psa_key_lifetime_t psa_get_key_lifetime(
00394     const psa_key_attributes_t *attributes)
00395 {
00396     return( attributes->core.lifetime );
00397 }
00398 
00399 static inline void psa_set_key_usage_flags(psa_key_attributes_t *attributes,
00400                                            psa_key_usage_t usage_flags)
00401 {
00402     attributes->core.policy.usage = usage_flags;
00403 }
00404 
00405 static inline psa_key_usage_t psa_get_key_usage_flags(
00406     const psa_key_attributes_t *attributes)
00407 {
00408     return( attributes->core.policy.usage );
00409 }
00410 
00411 static inline void psa_set_key_algorithm(psa_key_attributes_t *attributes,
00412                                          psa_algorithm_t alg)
00413 {
00414     attributes->core.policy.alg = alg;
00415 }
00416 
00417 static inline psa_algorithm_t psa_get_key_algorithm(
00418     const psa_key_attributes_t *attributes)
00419 {
00420     return( attributes->core.policy.alg );
00421 }
00422 
00423 /* This function is declared in crypto_extra.h, which comes after this
00424  * header file, but we need the function here, so repeat the declaration. */
00425 psa_status_t psa_set_key_domain_parameters(psa_key_attributes_t *attributes,
00426                                            psa_key_type_t type,
00427                                            const uint8_t *data,
00428                                            size_t data_length);
00429 
00430 static inline void psa_set_key_type(psa_key_attributes_t *attributes,
00431                                     psa_key_type_t type)
00432 {
00433     if( attributes->domain_parameters == NULL )
00434     {
00435         /* Common case: quick path */
00436         attributes->core.type = type;
00437     }
00438     else
00439     {
00440         /* Call the bigger function to free the old domain paramteres.
00441          * Ignore any errors which may arise due to type requiring
00442          * non-default domain parameters, since this function can't
00443          * report errors. */
00444         (void) psa_set_key_domain_parameters( attributes, type, NULL, 0 );
00445     }
00446 }
00447 
00448 static inline psa_key_type_t psa_get_key_type(
00449     const psa_key_attributes_t *attributes)
00450 {
00451     return( attributes->core.type );
00452 }
00453 
00454 static inline void psa_set_key_bits(psa_key_attributes_t *attributes,
00455                                     size_t bits)
00456 {
00457     if( bits > PSA_MAX_KEY_BITS )
00458         attributes->core.bits = PSA_KEY_BITS_TOO_LARGE;
00459     else
00460         attributes->core.bits = (psa_key_bits_t) bits;
00461 }
00462 
00463 static inline size_t psa_get_key_bits(
00464     const psa_key_attributes_t *attributes)
00465 {
00466     return( attributes->core.bits );
00467 }
00468 
00469 #ifdef __cplusplus
00470 }
00471 #endif
00472 
00473 #endif /* PSA_CRYPTO_STRUCT_H */