src/group.h

   1 // Copyright (c) 2013 Pieter Wuille
   2 // Distributed under the MIT/X11 software license, see the accompanying
   3 // file COPYING or http://www.opensource.org/licenses/mit-license.php.
   4
   5 #ifndef _SECP256K1_GROUP_
   6 #define _SECP256K1_GROUP_
   7
   8 #include "num.h"
   9 #include "field.h"
  10
  11 /** A group element of the secp256k1 curve, in affine coordinates. */
  12 typedef struct {
  13     secp256k1_fe_t x;
  14     secp256k1_fe_t y;
  15     int infinity; // whether this represents the point at infinity
  16 } secp256k1_ge_t;
  17
  18 /** A group element of the secp256k1 curve, in jacobian coordinates. */
  19 typedef struct {
  20     secp256k1_fe_t x; // actual X: x/z^2
  21     secp256k1_fe_t y; // actual Y: y/z^3
  22     secp256k1_fe_t z;
  23     int infinity; // whether this represents the point at infinity
  24 } secp256k1_gej_t;
  25
  26 /** Global constants related to the group */
  27 typedef struct {
  28     secp256k1_num_t order; // the order of the curve (= order of its generator)
  29     secp256k1_num_t half_order; // half the order of the curve (= order of its generator)
  30     secp256k1_ge_t g; // the generator point
  31
  32 #ifdef USE_ENDOMORPHISM
  33     // constants related to secp256k1's efficiently computable endomorphism
  34     secp256k1_fe_t beta;
  35     secp256k1_num_t lambda, a1b2, b1, a2;
  36 #endif
  37 } secp256k1_ge_consts_t;
  38
  39 static const secp256k1_ge_consts_t *secp256k1_ge_consts = NULL;
  40
  41 /** Initialize the group module. */
  42 void static secp256k1_ge_start(void);
  43
  44 /** De-initialize the group module. */
  45 void static secp256k1_ge_stop(void);
  46
  47 /** Set a group element equal to the point at infinity */
  48 void static secp256k1_ge_set_infinity(secp256k1_ge_t *r);
  49
  50 /** Set a group element equal to the point with given X and Y coordinates */
  51 void static secp256k1_ge_set_xy(secp256k1_ge_t *r, const secp256k1_fe_t *x, const secp256k1_fe_t *y);
  52
  53 /** Set a group element (affine) equal to the point with the given X coordinate, and given oddness
  54  *  for Y. Return value indicates whether the result is valid. */
  55 int  static secp256k1_ge_set_xo(secp256k1_ge_t *r, const secp256k1_fe_t *x, int odd);
  56
  57 /** Check whether a group element is the point at infinity. */
  58 int  static secp256k1_ge_is_infinity(const secp256k1_ge_t *a);
  59
  60 /** Check whether a group element is valid (i.e., on the curve). */
  61 int  static secp256k1_ge_is_valid(const secp256k1_ge_t *a);
  62
  63 void static secp256k1_ge_neg(secp256k1_ge_t *r, const secp256k1_ge_t *a);
  64
  65 /** Get a hex representation of a point. *rlen will be overwritten with the real length. */
  66 void static secp256k1_ge_get_hex(char *r, int *rlen, const secp256k1_ge_t *a);
  67
  68 /** Set a group element equal to another which is given in jacobian coordinates */
  69 void static secp256k1_ge_set_gej(secp256k1_ge_t *r, secp256k1_gej_t *a);
  70
  71 /** Set a batch of group elements equal to the inputs given in jacobian coordinates */
  72 void static secp256k1_ge_set_all_gej(size_t len, secp256k1_ge_t r[len], const secp256k1_gej_t a[len]);
  73
  74
  75 /** Set a group element (jacobian) equal to the point at infinity. */
  76 void static secp256k1_gej_set_infinity(secp256k1_gej_t *r);
  77
  78 /** Set a group element (jacobian) equal to the point with given X and Y coordinates. */
  79 void static secp256k1_gej_set_xy(secp256k1_gej_t *r, const secp256k1_fe_t *x, const secp256k1_fe_t *y);
  80
  81 /** Set a group element (jacobian) equal to another which is given in affine coordinates. */
  82 void static secp256k1_gej_set_ge(secp256k1_gej_t *r, const secp256k1_ge_t *a);
  83
  84 /** Get the X coordinate of a group element (jacobian). */
  85 void static secp256k1_gej_get_x(secp256k1_fe_t *r, const secp256k1_gej_t *a);
  86
  87 /** Set r equal to the inverse of a (i.e., mirrored around the X axis) */
  88 void static secp256k1_gej_neg(secp256k1_gej_t *r, const secp256k1_gej_t *a);
  89
  90 /** Check whether a group element is the point at infinity. */
  91 int  static secp256k1_gej_is_infinity(const secp256k1_gej_t *a);
  92
  93 /** Set r equal to the double of a. */
  94 void static secp256k1_gej_double(secp256k1_gej_t *r, const secp256k1_gej_t *a);
  95
  96 /** Set r equal to the sum of a and b. */
  97 void static secp256k1_gej_add(secp256k1_gej_t *r, const secp256k1_gej_t *a, const secp256k1_gej_t *b);
  98
  99 /** Set r equal to the sum of a and b (with b given in affine coordinates). This is more efficient
 100     than secp256k1_gej_add. */
 101 void static secp256k1_gej_add_ge(secp256k1_gej_t *r, const secp256k1_gej_t *a, const secp256k1_ge_t *b);
 102
 103 /** Get a hex representation of a point. *rlen will be overwritten with the real length. */
 104 void static secp256k1_gej_get_hex(char *r, int *rlen, const secp256k1_gej_t *a);
 105
 106 #ifdef USE_ENDOMORPHISM
 107 /** Set r to be equal to lambda times a, where lambda is chosen in a way such that this is very fast. */
 108 void static secp256k1_gej_mul_lambda(secp256k1_gej_t *r, const secp256k1_gej_t *a);
 109
 110 /** Find r1 and r2 such that r1+r2*lambda = a, and r1 and r2 are maximum 128 bits long (given that a is
 111     not more than 256 bits). */
 112 void static secp256k1_gej_split_exp(secp256k1_num_t *r1, secp256k1_num_t *r2, const secp256k1_num_t *a);
 113 #endif
 114
 115 /** Clear a secp256k1_gej_t to prevent leaking sensitive information. */
 116 void static secp256k1_gej_clear(secp256k1_gej_t *r);
 117
 118 /** Clear a secp256k1_ge_t to prevent leaking sensitive information. */
 119 void static secp256k1_ge_clear(secp256k1_ge_t *r);
 120
 121
 122 #endif