src/group.h

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