ecgroup

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]gThe 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]pThe 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]gThe elliptic curve group.
[in]aThe base.
[in]bThe power. Power must be less than the order of the elliptic curve group.
[out]rThe 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]gThe elliptic curve group.
[in]rnd_funcRandom number generator.
[in]rnd_func_paramPass through context data for rnd_func.
[in,out]rOutput 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]gThe elliptic curve group.
[in]msgThe message.
[in]msg_lenThe size of msg in bytes.
[in]hash_algThe hash algorithm.
[out]rThe hashed value.
[out]iterationsThe 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]gThe elliptic curve group.
[in]p_strA serialized point. Must be a G1ElemStr or G2ElemStr.
[in]strlenThe size of p_str in bytes.
[out]in_groupThe 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]gThe elliptic curve group.
[in]pThe point.
[out]rThe 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]gThe elliptic curve group.
[in]aA point to check.
[in]bAnother point to check.
[out]is_equalThe 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]gThe elliptic curve group.
[in]pThe point to check.
[out]is_identityThe 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]gThe elliptic curve group.
[in]xThe x coordinate.
[out]rThe 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]gThe elliptic curve group.
[in]aThe first operand to be multiplied.
[in]bThe second operand to be multiplied.
[out]rThe 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]gThe elliptic curve group.
[in]aThe bases.
[in]bThe powers. Power must be less than the order of the elliptic curve group.
[in]mNumber of entries in a and b.
[out]rThe 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]gThe elliptic curve group.
[in]aThe bases.
[in]bThe powers. Power must be less than the order of the elliptic curve group.
[in]mNumber of entries in a and b.
[out]rThe 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]gThe elliptic curve group.
[in]aThe base.
[in]bThe power. Power must be less than the order of the elliptic curve group.
[out]rThe 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]gThe elliptic curve group.
[in]aThe bases.
[in]bThe powers. Power must be less than the order of the elliptic curve group.
[in]mNumber of entries in a and b.
[out]rThe 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]gThe elliptic curve group.
[in]msgThe message.
[in]msg_lenThe size of msg in bytes.
[out]rThe 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]ffThe finite field on which the curve is based.
[in]aThe A value of the elliptic curve.
[in]bThe B value of the elliptic curve.
[in]xThe X-coordinate of the base point of the elliptic curve.
[in]yThe Y-coordinate of the base point of the elliptic curve.
[in]orderThe order of the elliptic curve group.
[in]cofactorThe co-factor of the elliptic curve.
[out]gThe 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]gElliptic curve group.
[out]pNewly 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]gThe elliptic curve group.
[in]p_strThe serialized value.
[in]strlenThe size of p_str in bytes.
[out]pThe 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]gThe elliptic curve group.
[in]pThe EcPoint to be serialized.
[out]p_strThe target string.
[in]strlenthe size of p_str in bytes.
Returns
EpidStatus
See also
NewEcPoint