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, void const p_str, size_t strlen, EcPoint *p)
	Deserializes an EcPoint from a string. More...

EpidStatus	WriteEcPoint (EcGroup g, EcPoint const p, void *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, void const p_str, size_t strlen, bool *in_group)
	Checks if a point is in an elliptic curve group. More...

EpidStatus	Epid11EcHash (EcGroup g, void const 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, void const msg, size_t msg_len, HashAlg hash_alg, EcPoint *r)
	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

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

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

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

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

EpidStatus EcHash	(	EcGroup *	g,
		void const *	msg,
		size_t	msg_len,
		HashAlg	hash_alg,
		EcPoint *	r
	)

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.

Returns: EpidStatus

See also: NewEcGroup; NewEcPoint

EpidStatus EcInGroup	(	EcGroup *	g,
		void const *	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

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

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

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

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

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

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

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

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

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

EpidStatus Epid11EcHash	(	EcGroup *	g,
		void const *	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

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

See also: DeleteEcGroup

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

See also: NewEcGroup; DeleteEcPoint

EpidStatus ReadEcPoint	(	EcGroup *	g,
		void const *	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

EpidStatus WriteEcPoint	(	EcGroup *	g,
		EcPoint const *	p,
		void *	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