github.com/ethereumproject/go-ethereum@v5.5.2+incompatible/crypto/secp256k1/libsecp256k1/src/field.h (about)

     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_FIELD_
     8  #define _SECP256K1_FIELD_
     9  
    10  /** Field element module.
    11   *
    12   *  Field elements can be represented in several ways, but code accessing
    13   *  it (and implementations) need to take certain properaties into account:
    14   *  - Each field element can be normalized or not.
    15   *  - Each field element has a magnitude, which represents how far away
    16   *    its representation is away from normalization. Normalized elements
    17   *    always have a magnitude of 1, but a magnitude of 1 doesn't imply
    18   *    normality.
    19   */
    20  
    21  #if defined HAVE_CONFIG_H
    22  #include "libsecp256k1-config.h"
    23  #endif
    24  
    25  #if defined(USE_FIELD_10X26)
    26  #include "field_10x26.h"
    27  #elif defined(USE_FIELD_5X52)
    28  #include "field_5x52.h"
    29  #else
    30  #error "Please select field implementation"
    31  #endif
    32  
    33  /** Normalize a field element. */
    34  static void secp256k1_fe_normalize(secp256k1_fe *r);
    35  
    36  /** Weakly normalize a field element: reduce it magnitude to 1, but don't fully normalize. */
    37  static void secp256k1_fe_normalize_weak(secp256k1_fe *r);
    38  
    39  /** Normalize a field element, without constant-time guarantee. */
    40  static void secp256k1_fe_normalize_var(secp256k1_fe *r);
    41  
    42  /** Verify whether a field element represents zero i.e. would normalize to a zero value. The field
    43   *  implementation may optionally normalize the input, but this should not be relied upon. */
    44  static int secp256k1_fe_normalizes_to_zero(secp256k1_fe *r);
    45  
    46  /** Verify whether a field element represents zero i.e. would normalize to a zero value. The field
    47   *  implementation may optionally normalize the input, but this should not be relied upon. */
    48  static int secp256k1_fe_normalizes_to_zero_var(secp256k1_fe *r);
    49  
    50  /** Set a field element equal to a small integer. Resulting field element is normalized. */
    51  static void secp256k1_fe_set_int(secp256k1_fe *r, int a);
    52  
    53  /** Verify whether a field element is zero. Requires the input to be normalized. */
    54  static int secp256k1_fe_is_zero(const secp256k1_fe *a);
    55  
    56  /** Check the "oddness" of a field element. Requires the input to be normalized. */
    57  static int secp256k1_fe_is_odd(const secp256k1_fe *a);
    58  
    59  /** Compare two field elements. Requires magnitude-1 inputs. */
    60  static int secp256k1_fe_equal_var(const secp256k1_fe *a, const secp256k1_fe *b);
    61  
    62  /** Compare two field elements. Requires both inputs to be normalized */
    63  static int secp256k1_fe_cmp_var(const secp256k1_fe *a, const secp256k1_fe *b);
    64  
    65  /** Set a field element equal to 32-byte big endian value. If successful, the resulting field element is normalized. */
    66  static int secp256k1_fe_set_b32(secp256k1_fe *r, const unsigned char *a);
    67  
    68  /** Convert a field element to a 32-byte big endian value. Requires the input to be normalized */
    69  static void secp256k1_fe_get_b32(unsigned char *r, const secp256k1_fe *a);
    70  
    71  /** Set a field element equal to the additive inverse of another. Takes a maximum magnitude of the input
    72   *  as an argument. The magnitude of the output is one higher. */
    73  static void secp256k1_fe_negate(secp256k1_fe *r, const secp256k1_fe *a, int m);
    74  
    75  /** Multiplies the passed field element with a small integer constant. Multiplies the magnitude by that
    76   *  small integer. */
    77  static void secp256k1_fe_mul_int(secp256k1_fe *r, int a);
    78  
    79  /** Adds a field element to another. The result has the sum of the inputs' magnitudes as magnitude. */
    80  static void secp256k1_fe_add(secp256k1_fe *r, const secp256k1_fe *a);
    81  
    82  /** Sets a field element to be the product of two others. Requires the inputs' magnitudes to be at most 8.
    83   *  The output magnitude is 1 (but not guaranteed to be normalized). */
    84  static void secp256k1_fe_mul(secp256k1_fe *r, const secp256k1_fe *a, const secp256k1_fe * SECP256K1_RESTRICT b);
    85  
    86  /** Sets a field element to be the square of another. Requires the input's magnitude to be at most 8.
    87   *  The output magnitude is 1 (but not guaranteed to be normalized). */
    88  static void secp256k1_fe_sqr(secp256k1_fe *r, const secp256k1_fe *a);
    89  
    90  /** Sets a field element to be the (modular) square root (if any exist) of another. Requires the
    91   *  input's magnitude to be at most 8. The output magnitude is 1 (but not guaranteed to be
    92   *  normalized). Return value indicates whether a square root was found. */
    93  static int secp256k1_fe_sqrt_var(secp256k1_fe *r, const secp256k1_fe *a);
    94  
    95  /** Sets a field element to be the (modular) inverse of another. Requires the input's magnitude to be
    96   *  at most 8. The output magnitude is 1 (but not guaranteed to be normalized). */
    97  static void secp256k1_fe_inv(secp256k1_fe *r, const secp256k1_fe *a);
    98  
    99  /** Potentially faster version of secp256k1_fe_inv, without constant-time guarantee. */
   100  static void secp256k1_fe_inv_var(secp256k1_fe *r, const secp256k1_fe *a);
   101  
   102  /** Calculate the (modular) inverses of a batch of field elements. Requires the inputs' magnitudes to be
   103   *  at most 8. The output magnitudes are 1 (but not guaranteed to be normalized). The inputs and
   104   *  outputs must not overlap in memory. */
   105  static void secp256k1_fe_inv_all_var(size_t len, secp256k1_fe *r, const secp256k1_fe *a);
   106  
   107  /** Convert a field element to the storage type. */
   108  static void secp256k1_fe_to_storage(secp256k1_fe_storage *r, const secp256k1_fe *a);
   109  
   110  /** Convert a field element back from the storage type. */
   111  static void secp256k1_fe_from_storage(secp256k1_fe *r, const secp256k1_fe_storage *a);
   112  
   113  /** If flag is true, set *r equal to *a; otherwise leave it. Constant-time. */
   114  static void secp256k1_fe_storage_cmov(secp256k1_fe_storage *r, const secp256k1_fe_storage *a, int flag);
   115  
   116  /** If flag is true, set *r equal to *a; otherwise leave it. Constant-time. */
   117  static void secp256k1_fe_cmov(secp256k1_fe *r, const secp256k1_fe *a, int flag);
   118  
   119  #endif