OpenBSD manual page server

NAME

BN_GF2m_add, BN_GF2m_sub, BN_GF2m_cmp, BN_GF2m_mod_arr, BN_GF2m_mod, BN_GF2m_mod_mul_arr, BN_GF2m_mod_mul, BN_GF2m_mod_sqr_arr, BN_GF2m_mod_sqr, BN_GF2m_mod_inv, BN_GF2m_mod_inv_arr, BN_GF2m_mod_div, BN_GF2m_mod_div_arr, BN_GF2m_mod_exp_arr, BN_GF2m_mod_exp, BN_GF2m_mod_sqrt_arr, BN_GF2m_mod_sqrt, BN_GF2m_mod_solve_quad_arr, BN_GF2m_mod_solve_quad, BN_GF2m_poly2arr, BN_GF2m_arr2poly — arithmetic in Galois fields of power-of-2 order

SYNOPSIS

#include <openssl/bn.h>

int
BN_GF2m_add(BIGNUM *r, const BIGNUM *a, const BIGNUM *b);

int
BN_GF2m_sub(BIGNUM *r, const BIGNUM *a, const BIGNUM *b);

int
BN_GF2m_cmp(const BIGNUM *a, const BIGNUM *b);

int
BN_GF2m_mod_arr(BIGNUM *r, const BIGNUM *a, const int p[]);

int
BN_GF2m_mod(BIGNUM *r, const BIGNUM *a, const BIGNUM *p);

int
BN_GF2m_mod_mul_arr(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, const int p[], BN_CTX *ctx);

int
BN_GF2m_mod_mul(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, const BIGNUM *p, BN_CTX *ctx);

int
BN_GF2m_mod_sqr_arr(BIGNUM *r, const BIGNUM *a, const int p[], BN_CTX *ctx);

int
BN_GF2m_mod_sqr(BIGNUM *r, const BIGNUM *a, const BIGNUM *p, BN_CTX *ctx);

int
BN_GF2m_mod_inv(BIGNUM *r, const BIGNUM *b, const BIGNUM *p, BN_CTX *ctx);

int
BN_GF2m_mod_inv_arr(BIGNUM *r, const BIGNUM *b, const int p[], BN_CTX *ctx);

int
BN_GF2m_mod_div(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, const BIGNUM *p, BN_CTX *ctx);

int
BN_GF2m_mod_div_arr(BIGNUM *r, const BIGNUM *a, const BIGNUM *b, const int p[], BN_CTX *ctx);

int
BN_GF2m_mod_exp_arr(BIGNUM *r, const BIGNUM *a, const BIGNUM *exponent, const int p[], BN_CTX *ctx);

int
BN_GF2m_mod_exp(BIGNUM *r, const BIGNUM *a, const BIGNUM *exponent, const BIGNUM *p, BN_CTX *ctx);

int
BN_GF2m_mod_sqrt_arr(BIGNUM *r, const BIGNUM *a, const int p[], BN_CTX *ctx);

int
BN_GF2m_mod_sqrt(BIGNUM *r, const BIGNUM *a, const BIGNUM *p, BN_CTX *ctx);

int
BN_GF2m_mod_solve_quad_arr(BIGNUM *r, const BIGNUM *a, const int p[], BN_CTX *ctx);

int
BN_GF2m_mod_solve_quad(BIGNUM *r, const BIGNUM *a, const BIGNUM *p, BN_CTX *ctx);

int
BN_GF2m_poly2arr(const BIGNUM *poly_in, int arr_out[], int arr_size);

int
BN_GF2m_arr2poly(const int arr_in[], BIGNUM *poly_out);

DESCRIPTION

Two fields containing the same, finite number of elements are isomorphic, and the number of elements is called their order. The unique field of a given finite order is called the Galois field of that order. The following functions perform arithmetic operations on $\mathrm{GF}\left(2^m\right)$ , the Galois fields of order $2^m$ , where $m$ is a natural number.

The $2^m$ elements of $\mathrm{GF}\left(2^m\right)$ are usually represented by the $2^m$ polynomials of a degrees less than $m$ with binary coefficients. Such a polynomial can either be specified by storing the coefficients in a BIGNUM object, using the $m$ lowest bits with bit numbers corresponding to degrees, or by storing the degrees that have coefficients of 1 in an integer array of at most $m+1$ elements. For the functions below, the array needs to be sorted in decreasing order and terminated by the delimiter element -1.

A specific representation of $\mathrm{GF}\left(2^m\right)$ is selected by choosing a polynomial of degree $m$ that is irreducible with binary coefficients, called the reducing polynomial. Making sure that $p$ is of the correct degree and indeed irreducible is the responsibility of the user. Typically, the following functions silently produce nonsensical results when given a p argument that is of the wrong degree or that is reducible. Storing the reducing polynomial requires $m+1$ bits in a BIGNUM object or an int array of up to $m+2$ elements, including the terminating -1 element.

All functions produce correct results even if some or all of the arguments r, a, and b point to the same object.

BN_GF2m_add() adds the two polynomials a and b with binary coefficients, which is equivalent to a pairwise exclusive OR operation on the coefficients, and places the result into r. In particular, if a and b are elements of the same representation of the same $\mathrm{GF}\left(2^m\right)$ field, the sum of both in that representation of that field is computed ( $r=a+b$ ). In contrast to most of the other functions described here, no modulo operation is performed. Consequently, if the degree of at least one of the arguments may be larger than or equal to $m$ , a follow-up call to BN_GF2m_mod_arr() or BN_GF2m_mod() may occasionally be useful.

