CryptoPkg/Library/BaseCryptLibNull/Pk/CryptEcNull.c

   1 /** @file
   2   Elliptic Curve and ECDH API implementation based on OpenSSL
   3
   4   Copyright (c) 2022, Intel Corporation. All rights reserved.<BR>
   5   SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7 **/
   8
   9 #include <Library/BaseCryptLib.h>
  10 #include <Library/DebugLib.h>
  11
  12 /**
  13   Initialize new opaque EcGroup object. This object represents an EC curve and
  14   and is used for calculation within this group. This object should be freed
  15   using EcGroupFree() function.
  16
  17   @param[in]  CryptoNid   Identifying number for the ECC curve (Defined in
  18                           BaseCryptLib.h).
  19
  20   @retval EcGroup object  On success.
  21   @retval NULL            On failure.
  22 **/
  23 VOID *
  24 EFIAPI
  25 EcGroupInit (
  26   IN UINTN  CryptoNid
  27   )
  28 {
  29   ASSERT (FALSE);
  30   return NULL;
  31 }
  32
  33 /**
  34   Get EC curve parameters. While elliptic curve equation is Y^2 mod P = (X^3 + AX + B) Mod P.
  35   This function will set the provided Big Number objects  to the corresponding
  36   values. The caller needs to make sure all the "out" BigNumber parameters
  37   are properly initialized.
  38
  39   @param[in]  EcGroup    EC group object.
  40   @param[out] BnPrime    Group prime number.
  41   @param[out] BnA        A coefficient.
  42   @param[out] BnB        B coefficient..
  43   @param[in]  BnCtx      BN context.
  44
  45   @retval TRUE          On success.
  46   @retval FALSE         Otherwise.
  47 **/
  48 BOOLEAN
  49 EFIAPI
  50 EcGroupGetCurve (
  51   IN CONST VOID  *EcGroup,
  52   OUT VOID       *BnPrime,
  53   OUT VOID       *BnA,
  54   OUT VOID       *BnB,
  55   IN VOID        *BnCtx
  56   )
  57 {
  58   ASSERT (FALSE);
  59   return FALSE;
  60 }
  61
  62 /**
  63   Get EC group order.
  64   This function will set the provided Big Number object to the corresponding
  65   value. The caller needs to make sure that the "out" BigNumber parameter
  66   is properly initialized.
  67
  68   @param[in]  EcGroup   EC group object.
  69   @param[out] BnOrder   Group prime number.
  70
  71   @retval TRUE          On success.
  72   @retval FALSE         Otherwise.
  73 **/
  74 BOOLEAN
  75 EFIAPI
  76 EcGroupGetOrder (
  77   IN VOID   *EcGroup,
  78   OUT VOID  *BnOrder
  79   )
  80 {
  81   ASSERT (FALSE);
  82   return FALSE;
  83 }
  84
  85 /**
  86   Free previously allocated EC group object using EcGroupInit().
  87
  88   @param[in]  EcGroup   EC group object to free.
  89 **/
  90 VOID
  91 EFIAPI
  92 EcGroupFree (
  93   IN VOID  *EcGroup
  94   )
  95 {
  96   ASSERT (FALSE);
  97 }
  98
  99 /**
 100   Initialize new opaque EC Point object. This object represents an EC point
 101   within the given EC group (curve).
 102
 103   @param[in]  EC Group, properly initialized using EcGroupInit().
 104
 105   @retval EC Point object  On success.
 106   @retval NULL             On failure.
 107 **/
 108 VOID *
 109 EFIAPI
 110 EcPointInit (
 111   IN CONST VOID  *EcGroup
 112   )
 113 {
 114   ASSERT (FALSE);
 115   return NULL;
 116 }
 117
 118 /**
 119   Free previously allocated EC Point object using EcPointInit().
 120
 121   @param[in]  EcPoint   EC Point to free.
 122   @param[in]  Clear     TRUE iff the memory should be cleared.
 123 **/
 124 VOID
 125 EFIAPI
 126 EcPointDeInit (
 127   IN VOID     *EcPoint,
 128   IN BOOLEAN  Clear
 129   )
 130 {
 131   ASSERT (FALSE);
 132 }
 133
 134 /**
 135   Get EC point affine (x,y) coordinates.
 136   This function will set the provided Big Number objects to the corresponding
 137   values. The caller needs to make sure all the "out" BigNumber parameters
 138   are properly initialized.
 139
 140   @param[in]  EcGroup    EC group object.
 141   @param[in]  EcPoint    EC point object.
 142   @param[out] BnX        X coordinate.
 143   @param[out] BnY        Y coordinate.
 144   @param[in]  BnCtx      BN context, created with BigNumNewContext().
 145
 146   @retval TRUE          On success.
 147   @retval FALSE         Otherwise.
 148 **/
 149 BOOLEAN
 150 EFIAPI
 151 EcPointGetAffineCoordinates (
 152   IN CONST VOID  *EcGroup,
 153   IN CONST VOID  *EcPoint,
 154   OUT VOID       *BnX,
 155   OUT VOID       *BnY,
 156   IN VOID        *BnCtx
 157   )
 158 {
 159   ASSERT (FALSE);
 160   return FALSE;
 161 }
 162
 163 /**
 164   Set EC point affine (x,y) coordinates.
 165
 166   @param[in]  EcGroup    EC group object.
 167   @param[in]  EcPoint    EC point object.
 168   @param[in]  BnX        X coordinate.
 169   @param[in]  BnY        Y coordinate.
 170   @param[in]  BnCtx      BN context, created with BigNumNewContext().
 171
 172   @retval TRUE          On success.
 173   @retval FALSE         Otherwise.
 174 **/
 175 BOOLEAN
 176 EFIAPI
 177 EcPointSetAffineCoordinates (
 178   IN CONST VOID  *EcGroup,
 179   IN VOID        *EcPoint,
 180   IN CONST VOID  *BnX,
 181   IN CONST VOID  *BnY,
 182   IN VOID        *BnCtx
 183   )
 184 {
 185   ASSERT (FALSE);
 186   return FALSE;
 187 }
 188
 189 /**
 190   EC Point addition. EcPointResult = EcPointA + EcPointB.
 191
 192   @param[in]  EcGroup          EC group object.
 193   @param[out] EcPointResult    EC point to hold the result. The point should
 194                                be properly initialized.
 195   @param[in]  EcPointA         EC Point.
 196   @param[in]  EcPointB         EC Point.
 197   @param[in]  BnCtx            BN context, created with BigNumNewContext().
 198
 199   @retval TRUE          On success.
 200   @retval FALSE         Otherwise.
 201 **/
 202 BOOLEAN
 203 EFIAPI
 204 EcPointAdd (
 205   IN CONST VOID  *EcGroup,
 206   OUT VOID       *EcPointResult,
 207   IN CONST VOID  *EcPointA,
 208   IN CONST VOID  *EcPointB,
 209   IN VOID        *BnCtx
 210   )
 211 {
 212   ASSERT (FALSE);
 213   return FALSE;
 214 }
 215
 216 /**
 217   Variable EC point multiplication. EcPointResult = EcPoint * BnPScalar.
 218
 219   @param[in]  EcGroup          EC group object.
 220   @param[out] EcPointResult    EC point to hold the result. The point should
 221                                be properly initialized.
 222   @param[in]  EcPoint          EC Point.
 223   @param[in]  BnPScalar        P Scalar.
 224   @param[in]  BnCtx            BN context, created with BigNumNewContext().
 225
 226   @retval TRUE          On success.
 227   @retval FALSE         Otherwise.
 228 **/
 229 BOOLEAN
 230 EFIAPI
 231 EcPointMul (
 232   IN CONST VOID  *EcGroup,
 233   OUT VOID       *EcPointResult,
 234   IN CONST VOID  *EcPoint,
 235   IN CONST VOID  *BnPScalar,
 236   IN VOID        *BnCtx
 237   )
 238 {
 239   ASSERT (FALSE);
 240   return FALSE;
 241 }
 242
 243 /**
 244   Calculate the inverse of the supplied EC point.
 245
 246   @param[in]     EcGroup   EC group object.
 247   @param[in,out] EcPoint   EC point to invert.
 248   @param[in]     BnCtx     BN context, created with BigNumNewContext().
 249
 250   @retval TRUE          On success.
 251   @retval FALSE         Otherwise.
 252 **/
 253 BOOLEAN
 254 EFIAPI
 255 EcPointInvert (
 256   IN CONST VOID  *EcGroup,
 257   IN OUT VOID    *EcPoint,
 258   IN VOID        *BnCtx
 259   )
 260 {
 261   ASSERT (FALSE);
 262   return FALSE;
 263 }
 264
 265 /**
 266   Check if the supplied point is on EC curve.
 267
 268   @param[in]  EcGroup   EC group object.
 269   @param[in]  EcPoint   EC point to check.
 270   @param[in]  BnCtx     BN context, created with BigNumNewContext().
 271
 272   @retval TRUE          On curve.
 273   @retval FALSE         Otherwise.
 274 **/
 275 BOOLEAN
 276 EFIAPI
 277 EcPointIsOnCurve (
 278   IN CONST VOID  *EcGroup,
 279   IN CONST VOID  *EcPoint,
 280   IN VOID        *BnCtx
 281   )
 282 {
 283   ASSERT (FALSE);
 284   return FALSE;
 285 }
 286
 287 /**
 288   Check if the supplied point is at infinity.
 289
 290   @param[in]  EcGroup   EC group object.
 291   @param[in]  EcPoint   EC point to check.
 292
 293   @retval TRUE          At infinity.
 294   @retval FALSE         Otherwise.
 295 **/
 296 BOOLEAN
 297 EFIAPI
 298 EcPointIsAtInfinity (
 299   IN CONST VOID  *EcGroup,
 300   IN CONST VOID  *EcPoint
 301   )
 302 {
 303   ASSERT (FALSE);
 304   return FALSE;
 305 }
 306
 307 /**
 308   Check if EC points are equal.
 309
 310   @param[in]  EcGroup   EC group object.
 311   @param[in]  EcPointA  EC point A.
 312   @param[in]  EcPointB  EC point B.
 313   @param[in]  BnCtx     BN context, created with BigNumNewContext().
 314
 315   @retval TRUE          A == B.
 316   @retval FALSE         Otherwise.
 317 **/
 318 BOOLEAN
 319 EFIAPI
 320 EcPointEqual (
 321   IN CONST VOID  *EcGroup,
 322   IN CONST VOID  *EcPointA,
 323   IN CONST VOID  *EcPointB,
 324   IN VOID        *BnCtx
 325   )
 326 {
 327   ASSERT (FALSE);
 328   return FALSE;
 329 }
 330
 331 /**
 332   Set EC point compressed coordinates. Points can be described in terms of
 333   their compressed coordinates. For a point (x, y), for any given value for x
 334   such that the point is on the curve there will only ever be two possible
 335   values for y. Therefore, a point can be set using this function where BnX is
 336   the x coordinate and YBit is a value 0 or 1 to identify which of the two
 337   possible values for y should be used.
 338
 339   @param[in]  EcGroup    EC group object.
 340   @param[in]  EcPoint    EC Point.
 341   @param[in]  BnX        X coordinate.
 342   @param[in]  YBit       0 or 1 to identify which Y value is used.
 343   @param[in]  BnCtx      BN context, created with BigNumNewContext().
 344
 345   @retval TRUE          On success.
 346   @retval FALSE         Otherwise.
 347 **/
 348 BOOLEAN
 349 EFIAPI
 350 EcPointSetCompressedCoordinates (
 351   IN CONST VOID  *EcGroup,
 352   IN VOID        *EcPoint,
 353   IN CONST VOID  *BnX,
 354   IN UINT8       YBit,
 355   IN VOID        *BnCtx
 356   )
 357 {
 358   ASSERT (FALSE);
 359   return FALSE;
 360 }
 361
 362 /**
 363   Allocates and Initializes one Elliptic Curve Context for subsequent use
 364   with the NID.
 365
 366   @param[in]  Nid cipher NID
 367   @return     Pointer to the Elliptic Curve Context that has been initialized.
 368               If the allocations fails, EcNewByNid() returns NULL.
 369 **/
 370 VOID *
 371 EFIAPI
 372 EcNewByNid (
 373   IN UINTN  Nid
 374   )
 375 {
 376   ASSERT (FALSE);
 377   return NULL;
 378 }
 379
 380 /**
 381   Release the specified EC context.
 382
 383   @param[in]  EcContext  Pointer to the EC context to be released.
 384 **/
 385 VOID
 386 EFIAPI
 387 EcFree (
 388   IN  VOID  *EcContext
 389   )
 390 {
 391   ASSERT (FALSE);
 392 }
 393
 394 /**
 395   Generates EC key and returns EC public key (X, Y), Please note, this function uses
 396   pseudo random number generator. The caller must make sure RandomSeed()
 397   function was properly called before.
 398   The Ec context should be correctly initialized by EcNewByNid.
 399   This function generates random secret, and computes the public key (X, Y), which is
 400   returned via parameter Public, PublicSize.
 401   X is the first half of Public with size being PublicSize / 2,
 402   Y is the second half of Public with size being PublicSize / 2.
 403   EC context is updated accordingly.
 404   If the Public buffer is too small to hold the public X, Y, FALSE is returned and
 405   PublicSize is set to the required buffer size to obtain the public X, Y.
 406   For P-256, the PublicSize is 64. First 32-byte is X, Second 32-byte is Y.
 407   For P-384, the PublicSize is 96. First 48-byte is X, Second 48-byte is Y.
 408   For P-521, the PublicSize is 132. First 66-byte is X, Second 66-byte is Y.
 409   If EcContext is NULL, then return FALSE.
 410   If PublicSize is NULL, then return FALSE.
 411   If PublicSize is large enough but Public is NULL, then return FALSE.
 412   @param[in, out]  EcContext      Pointer to the EC context.
 413   @param[out]      PublicKey      Pointer to t buffer to receive generated public X,Y.
 414   @param[in, out]  PublicKeySize  On input, the size of Public buffer in bytes.
 415                                   On output, the size of data returned in Public buffer in bytes.
 416   @retval TRUE   EC public X,Y generation succeeded.
 417   @retval FALSE  EC public X,Y generation failed.
 418   @retval FALSE  PublicKeySize is not large enough.
 419 **/
 420 BOOLEAN
 421 EFIAPI
 422 EcGenerateKey (
 423   IN OUT  VOID   *EcContext,
 424   OUT     UINT8  *PublicKey,
 425   IN OUT  UINTN  *PublicKeySize
 426   )
 427 {
 428   ASSERT (FALSE);
 429   return FALSE;
 430 }
 431
 432 /**
 433   Gets the public key component from the established EC context.
 434   The Ec context should be correctly initialized by EcNewByNid, and successfully
 435   generate key pair from EcGenerateKey().
 436   For P-256, the PublicSize is 64. First 32-byte is X, Second 32-byte is Y.
 437   For P-384, the PublicSize is 96. First 48-byte is X, Second 48-byte is Y.
 438   For P-521, the PublicSize is 132. First 66-byte is X, Second 66-byte is Y.
 439   @param[in, out]  EcContext      Pointer to EC context being set.
 440   @param[out]      PublicKey      Pointer to t buffer to receive generated public X,Y.
 441   @param[in, out]  PublicKeySize  On input, the size of Public buffer in bytes.
 442                                   On output, the size of data returned in Public buffer in bytes.
 443   @retval  TRUE   EC key component was retrieved successfully.
 444   @retval  FALSE  Invalid EC key component.
 445 **/
 446 BOOLEAN
 447 EFIAPI
 448 EcGetPubKey (
 449   IN OUT  VOID   *EcContext,
 450   OUT     UINT8  *PublicKey,
 451   IN OUT  UINTN  *PublicKeySize
 452   )
 453 {
 454   ASSERT (FALSE);
 455   return FALSE;
 456 }
 457
 458 /**
 459   Computes exchanged common key.
 460   Given peer's public key (X, Y), this function computes the exchanged common key,
 461   based on its own context including value of curve parameter and random secret.
 462   X is the first half of PeerPublic with size being PeerPublicSize / 2,
 463   Y is the second half of PeerPublic with size being PeerPublicSize / 2.
 464   If EcContext is NULL, then return FALSE.
 465   If PeerPublic is NULL, then return FALSE.
 466   If PeerPublicSize is 0, then return FALSE.
 467   If Key is NULL, then return FALSE.
 468   If KeySize is not large enough, then return FALSE.
 469   For P-256, the PeerPublicSize is 64. First 32-byte is X, Second 32-byte is Y.
 470   For P-384, the PeerPublicSize is 96. First 48-byte is X, Second 48-byte is Y.
 471   For P-521, the PeerPublicSize is 132. First 66-byte is X, Second 66-byte is Y.
 472   @param[in, out]  EcContext          Pointer to the EC context.
 473   @param[in]       PeerPublic         Pointer to the peer's public X,Y.
 474   @param[in]       PeerPublicSize     Size of peer's public X,Y in bytes.
 475   @param[in]       CompressFlag       Flag of PeerPublic is compressed or not.
 476   @param[out]      Key                Pointer to the buffer to receive generated key.
 477   @param[in, out]  KeySize            On input, the size of Key buffer in bytes.
 478                                       On output, the size of data returned in Key buffer in bytes.
 479   @retval TRUE   EC exchanged key generation succeeded.
 480   @retval FALSE  EC exchanged key generation failed.
 481   @retval FALSE  KeySize is not large enough.
 482 **/
 483 BOOLEAN
 484 EFIAPI
 485 EcDhComputeKey (
 486   IN OUT  VOID         *EcContext,
 487   IN      CONST UINT8  *PeerPublic,
 488   IN      UINTN        PeerPublicSize,
 489   IN      CONST INT32  *CompressFlag,
 490   OUT     UINT8        *Key,
 491   IN OUT  UINTN        *KeySize
 492   )
 493 {
 494   ASSERT (FALSE);
 495   return FALSE;
 496 }
 497
 498 /**
 499   Carries out the EC-DSA signature.
 500
 501   This function carries out the EC-DSA signature.
 502   If the Signature buffer is too small to hold the contents of signature, FALSE
 503   is returned and SigSize is set to the required buffer size to obtain the signature.
 504
 505   If EcContext is NULL, then return FALSE.
 506   If MessageHash is NULL, then return FALSE.
 507   If HashSize need match the HashNid. HashNid could be SHA256, SHA384, SHA512, SHA3_256, SHA3_384, SHA3_512.
 508   If SigSize is large enough but Signature is NULL, then return FALSE.
 509
 510   For P-256, the SigSize is 64. First 32-byte is R, Second 32-byte is S.
 511   For P-384, the SigSize is 96. First 48-byte is R, Second 48-byte is S.
 512   For P-521, the SigSize is 132. First 66-byte is R, Second 66-byte is S.
 513
 514   @param[in]       EcContext    Pointer to EC context for signature generation.
 515   @param[in]       HashNid      hash NID
 516   @param[in]       MessageHash  Pointer to octet message hash to be signed.
 517   @param[in]       HashSize     Size of the message hash in bytes.
 518   @param[out]      Signature    Pointer to buffer to receive EC-DSA signature.
 519   @param[in, out]  SigSize      On input, the size of Signature buffer in bytes.
 520                                 On output, the size of data returned in Signature buffer in bytes.
 521
 522   @retval  TRUE   Signature successfully generated in EC-DSA.
 523   @retval  FALSE  Signature generation failed.
 524   @retval  FALSE  SigSize is too small.
 525
 526 **/
 527 BOOLEAN
 528 EFIAPI
 529 EcDsaSign (
 530   IN      VOID         *EcContext,
 531   IN      UINTN        HashNid,
 532   IN      CONST UINT8  *MessageHash,
 533   IN      UINTN        HashSize,
 534   OUT     UINT8        *Signature,
 535   IN OUT  UINTN        *SigSize
 536   )
 537 {
 538   ASSERT (FALSE);
 539   return FALSE;
 540 }
 541
 542 /**
 543   Verifies the EC-DSA signature.
 544
 545   If EcContext is NULL, then return FALSE.
 546   If MessageHash is NULL, then return FALSE.
 547   If Signature is NULL, then return FALSE.
 548   If HashSize need match the HashNid. HashNid could be SHA256, SHA384, SHA512, SHA3_256, SHA3_384, SHA3_512.
 549
 550   For P-256, the SigSize is 64. First 32-byte is R, Second 32-byte is S.
 551   For P-384, the SigSize is 96. First 48-byte is R, Second 48-byte is S.
 552   For P-521, the SigSize is 132. First 66-byte is R, Second 66-byte is S.
 553
 554   @param[in]  EcContext    Pointer to EC context for signature verification.
 555   @param[in]  HashNid      hash NID
 556   @param[in]  MessageHash  Pointer to octet message hash to be checked.
 557   @param[in]  HashSize     Size of the message hash in bytes.
 558   @param[in]  Signature    Pointer to EC-DSA signature to be verified.
 559   @param[in]  SigSize      Size of signature in bytes.
 560
 561   @retval  TRUE   Valid signature encoded in EC-DSA.
 562   @retval  FALSE  Invalid signature or invalid EC context.
 563
 564 **/
 565 BOOLEAN
 566 EFIAPI
 567 EcDsaVerify (
 568   IN  VOID         *EcContext,
 569   IN  UINTN        HashNid,
 570   IN  CONST UINT8  *MessageHash,
 571   IN  UINTN        HashSize,
 572   IN  CONST UINT8  *Signature,
 573   IN  UINTN        SigSize
 574   )
 575 {
 576   ASSERT (FALSE);
 577   return FALSE;
 578 }