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 @addtogroup cc_ecpki_types 9 @{ 10 */ 11 12 /*! 13 @file 14 @brief This file contains all the type definitions that are used for the 15 CryptoCell ECPKI APIs. 16 */ 17 18 #ifndef _CC_ECPKI_TYPES_H 19 #define _CC_ECPKI_TYPES_H 20 21 22 #include "cc_bitops.h" 23 #include "cc_pal_types_plat.h" 24 #include "cc_hash_defs.h" 25 #include "cc_pka_defs_hw.h" 26 #include "cc_pal_compiler.h" 27 #ifdef USE_MBEDTLS_CRYPTOCELL 28 #include "mbedtls/md.h" 29 #endif 30 31 #ifdef __cplusplus 32 extern "C" 33 { 34 #endif 35 36 37 /************************ Defines ******************************/ 38 /*! The size of the internal buffer in words. */ 39 #define CC_PKA_DOMAIN_LLF_BUFF_SIZE_IN_WORDS (10 + 3*CC_ECPKI_MODUL_MAX_LENGTH_IN_WORDS) 40 41 /************************************************************************************** 42 * Enumerators 43 ***************************************************************************************/ 44 45 /*------------------------------------------------------------------*/ 46 /*! @brief EC domain idetifiers. 47 48 For more information, see <em>Standards for Efficient Cryptography Group 49 (SECG): SEC2 Recommended Elliptic Curve Domain Parameters, Version 1.0</em>. 50 */ 51 typedef enum 52 { 53 /* For prime field */ 54 /*! EC secp192k1. */ 55 CC_ECPKI_DomainID_secp192k1, 56 /*! EC secp192r1. */ 57 CC_ECPKI_DomainID_secp192r1, 58 /*! EC secp224k1. */ 59 CC_ECPKI_DomainID_secp224k1, 60 /*! EC secp224r1. */ 61 CC_ECPKI_DomainID_secp224r1, 62 /*! EC secp256k1. */ 63 CC_ECPKI_DomainID_secp256k1, 64 /*! EC secp256r1. */ 65 CC_ECPKI_DomainID_secp256r1, 66 /*! EC secp384r1. */ 67 CC_ECPKI_DomainID_secp384r1, 68 /*! EC secp521r1. */ 69 CC_ECPKI_DomainID_secp521r1, 70 /*! Reserved.*/ 71 CC_ECPKI_DomainID_OffMode, 72 /*! Reserved.*/ 73 CC_ECPKI_DomainIDLast = 0x7FFFFFFF, 74 75 }CCEcpkiDomainID_t; 76 77 78 /*------------------------------------------------------------------*/ 79 /*! 80 @brief Hash operation mode. 81 82 Defines hash modes according to <em>IEEE 1363-2000: IEEE Standard for 83 Standard Specifications for Public-Key Cryptography</em>. 84 */ 85 typedef enum 86 { 87 /*! The message data will be hashed with SHA-1. */ 88 CC_ECPKI_HASH_SHA1_mode = 0, 89 /*! The message data will be hashed with SHA-224. */ 90 CC_ECPKI_HASH_SHA224_mode = 1, 91 /*! The message data will be hashed with SHA-256. */ 92 CC_ECPKI_HASH_SHA256_mode = 2, 93 /*! The message data will be hashed with SHA-384. */ 94 CC_ECPKI_HASH_SHA384_mode = 3, 95 /*! The message data will be hashed with SHA-512. */ 96 CC_ECPKI_HASH_SHA512_mode = 4, 97 /*! The message data is a digest of SHA-1 and will not be hashed. */ 98 CC_ECPKI_AFTER_HASH_SHA1_mode = 5, 99 /*! The message data is a digest of SHA-224 and will not be hashed. */ 100 CC_ECPKI_AFTER_HASH_SHA224_mode = 6, 101 /*! The message data is a digest of SHA-256 and will not be hashed. */ 102 CC_ECPKI_AFTER_HASH_SHA256_mode = 7, 103 /*! The message data is a digest of SHA-384 and will not be hashed. */ 104 CC_ECPKI_AFTER_HASH_SHA384_mode = 8, 105 /*! The message data is a digest of SHA-512 and will not be hashed. */ 106 CC_ECPKI_AFTER_HASH_SHA512_mode = 9, 107 /*! The maximal number of hash modes. */ 108 CC_ECPKI_HASH_NumOfModes, 109 /*! Reserved. */ 110 CC_ECPKI_HASH_OpModeLast = 0x7FFFFFFF, 111 112 }CCEcpkiHashOpMode_t; 113 114 115 /*---------------------------------------------------*/ 116 /*! EC point-compression identifiers. 117 */ 118 typedef enum 119 { 120 /*! A compressed point. */ 121 CC_EC_PointCompressed = 2, 122 /*! An uncompressed point. */ 123 CC_EC_PointUncompressed = 4, 124 /*! An incorrect point-control value. */ 125 CC_EC_PointContWrong = 5, 126 /*! A hybrid point. */ 127 CC_EC_PointHybrid = 6, 128 /*! Reserved. */ 129 CC_EC_PointCompresOffMode = 8, 130 /*! Reserved. */ 131 CC_ECPKI_PointCompressionLast= 0x7FFFFFFF, 132 }CCEcpkiPointCompression_t; 133 134 /*----------------------------------------------------*/ 135 /*! EC key checks. */ 136 typedef enum { 137 /*! Check only preliminary input parameters. */ 138 CheckPointersAndSizesOnly = 0, 139 /*! Check preliminary input parameters and verify that the EC public-key 140 point is on the curve. */ 141 ECpublKeyPartlyCheck = 1, 142 /*! Check preliminary input parameters, verify that the EC public-key 143 point is on the curve, and verify that \c EC_GeneratorOrder*PubKey = 0 */ 144 ECpublKeyFullCheck = 2, 145 /*! Reserved. */ 146 PublKeyChecingOffMode, 147 /*! Reserved. */ 148 EC_PublKeyCheckModeLast = 0x7FFFFFFF, 149 }ECPublKeyCheckMode_t; 150 151 /*----------------------------------------------------*/ 152 /*! SW SCA protection type. */ 153 typedef enum { 154 /*! SCA protection inactive. */ 155 SCAP_Inactive, 156 /*! SCA protection active. */ 157 SCAP_Active, 158 /*! Reserved. */ 159 SCAP_OFF_MODE, 160 /*! Reserved. */ 161 SCAP_LAST = 0x7FFFFFFF 162 }CCEcpkiScaProtection_t; 163 164 /************************************************************************************** 165 * EC Domain structure definition 166 ***************************************************************************************/ 167 168 /*! 169 @brief The structure containing the EC domain parameters in little-endian 170 form. 171 172 EC equation: \c Y^2 = \c X^3 + \c A*X + \c B over prime field \p GFp. 173 */ 174 typedef struct { 175 /*! EC modulus: P. */ 176 uint32_t ecP [CC_ECPKI_MODUL_MAX_LENGTH_IN_WORDS]; 177 /*! EC equation parameter A. */ 178 uint32_t ecA [CC_ECPKI_MODUL_MAX_LENGTH_IN_WORDS]; 179 /*! EC equation parameter B. */ 180 uint32_t ecB [CC_ECPKI_MODUL_MAX_LENGTH_IN_WORDS]; 181 /*! Order of generator. */ 182 uint32_t ecR [CC_ECPKI_MODUL_MAX_LENGTH_IN_WORDS + 1]; 183 /*! EC cofactor EC_Cofactor_K. The coordinates of the EC base point 184 generator in projective form. */ 185 uint32_t ecGx [CC_ECPKI_MODUL_MAX_LENGTH_IN_WORDS]; 186 /*! EC cofactor EC_Cofactor_K. The coordinates of the EC base point 187 generator in projective form. */ 188 uint32_t ecGy [CC_ECPKI_MODUL_MAX_LENGTH_IN_WORDS]; 189 /*! EC cofactor EC_Cofactor_K. The coordinates of the EC base point 190 generator in projective form. */ 191 uint32_t ecH; 192 /*! Specific fields that are used by the low-level functions.*/ 193 uint32_t llfBuff[CC_PKA_DOMAIN_LLF_BUFF_SIZE_IN_WORDS]; 194 /*! The size of fields in bits. */ 195 uint32_t modSizeInBits; 196 /*! The size of the order in bits. */ 197 uint32_t ordSizeInBits; 198 /*! The size of each inserted Barret tag in words. Zero if not inserted.*/ 199 uint32_t barrTagSizeInWords; 200 /*! The EC Domain identifier. */ 201 CCEcpkiDomainID_t DomainID; 202 /*! Internal buffer. */ 203 int8_t name[20]; 204 }CCEcpkiDomain_t; 205 206 207 208 /************************************************************************************** 209 * EC point structures definitions 210 ***************************************************************************************/ 211 212 /*! The structure containing the EC point in affine coordinates 213 and little endian form. */ 214 typedef struct 215 { 216 /*! The X coordinate of the point. */ 217 uint32_t x[CC_ECPKI_MODUL_MAX_LENGTH_IN_WORDS]; 218 /*! The Y coordinate of the point. */ 219 uint32_t y[CC_ECPKI_MODUL_MAX_LENGTH_IN_WORDS]; 220 221 }CCEcpkiPointAffine_t; 222 223 224 /************************************************************************************** 225 * ECPKI public and private key Structures 226 ***************************************************************************************/ 227 228 /* --------------------------------------------------------------------- */ 229 /* .................. The public key structures definitions ............ */ 230 /* --------------------------------------------------------------------- */ 231 232 /*! The structure containing the public key in affine coordinates.*/ 233 typedef struct 234 { 235 /*! The X coordinate of the public key.*/ 236 uint32_t x[CC_ECPKI_MODUL_MAX_LENGTH_IN_WORDS]; 237 /*! The Y coordinate of the public key.*/ 238 uint32_t y[CC_ECPKI_MODUL_MAX_LENGTH_IN_WORDS]; 239 /*! The EC Domain.*/ 240 CCEcpkiDomain_t domain; 241 /*! The point type.*/ 242 uint32_t pointType; 243 } CCEcpkiPublKey_t; 244 245 246 /*! 247 @brief The user structure prototype of the EC public key. 248 249 This structure must be saved by the user. It is used as input to ECC functions, 250 for example, CC_EcdsaVerify(). 251 */ 252 typedef struct CCEcpkiUserPublKey_t 253 { 254 /*! The validation tag. */ 255 uint32_t valid_tag; 256 /*! The data of the public key. */ 257 uint32_t PublKeyDbBuff[(sizeof(CCEcpkiPublKey_t)+3)/4]; 258 } CCEcpkiUserPublKey_t; 259 260 261 /* --------------------------------------------------------------------- */ 262 /* .................. The private key structures definitions ........... */ 263 /* --------------------------------------------------------------------- */ 264 265 /*! The structure containing the data of the private key. */ 266 typedef struct 267 { 268 /*! The data of the private key. */ 269 uint32_t PrivKey[CC_ECPKI_MODUL_MAX_LENGTH_IN_WORDS + 1]; 270 /*! The EC domain. */ 271 CCEcpkiDomain_t domain; 272 /*! The SCA protection mode. */ 273 CCEcpkiScaProtection_t scaProtection; 274 }CCEcpkiPrivKey_t; 275 276 277 /*! 278 @brief The user structure prototype of the EC private key. 279 280 This structure must be saved by the user. It is used as input to ECC functions, 281 for example, CC_EcdsaSign(). 282 */ 283 typedef struct CCEcpkiUserPrivKey_t 284 { 285 /*! The validation tag. */ 286 uint32_t valid_tag; 287 /*! The data of the private key. */ 288 uint32_t PrivKeyDbBuff[(sizeof(CCEcpkiPrivKey_t)+3)/4]; 289 } CCEcpkiUserPrivKey_t; 290 291 /*! The type of the ECDH temporary data. */ 292 typedef struct CCEcdhTempData_t 293 { 294 /*! Temporary buffers. */ 295 uint32_t ccEcdhIntBuff[CC_PKA_ECDH_BUFF_MAX_LENGTH_IN_WORDS]; 296 }CCEcdhTempData_t; 297 298 /*! EC build temporary data. */ 299 typedef struct CCEcpkiBuildTempData_t 300 { 301 /*! Temporary buffers. */ 302 uint32_t ccBuildTmpIntBuff[CC_PKA_ECPKI_BUILD_TMP_BUFF_MAX_LENGTH_IN_WORDS]; 303 }CCEcpkiBuildTempData_t; 304 305 306 307 /************************************************************************** 308 * CryptoCell ECDSA context structures 309 **************************************************************************/ 310 311 /* --------------------------------------------------------------------- */ 312 /* CryptoCell ECDSA Signing context structure */ 313 /* --------------------------------------------------------------------- */ 314 /*! The internal buffer used in the signing process. */ 315 typedef uint32_t CCEcdsaSignIntBuff_t[CC_PKA_ECDSA_SIGN_BUFF_MAX_LENGTH_IN_WORDS]; 316 317 /*! The context definition for the signing operation. */ 318 typedef struct 319 { 320 /*! The data of the private key. */ 321 CCEcpkiUserPrivKey_t ECDSA_SignerPrivKey; 322 323 #ifdef USE_MBEDTLS_CRYPTOCELL 324 /*! The hash context. */ 325 mbedtls_md_context_t hash_ctx; 326 #else 327 /*! The hash context. */ 328 CCHashUserContext_t hashUserCtxBuff; 329 #endif 330 /*! The hash result buffer. */ 331 CCHashResultBuf_t hashResult; 332 /*! The size of the hash result in words. */ 333 uint32_t hashResultSizeWords; 334 /*! The hash mode. */ 335 CCEcpkiHashOpMode_t hashMode; 336 /*! Internal buffer. */ 337 CCEcdsaSignIntBuff_t ecdsaSignIntBuff; 338 }EcdsaSignContext_t; 339 340 341 /* --------------------------------------------------------------------- */ 342 /* ECDSA Signing User context database */ 343 /* --------------------------------------------------------------------- */ 344 345 /*! 346 @brief The context definition of the user for the signing operation. 347 348 This context saves the state of the operation, and must be saved by the user 349 until the end of the API flow. 350 */ 351 typedef struct CCEcdsaSignUserContext_t 352 { 353 /*! The data of the signing process. */ 354 uint32_t context_buff [(sizeof(EcdsaSignContext_t)+3)/4]; 355 /*! The validation tag. */ 356 uint32_t valid_tag; 357 } CCEcdsaSignUserContext_t; 358 359 360 361 /****************************************************************************/ 362 363 /* --------------------------------------------------------------------- */ 364 /* ECDSA Verifying context structure */ 365 /* --------------------------------------------------------------------- */ 366 /*! The internal buffer used in the verification process. */ 367 typedef uint32_t CCEcdsaVerifyIntBuff_t[CC_PKA_ECDSA_VERIFY_BUFF_MAX_LENGTH_IN_WORDS]; 368 369 /*! The context definition for verification operation. */ 370 typedef struct 371 { 372 /*! The data of the public key. */ 373 CCEcpkiUserPublKey_t ECDSA_SignerPublKey; 374 375 #ifdef USE_MBEDTLS_CRYPTOCELL 376 /*! The hash context. */ 377 mbedtls_md_context_t hash_ctx; 378 #else 379 /*! The hash context. */ 380 CCHashUserContext_t hashUserCtxBuff; 381 #endif 382 /*! The hash result. */ 383 CCHashResultBuf_t hashResult; 384 /*! The size of the hash result in words. */ 385 uint32_t hashResultSizeWords; 386 /*! The hash mode. */ 387 CCEcpkiHashOpMode_t hashMode; 388 /*! Internal buffer. */ 389 CCEcdsaVerifyIntBuff_t ccEcdsaVerIntBuff; 390 }EcdsaVerifyContext_t; 391 392 393 /* --------------------------------------------------------------------- */ 394 /* ECDSA Verifying User context database */ 395 /* --------------------------------------------------------------------- */ 396 /*! 397 @brief The context definition of the user for the verification operation. 398 399 The context saves the state of the operation, and must be saved by the user 400 until the end of the API flow. 401 */ 402 typedef struct CCEcdsaVerifyUserContext_t 403 { 404 /*! The data of the verification process. */ 405 uint32_t context_buff[(sizeof(EcdsaVerifyContext_t)+3)/4]; 406 /*! The validation tag. */ 407 uint32_t valid_tag; 408 }CCEcdsaVerifyUserContext_t; 409 410 411 /* --------------------------------------------------------------------- */ 412 /* .................. key generation temp buffer ........... */ 413 /* --------------------------------------------------------------------- */ 414 415 /*! The temporary data type of the ECPKI KG. */ 416 typedef struct CCEcpkiKgTempData_t 417 { 418 /*! Internal buffer. */ 419 uint32_t ccKGIntBuff[CC_PKA_KG_BUFF_MAX_LENGTH_IN_WORDS]; 420 }CCEcpkiKgTempData_t; 421 422 /*! The temporary data definition of the ECIES. */ 423 typedef struct CCEciesTempData_t { 424 /*! The data of the private key. */ 425 CCEcpkiUserPrivKey_t PrivKey; 426 /*! The data of the public key. */ 427 CCEcpkiUserPublKey_t PublKey; 428 /*! The public-key data used by conversion from Mbed TLS to CryptoCell. */ 429 CCEcpkiUserPublKey_t ConvPublKey; 430 /*! Internal buffer. */ 431 uint32_t zz[3*CC_ECPKI_MODUL_MAX_LENGTH_IN_WORDS + 1]; 432 /*! Internal buffers. */ 433 union { 434 CCEcpkiBuildTempData_t buildTempbuff; 435 CCEcpkiKgTempData_t KgTempBuff; 436 CCEcdhTempData_t DhTempBuff; 437 } tmp; 438 }CCEciesTempData_t; 439 440 441 /* --------------------------------------------------------------------- */ 442 /* .................. defines for FIPS ........... */ 443 /* --------------------------------------------------------------------- */ 444 445 /*! The order length for FIPS ECC tests. */ 446 #define CC_ECPKI_FIPS_ORDER_LENGTH (256/CC_BITS_IN_BYTE) // the order of secp256r1 in bytes 447 448 /*! ECPKI data structures for FIPS certification. */ 449 typedef struct CCEcpkiKgFipsContext_t 450 { 451 /*! Signing and verification data. */ 452 union { 453 CCEcdsaSignUserContext_t signCtx; 454 CCEcdsaVerifyUserContext_t verifyCtx; 455 }operationCtx; 456 /*! Internal buffer. */ 457 uint32_t signBuff[2*CC_ECPKI_ORDER_MAX_LENGTH_IN_WORDS] ; 458 }CCEcpkiKgFipsContext_t; 459 460 /*! ECDSA KAT data structures for FIPS certification. 461 The ECDSA KAT tests are defined for domain 256r1. */ 462 typedef struct CCEcdsaFipsKatContext_t{ 463 /*! The key data. */ 464 union { 465 /*! The private key data. */ 466 struct { 467 CCEcpkiUserPrivKey_t PrivKey; 468 CCEcdsaSignUserContext_t signCtx; 469 }userSignData; 470 /*! The public key data. */ 471 struct { 472 CCEcpkiUserPublKey_t PublKey; 473 union { 474 CCEcdsaVerifyUserContext_t verifyCtx; 475 CCEcpkiBuildTempData_t tempData; 476 }buildOrVerify; 477 }userVerifyData; 478 }keyContextData; 479 /*! Internal buffer. */ 480 uint8_t signBuff[2*CC_ECPKI_FIPS_ORDER_LENGTH]; 481 }CCEcdsaFipsKatContext_t; 482 483 /*! ECDH KAT data structures for FIPS certification. */ 484 typedef struct CCEcdhFipsKatContext_t{ 485 /*! The public key data. */ 486 CCEcpkiUserPublKey_t pubKey; 487 /*! The private key data. */ 488 CCEcpkiUserPrivKey_t privKey; 489 /*! Internal buffers. */ 490 union { 491 CCEcpkiBuildTempData_t ecpkiTempData; 492 CCEcdhTempData_t ecdhTempBuff; 493 }tmpData; 494 /*! The buffer for the secret key. */ 495 uint8_t secretBuff[CC_ECPKI_FIPS_ORDER_LENGTH]; 496 }CCEcdhFipsKatContext_t; 497 498 #ifdef __cplusplus 499 } 500 #endif 501 502 /*! 503 @} 504 */ 505 #endif 506 507
