1 /** 2 * Copyright Notice: 3 * Copyright 2021-2022 DMTF. All rights reserved. 4 * License: BSD 3-Clause License. For full text see link: https://github.com/DMTF/libspdm/blob/main/LICENSE.md 5 **/ 6 7 #ifndef CRYPTLIB_EXT_H 8 #define CRYPTLIB_EXT_H 9 10 #include "hal/base.h" 11 #include "hal/library/cryptlib.h" 12 13 /** 14 * Retrieve the common name (CN) string from one X.509 certificate. 15 * 16 * @param[in] cert Pointer to the DER-encoded X509 certificate. 17 * @param[in] cert_size Size of the X509 certificate in bytes. 18 * @param[out] common_name Buffer to contain the retrieved certificate common 19 * name string (UTF8). At most common_name_size bytes will be 20 * written and the string will be null terminated. May be 21 * NULL in order to determine the size buffer needed. 22 * @param[in,out] common_name_size The size in bytes of the common_name buffer on input, 23 * and the size of buffer returned common_name on output. 24 * If common_name is NULL then the amount of space needed 25 * in buffer (including the final null) is returned. 26 * 27 * @retval true 28 * @retval false 29 **/ 30 extern bool libspdm_x509_get_common_name(const uint8_t *cert, size_t cert_size, 31 char *common_name, 32 size_t *common_name_size); 33 34 /** 35 * Retrieve the organization name (O) string from one X.509 certificate. 36 * 37 * @param[in] cert Pointer to the DER-encoded X509 certificate. 38 * @param[in] cert_size Size of the X509 certificate in bytes. 39 * @param[out] name_buffer Buffer to contain the retrieved certificate organization 40 * name string. At most name_buffer_size bytes will be 41 * written and the string will be null terminated. May be 42 * NULL in order to determine the size buffer needed. 43 * @param[in,out] name_buffer_size The size in bytes of the name buffer on input, 44 * and the size of buffer returned name on output. 45 * If name_buffer is NULL then the amount of space needed 46 * in buffer (including the final null) is returned. 47 * 48 * @retval true 49 * @retval false 50 **/ 51 extern bool libspdm_x509_get_organization_name(const uint8_t *cert, size_t cert_size, 52 char *name_buffer, 53 size_t *name_buffer_size); 54 55 /** 56 * Retrieve the issuer common name (CN) string from one X.509 certificate. 57 * 58 * @param[in] cert Pointer to the DER-encoded X509 certificate. 59 * @param[in] cert_size Size of the X509 certificate in bytes. 60 * @param[out] common_name Buffer to contain the retrieved certificate issuer common 61 * name string. At most common_name_size bytes will be 62 * written and the string will be null terminated. May be 63 * NULL in order to determine the size buffer needed. 64 * @param[in,out] common_name_size The size in bytes of the common_name buffer on input, 65 * and the size of buffer returned common_name on output. 66 * If common_name is NULL then the amount of space needed 67 * in buffer (including the final null) is returned. 68 * 69 * @retval true 70 * @retval false 71 **/ 72 extern bool libspdm_x509_get_issuer_common_name(const uint8_t *cert, size_t cert_size, 73 char *common_name, 74 size_t *common_name_size); 75 76 /** 77 * Retrieve the issuer organization name (O) string from one X.509 certificate. 78 * 79 * @param[in] cert Pointer to the DER-encoded X509 certificate. 80 * @param[in] cert_size Size of the X509 certificate in bytes. 81 * @param[out] name_buffer Buffer to contain the retrieved certificate issuer organization 82 * name string. At most name_buffer_size bytes will be 83 * written and the string will be null terminated. May be 84 * NULL in order to determine the size buffer needed. 85 * @param[in,out] name_buffer_size The size in bytes of the name buffer on input, 86 * and the size of buffer returned name on output. 87 * If name_buffer is NULL then the amount of space needed 88 * in buffer (including the final null) is returned. 89 * 90 * @retval true 91 * @retval false 92 **/ 93 extern bool libspdm_x509_get_issuer_orgnization_name(const uint8_t *cert, size_t cert_size, 94 char *name_buffer, 95 size_t *name_buffer_size); 96 97 /** 98 * Retrieve the signature algorithm from one X.509 certificate. 99 * 100 * @param[in] cert Pointer to the DER-encoded X509 certificate. 101 * @param[in] cert_size Size of the X509 certificate in bytes. 102 * @param[out] oid Signature algorithm Object identifier buffer. 103 * @param[in,out] oid_size Signature algorithm Object identifier buffer size. 104 * 105 * @retval true 106 * @retval false 107 **/ 108 extern bool libspdm_x509_get_signature_algorithm(const uint8_t *cert, 109 size_t cert_size, uint8_t *oid, 110 size_t *oid_size); 111 112 /** 113 * Construct a X509 object from DER-encoded certificate data. 114 * 115 * If cert is NULL, then return false. 116 * If single_x509_cert is NULL, then return false. 117 * If this interface is not supported, then return false. 118 * 119 * @param[in] cert Pointer to the DER-encoded certificate data. 120 * @param[in] cert_size The size of certificate data in bytes. 121 * @param[out] single_x509_cert The generated X509 object. 122 * 123 * @retval true The X509 object generation succeeded. 124 * @retval false The operation failed. 125 * @retval false This interface is not supported. 126 **/ 127 extern bool libspdm_x509_construct_certificate(const uint8_t *cert, size_t cert_size, 128 uint8_t **single_x509_cert); 129 130 /** 131 * Construct a X509 stack object from a list of DER-encoded certificate data. 132 * 133 * If x509_stack is NULL, then return false. 134 * If this interface is not supported, then return false. 135 * 136 * @param[in, out] x509_stack On input, pointer to an existing or NULL X509 stack object. 137 * On output, pointer to the X509 stack object with new 138 * inserted X509 certificate. 139 * @param ... A list of DER-encoded single certificate data followed 140 * by certificate size. A NULL terminates the list. The 141 * pairs are the arguments to libspdm_x509_construct_certificate(). 142 * 143 * @retval true The X509 stack construction succeeded. 144 * @retval false The construction operation failed. 145 * @retval false This interface is not supported. 146 **/ 147 extern bool libspdm_x509_construct_certificate_stack(uint8_t **x509_stack, ...); 148 149 /** 150 * Release the specified X509 object. 151 * 152 * If the interface is not supported, then ASSERT(). 153 * 154 * @param[in] x509_cert Pointer to the X509 object to be released. 155 **/ 156 extern void libspdm_x509_free(void *x509_cert); 157 158 /** 159 * Release the specified X509 stack object. 160 * 161 * If the interface is not supported, then ASSERT(). 162 * 163 * @param[in] x509_stack Pointer to the X509 stack object to be released. 164 **/ 165 extern void libspdm_x509_stack_free(void *x509_stack); 166 167 /** 168 * Retrieve the TBSCertificate from one given X.509 certificate. 169 * 170 * @param[in] cert Pointer to the given DER-encoded X509 certificate. 171 * @param[in] cert_size size of the X509 certificate in bytes. 172 * @param[out] tbs_cert DER-Encoded to-Be-Signed certificate. 173 * @param[out] tbs_cert_size size of the TBS certificate in bytes. 174 * 175 * If cert is NULL, then return false. 176 * If tbs_cert is NULL, then return false. 177 * If tbs_cert_size is NULL, then return false. 178 * If this interface is not supported, then return false. 179 * 180 * @retval true The TBSCertificate was retrieved successfully. 181 * @retval false Invalid X.509 certificate. 182 **/ 183 extern bool libspdm_x509_get_tbs_cert(const uint8_t *cert, size_t cert_size, 184 uint8_t **tbs_cert, size_t *tbs_cert_size); 185 186 /** 187 * Retrieve the RSA Private key from the password-protected PEM key data. 188 * 189 * If pem_data is NULL, then return false. 190 * If rsa_context is NULL, then return false. 191 * If this interface is not supported, then return false. 192 * 193 * @param[in] pem_data Pointer to the PEM-encoded key data to be retrieved. 194 * @param[in] pem_size Size of the PEM key data in bytes. 195 * @param[in] password NULL-terminated passphrase used for encrypted PEM key data. 196 * @param[out] rsa_context Pointer to newly generated RSA context which contain the retrieved 197 * RSA private key component. Use libspdm_rsa_free() function to free the 198 * resource. 199 * 200 * @retval true RSA Private key was retrieved successfully. 201 * @retval false Invalid PEM key data or incorrect password. 202 * @retval false This interface is not supported. 203 **/ 204 extern bool libspdm_rsa_get_private_key_from_pem(const uint8_t *pem_data, 205 size_t pem_size, 206 const char *password, 207 void **rsa_context); 208 209 #if (LIBSPDM_RSA_SSA_SUPPORT) || (LIBSPDM_RSA_PSS_SUPPORT) 210 /** 211 * Gets the tag-designated RSA key component from the established RSA context. 212 * 213 * This function retrieves the tag-designated RSA key component from the 214 * established RSA context as a non-negative integer (octet string format 215 * represented in RSA PKCS#1). 216 * If specified key component has not been set or has been cleared, then returned 217 * bn_size is set to 0. 218 * If the big_number buffer is too small to hold the contents of the key, false 219 * is returned and bn_size is set to the required buffer size to obtain the key. 220 * 221 * If rsa_context is NULL, then return false. 222 * If bn_size is NULL, then return false. 223 * If bn_size is large enough but big_number is NULL, then return false. 224 * If this interface is not supported, then return false. 225 * 226 * @param[in, out] rsa_context Pointer to RSA context being set. 227 * @param[in] key_tag Tag of RSA key component being set. 228 * @param[out] big_number Pointer to octet integer buffer. 229 * @param[in, out] bn_size On input, the size of big number buffer in bytes. 230 * On output, the size of data returned in big number buffer in bytes. 231 * 232 * @retval true RSA key component was retrieved successfully. 233 * @retval false Invalid RSA key component tag. 234 * @retval false bn_size is too small. 235 * @retval false This interface is not supported. 236 **/ 237 extern bool libspdm_rsa_get_key(void *rsa_context, const libspdm_rsa_key_tag_t key_tag, 238 uint8_t *big_number, size_t *bn_size); 239 240 /** 241 * Validates key components of RSA context. 242 * NOTE: This function performs integrity checks on all the RSA key material, so 243 * the RSA key structure must contain all the private key data. 244 * 245 * This function validates key components of RSA context in following aspects: 246 * - Whether p is a prime 247 * - Whether q is a prime 248 * - Whether n = p * q 249 * - Whether d*e = 1 mod lcm(p-1,q-1) 250 * 251 * If rsa_context is NULL, then return false. 252 * If this interface is not supported, then return false. 253 * 254 * @param[in] rsa_context Pointer to RSA context to check. 255 * 256 * @retval true RSA key components are valid. 257 * @retval false RSA key components are not valid. 258 * @retval false This interface is not supported. 259 **/ 260 extern bool libspdm_rsa_check_key(void *rsa_context); 261 262 /** 263 * Generates RSA key components. 264 * 265 * This function generates RSA key components. It takes RSA public exponent E and 266 * length in bits of RSA modulus N as input, and generates all key components. 267 * If public_exponent is NULL, the default RSA public exponent (0x10001) will be used. 268 * 269 * If rsa_context is NULL, then return false. 270 * If this interface is not supported, then return false. 271 * 272 * @param[in, out] rsa_context Pointer to RSA context being set. 273 * @param[in] modulus_length Length of RSA modulus N in bits. 274 * @param[in] public_exponent Pointer to RSA public exponent. 275 * @param[in] public_exponent_size Size of RSA public exponent buffer in bytes. 276 * 277 * @retval true RSA key component was generated successfully. 278 * @retval false Invalid RSA key component tag. 279 * @retval false This interface is not supported. 280 **/ 281 extern bool libspdm_rsa_generate_key(void *rsa_context, size_t modulus_length, 282 const uint8_t *public_exponent, 283 size_t public_exponent_size); 284 #endif /* (LIBSPDM_RSA_SSA_SUPPORT) || (LIBSPDM_RSA_PSS_SUPPORT) */ 285 286 /** 287 * Retrieve the EC Private key from the password-protected PEM key data. 288 * 289 * @param[in] pem_data Pointer to the PEM-encoded key data to be retrieved. 290 * @param[in] pem_size Size of the PEM key data in bytes. 291 * @param[in] password NULL-terminated passphrase used for encrypted PEM key data. 292 * @param[out] ec_context Pointer to newly generated EC DSA context which contain the retrieved 293 * EC private key component. Use libspdm_ec_free() function to free the 294 * resource. 295 * 296 * If pem_data is NULL, then return false. 297 * If ec_context is NULL, then return false. 298 * 299 * @retval true EC Private key was retrieved successfully. 300 * @retval false Invalid PEM key data or incorrect password. 301 * 302 **/ 303 extern bool libspdm_ec_get_private_key_from_pem(const uint8_t *pem_data, size_t pem_size, 304 const char *password, 305 void **ec_context); 306 307 /** 308 * Retrieve the Ed Private key from the password-protected PEM key data. 309 * 310 * @param[in] pem_data Pointer to the PEM-encoded key data to be retrieved. 311 * @param[in] pem_size Size of the PEM key data in bytes. 312 * @param[in] password NULL-terminated passphrase used for encrypted PEM key data. 313 * @param[out] ecd_context Pointer to newly generated Ed DSA context which contain the retrieved 314 * Ed private key component. Use libspdm_ecd_free() function to free the 315 * resource. 316 * 317 * If pem_data is NULL, then return false. 318 * If ecd_context is NULL, then return false. 319 * 320 * @retval true Ed Private key was retrieved successfully. 321 * @retval false Invalid PEM key data or incorrect password. 322 **/ 323 extern bool libspdm_ecd_get_private_key_from_pem(const uint8_t *pem_data, 324 size_t pem_size, 325 const char *password, 326 void **ecd_context); 327 328 /** 329 * Retrieve the sm2 Private key from the password-protected PEM key data. 330 * 331 * @param[in] pem_data Pointer to the PEM-encoded key data to be retrieved. 332 * @param[in] pem_size Size of the PEM key data in bytes. 333 * @param[in] password NULL-terminated passphrase used for encrypted PEM key data. 334 * @param[out] sm2_context Pointer to newly generated sm2 context which contain the retrieved 335 * sm2 private key component. Use sm2_free() function to free the 336 * resource. 337 * 338 * If pem_data is NULL, then return false. 339 * If sm2_context is NULL, then return false. 340 * 341 * @retval true sm2 Private key was retrieved successfully. 342 * @retval false Invalid PEM key data or incorrect password. 343 * 344 **/ 345 extern bool libspdm_sm2_get_private_key_from_pem(const uint8_t *pem_data, 346 size_t pem_size, 347 const char *password, 348 void **sm2_context); 349 350 /** 351 * Derive key data using HMAC-SHA256 based KDF. 352 * 353 * @param[in] key Pointer to the user-supplied key. 354 * @param[in] key_size Key size in bytes. 355 * @param[in] salt Pointer to the salt value. 356 * @param[in] salt_size Salt size in bytes. 357 * @param[in] info Pointer to the application specific info. 358 * @param[in] info_size Info size in bytes. 359 * @param[out] out Pointer to buffer to receive hkdf value. 360 * @param[in] out_size Size of hkdf bytes to generate. 361 * 362 * @retval true Hkdf generated successfully. 363 * @retval false Hkdf generation failed. 364 **/ 365 extern bool libspdm_hkdf_sha256_extract_and_expand(const uint8_t *key, size_t key_size, 366 const uint8_t *salt, size_t salt_size, 367 const uint8_t *info, size_t info_size, 368 uint8_t *out, size_t out_size); 369 370 /** 371 * Derive key data using HMAC-SHA384 based KDF. 372 * 373 * @param[in] key Pointer to the user-supplied key. 374 * @param[in] key_size Key size in bytes. 375 * @param[in] salt Pointer to the salt value. 376 * @param[in] salt_size Salt size in bytes. 377 * @param[in] info Pointer to the application specific info. 378 * @param[in] info_size Info size in bytes. 379 * @param[out] out Pointer to buffer to receive hkdf value. 380 * @param[in] out_size Size of hkdf bytes to generate. 381 * 382 * @retval true Hkdf generated successfully. 383 * @retval false Hkdf generation failed. 384 **/ 385 extern bool libspdm_hkdf_sha384_extract_and_expand(const uint8_t *key, size_t key_size, 386 const uint8_t *salt, size_t salt_size, 387 const uint8_t *info, size_t info_size, 388 uint8_t *out, size_t out_size); 389 390 /** 391 * Derive key data using HMAC-SHA512 based KDF. 392 * 393 * @param[in] key Pointer to the user-supplied key. 394 * @param[in] key_size Key size in bytes. 395 * @param[in] salt Pointer to the salt value. 396 * @param[in] salt_size Salt size in bytes. 397 * @param[in] info Pointer to the application specific info. 398 * @param[in] info_size Info size in bytes. 399 * @param[out] out Pointer to buffer to receive hkdf value. 400 * @param[in] out_size Size of hkdf bytes to generate. 401 * 402 * @retval true Hkdf generated successfully. 403 * @retval false Hkdf generation failed. 404 **/ 405 extern bool libspdm_hkdf_sha512_extract_and_expand(const uint8_t *key, size_t key_size, 406 const uint8_t *salt, size_t salt_size, 407 const uint8_t *info, size_t info_size, 408 uint8_t *out, size_t out_size); 409 410 /** 411 * Derive SHA3_256 HMAC-based Extract-and-Expand key Derivation Function (HKDF). 412 * 413 * @param[in] key Pointer to the user-supplied key. 414 * @param[in] key_size Key size in bytes. 415 * @param[in] salt Pointer to the salt value. 416 * @param[in] salt_size Salt size in bytes. 417 * @param[in] info Pointer to the application specific info. 418 * @param[in] info_size Info size in bytes. 419 * @param[out] out Pointer to buffer to receive hkdf value. 420 * @param[in] out_size Size of hkdf bytes to generate. 421 * 422 * @retval true Hkdf generated successfully. 423 * @retval false Hkdf generation failed. 424 **/ 425 extern bool libspdm_hkdf_sha3_256_extract_and_expand(const uint8_t *key, size_t key_size, 426 const uint8_t *salt, size_t salt_size, 427 const uint8_t *info, size_t info_size, 428 uint8_t *out, size_t out_size); 429 430 /** 431 * Derive SHA3_384 HMAC-based Extract-and-Expand key Derivation Function (HKDF). 432 * 433 * @param[in] key Pointer to the user-supplied key. 434 * @param[in] key_size Key size in bytes. 435 * @param[in] salt Pointer to the salt value. 436 * @param[in] salt_size Salt size in bytes. 437 * @param[in] info Pointer to the application specific info. 438 * @param[in] info_size Info size in bytes. 439 * @param[out] out Pointer to buffer to receive hkdf value. 440 * @param[in] out_size Size of hkdf bytes to generate. 441 * 442 * @retval true Hkdf generated successfully. 443 * @retval false Hkdf generation failed. 444 **/ 445 extern bool libspdm_hkdf_sha3_384_extract_and_expand(const uint8_t *key, size_t key_size, 446 const uint8_t *salt, size_t salt_size, 447 const uint8_t *info, size_t info_size, 448 uint8_t *out, size_t out_size); 449 450 /** 451 * Derive SHA3_512 HMAC-based Extract-and-Expand key Derivation Function (HKDF). 452 * 453 * @param[in] key Pointer to the user-supplied key. 454 * @param[in] key_size Key size in bytes. 455 * @param[in] salt Pointer to the salt value. 456 * @param[in] salt_size Salt size in bytes. 457 * @param[in] info Pointer to the application specific info. 458 * @param[in] info_size Info size in bytes. 459 * @param[out] out Pointer to buffer to receive hkdf value. 460 * @param[in] out_size Size of hkdf bytes to generate. 461 * 462 * @retval true Hkdf generated successfully. 463 * @retval false Hkdf generation failed. 464 **/ 465 extern bool libspdm_hkdf_sha3_512_extract_and_expand(const uint8_t *key, size_t key_size, 466 const uint8_t *salt, size_t salt_size, 467 const uint8_t *info, size_t info_size, 468 uint8_t *out, size_t out_size); 469 470 /** 471 * Derive SM3_256 HMAC-based Extract-and-Expand key Derivation Function (HKDF). 472 * 473 * @param[in] key Pointer to the user-supplied key. 474 * @param[in] key_size Key size in bytes. 475 * @param[in] salt Pointer to the salt value. 476 * @param[in] salt_size Salt size in bytes. 477 * @param[in] info Pointer to the application specific info. 478 * @param[in] info_size Info size in bytes. 479 * @param[out] out Pointer to buffer to receive hkdf value. 480 * @param[in] out_size Size of hkdf bytes to generate. 481 * 482 * @retval true Hkdf generated successfully. 483 * @retval false Hkdf generation failed. 484 **/ 485 extern bool libspdm_hkdf_sm3_256_extract_and_expand(const uint8_t *key, size_t key_size, 486 const uint8_t *salt, size_t salt_size, 487 const uint8_t *info, size_t info_size, 488 uint8_t *out, size_t out_size); 489 490 /** 491 * Sets the private key component into the established EC context. 492 * 493 * For P-256, the private_key_size is 32 byte. 494 * For P-384, the private_key_size is 48 byte. 495 * For P-521, the private_key_size is 66 byte. 496 * 497 * @param[in, out] ec_context Pointer to EC context being set. 498 * @param[in] private_key Pointer to the private key buffer. 499 * @param[in] private_key_size The size of private key buffer in bytes. 500 * 501 * @retval true EC private key component was set successfully. 502 * @retval false Invalid EC private key component. 503 * 504 **/ 505 extern bool libspdm_ec_set_priv_key(void *ec_context, const uint8_t *private_key, 506 size_t private_key_size); 507 508 /** 509 * Sets the public key component into the established EC context. 510 * 511 * For P-256, the public_size is 64. first 32-byte is X, second 32-byte is Y. 512 * For P-384, the public_size is 96. first 48-byte is X, second 48-byte is Y. 513 * For P-521, the public_size is 132. first 66-byte is X, second 66-byte is Y. 514 * 515 * @param[in, out] ec_context Pointer to EC context being set. 516 * @param[in] public Pointer to the buffer to receive generated public X,Y. 517 * @param[in] public_size The size of public buffer in bytes. 518 * 519 * @retval true EC public key component was set successfully. 520 * @retval false Invalid EC public key component. 521 **/ 522 extern bool libspdm_ec_set_pub_key(void *ec_context, const uint8_t *public_key, 523 size_t public_key_size); 524 525 /** 526 * Gets the public key component from the established EC context. 527 * 528 * For P-256, the public_size is 64. first 32-byte is X, second 32-byte is Y. 529 * For P-384, the public_size is 96. first 48-byte is X, second 48-byte is Y. 530 * For P-521, the public_size is 132. first 66-byte is X, second 66-byte is Y. 531 * 532 * @param[in, out] ec_context Pointer to EC context being set. 533 * @param[out] public Pointer to the buffer to receive generated public X,Y. 534 * @param[in, out] public_size On input, the size of public buffer in bytes. 535 * On output, the size of data returned in public buffer in bytes. 536 * 537 * @retval true EC key component was retrieved successfully. 538 * @retval false Invalid EC key component. 539 **/ 540 extern bool libspdm_ec_get_pub_key(void *ec_context, uint8_t *public_key, size_t *public_key_size); 541 542 /** 543 * Validates key components of EC context. 544 * NOTE: This function performs integrity checks on all the EC key material, so 545 * the EC key structure must contain all the private key data. 546 * 547 * If ec_context is NULL, then return false. 548 * 549 * @param[in] ec_context Pointer to EC context to check. 550 * 551 * @retval true EC key components are valid. 552 * @retval false EC key components are not valid. 553 **/ 554 extern bool libspdm_ec_check_key(const void *ec_context); 555 556 /** 557 * Validates key components of Ed context. 558 * NOTE: This function performs integrity checks on all the Ed key material, so 559 * the Ed key structure must contain all the private key data. 560 * 561 * If ecd_context is NULL, then return false. 562 * 563 * @param[in] ecd_context Pointer to Ed context to check. 564 * 565 * @retval true Ed key components are valid. 566 * @retval false Ed key components are not valid. 567 **/ 568 extern bool libspdm_ecd_check_key(const void *ecd_context); 569 570 /** 571 * Generates Ed key and returns Ed public key. 572 * 573 * For ed25519, the public_size is 32. 574 * For ed448, the public_size is 57. 575 * 576 * If ecd_context is NULL, then return false. 577 * If public_size is NULL, then return false. 578 * If public_size is large enough but public is NULL, then return false. 579 * 580 * @param[in, out] ecd_context Pointer to the Ed context. 581 * @param[out] public_key Pointer to the buffer to receive generated public key. 582 * @param[in, out] public_key_size On input, the size of public buffer in bytes. 583 * On output, the size of data returned in public buffer in bytes. 584 * 585 * @retval true Ed public key generation succeeded. 586 * @retval false Ed public key generation failed. 587 * @retval false public_size is not large enough. 588 **/ 589 extern bool libspdm_ecd_generate_key(void *ecd_context, uint8_t *public_key, 590 size_t *public_key_size); 591 592 /** 593 * Generates DH parameter. 594 * 595 * Given generator g, and length of prime number p in bits, this function generates p, 596 * and sets DH context according to value of g and p. 597 * 598 * If dh_context is NULL, then return false. 599 * If prime is NULL, then return false. 600 * If this interface is not supported, then return false. 601 * 602 * @param[in, out] dh_context Pointer to the DH context. 603 * @param[in] generator Value of generator. 604 * @param[in] prime_length Length in bits of prime to be generated. 605 * @param[out] prime Pointer to the buffer to receive the generated prime number. 606 * 607 * @retval true DH parameter generation succeeded. 608 * @retval false Value of generator is not supported. 609 * @retval false Random number generator fails to generate random prime number with prime_length. 610 * @retval false This interface is not supported. 611 **/ 612 extern bool libspdm_dh_generate_parameter(void *dh_context, size_t generator, 613 size_t prime_length, uint8_t *prime); 614 615 /** 616 * Sets generator and prime parameters for DH. 617 * 618 * Given generator g, and prime number p, this function and sets DH context accordingly. 619 * 620 * If dh_context is NULL, then return false. 621 * If prime is NULL, then return false. 622 * If this interface is not supported, then return false. 623 * 624 * @param[in, out] dh_context Pointer to the DH context. 625 * @param[in] generator Value of generator. 626 * @param[in] prime_length Length in bits of prime to be generated. 627 * @param[in] prime Pointer to the prime number. 628 * 629 * @retval true DH parameter setting succeeded. 630 * @retval false Value of generator is not supported. 631 * @retval false Value of generator is not suitable for the prime. 632 * @retval false Value of prime is not a prime number. 633 * @retval false Value of prime is not a safe prime number. 634 * @retval false This interface is not supported. 635 **/ 636 extern bool libspdm_dh_set_parameter(void *dh_context, size_t generator, 637 size_t prime_length, const uint8_t *prime); 638 639 /** 640 * Sets the public key component into the established sm2 context. 641 * 642 * The public_size is 64. first 32-byte is X, second 32-byte is Y. 643 * 644 * @param[in, out] ec_context Pointer to sm2 context being set. 645 * @param[in] public_key Pointer to the buffer to receive generated public X,Y. 646 * @param[in] public_key_size The size of public buffer in bytes. 647 * 648 * @retval true sm2 public key component was set successfully. 649 * @retval false Invalid sm2 public key component. 650 **/ 651 extern bool libspdm_sm2_dsa_set_pub_key(void *sm2_context, const uint8_t *public_key, 652 size_t public_key_size); 653 654 /** 655 * Gets the public key component from the established sm2 context. 656 * 657 * The public_size is 64. first 32-byte is X, second 32-byte is Y. 658 * 659 * @param[in, out] sm2_context Pointer to sm2 context being set. 660 * @param[out] public_key Pointer to the buffer to receive generated public X,Y. 661 * @param[in, out] public_key_size On input, the size of public buffer in bytes. 662 * On output, the size of data returned in public buffer in bytes. 663 * 664 * @retval true sm2 key component was retrieved successfully. 665 * @retval false Invalid sm2 key component. 666 **/ 667 extern bool libspdm_sm2_dsa_get_pub_key(void *sm2_context, uint8_t *public_key, 668 size_t *public_key_size); 669 670 /** 671 * Validates key components of sm2 context. 672 * NOTE: This function performs integrity checks on all the sm2 key material, so 673 * the sm2 key structure must contain all the private key data. 674 * 675 * If sm2_context is NULL, then return false. 676 * 677 * @param[in] sm2_context Pointer to sm2 context to check. 678 * 679 * @retval true sm2 key components are valid. 680 * @retval false sm2 key components are not valid. 681 **/ 682 extern bool libspdm_sm2_dsa_check_key(const void *sm2_context); 683 684 /** 685 * Generates sm2 key and returns sm2 public key (X, Y), based upon GB/T 32918.3-2016: SM2 - Part3. 686 * 687 * This function generates random secret, and computes the public key (X, Y), which is 688 * returned via parameter public, public_size. 689 * X is the first half of public with size being public_size / 2, 690 * Y is the second half of public with size being public_size / 2. 691 * sm2 context is updated accordingly. 692 * If the public buffer is too small to hold the public X, Y, false is returned and 693 * public_size is set to the required buffer size to obtain the public X, Y. 694 * 695 * The public_size is 64. first 32-byte is X, second 32-byte is Y. 696 * 697 * If sm2_context is NULL, then return false. 698 * If public_size is NULL, then return false. 699 * If public_size is large enough but public is NULL, then return false. 700 * 701 * @param[in, out] sm2_context Pointer to the sm2 context. 702 * @param[out] public_data Pointer to the buffer to receive generated public X,Y. 703 * @param[in, out] public_size On input, the size of public buffer in bytes. 704 * On output, the size of data returned in public buffer in bytes. 705 * 706 * @retval true sm2 public X,Y generation succeeded. 707 * @retval false sm2 public X,Y generation failed. 708 * @retval false public_size is not large enough. 709 **/ 710 extern bool libspdm_sm2_dsa_generate_key(void *sm2_context, uint8_t *public_data, 711 size_t *public_size); 712 713 #if LIBSPDM_ENABLE_CAPABILITY_CSR_CAP 714 /** 715 * Generate a CSR. 716 * 717 * @param[in] hash_nid hash algo for sign 718 * @param[in] asym_nid asym algo for sign 719 * 720 * @param[in] requester_info requester info to gen CSR 721 * @param[in] requester_info_length The len of requester info 722 * 723 * @param[in] is_ca if true, set basic_constraints: CA:true; Otherwise, set to false. 724 * 725 * @param[in] context Pointer to asymmetric context 726 * @param[in] subject_name Subject name: should be break with ',' in the middle 727 * example: "C=AA,CN=BB" 728 * 729 * Subject names should contain a comma-separated list of OID types and values: 730 * The valid OID type name is in: 731 * {"CN", "commonName", "C", "countryName", "O", "organizationName","L", 732 * "OU", "organizationalUnitName", "ST", "stateOrProvinceName", "emailAddress", 733 * "serialNumber", "postalAddress", "postalCode", "dnQualifier", "title", 734 * "SN","givenName","GN", "initials", "pseudonym", "generationQualifier", "domainComponent", "DC"}. 735 * Note: The object of C and countryName should be CSR Supported Country Codes 736 * 737 * @param[in, out] csr_len For input, csr_len is the size of store CSR buffer. 738 * For output, csr_len is CSR len for DER format 739 * @param[in, out] csr_pointer For input, csr_pointer is buffer address to store CSR. 740 * For output, csr_pointer is address for stored CSR. 741 * The csr_pointer address will be changed. 742 * 743 * @retval true Success. 744 * @retval false Failed to gen CSR. 745 **/ 746 extern bool libspdm_gen_x509_csr(size_t hash_nid, size_t asym_nid, 747 uint8_t *requester_info, size_t requester_info_length, 748 bool is_ca, 749 void *context, char *subject_name, 750 size_t *csr_len, uint8_t *csr_pointer); 751 #endif /* LIBSPDM_ENABLE_CAPABILITY_CSR_CAP */ 752 753 #endif /* CRYPTLIB_EXT_H */ 754