#include <Library/BaseCryptLib.h>
#include <Library/DebugLib.h>

Functions
VOID *EFIAPI	EcGroupInit (IN UINTN CryptoNid)

BOOLEAN EFIAPI	EcGroupGetCurve (IN CONST VOID EcGroup, OUT VOID BnPrime, OUT VOID BnA, OUT VOID BnB, IN VOID *BnCtx)

BOOLEAN EFIAPI	EcGroupGetOrder (IN VOID EcGroup, OUT VOID BnOrder)

VOID EFIAPI	EcGroupFree (IN VOID *EcGroup)

VOID *EFIAPI	EcPointInit (IN CONST VOID *EcGroup)

VOID EFIAPI	EcPointDeInit (IN VOID *EcPoint, IN BOOLEAN Clear)

BOOLEAN EFIAPI	EcPointGetAffineCoordinates (IN CONST VOID EcGroup, IN CONST VOID EcPoint, OUT VOID BnX, OUT VOID BnY, IN VOID *BnCtx)

BOOLEAN EFIAPI	EcPointSetAffineCoordinates (IN CONST VOID EcGroup, IN VOID EcPoint, IN CONST VOID BnX, IN CONST VOID BnY, IN VOID *BnCtx)

BOOLEAN EFIAPI	EcPointAdd (IN CONST VOID EcGroup, OUT VOID EcPointResult, IN CONST VOID EcPointA, IN CONST VOID EcPointB, IN VOID *BnCtx)

BOOLEAN EFIAPI	EcPointMul (IN CONST VOID EcGroup, OUT VOID EcPointResult, IN CONST VOID EcPoint, IN CONST VOID BnPScalar, IN VOID *BnCtx)

BOOLEAN EFIAPI	EcPointInvert (IN CONST VOID EcGroup, IN OUT VOID EcPoint, IN VOID *BnCtx)

BOOLEAN EFIAPI	EcPointIsOnCurve (IN CONST VOID EcGroup, IN CONST VOID EcPoint, IN VOID *BnCtx)

BOOLEAN EFIAPI	EcPointIsAtInfinity (IN CONST VOID EcGroup, IN CONST VOID EcPoint)

BOOLEAN EFIAPI	EcPointEqual (IN CONST VOID EcGroup, IN CONST VOID EcPointA, IN CONST VOID EcPointB, IN VOID BnCtx)

BOOLEAN EFIAPI	EcPointSetCompressedCoordinates (IN CONST VOID EcGroup, IN VOID EcPoint, IN CONST VOID BnX, IN UINT8 YBit, IN VOID BnCtx)

VOID *EFIAPI	EcNewByNid (IN UINTN Nid)

VOID EFIAPI	EcFree (IN VOID *EcContext)

BOOLEAN EFIAPI	EcGenerateKey (IN OUT VOID EcContext, OUT UINT8 PublicKey, IN OUT UINTN *PublicKeySize)

BOOLEAN EFIAPI	EcGetPubKey (IN OUT VOID EcContext, OUT UINT8 PublicKey, IN OUT UINTN *PublicKeySize)

BOOLEAN EFIAPI	EcDhComputeKey (IN OUT VOID EcContext, IN CONST UINT8 PeerPublic, IN UINTN PeerPublicSize, IN CONST INT32 CompressFlag, OUT UINT8 Key, IN OUT UINTN *KeySize)

BOOLEAN EFIAPI	EcDsaSign (IN VOID EcContext, IN UINTN HashNid, IN CONST UINT8 MessageHash, IN UINTN HashSize, OUT UINT8 Signature, IN OUT UINTN SigSize)

BOOLEAN EFIAPI	EcDsaVerify (IN VOID EcContext, IN UINTN HashNid, IN CONST UINT8 MessageHash, IN UINTN HashSize, IN CONST UINT8 *Signature, IN UINTN SigSize)

Detailed Description

Elliptic Curve and ECDH API implementation based on MbedTLS

Copyright (c) 2023, Intel Corporation. All rights reserved.
SPDX-License-Identifier: BSD-2-Clause-Patent

Definition in file CryptEcNull.c.

Function Documentation

◆ EcDhComputeKey()

BOOLEAN EFIAPI EcDhComputeKey	(	IN OUT VOID *	EcContext,
		IN CONST UINT8 *	PeerPublic,
		IN UINTN	PeerPublicSize,
		IN CONST INT32 *	CompressFlag,
		OUT UINT8 *	Key,
		IN OUT UINTN *	KeySize
	)

