1 /* 2 * Copyright (c) 2001-2019, Arm Limited and Contributors. All rights reserved. 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 */ 6 7 #ifndef _CC_KDF_H 8 #define _CC_KDF_H 9 10 11 12 #ifdef __cplusplus 13 extern "C" 14 { 15 #endif 16 17 /*! 18 @file 19 @brief This file defines the API that supports Key derivation function in modes 20 as defined in Public-Key Cryptography Standards (PKCS) #3: Diffie-Hellman Key Agreement Standard, 21 ANSI X9.42-2003: Public Key Cryptography for the Financial Services Industry: Agreement of Symmetric Keys Using Discrete Logarithm Cryptography, 22 and ANSI X9.63-2011: Public Key Cryptography for the Financial Services Industry - Key Agreement and Key Transport Using Elliptic Curve 23 Cryptography. 24 @defgroup cc_kdf CryptoCell Key Derivation APIs 25 @{ 26 @ingroup cryptocell_api 27 28 */ 29 30 #include "cc_hash_defs.h" 31 32 /************************ Defines ******************************/ 33 34 /*! Shared secret value max size in bytes */ 35 #define CC_KDF_MAX_SIZE_OF_SHARED_SECRET_VALUE 1024 36 37 /* Count and max. sizeof OtherInfo entries (pointers to data buffers) */ 38 /*! Number of other info entries. */ 39 #define CC_KDF_COUNT_OF_OTHER_INFO_ENTRIES 5 40 41 /*! Maximal size of keying data in bytes. */ 42 #define CC_KDF_MAX_SIZE_OF_KEYING_DATA 2048 43 /*! Size of KDF counter in bytes */ 44 #define CC_KDF_COUNTER_SIZE_IN_BYTES 4 45 46 /************************ Enums ********************************/ 47 48 /*! HASH operation modes */ 49 typedef enum 50 { 51 /*! SHA1 mode.*/ 52 CC_KDF_HASH_SHA1_mode = 0, 53 /*! SHA224 mode.*/ 54 CC_KDF_HASH_SHA224_mode = 1, 55 /*! SHA256 mode.*/ 56 CC_KDF_HASH_SHA256_mode = 2, 57 /*! SHA384 mode.*/ 58 CC_KDF_HASH_SHA384_mode = 3, 59 /*! SHA512 mode.*/ 60 CC_KDF_HASH_SHA512_mode = 4, 61 /*! Maximal number of HASH modes. */ 62 CC_KDF_HASH_NumOfModes, 63 /*! Reserved.*/ 64 CC_KDF_HASH_OpModeLast = 0x7FFFFFFF, 65 66 }CCKdfHashOpMode_t; 67 68 /*! Key derivation modes. */ 69 typedef enum 70 { 71 /*! ASN1 key derivation mode.*/ 72 CC_KDF_ASN1_DerivMode = 0, 73 /*! Concatination key derivation mode.*/ 74 CC_KDF_ConcatDerivMode = 1, 75 /*! X963 key derivation mode.*/ 76 CC_KDF_X963_DerivMode = CC_KDF_ConcatDerivMode, 77 /*! ISO 18033 KDF1 key derivation mode.*/ 78 CC_KDF_ISO18033_KDF1_DerivMode = 3, 79 /*! ISO 18033 KDF2 key derivation mode.*/ 80 CC_KDF_ISO18033_KDF2_DerivMode = 4, 81 /*! Maximal number of key derivation modes. */ 82 CC_KDF_DerivFunc_NumOfModes = 5, 83 /*! Reserved.*/ 84 CC_KDF_DerivFuncModeLast= 0x7FFFFFFF, 85 86 }CCKdfDerivFuncMode_t; 87 88 /*! Enumerator for the additional information given to the KDF. */ 89 typedef enum 90 { 91 CC_KDF_ALGORITHM_ID = 0, /*! An identifier (OID), indicating algorithm for which the keying data is used. */ 92 CC_KDF_PARTY_U_INFO = 1, /*! Optional data of party U .*/ 93 CC_KDF_PARTY_V_INFO = 2, /*! Optional data of party V. */ 94 CC_KDF_SUPP_PRIV_INFO = 3, /*! Optional supplied private shared data. */ 95 CC_KDF_SUPP_PUB_INFO = 4, /*! Optional supplied public shared data. */ 96 97 CC_KDF_MAX_COUNT_OF_ENTRIES, /*! Maximal allowed number of entries in Other Info structure. */ 98 /*! Reserved.*/ 99 CC_KDF_ENTRYS_MAX_VAL = 0x7FFFFFFF, 100 101 }CCKdfOtherInfoEntries_t; 102 /************************ Typedefs ****************************/ 103 104 /*! KDF structure, containing pointers to OtherInfo data entries and sizes. 105 106 The structure contains two arrays: one for data pointers and one for sizes, placed according 107 to the order given in the the ANSI X9.42-2003: Public Key Cryptography for the Financial Services 108 Industry: Agreement of Symmetric Keys Using Discrete Logarithm Cryptography standard 109 and defined in CCKdfOtherInfoEntries_t enumerator. 110 On KDF ASN1 mode this order is mandatory. On other KDF modes the user may insert 111 optional OtherInfo simply in one (preferably the first) or in some entries. 112 If any data entry is not used, then the pointer value and the size must be set to NULL. */ 113 typedef struct 114 { 115 /*! Pointers to data entries. */ 116 uint8_t *dataPointers[CC_KDF_MAX_COUNT_OF_ENTRIES]; 117 /*! Sizes of data entries. */ 118 uint32_t dataSizes[CC_KDF_MAX_COUNT_OF_ENTRIES]; 119 }CCKdfOtherInfo_t; 120 121 122 /************************ Structs ******************************/ 123 124 /************************ Public Variables **********************/ 125 126 /************************ Public Functions **********************/ 127 128 /****************************************************************/ 129 130 /*********************************************************************************************************/ 131 /*! 132 @brief CC_KdfKeyDerivFunc performs key derivation according to one of the modes defined in standards: 133 ANSI X9.42-2003: Public Key Cryptography for the Financial Services Industry: Agreement of Symmetric Keys Using Discrete Logarithm Cryptography, 134 ANSI X9.63-2011: Public Key Cryptography for the Financial Services Industry - Key Agreement and Key Transport Using Elliptic Curve Cryptography, 135 ISO/IEC 18033-2:2006: Information technology -- Security techniques -- Encryption algorithms -- Part 2: Asymmetric ciphers. 136 137 The present implementation of the function allows the following operation modes: 138 <ul><li> CC_KDF_ASN1_DerivMode - mode based on ASN.1 DER encoding; </li> 139 <li> CC_KDF_ConcatDerivMode - mode based on concatenation;</li> 140 <li> CC_KDF_X963_DerivMode = CC_KDF_ConcatDerivMode;</li> 141 <li> CC_KDF_ISO18033_KDF1_DerivMode, CC_KDF_ISO18033_KDF2_DerivMode - specific modes according to 142 ISO/IEC 18033-2 standard.</li></ul> 143 144 The purpose of this function is to derive a keying data from the shared secret value and some 145 other optional shared information, included in OtherInfo (SharedInfo). 146 147 \note All buffers arguments are represented in Big-Endian format. 148 149 @return CC_OK on success. 150 @return A non-zero value on failure as defined cc_kdf_error.h or cc_hash_error.h. 151 */ 152 CCError_t CC_KdfKeyDerivFunc( 153 uint8_t *pZzSecret, /*!< [in] A pointer to shared secret value octet string. */ 154 size_t zzSecretSize, /*!< [in] The size of the shared secret value in bytes. 155 The maximal size is defined as: ::CC_KDF_MAX_SIZE_OF_SHARED_SECRET_VALUE. */ 156 CCKdfOtherInfo_t *pOtherInfo, /*!< [in] A pointer to the structure, containing pointers to the data, shared by 157 two entities of agreement, depending on KDF mode: 158 <ul><li> In KDF ASN1 mode OtherInfo includes ASN1 DER encoding of AlgorithmID (mandatory), 159 and some optional data entries as described in section 7.7.1 of the ANSI X9.42-2003: 160 Public Key Cryptography for the Financial Services Industry: Agreement of Symmetric Keys Using 161 Discrete Logarithm Cryptography standard.</li> 162 <li> In both ISO/IEC 18033-2:2006: Information technology -- Security techniques -- Encryption algorithms -- Part 2: 163 Asymmetric ciphers standard: KDF1 and KDF2 modes this parameter is ignored and may be set to NULL. </li> 164 <li> In other modes it is optional and may be set to NULL. </li></ul>*/ 165 CCKdfHashOpMode_t kdfHashMode, /*!< [in] The KDF identifier of hash function to be used. The hash function output 166 must be at least 160 bits. */ 167 CCKdfDerivFuncMode_t derivMode, /*!< [in] The enum value, specifies one of above described derivation modes. */ 168 uint8_t *pKeyingData, /*!< [out] A pointer to the buffer for derived keying data. */ 169 size_t keyingDataSize /*!< [in] The size in bytes of the keying data to be derived. 170 The maximal size is defined as :: CC_KDF_MAX_SIZE_OF_KEYING_DATA. */ ); 171 172 /*********************************************************************************************************/ 173 /*! 174 CC_KdfAsn1KeyDerivFunc is a macro that performs key derivation according to ASN1 DER encoding method defined 175 in section 7.2.1 of ANSI X9.42-2003: Public Key Cryptography for the Financial Services Industry: Agreement of Symmetric Keys Using Discrete Logarithm Cryptography standard. 176 For a description of the parameters see ::CC_KdfKeyDerivFunc. 177 */ 178 #define CC_KdfAsn1KeyDerivFunc(ZZSecret_ptr,ZZSecretSize,OtherInfo_ptr,kdfHashMode,KeyingData_ptr,KeyLenInBytes)\ 179 CC_KdfKeyDerivFunc((ZZSecret_ptr),(ZZSecretSize),(OtherInfo_ptr),(kdfHashMode),CC_KDF_ASN1_DerivMode,(KeyingData_ptr),(KeyLenInBytes)) 180 181 182 /*********************************************************************************************************/ 183 /*! 184 CC_KdfConcatKeyDerivFunc is a macro that performs key derivation according to concatenation mode defined 185 in section 7.2.2 of ANSI X9.42-2003: Public Key Cryptography for the Financial Services Industry: Agreement of Symmetric Keys Using Discrete Logarithm Cryptography 186 standard and also meets ANSI X9.63-2011: Public Key Cryptography for the Financial Services Industry - Key Agreement and Key Transport Using Elliptic Curve 187 Cryptography standard. For a description of the parameters see ::CC_KdfKeyDerivFunc. 188 */ 189 #define CC_KdfConcatKeyDerivFunc(ZZSecret_ptr,ZZSecretSize,OtherInfo_ptr,kdfHashMode,KeyingData_ptr,KeyLenInBytes)\ 190 CC_KdfKeyDerivFunc((ZZSecret_ptr),(ZZSecretSize),(OtherInfo_ptr),(kdfHashMode),CC_KDF_ConcatDerivMode,(KeyingData_ptr),(KeyLenInBytes)) 191 192 193 #ifdef __cplusplus 194 } 195 #endif 196 /** 197 @} 198 */ 199 #endif 200 201
