org.bouncycastle.math.ec.custom.gm

Class SM9P256V1Field

java.lang.Object

org.bouncycastle.math.ec.custom.gm.SM9P256V1Field

public class SM9P256V1Field
extends java.lang.Object

Prime-field arithmetic for the SM9 256-bit Barreto-Naehrig base field F_q (GM/T 0044.5-2016), used by the G1 curve SM9P256V1Curve.

Unlike SM2P256V1Field (whose sparse prime admits a fast Solinas reduction and stores elements in the ordinary residue representation), the SM9 BN prime is a general 256-bit prime, so this field keeps elements in Montgomery form (a·R mod q, R = 2^256), always fully reduced, below q, and multiplies by Koc, Acar and Kaliski's CIOS method.

Addition, subtraction, negation, multiplication, squaring and inversion run the same instructions whatever values they are given: no branch, early exit or array index depends on them, a result is brought below q by a subtraction of q that is always made, its difference kept or discarded through a mask, and the inverse is BouncyCastle's constant-time Mod.modOddInverse(int[], int[], int[]). This is the arithmetic of the F_q the SM9 pairing computes in, org.bouncycastle.math.ec.sm9.Fp, whose elements have the same form.

Method Summary

Modifier and Type	Method and Description
static void	add(int[] x, int[] y, int[] z)
static int[]	fromBigInteger(java.math.BigInteger x)
static void	inv(int[] x, int[] z) z = x^-1.
static boolean	isZero(int[] x) Deprecated. Nothing in the library calls this method. Use Nat256.isZero(int[]) instead: an element is 0 exactly when its Montgomery form is.
static void	multiply(int[] x, int[] y, int[] z) z = x y R^-1 mod q, the Montgomery product, which for x and y in Montgomery form is their product in that form: for each limb x_i of x, a running sum takes x_i y, then the multiple of q that makes its low limb 0, and is shifted down a limb.
static void	negate(int[] x, int[] z)
static void	random(java.security.SecureRandom r, int[] z) A uniformly random element, drawn as its Montgomery-form limbs: the form is a bijection on [0, q), so a uniform representation is a uniform element.
static void	randomMult(java.security.SecureRandom r, int[] z) A uniformly random non-zero element, as random(java.security.SecureRandom, int[]) draws them; if none of a thousand of them is other than 0, it throws IllegalStateException.
static void	square(int[] x, int[] z)
static void	squareN(int[] x, int n, int[] z) Deprecated. Nothing in the library calls this method. Use square(int[], int[]) n times instead.
static void	subtract(int[] x, int[] y, int[] z)
static java.math.BigInteger	toBigInteger(int[] xMont)
static void	twice(int[] x, int[] z) Deprecated. Nothing in the library calls this method. Use add(int[], int[], int[]) with x as both operands instead.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

add

public static void add(int[] x,
                       int[] y,
                       int[] z)

subtract

public static void subtract(int[] x,
                            int[] y,
                            int[] z)

negate

public static void negate(int[] x,
                          int[] z)

twice

@Deprecated
public static void twice(int[] x,
                                     int[] z)

Deprecated. Nothing in the library calls this method. Use add(int[], int[], int[]) with x as both operands instead.

multiply

public static void multiply(int[] x,
                            int[] y,
                            int[] z)

z = x y R^-1 mod q, the Montgomery product, which for x and y in Montgomery form is their product in that form: for each limb x_i of x, a running sum takes x_i y, then the multiple of q that makes its low limb 0, and is shifted down a limb. The sum stays below 2q, so one subtraction of q leaves the result below q. z may be x or y.

square

public static void square(int[] x,
                          int[] z)

squareN

@Deprecated
public static void squareN(int[] x,
                                       int n,
                                       int[] z)

Deprecated. Nothing in the library calls this method. Use square(int[], int[]) n times instead.

fromBigInteger

public static int[] fromBigInteger(java.math.BigInteger x)

toBigInteger

public static java.math.BigInteger toBigInteger(int[] xMont)

inv

public static void inv(int[] x,
                       int[] z)

z = x^-1. For x in Montgomery form, x R, Mod.checkedModOddInverse(int[], int[], int[]) gives the integer (x R)^-1 = x^-1 R^-1 mod q, and its Montgomery product with R^3 is x^-1 R. Zero has no inverse, and is refused with an ArithmeticException, as the other fields refuse it.

isZero

@Deprecated
public static boolean isZero(int[] x)

Deprecated. Nothing in the library calls this method. Use Nat256.isZero(int[]) instead: an element is 0 exactly when its Montgomery form is.

random

public static void random(java.security.SecureRandom r,
                          int[] z)

A uniformly random element, drawn as its Montgomery-form limbs: the form is a bijection on [0, q), so a uniform representation is a uniform element. The same rejection sampling SM2P256V1Field.random(java.security.SecureRandom, int[]) uses; q is a little over 2^255.5, so under 1.5 draws on average, and if none of a thousand draws is below q it throws IllegalStateException.

randomMult

public static void randomMult(java.security.SecureRandom r,
                              int[] z)

A uniformly random non-zero element, as random(java.security.SecureRandom, int[]) draws them; if none of a thousand of them is other than 0, it throws IllegalStateException.