Computes exchanged common key. Given peer's public key (X, Y), this function computes the exchanged common key, based on its own context including value of curve parameter and random secret. X is the first half of PeerPublic with size being PeerPublicSize / 2, Y is the second half of PeerPublic with size being PeerPublicSize / 2. If EcContext is NULL, then return FALSE. If PeerPublic is NULL, then return FALSE. If PeerPublicSize is 0, then return FALSE. If Key is NULL, then return FALSE. If KeySize is not large enough, then return FALSE. For P-256, the PeerPublicSize is 64. First 32-byte is X, Second 32-byte is Y. For P-384, the PeerPublicSize is 96. First 48-byte is X, Second 48-byte is Y. For P-521, the PeerPublicSize is 132. First 66-byte is X, Second 66-byte is Y.

Parameters

[in,out]	EcContext	Pointer to the EC context.
[in]	PeerPublic	Pointer to the peer's public X,Y.
[in]	PeerPublicSize	Size of peer's public X,Y in bytes.
[in]	CompressFlag	Flag of PeerPublic is compressed or not.
[out]	Key	Pointer to the buffer to receive generated key.
[in,out]	KeySize	On input, the size of Key buffer in bytes. On output, the size of data returned in Key buffer in bytes.

Return values

TRUE	EC exchanged key generation succeeded.
FALSE	EC exchanged key generation failed.
FALSE	KeySize is not large enough.

Definition at line 485 of file CryptEcNull.c.

◆ EcDsaSign()

BOOLEAN EFIAPI EcDsaSign	(	IN VOID *	EcContext,
		IN UINTN	HashNid,
		IN CONST UINT8 *	MessageHash,
		IN UINTN	HashSize,
		OUT UINT8 *	Signature,
		IN OUT UINTN *	SigSize
	)

Carries out the EC-DSA signature.

This function carries out the EC-DSA signature. If the Signature buffer is too small to hold the contents of signature, FALSE is returned and SigSize is set to the required buffer size to obtain the signature.

If EcContext is NULL, then return FALSE. If MessageHash is NULL, then return FALSE. If HashSize need match the HashNid. HashNid could be SHA256, SHA384, SHA512, SHA3_256, SHA3_384, SHA3_512. If SigSize is large enough but Signature is NULL, then return FALSE.

For P-256, the SigSize is 64. First 32-byte is R, Second 32-byte is S. For P-384, the SigSize is 96. First 48-byte is R, Second 48-byte is S. For P-521, the SigSize is 132. First 66-byte is R, Second 66-byte is S.

Parameters

[in]	EcContext	Pointer to EC context for signature generation.
[in]	HashNid	hash NID
[in]	MessageHash	Pointer to octet message hash to be signed.
[in]	HashSize	Size of the message hash in bytes.
[out]	Signature	Pointer to buffer to receive EC-DSA signature.
[in,out]	SigSize	On input, the size of Signature buffer in bytes. On output, the size of data returned in Signature buffer in bytes.

Return values

TRUE	Signature successfully generated in EC-DSA.
FALSE	Signature generation failed.
FALSE	SigSize is too small.

Definition at line 529 of file CryptEcNull.c.

◆ EcDsaVerify()

BOOLEAN EFIAPI EcDsaVerify	(	IN VOID *	EcContext,
		IN UINTN	HashNid,
		IN CONST UINT8 *	MessageHash,
		IN UINTN	HashSize,
		IN CONST UINT8 *	Signature,
		IN UINTN	SigSize
	)

Verifies the EC-DSA signature.

If EcContext is NULL, then return FALSE. If MessageHash is NULL, then return FALSE. If Signature is NULL, then return FALSE. If HashSize need match the HashNid. HashNid could be SHA256, SHA384, SHA512, SHA3_256, SHA3_384, SHA3_512.

For P-256, the SigSize is 64. First 32-byte is R, Second 32-byte is S. For P-384, the SigSize is 96. First 48-byte is R, Second 48-byte is S. For P-521, the SigSize is 132. First 66-byte is R, Second 66-byte is S.

Parameters

[in]	EcContext	Pointer to EC context for signature verification.
[in]	HashNid	hash NID
[in]	MessageHash	Pointer to octet message hash to be checked.
[in]	HashSize	Size of the message hash in bytes.
[in]	Signature	Pointer to EC-DSA signature to be verified.
[in]	SigSize	Size of signature in bytes.

Return values

TRUE	Valid signature encoded in EC-DSA.
FALSE	Invalid signature or invalid EC context.

