Add javadoc and add random tests.

Author: gefeili

core/src/main/java/org/bouncycastle/crypto/kems/SAKKEKEMExtractor.java

@@ -2,6 +2,7 @@
 
 import java.math.BigInteger;
 
+import org.bouncycastle.crypto.Digest;
 import org.bouncycastle.crypto.EncapsulatedSecretExtractor;
 import org.bouncycastle.crypto.params.SAKKEPrivateKeyParameters;
 import org.bouncycastle.crypto.params.SAKKEPublicKeyParameters;
@@ -10,7 +11,22 @@
 import org.bouncycastle.util.Arrays;
 import org.bouncycastle.util.BigIntegers;
 
-
+/**
+ * Implements the receiver side of the SAKKE (Sakai-Kasahara Key Encryption) protocol
+ * as defined in RFC 6508. This class extracts the shared secret value (SSV) from
+ * encapsulated data using the receiver's private key.
+ * <p>
+ * The extraction process follows these steps (RFC 6508, Section 6.2.2):
+ * <ol>
+ *   <li>Parse encapsulated data into R_(b,S) and H</li>
+ *   <li>Compute pairing result w = &lt;R_(b,S), K_(b,S)&gt;</li>
+ *   <li>Recover SSV via SSV = H XOR HashToIntegerRange(w, 2^n)</li>
+ *   <li>Validate R_(b,S) by recomputing it with derived parameters</li>
+ * </ol>
+ * </p>
+ *
+ * @see <a href="https://datatracker.ietf.org/doc/html/rfc6508">Sakai-Kasahara Key Encryption (SAKKE)</a>
+ */
 public class SAKKEKEMExtractor
     implements EncapsulatedSecretExtractor
 {
@@ -22,65 +38,88 @@ public class SAKKEKEMExtractor
     private final ECPoint K_bs;
     private final int n; // Security parameter
     private final BigInteger identifier;
-
+    private final Digest digest;
+
+    /**
+     * Initializes the extractor with cryptographic parameters from the receiver's private key.
+     *
+     * @param privateKey The receiver's private key containing public parameters
+     *                   (curve, prime, generator, etc.) and the Receiver Secret Key (RSK).
+     *                   Must not be {@code null}.
+     */
     public SAKKEKEMExtractor(SAKKEPrivateKeyParameters privateKey)
     {
         SAKKEPublicKeyParameters publicKey = privateKey.getPublicParams();
         this.curve = publicKey.getCurve();
         this.q = publicKey.getQ();
-        this.P = publicKey.getP();
+        this.P = publicKey.getPoint();
         this.p = publicKey.getPrime();
         this.Z_S = publicKey.getZ();
-        this.K_bs = privateKey.getRSK();
-        this.n = publicKey.getN();
         this.identifier = publicKey.getIdentifier();
+        this.K_bs = P.multiply(this.identifier.add(privateKey.getMasterSecret()).modInverse(q)).normalize();
+        this.n = publicKey.getN();
+
+        this.digest = publicKey.getDigest();
     }
 
+    /**
+     * Extracts the shared secret value (SSV) from encapsulated data as per RFC 6508.
+     *
+     * @param encapsulation The encapsulated data containing:
+     *                      <ul>
+     *                        <li>R_(b,S): Elliptic curve point (uncompressed format, 257 bytes)</li>
+     *                        <li>H: Integer value (n/8 bytes)</li>
+     *                      </ul>
+     * @return The extracted SSV as a byte array.
+     * @throws IllegalStateException If: Validation of R_(b,S) fails
+     */
     @Override
     public byte[] extractSecret(byte[] encapsulation)
     {
-        try
-        {
-            // Step 1: Parse Encapsulated Data (R_bS, H)
-            ECPoint R_bS = curve.decodePoint(Arrays.copyOfRange(encapsulation, 0, 257));
-            BigInteger H = new BigInteger(Arrays.copyOfRange(encapsulation, 257, 274));
-
-            // Step 2: Compute w = <R_bS, K_bS> using pairing
-            BigInteger w = computePairing(R_bS, K_bs, p, q);
-
-            // Step 3: Compute SSV = H XOR HashToIntegerRange(w, 2^n)
-            BigInteger twoToN = BigInteger.ONE.shiftLeft(n);
-            BigInteger mask = SAKKEUtils.hashToIntegerRange(w.toByteArray(), twoToN);
-            BigInteger ssv = H.xor(mask);
-
-            // Step 4: Compute r = HashToIntegerRange(SSV || b)
-            BigInteger b = identifier;
-            BigInteger r = SAKKEUtils.hashToIntegerRange(Arrays.concatenate(ssv.toByteArray(), b.toByteArray()), q);
-
-            // Step 5: Validate R_bS
-            ECPoint bP = P.multiply(b).normalize();
-            ECPoint Test = bP.add(Z_S).multiply(r).normalize();
-            if (!R_bS.equals(Test))
-            {
-                throw new IllegalStateException("Validation of R_bS failed");
-            }
-
-            return BigIntegers.asUnsignedByteArray(n / 8, ssv);
-        }
-        catch (Exception e)
+        // Step 1: Parse Encapsulated Data (R_bS, H)
+        ECPoint R_bS = curve.decodePoint(Arrays.copyOfRange(encapsulation, 0, 257));
+        BigInteger H = BigIntegers.fromUnsignedByteArray(encapsulation, 257, 16);
+
+        // Step 2: Compute w = <R_bS, K_bS> using pairing
+        BigInteger w = computePairing(R_bS, K_bs, p, q);
+
+        // Step 3: Compute SSV = H XOR HashToIntegerRange(w, 2^n)
+        BigInteger twoToN = BigInteger.ONE.shiftLeft(n);
+        BigInteger mask = SAKKEKEMSGenerator.hashToIntegerRange(w.toByteArray(), twoToN, digest);
+        BigInteger ssv = H.xor(mask).mod(p);
+
+        // Step 4: Compute r = HashToIntegerRange(SSV || b)
+        BigInteger b = identifier;
+        BigInteger r = SAKKEKEMSGenerator.hashToIntegerRange(Arrays.concatenate(ssv.toByteArray(), b.toByteArray()), q, digest);
+
+        // Step 5: Validate R_bS
+        ECPoint bP = P.multiply(b).normalize();
+        ECPoint Test = bP.add(Z_S).multiply(r).normalize();
+        if (!R_bS.equals(Test))
         {
-            throw new IllegalStateException("SAKKE extraction failed: " + e.getMessage());
+            throw new IllegalStateException("Validation of R_bS failed");
         }
+
+        return BigIntegers.asUnsignedByteArray(n / 8, ssv);
     }
 
     @Override
     public int getEncapsulationLength()
     {
-        return 0;
+        return 273; //257 (length of ECPoint) + 16 (length of Hash)
     }
 
-
-    public static BigInteger computePairing(ECPoint R, ECPoint Q, BigInteger p, BigInteger q)
+    /**
+     * Computes the Tate-Lichtenbaum pairing &lt;R, Q&gt; for SAKKE validation.
+     * Follows the pairing algorithm described in RFC 6508, Section 3.2.
+     *
+     * @param R First pairing input (elliptic curve point)
+     * @param Q Second pairing input (elliptic curve point)
+     * @param p Prime field characteristic
+     * @param q Subgroup order
+     * @return Pairing result in PF_p[q], represented as a field element
+     */
+    static BigInteger computePairing(ECPoint R, ECPoint Q, BigInteger p, BigInteger q)
     {
         // v = (1,0) in F_p^2
         BigInteger[] v = new BigInteger[]{BigInteger.ONE, BigInteger.ZERO};
@@ -133,6 +172,16 @@ public static BigInteger computePairing(ECPoint R, ECPoint Q, BigInteger p, BigI
         return v[1].multiply(v[0].modInverse(p)).mod(p);
     }
 
+    /**
+     * Performs multiplication in F_p^2 field.
+     *
+     * @param x_real Real component of first operand
+     * @param x_imag Imaginary component of first operand
+     * @param y_real Real component of second operand
+     * @param y_imag Imaginary component of second operand
+     * @param p      Prime field characteristic
+     * @return Result of multiplication in F_p^2 as [real, imaginary] array
+     */
     static BigInteger[] fp2Multiply(BigInteger x_real, BigInteger x_imag, BigInteger y_real, BigInteger y_imag, BigInteger p)
     {
         return new BigInteger[]{
@@ -141,6 +190,14 @@ static BigInteger[] fp2Multiply(BigInteger x_real, BigInteger x_imag, BigInteger
         };
     }
 
+    /**
+     * Computes squaring operation in F_p^2 field.
+     *
+     * @param currentX Real component of input
+     * @param currentY Imaginary component of input
+     * @param p        Prime field characteristic
+     * @return Squared result in F_p^2 as [newX, newY] array
+     */
     static BigInteger[] fp2PointSquare(BigInteger currentX, BigInteger currentY, BigInteger p)
     {
         BigInteger xPlusY = currentX.add(currentY).mod(p);

core/src/main/java/org/bouncycastle/crypto/kems/SAKKEKEMSGenerator.java

@@ -1,5 +1,6 @@
 package org.bouncycastle.crypto.kems;
 
+import org.bouncycastle.crypto.Digest;
 import org.bouncycastle.crypto.EncapsulatedSecretGenerator;
 import org.bouncycastle.crypto.SecretWithEncapsulation;
 import org.bouncycastle.crypto.params.AsymmetricKeyParameter;
@@ -12,19 +13,59 @@
 import java.math.BigInteger;
 import java.security.SecureRandom;
 
+/**
+ * This class implements the SAKKE (Sakai-Kasahara Key Encryption) Key Encapsulation Mechanism
+ * as defined in RFC 6508. It generates an encapsulated shared secret value (SSV) using
+ * Identity-Based Encryption (IBE) for secure transmission from a Sender to a Receiver.
+ * <p>
+ * The algorithm follows these steps (as per RFC 6508, Section 6.2.1):
+ * <ol>
+ *   <li>Generate a random SSV in the range [0, 2^n - 1].</li>
+ *   <li>Compute r = HashToIntegerRange(SSV || b, q).</li>
+ *   <li>Compute R_(b,S) = [r]([b]P + Z_S) on the elliptic curve.</li>
+ *   <li>Compute H = SSV XOR HashToIntegerRange(g^r, 2^n).</li>
+ *   <li>Encode the encapsulated data (R_(b,S), H).</li>
+ * </ol>
+ * </p>
+ *
+ * @see <a href="https://datatracker.ietf.org/doc/html/rfc6508">RFC 6508: Sakai-Kasahara Key Encryption (SAKKE)</a>
+ */
 public class SAKKEKEMSGenerator
     implements EncapsulatedSecretGenerator
 {
     private final SecureRandom random;
 
+    /**
+     * Constructs a SAKKEKEMSGenerator with the specified source of randomness.
+     *
+     * @param random a {@link SecureRandom} instance for generating cryptographically secure random values.
+     *               Must not be {@code null}.
+     */
     public SAKKEKEMSGenerator(SecureRandom random)
     {
         this.random = random;
     }
 
+    /**
+     * Generates an encapsulated shared secret value (SSV) using the recipient's public key parameters
+     * as specified in RFC 6508, Section 6.2.1.
+     * <p>
+     * This method performs the following operations:
+     * <ul>
+     *   <li>Derives cryptographic parameters from the recipient's public key.</li>
+     *   <li>Generates a random SSV and computes the encapsulation components (R_(b,S), H).</li>
+     *   <li>Encodes the encapsulated data as specified in RFC 6508, Section 4.</li>
+     * </ul>
+     * </p>
+     *
+     * @param recipientKey the recipient's public key parameters. Must be an instance of
+     *                     {@link SAKKEPublicKeyParameters}. Must not be {@code null}.
+     * @return a {@link SecretWithEncapsulation} containing the SSV and the encapsulated data.
+     */
     @Override
     public SecretWithEncapsulation generateEncapsulated(AsymmetricKeyParameter recipientKey)
     {
+        // Extract public parameters from the recipient's key
         SAKKEPublicKeyParameters keyParameters = (SAKKEPublicKeyParameters)recipientKey;
         ECPoint Z = keyParameters.getZ();
         BigInteger b = keyParameters.getIdentifier();
@@ -33,54 +74,31 @@ public SecretWithEncapsulation generateEncapsulated(AsymmetricKeyParameter recip
         BigInteger g = keyParameters.getG();
         int n = keyParameters.getN();
         ECCurve curve = keyParameters.getCurve();
-        ECPoint P = keyParameters.getP();
+        ECPoint P = keyParameters.getPoint();
+        Digest digest = keyParameters.getDigest();
 
         // 1. Generate random SSV in range [0, 2^n - 1]
         BigInteger ssv = new BigInteger(n, random);
 
-
         // 2. Compute r = HashToIntegerRange(SSV || b, q)
-
-        BigInteger r = SAKKEUtils.hashToIntegerRange(Arrays.concatenate(ssv.toByteArray(), b.toByteArray()), q);
+        BigInteger r = hashToIntegerRange(Arrays.concatenate(ssv.toByteArray(), b.toByteArray()), q, digest);
 
 
         // 3. Compute R_(b,S) = [r]([b]P + Z_S)
         ECPoint bP = P.multiply(b).normalize();
-        ECPoint R_bS = bP.add(Z).multiply(r).normalize();         // [r]([b]P + Z_S)
+        ECPoint R_bS = bP.add(Z).multiply(r).normalize();
 
         // 4. Compute H = SSV XOR HashToIntegerRange( g^r, 2^n )
-        BigInteger[] v = fp2Exponentiate(p, BigInteger.ONE, g, r, curve);
-        BigInteger g_r = v[1].multiply(v[0].modInverse(p)).mod(p);
-
-        BigInteger mask = SAKKEUtils.hashToIntegerRange(g_r.toByteArray(), BigInteger.ONE.shiftLeft(n)); // 2^n
-
-        BigInteger H = ssv.xor(mask);
-        //System.out.println(new String(Hex.encode(H.toByteArray())));
-        // 5. Encode encapsulated data (R_bS, H)
-        byte[] encapsulated = Arrays.concatenate(R_bS.getEncoded(false), H.toByteArray());
-
-        return new SecretWithEncapsulationImpl(
-            BigIntegers.asUnsignedByteArray(n / 8, ssv), // Output SSV as key material
-            encapsulated
-        );
-    }
-
-
-    public static BigInteger[] fp2Exponentiate(
-        BigInteger p,
-        BigInteger pointX,
-        BigInteger pointY,
-        BigInteger n,
-        ECCurve curve)
-    {
-        BigInteger[] result = new BigInteger[2];
+        BigInteger pointX = BigInteger.ONE;
+        BigInteger pointY = g;
+        BigInteger[] v = new BigInteger[2];
 
         // Initialize result with the original point
-        BigInteger currentX = pointX;
-        BigInteger currentY = pointY;
+        BigInteger currentX = BigInteger.ONE;
+        BigInteger currentY = g;
         ECPoint current = curve.createPoint(currentX, currentY);
 
-        int numBits = n.bitLength();
+        int numBits = r.bitLength();
         BigInteger[] rlt;
         // Process bits from MSB-1 down to 0
         for (int i = numBits - 2; i >= 0; i--)
@@ -91,7 +109,7 @@ public static BigInteger[] fp2Exponentiate(
             currentX = rlt[0];
             currentY = rlt[1];
             // Multiply if bit is set
-            if (n.testBit(i))
+            if (r.testBit(i))
             {
                 rlt = SAKKEKEMExtractor.fp2Multiply(currentX, currentY, pointX, pointY, p);
 
@@ -100,8 +118,59 @@ public static BigInteger[] fp2Exponentiate(
             }
         }
 
-        result[0] = currentX;
-        result[1] = currentY;
-        return result;
+        v[0] = currentX;
+        v[1] = currentY;
+        BigInteger g_r = v[1].multiply(v[0].modInverse(p)).mod(p);
+
+        BigInteger mask = hashToIntegerRange(g_r.toByteArray(), BigInteger.ONE.shiftLeft(n), digest); // 2^n
+
+        BigInteger H = ssv.xor(mask);
+        // 5. Encode encapsulated data (R_bS, H)
+//        byte[] encapsulated = Arrays.concatenate(new byte[]{(byte)0x04},
+//            BigIntegers.asUnsignedByteArray(n, R_bS.getXCoord().toBigInteger()),
+//            BigIntegers.asUnsignedByteArray(n, R_bS.getYCoord().toBigInteger()),
+//            BigIntegers.asUnsignedByteArray(16, H));
+        byte[] encapsulated = Arrays.concatenate(R_bS.getEncoded(false), BigIntegers.asUnsignedByteArray(16, H));
+
+        return new SecretWithEncapsulationImpl(
+            BigIntegers.asUnsignedByteArray(n / 8, ssv), // Output SSV as key material
+            encapsulated
+        );
+    }
+
+    static BigInteger hashToIntegerRange(byte[] input, BigInteger q, Digest digest)
+    {
+        // RFC 6508 Section 5.1: Hashing to an Integer Range
+        byte[] hash = new byte[digest.getDigestSize()];
+
+        // Step 1: Compute A = hashfn(s)
+        digest.update(input, 0, input.length);
+        digest.doFinal(hash, 0);
+        byte[] A = hash.clone();
+
+        // Step 2: Initialize h_0 to all-zero bytes of hashlen size
+        byte[] h = new byte[digest.getDigestSize()];
+
+        // Step 3: Compute l = Ceiling(lg(n)/hashlen)
+        int l = q.bitLength() >> 8;
+
+        BigInteger v = BigInteger.ZERO;
+
+        // Step 4: Compute h_i and v_i
+        for (int i = 0; i <= l; i++)
+        {
+            // h_i = hashfn(h_{i-1})
+            digest.update(h, 0, h.length);
+            digest.doFinal(h, 0);
+            // v_i = hashfn(h_i || A)
+            digest.update(h, 0, h.length);
+            digest.update(A, 0, A.length);
+            byte[] v_i = new byte[digest.getDigestSize()];
+            digest.doFinal(v_i, 0);
+            // Append v_i to v'
+            v = v.shiftLeft(v_i.length * 8).add(new BigInteger(1, v_i));
+        }
+        // Step 6: v = v' mod n
+        return v.mod(q);
     }
 }