BN_GF2m_sub() calculates the difference of a and b ( $r=a-b=a+b$ ). Since -1 is the same as 1 in binary arithmetic, BN_GF2m_sub() does exactly the same as BN_GF2m_add(). It is implemented as a macro.

BN_GF2m_cmp() is an alias for BN_ucmp(3). Despite its name, it does not attempt to find out whether the two polynomials belong to the same congruence class with respect to some Galois field.

BN_GF2m_mod_arr() and its wrapper BN_GF2m_mod() divide the polynomial with binary coefficients a by the polynomial with binary coefficients p and place the remainder into r ( $r=a\left(\mathrm{mod}p\right)$ ). If r and a point to the same object, the modular reduction is done in place.

BN_GF2m_mod_mul_arr() and its wrapper BN_GF2m_mod_mul() multiply a and b, divide the result by p, and place the remainder in r ( $r=a*b\left(\mathrm{mod}p\right)$ ).

BN_GF2m_mod_sqr_arr() and its wrapper BN_GF2m_mod_sqr() divide the square of a by p and place the remainder in r ( $r=a*a\left(\mathrm{mod}p\right)$ ).

BN_GF2m_mod_inv() and its wrapper BN_GF2m_mod_inv_arr() reduce b modulo p, find the multiplicative inverse element in $\mathrm{GF}\left(2^m\right)$ using the reducing polynomial $p$ , and place the result into r ( $r=1/b\left(\mathrm{mod}p\right)$ ).

BN_GF2m_mod_div() and its wrapper BN_GF2m_mod_div_arr() reduce a and b modulo p, compute their quotient in $\mathrm{GF}\left(2^m\right)$ using the reducing polynomial $p$ , and place the result into r ( $r=a/b\left(\mathrm{mod}p\right)$ ).

BN_GF2m_mod_exp_arr() and its wrapper BN_GF2m_mod_exp() reduce a modulo p, raise it to the power of exponent in $\mathrm{GF}\left(2^m\right)$ using the reducing polynomial $p$ , and place the result into r ( $r=a^{\mathrm{exponent}}\left(\mathrm{mod}p\right)$ ).

BN_GF2m_mod_sqrt_arr() and its wrapper BN_GF2m_mod_sqrt() reduce a modulo p, calculate the square root in $\mathrm{GF}\left(2^m\right)$ using the reducing polynomial $p$ by raising it to the power of $2^{m-1}$ , and place the result into r ( $r=\sqrt{a}\left(\mathrm{mod}p\right)$ ). This works because of the identity $a^{2^m}=a$ which holds for all field elements $a$ .

BN_GF2m_mod_solve_quad_arr() and its wrapper BN_GF2m_mod_solve_quad() reduce a modulo p, solve the quadratic equation $r^2+r=a\left(\mathrm{mod}p\right)$ in $\mathrm{GF}\left(2^m\right)$ using the reducing polynomial $p$ , and place the solution into r.

BN_GF2m_poly2arr() converts a polynomial from a bit string stored in the BIGNUM object poly_in to an array containing the degrees of the non-zero terms. It is the responsibility of the caller to provide an array arr_out of sufficient size and to provide the number of elements that can be stored in the array as the arr_size argument. The array is filled with the degrees in decreasing order, followed by an element with the value -1.

BN_GF2m_arr2poly() converts a polynomial from the array arr_in containing degrees to a bit string placed in the BIGNUM object poly_out. It is the responsibility of the caller to provide the storage for poly_out and to make sure that arr_in is terminated with a -1 element.

RETURN VALUES

BN_GF2m_cmp() interprets a and b as integer numbers and returns -1 if $\left|a\right|<\left|b\right|$ , 0 if $\left|a\right|=\left|b\right|$ , or 1 if $\left|a\right|>\left|b\right|$ .

BN_GF2m_poly2arr() returns:

• 0 if poly_in has the value 0;
• a number in the range from 2 to arr_size, inclusive, in case of success, specifying the number of elements that have been stored into the array;
• a number greater than arr_size if the function failed because the array was too small, specifying the array size that would have been needed.

The other functions return 1 for success or 0 for failure.

ERRORS

After some cases of failure, the following diagnostics can be retrieved with ERR_get_error(3), ERR_GET_REASON(3), and ERR_reason_error_string(3):

BN_R_NO_SOLUTION "no solution"

No solution exists for the equation that BN_GF2m_mod_solve_quad_arr() or BN_GF2m_mod_solve_quad() attempted to solve.

BN_R_INVALID_LENGTH "invalid length"

In one of the functions wrapping an *_arr() variant, the BIGNUM *p argument had a value of zero.

SEE ALSO

BN_add(3), BN_CTX_new(3), BN_new(3), BN_set_bit(3), EC_POINT_new(3)

Darrel Hankerson, Julio López Hernandez, and Alfred Menezes, Software Implementation of Elliptic Curve Cryptography over Binary Fields, CHES 2000: International Workshop on Cryptographic Hardware and Embedded Systems, Springer, Lecture Notes in Computer Science, vol 1965, https://doi.org/10.1007/3-540-44499-8_1, Worcester, MA, USA, August 2000, Algorithm 10: Modified Almost Inverse Algorithm for inversion in FP(2^m).

Specifications for Public-Key Cryptography, IEEE Standard 1363, https://doi.org/10.1109/IEEESTD.2000.92292, August 29, 2000, square-and-multiply algorithm A.5.1 for exponentiation, exponentiation algorithm A.4.1 for square roots, and algorithms A.4.7 and A.4.6 for the quadratic equation.