1 /* 2 * Copyright (c) 2001-2019, Arm Limited and Contributors. All rights reserved. 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 */ 6 7 8 #ifndef _CC_FFCDH_H 9 #define _CC_FFCDH_H 10 11 #include "cc_pal_types.h" 12 #include "cc_pka_defs_hw.h" 13 #include "cc_pal_types.h" 14 #include "cc_pal_compiler.h" 15 #include "cc_hash_defs.h" 16 #include "mbedtls_cc_hkdf.h" 17 #include "cc_ffc_domain.h" 18 #include "cc_rnd_common.h" 19 20 #ifdef __cplusplus 21 extern "C" 22 { 23 #endif 24 25 26 /*! 27 @file 28 @brief This file defines the API that supports FFC Diffie-Hellman key exchange, as defined in NIST SP 56A rev.2 standard. 29 @defgroup cc_ffcdh CryptoCell FFCDH APIs 30 @{ 31 @ingroup cryptocell_api 32 33 */ 34 35 36 /************************ Defines ******************************/ 37 38 /*! Definition for DH public key.*/ 39 40 /*!< Size limitation according to NIST SP 56A ver.2 standard */ 41 #define CC_FFCDH_MAX_VALID_KEY_SIZE_VALUE_IN_BITS 2048 /*! Maximal valid key size in bits.*/ 42 /*! Minimal valid key size in bits.*/ 43 #define CC_FFCDH_MIN_VALID_KEY_SIZE_VALUE_IN_BITS 1024 /*!< Size limitation according to NSI standard */ 44 /*! Maximal prime P (modulus) size in bytes.*/ 45 #define CC_FFCDH_MAX_MOD_SIZE_IN_BYTES (CC_FFCDH_MAX_VALID_KEY_SIZE_VALUE_IN_BITS / CC_BITS_IN_BYTE) 46 /*! Maximal prime P (modulus) size in words.*/ 47 #define CC_FFCDH_MAX_MOD_SIZE_IN_WORDS (CC_FFCDH_MAX_MOD_SIZE_IN_BYTES / CC_32BIT_WORD_SIZE) 48 /*! Prime P (modulus) buffer size in words.*/ 49 #define CC_FFCDH_MAX_MOD_BUFFER_SIZE_IN_WORDS (CC_FFCDH_MAX_MOD_SIZE_IN_WORDS + 2) 50 #define CC_FFCDH_MAX_MOD_BUFFER_SIZE_IN_BYTES (CC_FFCDH_MAX_MOD_BUFFER_SIZE_IN_WORDS * CC_32BIT_WORD_SIZE) 51 52 /*! Maximal FFC subgroup order size. */ 53 #define CC_FFCDH_MAX_GENER_ORDER_SIZE_IN_BITS CC_FFC_DOMAIN_MAX_GENER_ORDER_SIZE_IN_BITS 54 #define CC_FFCDH_MAX_GENER_ORDER_SIZE_IN_BYTES (CC_FFCDH_MAX_GENER_ORDER_SIZE_IN_BITS / CC_BITS_IN_BYTE) 55 #define CC_FFCDH_MAX_GENER_ORDER_SIZE_IN_WORDS (CC_FFCDH_MAX_GENER_ORDER_SIZE_IN_BITS / CC_BITS_IN_32BIT_WORD) 56 /*!< Maximal size of buffer for Generator order (added 2 words for internal using) */ 57 #define CC_FFCDH_MAX_GENER_ORDER_BUFF_SIZE_IN_WORDS (CC_FFCDH_MAX_GENER_ORDER_SIZE_IN_WORDS + 2) 58 59 /* Size in bytes of Length-counter (used for TLS data transfer etc. in form Len||Data) */ 60 #define CC_FFCDH_LENGTH_COUNTER_SIZE_IN_BYTES 2 61 #define CC_FFCDH_KDF_COUNTER_SIZE_IN_BYTES 4 /* counter used in some KDF functions and concatenated 62 with OtherInfo */ 63 #define CC_FFCDH_PUBL_KEY_TMP_BUFF_IN_WORDS CC_FFCDH_MAX_MOD_SIZE_IN_WORDS 64 #define CC_FFCDH_PRIV_KEY_TMP_BUFF_IN_WORDS (CC_FFCDH_MAX_GENER_ORDER_BUFF_SIZE_IN_WORDS) 65 66 /*! Number of other info entries */ 67 #define CC_FFCDH_COUNT_OF_OTHER_INFO_ENTRIES 13 68 69 #define CC_FFCDH_MAX_SIZE_OF_ALG_ID_ENTRY_BYTES 32 /*!< Algorithm ID in bytes.*/ 70 71 /*! Maximal size of supplied Private or Public data entry. */ 72 #define CC_FFCDH_MAX_SIZE_OF_OTHER_INFO_SUPPL_ENTRY_BYTES 64 /*!< Size is in bytes */ 73 #define CC_FFCDH_MAX_SIZE_OF_PARTY_ID_BYTES 32 /*!< implementation limit, in bytes. */ 74 75 /*! Size of Nonce for Key Confirmation (if it is used) should be equal to FFC sub-group order size (meets to SP 800-56Arev.2, sec. 5.4) */ 76 #define CC_FFCDH_MAX_SIZE_OF_NONCE_SUB_ENTRY_BYTES CC_FFCDH_MAX_GENER_ORDER_SIZE_IN_BYTES 77 #define CC_FFCDH_MAX_SIZE_OF_PUBL_KEY_DATA_BYTES CC_FFCDH_MAX_MOD_SIZE_IN_BYTES /*!< Party Public Key max. size in bytes. */ 78 #define CC_FFCDH_MAX_SIZE_OF_PARTY_INFO_OTHER_DATA_BYTES 64 /*!< Party Public Keys Info max. size in bytes.*/ 79 /*!< Count of concatenated sub-entries of Party (U or V) Info */ 80 #define CC_FFCDH_COUNT_OF_PARTY_INFO_ENTRIES 5 81 /*! Maximal size of PartyInfo (U or V). Note: Buffers for Nonce and Ephemeral key 82 * are joined, because only one of them is used actually */ 83 #define CC_FFCDH_MAX_SIZE_OF_PARTY_INFO_BYTES (CC_FFCDH_MAX_SIZE_OF_PARTY_ID_BYTES + 2*CC_FFCDH_MAX_SIZE_OF_PUBL_KEY_DATA_BYTES + \ 84 CC_FFCDH_MAX_SIZE_OF_NONCE_SUB_ENTRY_BYTES + CC_FFCDH_MAX_SIZE_OF_PARTY_INFO_OTHER_DATA_BYTES + \ 85 CC_FFCDH_COUNT_OF_PARTY_INFO_ENTRIES * CC_FFCDH_LENGTH_COUNTER_SIZE_IN_BYTES) 86 87 /*! Maximal size of OtherInfo buffer, including KDF Counter and all entries of actual OtherInfo data */ 88 #define CC_FFCDH_MAX_SIZE_OF_OTHER_INFO_DATA_BYTES (CC_FFCDH_LENGTH_COUNTER_SIZE_IN_BYTES + CC_FFCDH_MAX_SIZE_OF_ALG_ID_ENTRY_BYTES + \ 89 2 * (CC_FFCDH_MAX_SIZE_OF_PARTY_INFO_BYTES + CC_FFCDH_LENGTH_COUNTER_SIZE_IN_BYTES + CC_FFCDH_MAX_SIZE_OF_OTHER_INFO_SUPPL_ENTRY_BYTES)) 90 /*! Extended KDF data buffer: containing: Counter||SharedSecretZZ||OtherInfo */ 91 #define CC_FFCDH_MAX_SIZE_OF_KDF_DATA_BUFFER_BYTES (CC_FFCDH_KDF_COUNTER_SIZE_IN_BYTES + 2*CC_FFCDH_MAX_MOD_SIZE_IN_BYTES/*ZZ size*/ + \ 92 CC_FFCDH_MAX_SIZE_OF_OTHER_INFO_DATA_BYTES) 93 #define CC_FFCDH_MAX_SIZE_OF_KDF_DATA_BUFFER_WORDS (CC_FFCDH_MAX_SIZE_OF_KDF_DATA_BUFFER_BYTES / CC_32BIT_WORD_SIZE) 94 95 #define CC_FFCDH_MAX_SIZE_OF_KEYING_MATERIAL_BYTES 1024 /*!< Size is in bytes*/ 96 97 /*! Maximal size of Confirmation MacData in bytes. 98 * msg_str || IDp || IDr || EphemDataP || EphemDataR {|| TextP} 99 * (Max.size 614 bytes */ 100 #define CC_FFCDH_SIZE_OF_CONFIRM_MSG_STRING_BYTES 6 /*!< standard confirmation message string size in bytes. */ 101 #define CC_FFCDH_MAX_SIZE_OF_CONFIRM_TEXT_DATA_BYTES 32 /*!< party supplied confirmation text size in bytes. */ 102 #define CC_FFCDH_MAX_SIZE_OF_CONFIRM_MAC_DATA_BYTES (CC_FFCDH_SIZE_OF_CONFIRM_MSG_STRING_BYTES + 2*(CC_FFCDH_MAX_SIZE_OF_PARTY_ID_BYTES + \ 103 CC_FFCDH_MAX_MOD_SIZE_IN_BYTES) + CC_FFCDH_MAX_SIZE_OF_CONFIRM_TEXT_DATA_BYTES) 104 /*! Maximal size of Confirmation MacTag (according max. HASH output size) */ 105 #define CC_FFCDH_MAX_SIZE_OF_CONFIRM_MAC_TAG_BYTES CC_HASH_SHA512_DIGEST_SIZE_IN_BYTES 106 /*! Minimal size in bytes of Confirmation MacTag (sec 5.9.3, tab.8) */ 107 #define CC_FFCDH_MIN_SIZE_OF_CONFIRM_MAC_TAG_BYTES 8 108 #define CC_FFCDH_MAX_SIZE_OF_HMAC_SALT_BUFF_BYTES CC_HASH_SHA512_BLOCK_SIZE_IN_BYTES 109 110 /*! Constant size in bytes of Confirmation MacTag defined in this implementation; 111 * note: minimal size according to standards is 6 bytes (112 bit - sec 5.9.3, tab.8) */ 112 #define CC_FFCDH_SIZE_OF_CONFIRM_MAC_KEY_IN_BYTES 8 113 114 /*! The size of the buffer for User ID */ 115 //#define CC_FFCDH_USER_ID_SIZE_IN_BYTES 8 116 /*! Buffer for Barrett Tag - special value, used in modular multiplication */ 117 #define CC_FFCDH_BARRETT_TAG_MAX_SIZE_IN_WORDS CC_FFC_DOMAIN_BARRETT_TAG_MAX_SIZE_IN_WORDS 118 #define CC_FFCDH_BARRETT_TAG_MAX_SIZE_IN_BYTES (CC_FFCDH_BARRETT_TAG_MAX_SIZE_IN_WORDS * CC_32BIT_WORD_SIZE) 119 120 /*! Size (in 32-bit words) of additional buffer used in random generation of vector 121 in range according to FIPS 186-4 sec. B.1.1 */ 122 #define FFCDH_RND_ADDING_SIZE_WORDS 2 123 #define FFCDH_RND_ADDING_SIZE_BYTES (FFCDH_RND_ADDING_SIZE_WORDS * CC_32BIT_WORD_SIZE) 124 125 /*! Max. size of DH Context temp buffer in words */ 126 #define CC_FFCDH_CTX_TMP_BUFF_MAX_SIZE_IN_WORDS (CC_FFCDH_MAX_MOD_SIZE_IN_WORDS + CC_FFCDH_MAX_GENER_ORDER_SIZE_IN_WORDS) 127 /* Size of FFCDH Context internal buffer */ 128 #define CC_FFCDH_CONTEXT_BUFF_SIZE_IN_BYTES \ 129 ROUNDUP_BYTES_TO_32BIT_WORD((FFC_DOMAIN_SIZE_BYTES + 32/*schemeInfo*/ + CC_FFCDH_MAX_SIZE_OF_HMAC_SALT_BUFF_BYTES + \ 130 CC_FFCDH_MAX_SIZE_OF_KEYING_MATERIAL_BYTES + 4*CC_FFCDH_MAX_GENER_ORDER_SIZE_IN_BYTES + 2*CC_FFCDH_MAX_SIZE_OF_PARTY_ID_BYTES + \ 131 4*CC_FFCDH_MAX_MOD_SIZE_IN_BYTES + CC_FFCDH_MAX_SIZE_OF_KDF_DATA_BUFFER_BYTES + 2*CC_HASH_RESULT_SIZE_IN_WORDS*CC_32BIT_WORD_SIZE/*MacTags*/ + \ 132 84/*dataOffsets*/ + 2*CC_FFCDH_MAX_SIZE_OF_CONFIRM_TEXT_DATA_BYTES + 26*CC_32BIT_WORD_SIZE/*separ.words*/ + \ 133 CC_FFCDH_CTX_TMP_BUFF_MAX_SIZE_IN_WORDS*CC_32BIT_WORD_SIZE)) 134 #define CC_FFCDH_CONTEXT_BUFF_SIZE_IN_WORDS (CC_FFCDH_CONTEXT_BUFF_SIZE_IN_BYTES / CC_32BIT_WORD_SIZE) 135 136 #define CC_FFCDH_CALC_USER_MAC_TAG FALSE 137 #define CC_FFCDH_CALC_PARTN_MAC_TAG TRUE 138 139 /*! Key size used for FIPS tests.*/ 140 #define CC_FFCDH_FIPS_PRIME_SIZE_VALUE_IN_BITS 2048 141 #define CC_FFCDH_FIPS_PRIME_SIZE_VALUE_IN_WORDS (CC_FFCDH_FIPS_PRIME_SIZE_VALUE_IN_BITS / CC_BITS_IN_32BIT_WORD) 142 #define CC_FFCDH_FIPS_ORDER_SIZE_VALUE_IN_WORDS 32 143 144 145 146 /************************ Enums ********************************/ 147 148 /*! Key derivation modes according NIST SP 800-56A ver.2 sec. 5.8.2 with reference to 149 * SP 800-56C sec. 4, SP 800-108 and RFC 5869. */ 150 typedef enum 151 { 152 CC_FFCDH_KDF_HMAC_RFC5869_MODE, /*!< extraction-then-expansion KDF(RFC 5869), based on HMAC function; 153 note: input salt assumed to be NULL. */ 154 CC_FFCDH_KDF_NUM_OFF_MODE, /*!< not allowed value */ 155 CC_FFCDH_KDF_MODE_LAST = 0x7FFFFFFF 156 } CCFfcDhKdfModeSp56A_t; 157 158 159 /*! FFC DH key Agreement Schemes enumeration according to 160 NIST SP 56A Rev. 2, Section 6, tab. 10-12. */ 161 typedef enum 162 { 163 CC_FFCDH_SCHEM_HYBRID1, /*!< dhHybrid1 C(2e, 2s, FFC DH) */ 164 CC_FFCDH_SCHEM_HYBRID_ONE_FLOW, /*!< dhHybridOneFlow C(1e, 2s, FFC DH) */ 165 CC_FFCDH_SCHEM_EPHEM, /*!< dhEphem C(2e, 0s, FFC DH) */ 166 CC_FFCDH_SCHEM_ONE_FLOW, /*!< dhOneFlow C(1e, 1s, FFC DH) */ 167 CC_FFCDH_SCHEM_STATIC, /*!< dhStatic C(0e, 2s, FFC DH) */ 168 CC_FFCDH_SCHEM_NUM_OFF_MODE, /*!< not allowed value */ 169 CC_FFCDH_SCHEM_LAST = 0x7FFFFFFF 170 } CCFfcDhSchemeId_t; 171 172 /*! An enumeration ID, defining user role in DH Agreement, represented as U, V 173 in NIST SP 56A Rev. 2, Sections 3.1, 5.8.1.2, 5.9.1, 6 */ 174 typedef enum 175 { 176 CC_FFCDH_PARTY_U, /*!< party U of Key Agreement */ 177 CC_FFCDH_PARTY_V, /*!< party V of Key Agreement */ 178 CC_FFCDH_PARTY_NUM_OFF_MODE, /*!< not allowed value */ 179 CC_FFCDH_PARTY_LAST = 0x7FFFFFFF 180 } CCFfcDhUserPartyIs_t; 181 182 /*! DH Agreement Confirmation mode: which parts is provider or/and receiver. 183 NIST SP 56A Rev. 2, Sections 5.9, 6.1, 6.2, 6.3 */ 184 typedef enum 185 { 186 CC_FFCDH_CONFIRM_U_TO_V, /*!< only party U provides MacTag to V. */ 187 CC_FFCDH_CONFIRM_V_TO_U, /*!< only party V provides MacTag to U. */ 188 CC_FFCDH_CONFIRM_BILATERAL, /*!< each party provides MacTag to other. */ 189 CC_FFCDH_CONFIRM_NOT_USED, /*!< the confirmation is not performed by the scheme */ 190 CC_FFCDH_CONFIRM_NUM_OFF_MODE, /*!< not allowed value */ 191 CC_FFCDH_CONFIRM_MODE_LAST = 0x7FFFFFFF 192 }CCFfcDhUserConfirmMode_t; 193 194 195 /*! DH key status according to its life time (or purpose): static/ephemeral */ 196 typedef enum 197 { 198 CC_FFCDH_KEY_STATIC, /*!< static (long term) key */ 199 CC_FFCDH_KEY_EPHEMER, /*!< ephemeral (one-time) key */ 200 CC_FFCDH_KEY_STATUS_NUM_OFF_MODE, /*!< not allowed value */ 201 CC_FFCDH_KEY_STATUS_LAST = 0x7FFFFFFF 202 } CCFfcDhKeyStatus_t; 203 204 205 /*! FFC DH Public Key validation mode definitions : 206 (such enumerator mode should be given for each key separately). */ 207 typedef enum { 208 CC_FFCDH_KEY_VALIDAT_FULL_MODE, /*!< full validation (NIST SP 56A Rev. 2) */ 209 CC_FFCDH_KEY_VALIDAT_PARTIAL_MODE, /*!< checking of sizes, pointers and ranges; 210 this mode may be used on user's responsibility 211 when he has assurance about received data */ 212 CC_FFCDH_KEY_VALIDAT_NUM_OFF_MODE, /*!< not allowed value */ 213 CC_FFCDH_KEY_VALIDAT_MODE_LAST = 0x7FFFFFFF 214 } CCFfcDhKeyValidMode_t; 215 216 /*! FFC DH both PartyInfo (Public Keys) validation mode definitions (NIST SP 56A Rev. 2). 217 Such enumerator mode might be applied to all existed Public keys, belonging to the party, 218 namely: static and ephemeral keys. If full mode for any existed key is not defined, 219 then it will be validated partially (checking of sizes, pointers and ranges). */ 220 typedef enum { 221 CC_FFCDH_STAT_KEY_FULL_VALIDAT_MODE, /*!< full validation of static key only */ 222 CC_FFCDH_EPHEM_KEY_FULL_VALIDAT_MODE, /*!< full validation of ephemeral key only */ 223 CC_FFCDH_BOTH_KEYS_FULL_VALIDAT_MODE, /*!< full validation of both keys */ 224 CC_FFCDH_NO_FULL_VALIDAT_MODE, /*!< only partial validation of existed keys */ 225 CC_FFCDH_KEYS_VALIDAT_NUM_OFF_MODE, /*!< not allowed value */ 226 CC_FFCDH_KEYS_VALIDAT_MODE_LAST = 0x7FFFFFFF 227 } CCFfcDhPartyInfoValidMode_t; 228 229 230 /************************ Structures ***********************************/ 231 232 /*! FFC Domain parameters structure (p,q,g,{seed,genCounter}. */ 233 //#define CCFfcDhDomain_t CCFfcDomain_t 234 235 /*! FFC DH Domain parameters sets definition: NIST SP 56A Rev. 2, sec. 5.8.1, tab.6, 236 * Note: modulus (prime) size 3072 is not allowed in FFC DH. */ 237 //#define CCFfcDhParamSetId_t CCFfcParamSetId_t 238 239 /**************************************************************/ 240 /*! Definition of PartyInfo entry structure. 241 The structure (buffer) containing data, which should be supplied, to the key agreement 242 by any Party (partyU or partyV) and used for derivation of Shared Secret Keying Data. \par 243 The data should be constructed according to concatenation method, described in 244 NIST SP 56A rev.2 standard sec. 5.8.1, and the following requirements: 245 246 <ul><li> PartyInfo = PartyInfoLen||PartyId||PartyNonce{||PartyOtherData}, where 247 each sub-entry is formatted as follows: </li> 248 <li> - entries in {} parenthesis are optional. </li> 249 <li> - each sub-entry is formatted as length (Len), followed by the data: Len||Data; </li> 250 <li> - length (Len) is a 2-bytes big endianness counter; </li> 251 <li> - actual length of PartyInfo shall be not great than CC_FFCDH_MAX_SIZE_OF_OTHER_INFO_ENTRY bytes. </li> 252 <li> - if any explicitly defined there optionally entry or sub-entry is omitted, then its length 253 should be set zero and data is empty string. </li></ul> 254 \note Said requirements are mandatory and should be agreed by both parties as a part of Key 255 Establishment Agreement protocol. 256 */ 257 typedef struct CCFfcDhPartyInfo_t{ 258 uint8_t data[CC_FFCDH_MAX_SIZE_OF_PARTY_INFO_BYTES]; 259 }CCFfcDhPartyInfo_t; 260 261 /**************************************************************/ 262 /*! Definition of OtherInfo structure. 263 This structure containing "other data", shared by both key agreement parties 264 and used for derivation of Shared Secret Keying Data. \par 265 The data should be constructed according to concatenation method, described in 266 NIST SP 56A rev.2 standard sec. 5.8.1, and the following requirements: 267 268 <ul><li> OtherInfo data should be concatenated according to the roles, performed by each 269 party in the Key Agreement (partyU or partyV), and include the following entries: </li> 270 <li> AlgorithmId||PartyUInfo||PartyVInfo {||SuppPubInfo}{||SuppPrivInfo}, where each entry 271 is formatted as follows: </li> 272 <li> - entries in {} parenthesis are optional. </li> 273 <li> - each entry could include some sub-entries, which are formatted as length (Len), followed 274 by the data of said length: Len||Data; </li> 275 <li> - length (Len) of the data is formatted as 2-bytes big endianness counter; </li> 276 <li> - numerical parameters, such as size of HMAC-Key etc., are considered as separate sub-entry 277 and formatted accordingly; 278 <li> - actual length of OtherInfo shall be not great than CC_FFCDH_MAX_SIZE_OF_OTHER_INFO_DATA_BYTES bytes. </li> 279 <li> - if any explicitly defined optionally entry or sub-entry is omitted, then its length 280 should be zero and data array remained empty. </li></ul> 281 <ul><li> Formatting of separate entries is described below (each sub-entry includes Len||Data): </li> 282 <li> - AlgorithmId entry includes information how the extracted keying material should be parsed between 283 HMAC Key (used for internal calculation of Confirmation MacTag) and between Key for External Algorithm, 284 i.e. output SecretKeyingData. This entry also includes ID of algorithms, for which these keys are intended: 285 AlgorithmId = HmacKeySize||InternalAlgorithmId||ExternalAlgorithmKeySize||ExternalAlgorithmId, where 286 first two sub-entries will be set by CC functions as array: 0x00||0x02||0x00||0x04||"HMAC" and 287 sub-entries, related to ExternalAlgorithm, should be given by the user as input to appropriate CC functions. </li> 288 <li> - PartyUInfo and PartyVInfo should be constructed as described in CCFfcDhPartyInfo_t structure. </li> 289 <li> - Optional SuppPubInfo and SuppPrivInfo entries and their sub-entries should be defined in the Key 290 Agreement protocol. </li></ul> 291 \note Said requirements are mandatory and should be agreed by both parties as a part of Key Establishment 292 Agreement protocol. 293 */ 294 typedef struct CCFfcDhOtherInfo_t{ 295 uint8_t data[CC_FFCDH_MAX_SIZE_OF_OTHER_INFO_DATA_BYTES/*884 bytes ???*/]; 296 }CCFfcDhOtherInfo_t; 297 298 /**************************************************************/ 299 /*! Definition of MAC Data structure, containing data, known to both key agreement 300 parties and used for key confirmation. \par 301 The data should be constructed according to NIST SP 56A rev.2 standard, 302 sec. 5.9, 5.9.1.1 and the following requirements: 303 <ul><li> MacData should be concatenated according to the role, performed by the user 304 in the Key Agreement: is he partyU or partyV and is he confirmation provider (P) 305 or recipient (R): </li> 306 <li> MacDataP = messageStringP||IDP||IDR{||EphemDataP}||EphemDataR{||TextP}, 307 where each entry is formatted as follows: </li> 308 <li> - actually, instead letters "P" and "R" must be set "U" or "V" according to parties roles in DH Scheme; </li> 309 <li> - EphemData is an EphemeralPublicKey or Nonce, contributed by the party to the Agreement; </li> 310 <li> - messageStringP is a 6-byte string, defined in the sec.5.9.1, 5.9.2 according to used DH Scheme; <li> 311 <li> - TextP is an optional bit-string about Confirmation, known to both parties; </li> 312 <li> - each entry is formatted as length, followed by bytes-array of data: Len||Data; </li> 313 <li> - length (Len) of the data is formatted as 2-bytes big endianness counter; </li> 314 <li> - if any explicitly defined there optionally sub-entry is omitted, then its length should be 315 zero and data array remained empty. </li></ul> 316 <li> - total length of MacDataP shall be not great than CC_FFCDH_MAX_SIZE_OF_MAC_DATA bytes. </li></ul> 317 \note Confirmation is possible (effective) only if Confirmation Receiver contribute an EphemeralKey or Nonce 318 to the Key Agreement. 319 \note Said requirements are mandatory and should be agreed by both parties as a part of Key Establishment 320 Agreement protocol. 321 */ 322 typedef struct CCFfcDhConfirmMacData_t{ 323 uint32_t sizeInBytes; /*!< actual size of data in the MacData buffer, in bytes */ 324 uint8_t macData[CC_FFCDH_MAX_SIZE_OF_CONFIRM_MAC_DATA_BYTES]; 325 } CCFfcDhConfirmMacData_t; 326 327 328 /**************************************************************/ 329 /*! DH Key Agreement Confirmation MacTag, calculated as HMAC of MacData. 330 See NIST SP 56A rev.2 standard, sec. 5.9. Optionally MacTag may be 331 truncated (sec. 5.9.3) */ 332 typedef struct CCFfcDhConfirmMacTag_t{ 333 uint32_t sizeInBytes; 334 uint8_t macTag[CC_FFCDH_MAX_SIZE_OF_CONFIRM_MAC_TAG_BYTES]; 335 }CCFfcDhConfirmMacTag_t; 336 337 338 typedef struct CCFfcDhHashBlockAndDigestSizes_t{ 339 uint32_t blockSizeInBytes; /*!< HASH function block size in bytes */ 340 uint32_t digestSizeInBytes; /*!< HASH function digest (output) size in bytes */ 341 } CCFfcDhHashBlockAndDigestSizes_t; 342 343 344 /**************************************************************/ 345 /*! The structure containing the FFC DH Public Key parameters. */ 346 typedef struct CCFfcDhPublKey_t 347 { 348 size_t keySizeBits; 349 uint32_t pubKey[CC_FFCDH_MAX_MOD_SIZE_IN_WORDS]; /*!< Public Key .*/ 350 CCFfcDhKeyStatus_t status; /*! enumerator, defining the key status according to its lifetime 351 or purpose: static/ephemeral/nonce */ 352 }CCFfcDhPublKey_t; 353 354 355 /**************************************************************/ 356 /*! The FFC DH public key's user structure prototype. This structure must be saved by the user, 357 and is used as input to the DH functions (such as ::CC_FfcDhGeneratePubPrv etc.). */ 358 typedef struct CCFfcDhUserPubKey_t 359 { 360 uint32_t validTag; /*!< Validation tag.*/ 361 uint32_t publKeyDbBuff[CALC_32BIT_WORDS_FROM_BYTES(sizeof(CCFfcDhPublKey_t))]; /*!< Public key data. */ 362 }CCFfcDhUserPubKey_t; 363 364 #ifdef FFC_FURTHER_USING 365 /**************************************************************/ 366 /*! The structure containing the FFC DH Public Keys parameters. */ 367 typedef struct CCFfcDhCtxPublKeys_t 368 { 369 uint32_t statKeySizeBytes; 370 uint8_t statPublKey[CC_FFCDH_MAX_MOD_SIZE_IN_WORDS]; 371 uint32_t ephemKeySizeBytes; 372 uint32_t ephemPublKey[CC_FFCDH_MAX_MOD_SIZE_IN_WORDS]; 373 uint32_t nonceSizeBytes; 374 uint32_t userNonce[CC_FFCDH_MAX_GENER_ORDER_SIZE_IN_WORDS]; 375 }CCFfcDhCtxPublKeys_t; 376 377 378 /**************************************************************/ 379 /*! The structure containing the FFC DH Private Key parameters. 380 \note The maximal bit length of private key must be 160, 224 or 256 381 according to NIST SP 56A rev.2, sec.5.5.1.1 */ 382 typedef struct CCFfcDhPrivKey_t 383 { 384 /*! Private Key exponent.*/ 385 size_t keySizeBits; 386 uint32_t key[CC_FFCDH_MAX_GENER_ORDER_SIZE_IN_WORDS + FFCDH_RND_ADDING_SIZE_BYTES]; 387 CCFfcDhKeyStatus_t status; /*! enumerator, defining the key status according to its lifetime 388 or purpose: static/ephemeral/nonce */ 389 }CCFfcDhPrivKey_t; 390 391 392 /**************************************************************/ 393 /*! The FFC DH public key's user structure prototype. This structure must be saved by the user 394 as secret, and is used as input to the DH functions (such as ::CC_FfcDhGeneratePubPrv etc.). */ 395 typedef struct CCFfcDhUserPrivKey_t 396 { 397 uint32_t validTag; /*!< key validation tag. */ 398 uint32_t privKeyDbBuff[CALC_32BIT_WORDS_FROM_BYTES(sizeof(CCFfcDhPrivKey_t))]; /*!< Private key data. */ 399 }CCFfcDhUserPrivKey_t; 400 401 402 /**************************************************************/ 403 /*! The structure defines context temp buffer, used for internal calculations. 404 \note The maximal bit length of private key must be 160, 224 or 256 405 according to NIST SP 56A rev.2, sec.5.5.1.1 */ 406 typedef struct CCFfcDhCtxTempBuff_t 407 { 408 uint32_t key[CC_FFCDH_CTX_TMP_BUFF_MAX_SIZE_IN_WORDS]; 409 }CCFfcDhCtxTempBuff_t; 410 411 #endif 412 413 /* temp buffer structure, used for DH functions */ 414 typedef struct CCFfcDhTemp_t 415 { 416 uint32_t TempBuff[CC_FFCDH_CTX_TMP_BUFF_MAX_SIZE_IN_WORDS]; 417 } CCFfcDhTemp_t; 418 419 420 /* Definition of name of function that translates the FCC Domain and DH Hash modes into 421 * HASH, KDF-Hash modes and gives HASH block and digest sizes (in bytes). Note: the function 422 * sets on output only required parameters, which pointers are not NULL. 423 * */ 424 #define FfcDhGetHashMode FfcDomainGetHashMode 425 426 /***************************************************************************/ 427 /*!< Set of DH FFC parameters size approved by NIST SP 800-56A rev.2. tab.6,8 428 Intended for initialisation of array of structures of following type. 429 */ 430 #define CCFfcDhDomainParamSizes_t CCFfcDomainParamSizes_t 431 432 /**************************************************************/ 433 /*! DH Key Agreement user context structure is passed by the user to the DH APIs. 434 The context saves the state of the operations and must be saved by the user 435 till the end of the APIs flow. */ 436 typedef struct CCFfcDhUserContext_t 437 { 438 /*! Validation tag. */ 439 uint32_t validTag; 440 /*! Private data context buffer. */ 441 uint32_t contextBuff[CC_FFCDH_CONTEXT_BUFF_SIZE_IN_WORDS]; 442 // uint32_t contextBuff[(sizeof(DhContext_t)+3)/4]; 443 } CCFfcDhUserContext_t; 444 445 446 447 /***************************************************************************/ 448 /*! Definition of FFC-DH buffer used for FIPS Known Answer Tests. */ 449 typedef struct 450 { 451 /* FFC Domain parameters */ 452 uint32_t prime[CC_FFCDH_FIPS_PRIME_SIZE_VALUE_IN_WORDS]; /*!< prime modulus - in KAT used 2048 bit size. */ 453 uint32_t generator[CC_FFCDH_FIPS_PRIME_SIZE_VALUE_IN_WORDS]; /*!< FFC sub-group generator */ 454 uint32_t order[CC_FFCDH_FIPS_ORDER_SIZE_VALUE_IN_WORDS]; /*!< order of FFC sub-group - in KAT used 256 bit size*/ 455 uint32_t privKey[CC_FFCDH_FIPS_ORDER_SIZE_VALUE_IN_WORDS]; /*!< private key */ 456 uint32_t pubKey[CC_FFCDH_FIPS_PRIME_SIZE_VALUE_IN_WORDS]; /*!< public key */ 457 CCFfcDhTemp_t tmpBuff; /*!< temporary buffer */ 458 } CCFfcDhFipsKat_t; 459 460 461 /************************ Public Variables ******************************/ 462 /*!< Set of DH FFC parameters sizes, approved by NIST SP 800-56A rev.2: sec. 5.8.1, 5.9.3. 463 Intended for initialization of array of structures of type CCFfcDhFfcDomainParamSizes_t. 464 All sizes are given in bytes. 465 \note Index of array is given according to CCFfcDhFfcParamsSetId_t enumerator: 466 {CC_FFCDH_PARAMS_SET_FA, CC_FFCDH_PARAMS_SET_FB, CC_FFCDH_PARAMS_SET_FC} = {0,1,2}. 467 */ 468 #define CC_FFCDH_DOMAIN_PARAM_SIZES_SET CC_FFC_DOMAIN_PARAM_SIZES_SET 469 //{{80,1024,160,80},{112,2048,224,112},{112,2048,256,112}} 470 /*! Define and init parameters array */ 471 //CCFfcDhDomainParamSizes_t ffcDomainParamSizes[(uint32_t)CC_FFCDH_PARAMS_SET_NUM_OFF_MODE] = FFCDH_DOMAIN_PARAM_SIZES_SET; 472 473 /*! Array of allowed HASH SHA-x block and digest sizes for all SHA modes (size in bytes). 474 \note Index of array is according to CCFfcDhParamsSetId_t enumerator: {CC_HASH_SHA1_mode, CC_HASH_SHA224_mode, CC_HASH_SHA256_mode, 475 CC_HASH_SHA384_mode, CC_HASH_SHA512_mode} = {0,1,2,3,4}. */ 476 #define CC_DH_SHA_PARAMETERS_SIZES_IN_BYTES CC_FFC_SHA_PARAMETERS_SIZES_IN_BYTES 477 //{{64,20},{64,28},{64,32},{128,48},{128,64}} 478 /*! Define and initialize HASH parameters array */ 479 //CCFfcDhHashBlockAndDigestSizes_t DhHashBlockAndDigestSizes[(uint32_t)CC_FFCDH_HASH_NUM_OFF_MODE] = 480 // DH_SHA_PARAMETERS_SIZES_IN_BYTES; 481 482 483 /************************ Public Functions ******************************/ 484 485 /*******************************************************************************************/ 486 /*! The functions initializes the DH Context structure: 487 <li> zeroes context buffers, initializes 3 MS bytes of validation tag by context ID and sets LS byte 488 to zero to prepare it for further indications of setting appropriate parts of data into context 489 */ 490 CIMPORT_C CCError_t CC_FfcDhInitCtx( CCFfcDhUserContext_t *pDhUserCtx); 491 492 493 /*******************************************************************************************/ 494 /*! The functions destroys (zeroes) the DH Context structure. 495 496 @return CC_OK on success. 497 @return A non-zero value on failure as defined cc_dh_error.h. 498 499 */ 500 CIMPORT_C CCError_t CC_FfcDhFreeCtx( CCFfcDhUserContext_t *pDhUserCtx); 501 502 503 /*******************************************************************************************/ 504 /*! The function sets into DH context FFCDH Scheme agreed parameters: SchemeId, User role, Confirmation mode etc. 505 \note The context is used in DH Agreement functions, implementing NIST SP 800-56A rev.2 standard. 506 \note Assumed, that input FFC Domain is properly generated or imported and validated according to 507 NIST SP 800-56A and FIPS 186-4 standards. 508 509 @return CC_OK on success. 510 @return A non-zero value on failure as defined cc_dh_error.h. 511 */ 512 CEXPORT_C CCError_t CC_FfcDhCtxSetSchemeParams( 513 CCFfcDhUserContext_t *pDhUserCtx, /*!< [in/out] pointer to context structure, containing all parameters and data, 514 defining DH Key Agreement Scheme */ 515 CCFfcDomain_t *pDomain, /*!< [in] pointer to DH FFC Domain structure. */ 516 uint8_t *pAlgId, /*!< [in] pointer to Algorithm ID agreed by both parties and indicates how the derived 517 secret keying material will be parsed and for which algorithms (sec.5.8.1.2). 518 In partial, Algorithm ID should indicate also how much bits are intended for 519 internal confirmation MAC algorithm and how much remaining bits will be 520 returned to the user for external applications/algorithms (the total size should 521 be equal to chosen secretKeyDataSize). */ 522 size_t algIdSize, /*!< [in] size of Algorithm ID in bytes, should be less than 523 CC_FFCDH_MAX_SIZE_OF_ALG_ID_SUB_ENTRY. */ 524 size_t secretKeyingDataSize, /*!< [in] size in bytes of shared secret keying data, which will be extracted and in 525 the next steps and passed to the user for using in external algorithm(s). 526 It is used for calculation of Derived Keying material size = 527 key size of the used HMAC function + secretKeyingDataSize. */ 528 uint8_t *pUserId, /*!< [in] pointer to the user ID - a distinct identifier of the user. */ 529 size_t userIdSize, /*!< [in] size of the user ID in bytes. */ 530 uint8_t *pPartnId, /*!< [in] pointer to the partner ID - a distinct identifier of the party. */ 531 size_t partnIdSize, /*!< [in] size of the partner ID in bytes. */ 532 CCFfcDhUserPartyIs_t userParty, /*!< [in] enumerator, defining role of the user (function's caller) in the 533 DH Agreement Scheme: partyU or partyV. */ 534 CCFfcDhSchemeId_t dhSchemeId, /*!< [in] enumerator ID of used FFC DH Key Agreement Scheme, as defined 535 in sec. 6, tab. 12. */ 536 CCFfcParamSetId_t ffcParamSetId, /*!< [in] enumerator, defining the set of FFC domain parameters 537 according to SP 56A rev.2 section 5.5.1.1, tab.1. */ 538 CCFfcDhKdfModeSp56A_t kdfMode, /*!< [in] enumerator ID of used KDF function, based on HASH or HMAC algorithms. In current 539 implementation is allowed only KDF HMAC_RFC5869 mode, according to KDF_HMAC_RFC-5869. */ 540 CCFfcHashOpMode_t ffcHashMode, /*!< [in] enumerator ID of used SHAXXX HASH mode, supported by the product. 541 Note: HASH SHA1 function may be used only with SA set of domain parameters 542 (sec. 5.8.1, tab.6); with other sets the function returns an error. */ 543 CCFfcDhUserConfirmMode_t confirmMode, /*!< enumerator, defining confirmation mode of each party: provider 544 or/and recipient, according to sec. 5.9. */ 545 uint8_t *pHmacSalt, /*!< [in] optional, pointer to the Salt, used as key in HMAC-KDF function on appropriate modes. 546 If HMAC-KDF mode is set, and the pointer and size are zero, then the Salt is 547 treated as full-zero bytes array of size equalled to block-size of used HMAC function. 548 If HMAC-KDF mode is HMAC_RFC5869_MODE, then the Salt is treated as HMAC Key. 549 If only one of parameters (pointer and size) is zero, but other not, then the 550 function returns an error. */ 551 size_t hmacSaltSize, /*!< [in] optional, size of Salt in bytes, should be equalled to the HMAC block size if 552 salt is used. */ 553 size_t macTagSize /*!< [in] optional, size in bytes ofof confirmation MacTag. Should be in range: 554 [CC_FFCDH_MIN_SIZE_OF_CONFIRM_MAC_TAG_BYTES, CC_FFCDH_MAX_SIZE_OF_CONFIRM_MAC_TAG_BYTES]. */ 555 ); 556 557 558 559 /*******************************************************************************************/ 560 /*! 561 @brief The function generates FFC DH key pairs according to DH Scheme and NIST SP 800-56A rev.2 standard: 562 <ol><li> - count of required key pairs (one or two is dependent on DH Scheme and user Party (U or V), 563 inserted into Context. For each of key pair the function performs the following steps: </li> 564 <li> - randomly generates the private key X according to section 5.6.1.1 and FIPS 184-4, B.1.1; </li> 565 <li> - the sizes of primes P,Q should be taken from DH FFC sizes set previously inserted into Context; </li> 566 <li> - calculates the associated public key Y = G^X mod P; </li> 567 <li> - sets private and public keys in appropriate place in the Context according to user party (U,V) and keys 568 status (static, ephemeral); </li> 569 <li> - exports the public key as big endianness order of bytes. </li></ol> 570 \note Before calling of this function, DH context should be initialized, DH Scheme parameters and 571 DH Domain are inserted by calling appropriate functions, else the function returns an error. 572 573 @return CC_OK on success. 574 @return A non-zero value on failure as defined cc_dh_error.h, cc_rnd_error.h. 575 */ 576 CIMPORT_C CCError_t CC_FfcDhGeneratePublPrivKeys( 577 CCFfcDhUserContext_t *pDhUserCtx,/*!< [in/out] pointer to DH FFC User Context structure. */ 578 CCRndContext_t *pRndContext /*!< [in] random generation function context. */ 579 ); 580 581 /*******************************************************************************************/ 582 /*! 583 @brief This function validates the FFC DH public key according to NIST SP 800-56A rev.2, 584 sec.5.6.2.3.1 and checking mode: 585 586 <ul><li> - on "partial" mode - checks the pointers and high/low limits of key value;</li> 587 <li> - on "full" mode - checks also that the the key belongs to the FFC subgroup; </li></ul> 588 \note Before calling of this function, appropriate FFC Domain parameters should be obtained and validated, 589 else the function returns an error. 590 @return CC_OK on success. 591 @return A non-zero value on failure as defined cc_dh_error.h. 592 */ 593 CIMPORT_C CCError_t CC_FfcDhValidatePublKey( 594 CCFfcDomain_t *pFfcDomain, /*!< [in/out] pointer to DH FFC Context structure. */ 595 uint8_t *pPublKeyData, /*!< [in] pointer to given DH FFC public key formatted as big endianness array; 596 it should be in range [2, P-2], where P is the Domain Prime P. */ 597 size_t publKeyDataSize, /*!< [in] pointer to public key size, in bytes: should be not great than Prime size. */ 598 599 CCFfcDhKeyValidMode_t validatMode, /*!< [in] enumerator ID defining the validation mode: 600 CC_FFCDH_CHECK_FULL_MODE - full validation (sec. 5.6.2.3.1); 601 CC_FFCDH_CHECK_PARTIAL_MODE - check pointers, sizes and range of values. */ 602 uint32_t *pTmpBuff); /*!< [in] temporary buffer of size not less 2*Prime size. ??? */ 603 604 605 606 /*******************************************************************************************/ 607 /*! 608 @brief The function checks and sets the FFC DH partner's public key into DH Context 609 according to NIST SP 800-56A rev.2 sec.5.6.2.3.1 and checking mode: 610 611 <ul><li> - if the key belongs to user's party, then the function returns an error, meaning 612 that the user should use other function to import both public and private keys together;</li>. 613 <li> - on "partial" mode - checks the pointers and high/low limits of key value;</li> 614 <li> - on "full" mode - checks also that the the key belongs to the FFC subgroup; </li> 615 <li> - sets the key data into DH Context according to party's role and key status. </li></ul> 616 \note Before calling of this function, DH context should be initialized and Scheme and FFC Domain 617 parameters are inserted by calling appropriate functions, else the function returns an error. 618 @return CC_OK on success. 619 @return A non-zero value on failure as defined cc_dh_error.h. 620 */ 621 CIMPORT_C CCError_t CC_FfcDhValidateAndImportPublKey( 622 CCFfcDhUserContext_t *pDhUserCtx, /*!< [in/out] pointer to DH FFC Context structure. */ 623 uint8_t *pPublKeyData, /*!< [in] pointer to given DH FFC public key or Nonce in big endianness; 624 it should be in range [2, P-2], where P is the Domain Prime. */ 625 size_t publKeyDataSize, /*!< [in] public key size, in bytes: should be not great than Domain Prime size. */ 626 CCFfcDhKeyValidMode_t validatMode, /*!< [in] enumerator ID defining the validation mode: 627 CC_FFCDH_CHECK_FULL_MODE - full validation (sec. 5.6.2.3.1); 628 CC_FFCDH_CHECK_PARTIAL_MODE - check pointers, sizes and range of values; 629 Note: for Nonce only size and range checking is performed. */ 630 CCFfcDhKeyStatus_t keyStatus /*!< [in] enumerator, defining the key status according to its life time 631 or purpose: static/ephemeral/nonce */ 632 ); 633 634 635 636 637 /*******************************************************************************************/ 638 /*! 639 @brief The function checks and sets the FFC DH user's private/public key pair into DH Context 640 according to NIST SP 800-56A rev.2 sec.5.6.2.3.1 and checking mode: 641 642 <ul><li> - if the key belongs to partner's party, then the function returns an error, meaning 643 that the user should use other function to import only public key;</li>. 644 <li> - on "partial" mode - checks the pointers and high/low limits of key value;</li> 645 <li> - on "full" mode - checks also that the the public key meets to private key; </li> 646 <li> - sets the key data into DH Context according to party's role and key status. </li></ul> 647 \note Before calling of this function, DH context should be initialized and Scheme and FFC Domain 648 parameters are inserted by calling appropriate functions, else the function returns an error. 649 @return CC_OK on success. 650 @return A non-zero value on failure as defined cc_dh_error.h. 651 */ 652 CIMPORT_C CCError_t CC_FfcDhValidateAndImportKeyPair( 653 CCFfcDhUserContext_t *pDhUserCtx, /*!< [in/out] pointer to DH FFC Context structure. */ 654 uint8_t *pPrivKeyData, /*!< [in] pointer to given DH FFC private key in big endianness; 655 it should be in range [1, n-1], where n is the Domain generator order. */ 656 size_t privKeyDataSize, /*!< [in] private key size, in bytes: should be equaled Domain 657 generator order size. */ 658 uint8_t *pPublKeyData, /*!< [in] pointer to given DH FFC public key in big endianness; 659 it should be in range [2, P-2], where P is the Domain Prime. */ 660 size_t publKeyDataSize, /*!< [in] public key size, in bytes: should be equaled to Domain Prime size, 661 including leading zeros. */ 662 CCFfcDhKeyValidMode_t validatMode, /*!< [in] enumerator ID defining the validation mode: 663 CC_FFCDH_CHECK_FULL_MODE - full validation (sec. 5.6.2.3.1); 664 CC_FFCDH_CHECK_PARTIAL_MODE - check pointers, sizes and range of values. */ 665 CCFfcDhKeyStatus_t keyStatus /*!< [in] enumerator, defining the key status according to its life time 666 or purpose: static/ephemeral/nonce */ 667 ); 668 669 /*******************************************************************************************/ 670 /*! 671 @brief This function generates random Nonce, used in appropriate DH Schemes (NIST SP 56A rev.2 sec.5.9, 6). 672 <li> The function generates random vector of given size, sets it into DH context according. </li> 673 \note Before calling of this function, DH context should be initialized and Scheme parameters and 674 DH Domain are inserted by calling appropriate functions, else the function returns an error. 675 \note The Nonce should be generated and the function called only if it is required by DH scheme, and 676 the Nonce is not inserted previously, else the function returns an error. 677 \note The function is used when the user not generates an ephemeral key, but requires key confirmation and 678 therefore Nonce generation. 679 @return CC_OK on success. 680 @return A non-zero value on failure as defined cc_dh_error.h. 681 */ 682 CIMPORT_C CCError_t CC_FfcDhGenerateRandomNonce( 683 CCFfcDhUserContext_t *pDhUserCtx, /*!< [in/out] pointer to DH FFC Context structure. */ 684 CCRndContext_t *pRndContext); /*!< [in] random generation function context. */ 685 686 687 688 /*******************************************************************************************/ 689 /*! 690 @brief This function formats the UserInfo according to the user role (PartyU or PartyV) and NIST SP 56A rev.2, 691 sec. 5.8.1.2, 5.8.1.2.1. 692 693 <ul><li> Input and previously inserted data is concatenated as defined in the CCFfcDhPartyInfo_t structure and 694 sets it into the Context: UserInfo = UserId||UserStatPublKey||UserStatPublKey||UserNonce}{||UserOtherData}, where: </li> 695 <li> - UserInfo and each its sub-entry are formatted as length (Len) and then appropriate data: Len||Data, 696 where each length is a 2-bytes big endianness counter; </li> 697 <li> - If any sub-entry is not used in chosen DH Scheme, than its lengths should be set 0 and the data is empty. </li> 698 <li> - total size of PartyInfo, including said lengths, should be not great, than the size of CCDhPartyInfo_t. </li></ul> 699 \note Before calling of this function the User should initialize DH Context, insert FFC Domain, DH Scheme parameters and 700 all his Private/Public Keys (or Nonce) using appropriate CC functions. 701 \note The output from this function will be exported to the other party of the Agreement and vice versa, UserInfo, received 702 from other party, will be used as input to DhCtxSetSchemeData() function. 703 704 @return CC_OK on success. 705 @return A non-zero value on failure as defined cc_dh_error.h. 706 */ 707 CIMPORT_C CCError_t CC_FfcDhCreateUserInfo( 708 CCFfcDhUserContext_t *pDhUserCtx, /*!< [in/out] pointer to context structure, containing all data, 709 used in DH Key Agreement Scheme. */ 710 uint8_t *pUserOtherData, /*!< [in] optional, pointer to other data, which the user will 711 insert in addition to its ID, keys and Nonce. */ 712 size_t userOtherDataSize, /*!< [in] optional, size of additional data (in bytes), which the 713 user will include into the UserInfo. */ 714 uint8_t *pUserConfirmText, /*!< [in] optional, pointer to confirmation Text of the User. */ 715 size_t userConfirmTextSize, /*!< [in] optional size of Text data of partyU, in bytes. */ 716 CCFfcDhPartyInfo_t *pUserInfo, /*!< [out] pointer to the concatenated UserInfo (i.e. PartyU or PartyV Info). */ 717 size_t *pUserInfoSize /*!< [in/out] pointer to the size of UserInfo, in bytes: 718 in - given buffer size (should be not less than CC_FFCDH_MAX_SIZE_OF_OTHER_INFO_ENTRY; 719 out - actual size of UserInfo, including length counters */ 720 ); 721 722 723 /*******************************************************************************************/ 724 /*! 725 @brief This function checks and sets given "OtherInfo" entries, calculates shared secret value and 726 derives the "secret keying material". 727 The function's implementation meets to NIST SP 56A rev.2 standard requirements. 728 \note Before calling of this function, DH Context should be initialized, DH Scheme, Domain parameters and all 729 required user's Private, Public keys or nonces are inserted by calling appropriate CC functions. 730 <ul><li> The function sets input data into the Context to form the "OtherInfo" (sec. 5.8.1) according to 731 said standard and the implementation requirements: 732 <li> - OtherInfo = AlgorithmId||PartyUInfo||PartyVInfo {||SuppPubInfo}{||SuppPrivInfo}, where each PartyInfo is 733 formatted as : </li> 734 <li> - Remark: AlgorithmId includes information about length in bits of derived Keying Material and its 735 parsing between internal using for confirmation HMAC algorithm and output Secret Keying Data 736 and algorithm, which it is intended for. </li> 737 <li> - PartyInfo = PartyId||PartyStatPublKey||PartyEphemKey||PartyNonce{||PartyOtherData}. </li> 738 <li> - for detailed description of "OtherInfo" construction and concatenation its sub-entries, see 739 CCFfcDhOtherInfo_t structure definition; </li></ul> 740 \note - the function performs the following calculations: 741 <ul><li> - calculates shared secret value according to DH Scheme: 742 - SharedSecretVal = (PublKey1 ^ PrivKey1) modulo Prime or 743 - SharedSecretVal = (PartnPublKey1 ^ UserPrivKey1) || (PartnPublKey2 ^ UserPrivKey2) modulo Prime; </li> 744 <li> - derives the secret keying material of required size from the shared secret value by calling KDF function 745 with shared OtherInfo data: DerivedKeyingMaterial = KDF(ZZ, OtherInfo, keyingMaterialSize); </li></ul> 746 <ul><li> - If DH Scheme includes Key Confirmation, then the function calculates confirmation HMAC MacTag, which is 747 intended to be provided to the partner (sec. 5.2, 5.9, 6); in this case the secret keying material is parsed to MacKey 748 of size, equaled to HMAC key size. </li> 749 <li> - in our implementation HMAC key size is defined to be equaled to FFC sub-group order (meets to sec.5.9.3). </li> 750 <li> - if in the chosen DH Scheme the user is not a Confirmation Provider, then both the pointer and the size of 751 appropriate MacTag should be set to NULL. </li> 752 <li> - for detailed description of Confirmation "MacData" see CCFfcDhConfirmMacData_t structure definition. </li></ul> 753 754 @return CC_OK on success. 755 @return A non-zero value on failure as defined cc_dh_error.h. 756 */ 757 CIMPORT_C CCError_t CC_FfcDhSetAndCalculateSchemeData( 758 CCFfcDhUserContext_t *pDhUserCtx, /*!< [in/out] pointer to context structure, containing all data, used in DH Key 759 Agreement Scheme, required for implementation of said standard. */ 760 /*! Partner's Data to be included into OtherInfo entry. Detailed description see in CCFfcDhOtherInfo_t. */ 761 uint8_t *pPartnerInfo, /*!< [in] pointer to the concatenated PartnerInfo. Detailed description see in CCFfcDhOtherInfo_t. */ 762 size_t sizeOfPartnerInfo, /*!< [in] size of PartnerInfo, in bytes, should be <= CC_FFCDH_MAX_SIZE_OF_PARTY_INFO_BYTES. */ 763 CCFfcDhPartyInfoValidMode_t partnInfoValidMode, /*!< enumerator, defining which of public keys (static, ephemeral), 764 included in the PartnerInfo, should be full validated and which partial only. */ 765 uint8_t *pSuppPubInfo, /*!< [in] pointer to optional shared public data to be included into SuppPubInfo entry */ 766 size_t suppPubInfoSize, /*!< [in] size of SuppPubInfo data, in bytes. */ 767 uint8_t *pSuppPrivInfo, /*!< [in] pointer to optional shared private data to be included into SuppPrivInfo entry */ 768 size_t suppPrivInfoSize, /*!< [in] size of other SuppPrivInfo data, in bytes (should be not great than 769 CC_FFCDH_MAX_SIZE_OF_OTHER_INFO_SUPPL_ENTRY_BYTES */ 770 uint8_t *pUserMacTag, /*!< [out] optional, pointer to the user-provider confirmation MacTag depending 771 on used Key Agreement Scheme. The tag is calculated by HMAC with given 772 hashMode, as described in SP800-56A sec. 5.9. */ 773 size_t macTagSize /*!< [in] optional, required size in bytes of confirmation MacTag. */ 774 ); 775 776 777 ///******************************************************************************************/ 778 ///*! 779 //@brief The function calculates user's confirmation MacTags for FFC DH Schemes according to NIST SP 56A rev.2 standard. 780 // 781 //\note Before calling of this function the user should obtain assurance of used FFC Domain and public, private keys, 782 //involved in the key agreement, using one of the methods, described in sec. 5.6.2 of above named standard. 783 //<ul><li> - depending on DH Scheme, calculates confirmation HMAC MacTag, which is intended to be provided to the partner 784 //(sec. 5.2, 5.9, 6); in this case the secret keying material is parsed to MacKey of size, equaled to HMAC key size. </li> 785 //<li> - in our implementation HMAC key size defined equal to FFC sub-group order (meets to sec.5.9.3). </li> 786 //<li> - if in the chosen DH Scheme the user is not Confirmation provider, then both the pointer and the size of 787 //appropriate MacTag should be set to NULL. </li> 788 //<li> - for detailed description of Confirmation "MacData" see CCFfcDhConfirmMacData_t structure definition. </li></ul> 789 // 790 //@return CC_OK on success. 791 //@return A non-zero value on failure as defined in cc_dh_error.h, cc_kdf_error.h or cc_hash_error.h. 792 //*/ 793 //CIMPORT_C CCError_t CC_FfcDhCalcConfirmMacTags( 794 // CCFfcDhUserContext_t *pDhUserCtx, /*!< [in] pointer to the user's DH context structure, containing all data, defining 795 // DH Key Agreement Scheme. The context shall be initialized for user's roles 796 // (U or V; Provider or Receiver) using CC_FfcDhSetCtx function. */ 797 // uint8_t *pUserMacTag, /*!< [out] optional, pointer to the user (provider) confirmation MacTag depending 798 // on used Key Agreement Scheme. The tag is calculated by HMAC with given 799 // hashMode, as described in section 5.9. */ 800 // size_t *pMacTagSize, /*!< [in/out] optional, required size of MacTag, in bytes; maximal allowed size is the 801 // HMAC output size; minimal size is 8 bytes according to tab. 8 of said standard. */ 802 // uint8_t *pUserConfirmText, /*!< [in] optional, pointer to confirmation Text of the User. */ 803 // uint8_t userConfirmTextSize, /*!< [in] optional size of Text data of partyU, in bytes. */ 804 // uint8_t *pPartnerConfirmText, /*!< [in] optional, pointer to confirmation Text of the Partner. */ 805 // uint8_t partnerConfirmTextSize /*!< [in] optional, size of Text data of partyV, in bytes. */ 806 //); 807 808 809 /*******************************************************************************************/ 810 /*! 811 @brief This function performs DH Key Agreement Confirmation and, on success, outputs the shared keying data. 812 The function calculates expected partner's confirmation MacTag' and compares it to value, 813 received from the partner. 814 <li> If the tags are not equaled, then the function returns an error and zeroes the secure 815 sensitive data. </li> 816 <li> If no errors, the function puts the derived secret keying data into output buffer. </li> 817 \note Assumed, that the user yet have obtained assurance of public and private keys, 818 involved in the key agreement. 819 \note Before calling this function the user should perform all required DH Key Agreement 820 operations, including calculation of shared secret keying material by calling 821 CC_FfcDhCalcUserConfirmMacTag function. 822 \note If according to chosen Scheme the user is not a Confirmation Recipient, 823 then all, the pointer and the size of MacTag should be 824 set to zero, else the function returns an error. 825 826 @return CC_OK on success. 827 @return A non-zero value on failure as defined in cc_dh_error.h 828 */ 829 CIMPORT_C CCError_t CC_FfcDhGetSharedSecretKeyingData( 830 CCFfcDhUserContext_t *pDhUserCtx, /*!< [in] pointer to the user's DH context structure, containing all data, 831 defining DH Key Agreement Scheme and its results. */ 832 uint8_t *pSecretKeyData, /*!< [out] pointer to the shared secret keying data, extracted 833 from keying material after parsing to . */ 834 size_t *pSecretKeyDataSize, /*!< [in/out] the pointer to the size of shared secret key data: 835 in - size of the given output buffer, out - actual size of extracted 836 key data */ 837 uint8_t *pPartnerMacTag, /*!< [in] optional, pointer to the confirmation MacTag, provided by the partner */ 838 size_t macTagSize /*!< [in] optional, size of partner's MacTag, in bytes */ 839 ); 840 841 842 843 /*******************************************************************************************/ 844 /*! 845 @brief This function implements FFC DH primitive according to section 5.7.1.1 of NIST SP 56A rev.2 standard. 846 The function computes the shared secret value: SharedSecretVal = partnerPublKey ^ userPrivKey modulo Prime. 847 \note Before calling of this function the user should obtain assurance of FFC Domain, public and private keys, involved in the key 848 agreement, using one of methods, described in section 5.6.2 of above named standard. 849 \note For assurance of keys validity the user can use appropriate APIs for generating or building and validation, 850 of keys, described in cc_ffcdh.h file. 851 \note The function intended of-first for internal using in Keying Material derivation inside CC DH functions. 852 @return CC_OK on success. 853 @return A non-zero value on failure as defined in cc_dh_error.h or cc_rnd_error.h. 854 */ 855 CIMPORT_C CCError_t CC_FfcDhGetSharedSecretVal( 856 CCFfcDomain_t *pDomain, /*!< [in/out] pointer to DH FFC Context structure. */ 857 uint8_t *pSharedSecretVal, /*!< [out] pointer to the shared secret value in big endianness order 858 of bytes in the array (MS-byte is a most left one). This 859 buffer should be at least of prime (modulus) size in bytes. */ 860 size_t *pSharedSecretValSize, /*!< [in/out] pointer to the shared secret value size: 861 input - size of the given buffer, it should be at least 862 prime (modulus) size bytes; output - actual size. */ 863 uint8_t *pPrivKeyData, /*!< [in] pointer to given DH FFC private key in big endianness; 864 the Key should be in range [1, n-1], where n is the Domain 865 generator order. */ 866 size_t privKeyDataSize, /*!< [in] private key size, in bytes: should be not great than Domain 867 generator order size. */ 868 uint8_t *pPublKeyData, /*!< [in] pointer to given DH FFC public key in big endianness; 869 the key should be in range [2, P-2], where P is the Domain Prime. */ 870 size_t publKeyDataSize, /*!< [in] public key size, in bytes: should be not great than Domain Prime size. */ 871 uint32_t *pTmpBuff /*!< [in] pointer to temp buffer of size */ 872 ); 873 874 875 876 877 #ifdef __cplusplus 878 } 879 #endif 880 /** 881 @} 882 */ 883 #endif 884
