Elliptic curve group operations. More...

Typedefs
typedef struct EcGroup	EcGroup
	Elliptic curve group over finite field.

typedef struct EcPoint	EcPoint
	Point on elliptic curve over finite field.

Functions
EpidStatus	NewEcGroup (FiniteField const ff, FfElement const a, FfElement const b, FfElement const x, FfElement const y, BigNum const order, BigNum const cofactor, EcGroup *g)
	Constructs a new EcGroup. More...

void	DeleteEcGroup (EcGroup **g)
	Deletes a previously allocated EcGroup. More...

EpidStatus	NewEcPoint (EcGroup const g, EcPoint *p)
	Creates a new EcPoint. More...

void	DeleteEcPoint (EcPoint **p)
	Deletes a previously allocated EcPoint. More...

EpidStatus	ReadEcPoint (EcGroup g, ConstOctStr p_str, size_t strlen, EcPoint p)
	Deserializes an EcPoint from a string. More...

EpidStatus	WriteEcPoint (EcGroup g, EcPoint const p, OctStr p_str, size_t strlen)
	Serializes an EcPoint to a string. More...

EpidStatus	EcMul (EcGroup g, EcPoint const a, EcPoint const b, EcPoint r)
	Multiplies two elements in an elliptic curve group. More...

EpidStatus	EcExp (EcGroup g, EcPoint const a, BigNumStr const b, EcPoint r)
	Raises a point in an elliptic curve group to a power. More...

EpidStatus	EcSscmExp (EcGroup g, EcPoint const a, BigNumStr const b, EcPoint r)
	Software side-channel mitigated implementation of EcExp. More...

EpidStatus	EcMultiExp (EcGroup g, EcPoint const a, BigNumStr const b, size_t m, EcPoint r)
	Multi-exponentiates elements in elliptic curve group. More...

EpidStatus	EcMultiExpBn (EcGroup g, EcPoint const a, BigNum const b, size_t m, EcPoint r)
	Multi-exponentiates elements in elliptic curve group. More...

EpidStatus	EcSscmMultiExp (EcGroup g, EcPoint const a, BigNumStr const b, size_t m, EcPoint r)
	Software side-channel mitigated implementation of EcMultiExp. More...

EpidStatus	EcGetRandom (EcGroup g, BitSupplier rnd_func, void rnd_func_param, EcPoint *r)
	Generates a random element from an elliptic curve group. More...

EpidStatus	EcInGroup (EcGroup g, ConstOctStr p_str, size_t strlen, bool in_group)
	Checks if a point is in an elliptic curve group. More...

EpidStatus	Epid11EcHash (EcGroup g, ConstOctStr msg, size_t msg_len, EcPoint r)
	Hashes an arbitrary message to an Intel(R) EPID 1.1 element in an elliptic curve group. More...

EpidStatus	EcHash (EcGroup g, ConstOctStr msg, size_t msg_len, HashAlg hash_alg, EcPoint r, uint32_t *iterations)
	Hashes an arbitrary message to an element in an elliptic curve group. More...

EpidStatus	EcMakePoint (EcGroup g, FfElement const x, EcPoint *r)
	Sets an EcPoint variable to a point on a curve. More...

EpidStatus	EcInverse (EcGroup g, EcPoint const p, EcPoint *r)
	Computes the additive inverse of an EcPoint. More...

EpidStatus	EcIsEqual (EcGroup g, EcPoint const a, EcPoint const b, bool is_equal)
	Checks if two EcPoints are equal. More...

EpidStatus	EcIsIdentity (EcGroup g, EcPoint const p, bool *is_identity)
	Checks if an EcPoint is the identity element. More...

Detailed Description

Elliptic curve group operations.

Provides APIs for working with Elliptic curve groups. Elliptic curve groups allow simple mathematical operations based on points that lie on a defined elliptic curve. The results of these operations also lie on the same curve.

Curves themselves are defined based on elements (FfElement) of a finite field (FiniteField).

Function Documentation

◆ DeleteEcGroup()

void DeleteEcGroup ( EcGroup ** g )

Deletes a previously allocated EcGroup.

Frees memory pointed to by elliptic curve group. Nulls the pointer.

Parameters

