org.bouncycastle.math.ec.sm9
Class Fp12

java.lang.Object
  org.bouncycastle.math.ec.sm9.Fp12

public class Fp12

extends java.lang.Object

Element of F_p12 = F_p4[w]/(w^3 - v), i.e. w^3 = v, for SM9 (GM/T 0044.5-2016, 1-2-4-12 tower). This is the pairing target group G_T. Written a + b*w + c*w^2 with a the low and c the high (w^2-coefficient) dimension, a, b, c in Fp4. Immutable: its ninety-six limbs, a's, b's and then c's, are not changed once it is made.

The arithmetic is Fp's, on fixed-width limbs, and runs the same instructions whatever the values it is given; the static methods compute on elements held in int arrays, as Fp4's do. The products and squares form the products in F_q their formulas call for in full, as wide values - see Fp#WIDE - add and subtract them into each of the twelve coefficients of their result unreduced, and reduce each coefficient once.

Method Summary

boolean	equals(java.lang.Object other)
int	hashCode()
Fp12	multiply(Fp12 o)
Fp12	pow(java.math.BigInteger e) Variable-time exponentiation, for PUBLIC exponents only; the pairing's final exponentiation does not call it, raising to the BN parameter t through a chain of its own.
Fp12	powSecure(java.math.BigInteger e) Exponentiation by a SECRET exponent, a signing nonce or an ephemeral secret, as in w = g^r, of a base that can change from call to call - for SM9, the pairing value each key exchange forms with its peer's value and raises to its ephemeral.
Fp12	powSecureFixedBase(java.math.BigInteger e) Exponentiation by a SECRET exponent, as powSecure(java.math.BigInteger), of a PUBLIC base that is raised to one exponent after another - for SM9, the pairing value a master public key fixes, which signing, encryption, encapsulation and the key exchange raise to their nonce or ephemeral: by Lim and Lee's comb, over two tables of thirty-two powers of this element each that the first call makes and this element keeps, 24 KB of values anyone who knows the base can compute.

Methods inherited from class java.lang.Object

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

Method Detail

multiply

public Fp12 multiply(Fp12 o)

pow

public Fp12 pow(java.math.BigInteger e)

Variable-time exponentiation, for PUBLIC exponents only; the pairing's final exponentiation does not call it, raising to the BN parameter t through a chain of its own. For secret exponents use powSecure(java.math.BigInteger). The base must lie in the cyclotomic subgroup, as G_T and every value the final exponentiation exponentiates do, since the squaring is #cyclotomicSquare.

powSecure

public Fp12 powSecure(java.math.BigInteger e)

Exponentiation by a SECRET exponent, a signing nonce or an ephemeral secret, as in w = g^r, of a base that can change from call to call - for SM9, the pairing value each key exchange forms with its peer's value and raises to its ephemeral. The exponent is split into four, whose bits are read together, a column at a time from the top: each column squares the running value once and multiplies in an entry of a table of sixteen, the same steps whatever the bits are, and each entry is read out of the table in full, so that neither the operations nor the memory they read depend on the exponent - eighty-one squarings and eighty-one products, and seven more products for the table, where windows of four bits over the exponent blinded into 320 bits would take 316 squarings and ninety-four products. Unlike pow(java.math.BigInteger), it does not leak the exponent's Hamming weight or individual bits. The exponent must satisfy 0 <= e < N (every SM9 secret exponent is reduced mod the group order N), and the base must lie in the order-N subgroup of G_T, which every value SM9 raises to a secret power does - each is an R-ate pairing result, and the final exponentiation puts it there.

The split is Galbraith and Scott's. Raising to q is a Frobenius map, a handful of products in F_q, and on the order-N subgroup it is raising to LAMBDA = q mod N = 6t^2, so g^e is the product of g^k0, (g^q)^k1, (g^(q^2))^k2 and (g^(q^3))^k3 for any four exponents with k0 + k1 LAMBDA + k2 LAMBDA^2 + k3 LAMBDA^3 = e mod N; forms four below 2^82 from e and a random draw. They are read in Faz-Hernandez, Longa and Sanchez's sign-aligned columns: k0 is odd and its digits are 1 or -1, the top one 1, and the digits of the other three are 0 or the digit of k0 in the same column - see . So entry v + 8s of the table, for v = v1 + 2v2 + 4v3 and s = 0 or 1, is (g g^(q v1) g^(q^2 v2) g^(q^3 v3))^(1 - 2s), and each column reads the entry its digits of k1, k2 and k3 pick out, with s = 1 where its digit of k0 is -1: the inverse of an element of the subgroup is its conjugate, so the last eight entries are the conjugates of the first eight. Every entry carries g or its inverse, so none is 1, an element all but one of whose twelve coefficients are 0.

