# Intel® Enhanced Privacy ID SDK: ecgroup

ecgroup
epid » common » math

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 | 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 | 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 left hand parameter.
  [in] | b | The right hand parameter.
  [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 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 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 co-ordinate of the base point of the elliptic curve.
  [in] | y | The Y co-ordinate 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