[in] g The elliptic curve group. Can be NULL.

See also: NewEcGroup

◆ DeleteEcPoint()

void DeleteEcPoint ( EcPoint ** p )

Deletes a previously allocated EcPoint.

Frees memory used by a point on elliptic curve group. Nulls the pointer.

Parameters

[in] p The EcPoint. Can be NULL.

See also: NewEcPoint

◆ EcExp()

EpidStatus EcExp	(	EcGroup *	g,
		EcPoint const *	a,
		BigNumStr const *	b,
		EcPoint *	r
	)

Raises a point in an elliptic curve group to a power.

This exponentiation operation is also known as element multiplication for elliptic curve groups.

Parameters

[in]	g	The elliptic curve group.
[in]	a	The base.
[in]	b	The power. Power must be less than the order of the elliptic curve group.
[out]	r	The result of raising a to the power b.

Returns: EpidStatus

See also: NewEcGroup; NewEcPoint

◆ EcGetRandom()

EpidStatus EcGetRandom	(	EcGroup *	g,
		BitSupplier	rnd_func,
		void *	rnd_func_param,
		EcPoint *	r
	)

Generates a random element from an elliptic curve group.

This function is only available for G1 and GT.

Parameters

[in]	g	The elliptic curve group.
[in]	rnd_func	Random number generator.
[in]	rnd_func_param	Pass through context data for rnd_func.
[in,out]	r	Output random elliptic curve element.

Returns: EpidStatus

See also: NewEcPoint; BitSupplier

◆ EcHash()

EpidStatus EcHash	(	EcGroup *	g,
		ConstOctStr	msg,
		size_t	msg_len,
		HashAlg	hash_alg,
		EcPoint *	r,
		uint32_t *	iterations
	)

Hashes an arbitrary message to an element in an elliptic curve group.

Parameters

[in]	g	The elliptic curve group.
[in]	msg	The message.
[in]	msg_len	The size of msg in bytes.
[in]	hash_alg	The hash algorithm.
[out]	r	The hashed value.
[out]	iterations	The number of hash iterations needed to find a valid hash. Can be NULL.

Returns: EpidStatus

See also: NewEcGroup; NewEcPoint

◆ EcInGroup()

EpidStatus EcInGroup	(	EcGroup *	g,
		ConstOctStr	p_str,
		size_t	strlen,
		bool *	in_group
	)

Checks if a point is in an elliptic curve group.

Parameters

[in]	g	The elliptic curve group.
[in]	p_str	A serialized point. Must be a G1ElemStr or G2ElemStr.
[in]	strlen	The size of p_str in bytes.
[out]	in_group	The result of the check.

Returns: EpidStatus

See also: NewEcPoint

◆ EcInverse()

EpidStatus EcInverse	(	EcGroup *	g,
		EcPoint const *	p,
		EcPoint *	r
	)

Computes the additive inverse of an EcPoint.

This inverse operation is also known as element negation for elliptic curve groups.

Parameters

[in]	g	The elliptic curve group.
[in]	p	The point.
[out]	r	The inverted point.

Returns: EpidStatus

See also: NewEcGroup; NewEcPoint

◆ EcIsEqual()

EpidStatus EcIsEqual	(	EcGroup *	g,
		EcPoint const *	a,
		EcPoint const *	b,
		bool *	is_equal
	)

Checks if two EcPoints are equal.

Parameters

[in]	g	The elliptic curve group.
[in]	a	A point to check.
[in]	b	Another point to check.
[out]	is_equal	The result of the check.

Returns: EpidStatus

See also: NewEcGroup; NewEcPoint

◆ EcIsIdentity()

EpidStatus EcIsIdentity	(	EcGroup *	g,
		EcPoint const *	p,
		bool *	is_identity
	)

Checks if an EcPoint is the identity element.

Takes a group element P as input. It outputs true if P is the identity element of G. Otherwise, it outputs false.

Parameters

[in]	g	The elliptic curve group.
[in]	p	The point to check.
[out]	is_identity	The result of the check.

Returns: EpidStatus

See also: NewEcGroup; NewEcPoint

◆ EcMakePoint()

EpidStatus EcMakePoint	(	EcGroup *	g,
		FfElement const *	x,
		EcPoint *	r
	)