A random multiple of N added to e, as the other secret exponentiations and multiplications blind their secret, would not change the four exponents - the split of e + rN is the split of e - so decompose blinds the split itself, with random multiples of four vectors that stand for 0 mod N: sixty-three random bits, as many as draws for its multiple of N, and the columns differ from call to call whatever e is. They take the same steps whatever e is as well, from a top column whose digit of k0 is 1, so that no column spends its steps on the running value 1.

The blinding leaves each running value a power of the base fixed by the columns already taken, so anyone who knows the base could work out, column by column, the value each step is given. So the table's entries carry a random non-zero m in F_q drawn for the call - the Frobenius fixes m, so the conjugates carry it too - and the running value carries a factor f of F_q, starting at m: the square #cyclotomicSqr forms of f y carries f^2, and a product with an entry carries f m, so f is updated with each step and divided out once at the end. Every value the exponentiation works on carries a factor no two calls share, as the Miller loop's values do.

Reading the table in full still leaves one step of each column's scan depending on the column's bits: the one that moves its entry into place, the only step that moves any words. So each column's scan starts at an entry drawn at random for it, one byte each of an eighty-two-byte draw the call makes, and wraps round, and the value it reads into is cleared first - see #lookup.

powSecureFixedBase

public Fp12 powSecureFixedBase(java.math.BigInteger e)

Exponentiation by a SECRET exponent, as powSecure(java.math.BigInteger), of a PUBLIC base that is raised to one exponent after another - for SM9, the pairing value a master public key fixes, which signing, encryption, encapsulation and the key exchange raise to their nonce or ephemeral: by Lim and Lee's comb, over two tables of thirty-two powers of this element each that the first call makes and this element keeps, 24 KB of values anyone who knows the base can compute. Each call takes thirty-one squarings and sixty-three products, where powSecure(java.math.BigInteger), which makes its table for the call, takes eighty-one squarings and eighty-eight products, seven of them for its table; the first also makes the tables, in 288 squarings and sixty-two products. The result is powSecure's, and so are the preconditions: 0 <= e < N, and the base must lie in the order-N subgroup of G_T.

The exponent is blinded with a random multiple of N into exactly 320 bits, as the secret multiplications in G1 and G2 blind their scalars - see - and its bits fall into sixty-four columns of five, column c holding bits c, c + 64, c + 128, c + 192 and c + 256. Entry d of the first table, for d = d0 + 2d1 + 4d2 + 8d3 + 16d4, is this element g raised to 1 + d0 + d1 2^64 + d2 2^128 + d3 2^192 + d4 2^256, and entry d of the second is that raised to 2^32. The columns are read in pairs, c and c + 32, from the top pair down: each pair multiplies into the running value the entry column c's bits pick out of the first table and the one column c + 32's bits pick out of the second, the same steps whatever the bits are, and the running value is squared once between one pair and the next - thirty-one times, where a comb over the first table alone squares it between one column and the next, sixty-three times; and each entry is read out of its table in full, through #lookup, so that neither the operations nor the memory they read depend on the exponent. The 1 in each entry's exponent makes entry 0 of the first table g rather than 1, an element all but one of whose twelve coefficients are 0, which a column whose bits are all 0 would otherwise multiply in, and entry 0 of the second g^(2^32). The product of the entries the columns read then carries g^(2^64 - 1) as well, so the comb is run over the blinded exponent less 2^64 - 1, which the blinding leaves positive.

As in powSecure(java.math.BigInteger), every call multiplies the tables' entries by a random non-zero m in F_q, drawn for it, before it reads any of them, and the running value carries a factor f of F_q that starts at m, is squared with each squaring and multiplied by m with each product, and is divided out at the end: every value the exponentiation works on carries a factor no two calls share. The copies of the tables the factor is applied to are erased when the call ends; the tables themselves hold only powers of the base. Two threads that make the first call together may both make the tables, and get equal tables.

And as in powSecure(java.math.BigInteger), each column's scan of its table starts at an entry drawn at random for it, one byte each of a sixty-four-byte draw the call makes, and wraps round, and the value it reads into is cleared first, so that the step of the scan that moves the column's entry into place does not give the column's bits away - see #lookup.

equals

public boolean equals(java.lang.Object other)

hashCode

public int hashCode()