Definition at line 567 of file CryptEcNull.c.

◆ EcFree()

VOID EFIAPI EcFree ( IN VOID * EcContext )

Release the specified EC context.

Parameters

[in] EcContext Pointer to the EC context to be released.

Definition at line 387 of file CryptEcNull.c.

◆ EcGenerateKey()

BOOLEAN EFIAPI EcGenerateKey	(	IN OUT VOID *	EcContext,
		OUT UINT8 *	PublicKey,
		IN OUT UINTN *	PublicKeySize
	)

Generates EC key and returns EC public key (X, Y), Please note, this function uses pseudo random number generator. The caller must make sure RandomSeed() function was properly called before. The Ec context should be correctly initialized by EcNewByNid. This function generates random secret, and computes the public key (X, Y), which is returned via parameter Public, PublicSize. X is the first half of Public with size being PublicSize / 2, Y is the second half of Public with size being PublicSize / 2. EC context is updated accordingly. If the Public buffer is too small to hold the public X, Y, FALSE is returned and PublicSize is set to the required buffer size to obtain the public X, Y. For P-256, the PublicSize is 64. First 32-byte is X, Second 32-byte is Y. For P-384, the PublicSize is 96. First 48-byte is X, Second 48-byte is Y. For P-521, the PublicSize is 132. First 66-byte is X, Second 66-byte is Y. If EcContext is NULL, then return FALSE. If PublicSize is NULL, then return FALSE. If PublicSize is large enough but Public is NULL, then return FALSE.

Parameters

[in,out]	EcContext	Pointer to the EC context.
[out]	PublicKey	Pointer to t buffer to receive generated public X,Y.
[in,out]	PublicKeySize	On input, the size of Public buffer in bytes. On output, the size of data returned in Public buffer in bytes.

Return values

TRUE	EC public X,Y generation succeeded.
FALSE	EC public X,Y generation failed.
FALSE	PublicKeySize is not large enough.

Definition at line 422 of file CryptEcNull.c.

◆ EcGetPubKey()

BOOLEAN EFIAPI EcGetPubKey	(	IN OUT VOID *	EcContext,
		OUT UINT8 *	PublicKey,
		IN OUT UINTN *	PublicKeySize
	)

Gets the public key component from the established EC context. The Ec context should be correctly initialized by EcNewByNid, and successfully generate key pair from EcGenerateKey(). For P-256, the PublicSize is 64. First 32-byte is X, Second 32-byte is Y. For P-384, the PublicSize is 96. First 48-byte is X, Second 48-byte is Y. For P-521, the PublicSize is 132. First 66-byte is X, Second 66-byte is Y.

Parameters

[in,out]	EcContext	Pointer to EC context being set.
[out]	PublicKey	Pointer to t buffer to receive generated public X,Y.
[in,out]	PublicKeySize	On input, the size of Public buffer in bytes. On output, the size of data returned in Public buffer in bytes.

Return values

TRUE	EC key component was retrieved successfully.
FALSE	Invalid EC key component.

Definition at line 448 of file CryptEcNull.c.

◆ EcGroupFree()

VOID EFIAPI EcGroupFree ( IN VOID * EcGroup )

Free previously allocated EC group object using EcGroupInit().

Parameters

[in] EcGroup EC group object to free.

Definition at line 92 of file CryptEcNull.c.

◆ EcGroupGetCurve()

BOOLEAN EFIAPI EcGroupGetCurve	(	IN CONST VOID *	EcGroup,
		OUT VOID *	BnPrime,
		OUT VOID *	BnA,
		OUT VOID *	BnB,
		IN VOID *	BnCtx
	)

Get EC curve parameters. While elliptic curve equation is Y^2 mod P = (X^3 + AX + B) Mod P. This function will set the provided Big Number objects to the corresponding values. The caller needs to make sure all the "out" BigNumber parameters are properly initialized.

Parameters

[in]	EcGroup	EC group object.
[out]	BnPrime	Group prime number.
[out]	BnA	A coefficient.
[out]	BnB	B coefficient..
[in]	BnCtx	BN context.

Return values

TRUE	On success.
FALSE	Otherwise.

Definition at line 50 of file CryptEcNull.c.

◆ EcGroupGetOrder()

BOOLEAN EFIAPI EcGroupGetOrder	(	IN VOID *	EcGroup,
		OUT VOID *	BnOrder
	)

Get EC group order. This function will set the provided Big Number object to the corresponding value. The caller needs to make sure that the "out" BigNumber parameter is properly initialized.

