# OpenBSD manual page server

Manual Page Search Parameters

## 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 $GF2m$ , the Galois fields of order $2m$ , where $m$ is a natural number.

The $2m$ elements of $GF2m$ are usually represented by the $2m$ 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 $GF2m$ 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.

() 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 $GF2m$ 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.

() 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.

() 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.

() and its wrapper () divide the polynomial with binary coefficients a by the polynomial with binary coefficients p and place the remainder into r ( $r=a(modp)$ ). If r and a point to the same object, the modular reduction is done in place.

() and its wrapper () multiply a and b, divide the result by p, and place the remainder in r ( $r=a*b(modp)$ ).

() and its wrapper () divide the square of a by p and place the remainder in r ( $r=a*a(modp)$ ).

() and its wrapper () reduce b modulo p, find the multiplicative inverse element in $GF2m$ using the reducing polynomial $p$ , and place the result into r ( $r=1/b(modp)$ ).

() and its wrapper () reduce a and b modulo p, compute their quotient in $GF2m$ using the reducing polynomial $p$ , and place the result into r ( $r=a/b(modp)$ ).

() and its wrapper () reduce a modulo p, raise it to the power of exponent in $GF2m$ using the reducing polynomial $p$ , and place the result into r ( $r=aexponent(modp)$ ).

() and its wrapper () reduce a modulo p, calculate the square root in $GF2m$ using the reducing polynomial $p$ by raising it to the power of $2m−1$ , and place the result into r ( $r=a(modp)$ ). This works because of the identity $a2m=a$ which holds for all field elements $a$ .

() and its wrapper () reduce a modulo p, solve the quadratic equation $r2+r=a(modp)$ in $GF2m$ using the reducing polynomial $p$ , and place the solution into r.

() 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.

() 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 $a , 0 if $a=b$ , or 1 if $a>b$ .

`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):

"no solution"
No solution exists for the equation that `BN_GF2m_mod_solve_quad_arr`() or `BN_GF2m_mod_solve_quad`() attempted to solve.
"invalid length"
In one of the functions wrapping an `*_arr`() variant, the BIGNUM *p argument had a value of zero.