Sets an EcPoint variable to a point on a curve.

This function is only available for G1.

Parameters

[in]	g	The elliptic curve group.
[in]	x	The x coordinate.
[out]	r	The point.

Returns: EpidStatus

See also: NewEcGroup; NewEcPoint; NewFfElement

◆ EcMul()

EpidStatus EcMul	(	EcGroup *	g,
		EcPoint const *	a,
		EcPoint const *	b,
		EcPoint *	r
	)

Multiplies two elements in an elliptic curve group.

This multiplication operation is also known as element addition for elliptic curve groups.

Parameters

[in]	g	The elliptic curve group.
[in]	a	The first operand to be multiplied.
[in]	b	The second operand to be multiplied.
[out]	r	The result of multiplying a and b.

Returns: EpidStatus

See also: NewEcGroup; NewEcPoint

◆ EcMultiExp()

EpidStatus EcMultiExp	(	EcGroup *	g,
		EcPoint const **	a,
		BigNumStr const **	b,
		size_t	m,
		EcPoint *	r
	)

Multi-exponentiates elements in elliptic curve group.

Takes a group elements a[0], ... , a[m-1] in G and positive integers b[0], ..., b[m-1], where m is a small positive integer. Outputs r (in G) = EcExp(a[0],b[0]) * ... * EcExp(a[m-1],b[m-1]).

Parameters

[in]	g	The elliptic curve group.
[in]	a	The bases.
[in]	b	The powers. Power must be less than the order of the elliptic curve group.
[in]	m	Number of entries in a and b.
[out]	r	The result of raising each a to the corresponding power b and multiplying the results.

Returns: EpidStatus

See also: NewEcGroup; NewEcPoint

◆ EcMultiExpBn()

EpidStatus EcMultiExpBn	(	EcGroup *	g,
		EcPoint const **	a,
		BigNum const **	b,
		size_t	m,
		EcPoint *	r
	)

Multi-exponentiates elements in elliptic curve group.

Takes a group elements a[0], ... , a[m-1] in G and positive integers b[0], ..., b[m-1], where m is a small positive integer. Outputs r (in G) = EcExp(a[0],b[0]) * ... * EcExp(a[m-1],b[m-1]).

Parameters

[in]	g	The elliptic curve group.
[in]	a	The bases.
[in]	b	The powers. Power must be less than the order of the elliptic curve group.
[in]	m	Number of entries in a and b.
[out]	r	The result of raising each a to the corresponding power b and multiplying the results.

Returns: EpidStatus

See also: NewEcGroup; NewEcPoint

◆ EcSscmExp()

EpidStatus EcSscmExp	(	EcGroup *	g,
		EcPoint const *	a,
		BigNumStr const *	b,
		EcPoint *	r
	)

Software side-channel mitigated implementation of EcExp.

This exponentiation operation is also known as element multiplication for elliptic curve groups.

Attention: The reference implementation of EcSscmExp calls EcExp directly because the implementation of EcExp is already side channel mitigated. Implementers providing their own versions of this function are responsible for ensuring that EcSscmExp is side channel mitigated per section 8 of the Intel(R) EPID 2.0 spec.

Parameters

[in]	g	The elliptic curve group.
[in]	a	The base.
[in]	b	The power. Power must be less than the order of the elliptic curve group.
[out]	r	The result of raising a to the power b.

Returns: EpidStatus

See also: NewEcGroup; NewEcPoint

◆ EcSscmMultiExp()

EpidStatus EcSscmMultiExp	(	EcGroup *	g,
		EcPoint const **	a,
		BigNumStr const **	b,
		size_t	m,
		EcPoint *	r
	)

Software side-channel mitigated implementation of EcMultiExp.

Takes a group elements a[0], ... , a[m-1] in G and positive integers b[0], ..., b[m-1], where m is a small positive integer. Outputs r (in G) = EcExp(a[0],b[0]) * ... * EcExp(a[m-1],b[m-1]).

Attention: The reference implementation of EcSscmMultiExp calls EcMultiExp directly because the implementation of EcMultiExp is already side channel mitigated. Implementers providing their own versions of this function are responsible for ensuring that EcSscmMultiExp is side channel mitigated per section 8 of the Intel(R) EPID 2.0 spec.