Parameters

[in]	EcGroup	EC group object.
[out]	BnOrder	Group prime number.

Return values

TRUE	On success.
FALSE	Otherwise.

Definition at line 76 of file CryptEcNull.c.

◆ EcGroupInit()

VOID *EFIAPI EcGroupInit ( IN UINTN CryptoNid )

Initialize new opaque EcGroup object. This object represents an EC curve and and is used for calculation within this group. This object should be freed using EcGroupFree() function.

Parameters

[in] CryptoNid Identifying number for the ECC curve (Defined in BaseCryptLib.h).

Return values

EcGroup	object On success.
NULL	On failure.

Definition at line 25 of file CryptEcNull.c.

◆ EcNewByNid()

VOID *EFIAPI EcNewByNid ( IN UINTN Nid )

Allocates and Initializes one Elliptic Curve Context for subsequent use with the NID.

Parameters

[in] Nid cipher NID

Returns: Pointer to the Elliptic Curve Context that has been initialized. If the allocations fails, EcNewByNid() returns NULL.

Definition at line 372 of file CryptEcNull.c.

◆ EcPointAdd()

BOOLEAN EFIAPI EcPointAdd	(	IN CONST VOID *	EcGroup,
		OUT VOID *	EcPointResult,
		IN CONST VOID *	EcPointA,
		IN CONST VOID *	EcPointB,
		IN VOID *	BnCtx
	)

EC Point addition. EcPointResult = EcPointA + EcPointB.

Parameters

[in]	EcGroup	EC group object.
[out]	EcPointResult	EC point to hold the result. The point should be properly initialized.
[in]	EcPointA	EC Point.
[in]	EcPointB	EC Point.
[in]	BnCtx	BN context, created with BigNumNewContext().

Return values

TRUE	On success.
FALSE	Otherwise.

Definition at line 204 of file CryptEcNull.c.

◆ EcPointDeInit()

VOID EFIAPI EcPointDeInit	(	IN VOID *	EcPoint,
		IN BOOLEAN	Clear
	)

Free previously allocated EC Point object using EcPointInit().

Parameters

[in]	EcPoint	EC Point to free.
[in]	Clear	TRUE iff the memory should be cleared.

Definition at line 126 of file CryptEcNull.c.

◆ EcPointEqual()

BOOLEAN EFIAPI EcPointEqual	(	IN CONST VOID *	EcGroup,
		IN CONST VOID *	EcPointA,
		IN CONST VOID *	EcPointB,
		IN VOID *	BnCtx
	)

Check if EC points are equal.

Parameters

[in]	EcGroup	EC group object.
[in]	EcPointA	EC point A.
[in]	EcPointB	EC point B.
[in]	BnCtx	BN context, created with BigNumNewContext().

Return values

TRUE	A == B.
FALSE	Otherwise.

Definition at line 320 of file CryptEcNull.c.

◆ EcPointGetAffineCoordinates()

BOOLEAN EFIAPI EcPointGetAffineCoordinates	(	IN CONST VOID *	EcGroup,
		IN CONST VOID *	EcPoint,
		OUT VOID *	BnX,
		OUT VOID *	BnY,
		IN VOID *	BnCtx
	)

Get EC point affine (x,y) coordinates. This function will set the provided Big Number objects to the corresponding values. The caller needs to make sure all the "out" BigNumber parameters are properly initialized.

Parameters

[in]	EcGroup	EC group object.
[in]	EcPoint	EC point object.
[out]	BnX	X coordinate.
[out]	BnY	Y coordinate.
[in]	BnCtx	BN context, created with BigNumNewContext().

Return values

TRUE	On success.
FALSE	Otherwise.

Definition at line 151 of file CryptEcNull.c.

◆ EcPointInit()

VOID *EFIAPI EcPointInit ( IN CONST VOID * EcGroup )

Initialize new opaque EC Point object. This object represents an EC point within the given EC group (curve).

Parameters

[in] EC Group, properly initialized using EcGroupInit().

Return values

EC	Point object On success.
NULL	On failure.

Definition at line 110 of file CryptEcNull.c.

◆ EcPointInvert()

BOOLEAN EFIAPI EcPointInvert	(	IN CONST VOID *	EcGroup,
		IN OUT VOID *	EcPoint,
		IN VOID *	BnCtx
	)

Calculate the inverse of the supplied EC point.

Parameters

[in]	EcGroup	EC group object.
[in,out]	EcPoint	EC point to invert.
[in]	BnCtx	BN context, created with BigNumNewContext().

Return values

TRUE	On success.
FALSE	Otherwise.

Definition at line 255 of file CryptEcNull.c.

◆ EcPointIsAtInfinity()

BOOLEAN EFIAPI EcPointIsAtInfinity	(	IN CONST VOID *	EcGroup,
		IN CONST VOID *	EcPoint
	)

Check if the supplied point is at infinity.

Parameters

[in]	EcGroup	EC group object.
[in]	EcPoint	EC point to check.

Return values

TRUE	At infinity.
FALSE	Otherwise.

Definition at line 298 of file CryptEcNull.c.

◆ EcPointIsOnCurve()

BOOLEAN EFIAPI EcPointIsOnCurve	(	IN CONST VOID *	EcGroup,
		IN CONST VOID *	EcPoint,
		IN VOID *	BnCtx
	)

Check if the supplied point is on EC curve.

Parameters

[in]	EcGroup	EC group object.
[in]	EcPoint	EC point to check.
[in]	BnCtx	BN context, created with BigNumNewContext().

Return values

TRUE	On curve.
FALSE	Otherwise.

Definition at line 277 of file CryptEcNull.c.

◆ EcPointMul()

BOOLEAN EFIAPI EcPointMul	(	IN CONST VOID *	EcGroup,
		OUT VOID *	EcPointResult,
		IN CONST VOID *	EcPoint,
		IN CONST VOID *	BnPScalar,
		IN VOID *	BnCtx
	)

Variable EC point multiplication. EcPointResult = EcPoint * BnPScalar.

Parameters

[in]	EcGroup	EC group object.
[out]	EcPointResult	EC point to hold the result. The point should be properly initialized.
[in]	EcPoint	EC Point.
[in]	BnPScalar	P Scalar.
[in]	BnCtx	BN context, created with BigNumNewContext().

Return values

TRUE	On success.
FALSE	Otherwise.

Definition at line 231 of file CryptEcNull.c.

◆ EcPointSetAffineCoordinates()

BOOLEAN EFIAPI EcPointSetAffineCoordinates	(	IN CONST VOID *	EcGroup,
		IN VOID *	EcPoint,
		IN CONST VOID *	BnX,
		IN CONST VOID *	BnY,
		IN VOID *	BnCtx
	)

Set EC point affine (x,y) coordinates.

Parameters

[in]	EcGroup	EC group object.
[in]	EcPoint	EC point object.
[in]	BnX	X coordinate.
[in]	BnY	Y coordinate.
[in]	BnCtx	BN context, created with BigNumNewContext().

Return values

TRUE	On success.
FALSE	Otherwise.

Definition at line 177 of file CryptEcNull.c.

◆ EcPointSetCompressedCoordinates()

BOOLEAN EFIAPI EcPointSetCompressedCoordinates	(	IN CONST VOID *	EcGroup,
		IN VOID *	EcPoint,
		IN CONST VOID *	BnX,
		IN UINT8	YBit,
		IN VOID *	BnCtx
	)

Set EC point compressed coordinates. Points can be described in terms of their compressed coordinates. For a point (x, y), for any given value for x such that the point is on the curve there will only ever be two possible values for y. Therefore, a point can be set using this function where BnX is the x coordinate and YBit is a value 0 or 1 to identify which of the two possible values for y should be used.

Parameters

[in]	EcGroup	EC group object.
[in]	EcPoint	EC Point.
[in]	BnX	X coordinate.
[in]	YBit	0 or 1 to identify which Y value is used.
[in]	BnCtx	BN context, created with BigNumNewContext().

Return values

TRUE	On success.
FALSE	Otherwise.

Definition at line 350 of file CryptEcNull.c.

Functions

Detailed Description

Function Documentation

◆ EcDhComputeKey()

◆ EcDsaSign()

◆ EcDsaVerify()

◆ EcFree()

◆ EcGenerateKey()

◆ EcGetPubKey()

◆ EcGroupFree()

◆ EcGroupGetCurve()

◆ EcGroupGetOrder()

◆ EcGroupInit()

◆ EcNewByNid()

◆ EcPointAdd()

◆ EcPointDeInit()

◆ EcPointEqual()

◆ EcPointGetAffineCoordinates()

◆ EcPointInit()

◆ EcPointInvert()

◆ EcPointIsAtInfinity()

◆ EcPointIsOnCurve()

◆ EcPointMul()

◆ EcPointSetAffineCoordinates()

◆ EcPointSetCompressedCoordinates()