Parameters

[in]	g	The elliptic curve group.
[in]	a	The bases.
[in]	b	The powers. Power must be less than the order of the elliptic curve group.
[in]	m	Number of entries in a and b.
[out]	r	The result of raising each a to the corresponding power b and multiplying the results.

Returns: EpidStatus

See also: NewEcGroup; NewEcPoint

◆ Epid11EcHash()

EpidStatus Epid11EcHash	(	EcGroup *	g,
		ConstOctStr	msg,
		size_t	msg_len,
		EcPoint *	r
	)

Hashes an arbitrary message to an Intel(R) EPID 1.1 element in an elliptic curve group.

Parameters

[in]	g	The elliptic curve group.
[in]	msg	The message.
[in]	msg_len	The size of msg in bytes.
[out]	r	The hashed value.

Returns: EpidStatus

See also: NewEcGroup; NewEcPoint

◆ NewEcGroup()

EpidStatus NewEcGroup	(	FiniteField const *	ff,
		FfElement const *	a,
		FfElement const *	b,
		FfElement const *	x,
		FfElement const *	y,
		BigNum const *	order,
		BigNum const *	cofactor,
		EcGroup **	g
	)

Constructs a new EcGroup.

Allocates memory and creates a new elliptic curve group.

Use DeleteFiniteField() to free memory.

Parameters

[in]	ff	The finite field on which the curve is based.
[in]	a	The A value of the elliptic curve.
[in]	b	The B value of the elliptic curve.
[in]	x	The X-coordinate of the base point of the elliptic curve.
[in]	y	The Y-coordinate of the base point of the elliptic curve.
[in]	order	The order of the elliptic curve group.
[in]	cofactor	The co-factor of the elliptic curve.
[out]	g	The newly constructed elliptic curve group.

Returns: EpidStatus

Attention: It is the responsibility of the caller to ensure that ff exists for the entire lifetime of the new EcGroup.

See also: DeleteEcGroup

◆ NewEcPoint()

EpidStatus NewEcPoint	(	EcGroup const *	g,
		EcPoint **	p
	)

Creates a new EcPoint.

Allocates memory and creates a new point on elliptic curve group.

Use DeleteEcPoint() to free memory.

Parameters

[in]	g	Elliptic curve group.
[out]	p	Newly constructed point on the elliptic curve group g.

Returns: EpidStatus

Attention: It is the responsibility of the caller to ensure that g exists for the entire lifetime of the new EcPoint.

See also: NewEcGroup; DeleteEcPoint

◆ ReadEcPoint()

EpidStatus ReadEcPoint	(	EcGroup *	g,
		ConstOctStr	p_str,
		size_t	strlen,
		EcPoint *	p
	)

Deserializes an EcPoint from a string.

Parameters

[in]	g	The elliptic curve group.
[in]	p_str	The serialized value.
[in]	strlen	The size of p_str in bytes.
[out]	p	The target EcPoint.

Returns: EpidStatus

See also: NewEcPoint

◆ WriteEcPoint()

EpidStatus WriteEcPoint	(	EcGroup *	g,
		EcPoint const *	p,
		OctStr	p_str,
		size_t	strlen
	)

Serializes an EcPoint to a string.

Parameters

[in]	g	The elliptic curve group.
[in]	p	The EcPoint to be serialized.
[out]	p_str	The target string.
[in]	strlen	the size of p_str in bytes.

Returns: EpidStatus

See also: NewEcPoint

Typedefs

Functions

Detailed Description

Function Documentation

◆ DeleteEcGroup()

◆ DeleteEcPoint()

◆ EcExp()

◆ EcGetRandom()

◆ EcHash()

◆ EcInGroup()

◆ EcInverse()

◆ EcIsEqual()

◆ EcIsIdentity()

◆ EcMakePoint()

◆ EcMul()

◆ EcMultiExp()

◆ EcMultiExpBn()

◆ EcSscmExp()

◆ EcSscmMultiExp()

◆ Epid11EcHash()

◆ NewEcGroup()

◆ NewEcPoint()

◆ ReadEcPoint()

◆ WriteEcPoint()