Add java doc and more tests with different digests

Author: gefeili

core/src/main/java/org/bouncycastle/crypto/params/ECCSIKeyGenerationParameters.java

@@ -9,22 +9,68 @@
 import org.bouncycastle.math.ec.ECPoint;
 import org.bouncycastle.util.Arrays;
 
+/**
+ * Parameters for ECCSI key generation.
+ *
+ * <p>
+ * This class encapsulates the parameters required for ECCSI (Elliptic Curve
+ * Certificateless Signatures for Identity-based encryption) key generation.
+ * It holds the elliptic curve domain parameters and computes the key pair
+ * components used in ECCSI.
+ * </p>
+ *
+ * <p>
+ * The secret component {@code ksak} is generated randomly and reduced modulo
+ * {@code q}, while {@code kpak} is derived from {@code ksak} by multiplying the
+ * generator point.
+ * </p>
+ */
 public class ECCSIKeyGenerationParameters
     extends KeyGenerationParameters
 {
+    /**
+     * The order of the elliptic curve.
+     */
     private final BigInteger q;
+
+    /**
+     * The generator (base point) of the elliptic curve.
+     */
     private final ECPoint G;
+
+    /**
+     * The digest algorithm used in key generation.
+     */
     private final Digest digest;
+
+    /**
+     * The identifier (e.g. user identity) used in key generation.
+     */
     private final byte[] id;
+
+    /**
+     * The secret key component (ksak) used in ECCSI, generated randomly.
+     */
     private final BigInteger ksak;
+
+    /**
+     * The public key component (kpak), computed as G * ksak.
+     */
     private final ECPoint kpak;
+
+    /**
+     * The bit length used for key generation (typically the bit length of the curve's parameter A).
+     */
     private final int n;
 
     /**
-     * initialise the generator with a source of randomness
-     * and a strength (in bits).
+     * Constructs an instance of {@code ECCSIKeyGenerationParameters} with the specified
+     * source of randomness, elliptic curve parameters, digest algorithm, and identifier.
      *
-     * @param random the random byte source.
+     * @param random the source of randomness.
+     * @param params the elliptic curve parameters (in X9.62 format) providing the curve, order, and generator.
+     * @param digest the digest algorithm to be used.
+     * @param id     the identifier associated with the key generation (e.g. a user or device ID).
      */
     public ECCSIKeyGenerationParameters(SecureRandom random, X9ECParameters params, Digest digest, byte[] id)
     {
@@ -38,36 +84,73 @@ public ECCSIKeyGenerationParameters(SecureRandom random, X9ECParameters params,
         this.kpak = G.multiply(ksak).normalize();
     }
 
+    /**
+     * Returns a copy of the identifier used in these parameters.
+     *
+     * @return a byte array containing the identifier.
+     */
     public byte[] getId()
     {
-        return id;
+        return Arrays.clone(id);
     }
 
+    /**
+     * Returns the public key component (kpak) corresponding to the secret key.
+     *
+     * @return the public key point.
+     */
     public ECPoint getKPAK()
     {
         return kpak;
     }
 
+    /**
+     * Computes the session secret key (SSK) by adding the provided value to the secret key component
+     * and reducing modulo the curve order.
+     *
+     * @param hs_v a BigInteger value (typically derived from a hash) to be added to the secret.
+     * @return the computed session secret key.
+     */
     public BigInteger computeSSK(BigInteger hs_v)
     {
         return ksak.add(hs_v).mod(q);
     }
 
+    /**
+     * Returns the order of the elliptic curve.
+     *
+     * @return the curve order.
+     */
     public BigInteger getQ()
     {
         return q;
     }
 
+    /**
+     * Returns the generator (base point) of the elliptic curve.
+     *
+     * @return the generator point.
+     */
     public ECPoint getG()
     {
         return G;
     }
 
+    /**
+     * Returns the digest algorithm used for key generation.
+     *
+     * @return the digest.
+     */
     public Digest getDigest()
     {
         return digest;
     }
 
+    /**
+     * Returns the bit length used in key generation.
+     *
+     * @return the bit length.
+     */
     public int getN()
     {
         return n;

core/src/main/java/org/bouncycastle/crypto/params/ECCSIPrivateKeyParameters.java

@@ -2,24 +2,69 @@
 
 import java.math.BigInteger;
 
+/**
+ * Represents the private key parameters for the Elliptic Curve-based Certificateless
+ * Signature Infrastructure (ECCSI) scheme as defined in RFC 6507.
+ *
+ * <p>
+ * This class encapsulates the secret signing key (SSK) used in ECCSI. The SSK is generated by
+ * the Key Management Service (KMS) and is a random integer modulo the order of the elliptic curve.
+ * It is paired with the corresponding public key parameters, represented by an instance of
+ * {@link ECCSIPublicKeyParameters}, to form the complete key material required for generating
+ * and verifying ECCSI signatures without the use of traditional certificates.
+ * </p>
+ *
+ * <p>
+ * Per RFC 6507 Section 5.1:
+ * <ul>
+ *   <li>The SSK is generated as a random value in the appropriate range.</li>
+ *   <li>It is used in conjunction with the public validation token (PVT) to perform signature
+ *       operations.</li>
+ *   <li>The combination of the SSK and the public key parameters enables certificateless
+ *       signature generation and verification.</li>
+ * </ul>
+ * </p>
+ *
+ * @see ECCSIPublicKeyParameters
+ * @see <a href="https://datatracker.ietf.org/doc/html/rfc6507">
+ *      RFC 6507: Elliptic Curve-Based Certificateless Signatures for Identity-Based Encryption (ECCSI)
+ *      </a>
+ */
 public class ECCSIPrivateKeyParameters
     extends AsymmetricKeyParameter
 {
     private final BigInteger ssk;
     private final ECCSIPublicKeyParameters pub;
 
+    /**
+     * Constructs {@code ECCSIPrivateKeyParameters} with the specified secret signing key
+     * and associated public key parameters.
+     *
+     * @param ssk the secret signing key (SSK) as a BigInteger.
+     * @param pub the corresponding public key parameters, which encapsulate the public validation token.
+     */
     public ECCSIPrivateKeyParameters(BigInteger ssk, ECCSIPublicKeyParameters pub)
     {
         super(true);
         this.ssk = ssk;
         this.pub = pub;
     }
 
+    /**
+     * Returns the public key parameters associated with this private key.
+     *
+     * @return the {@link ECCSIPublicKeyParameters} containing the public validation token (PVT).
+     */
     public ECCSIPublicKeyParameters getPublicKeyParameters()
     {
         return pub;
     }
 
+    /**
+     * Returns the secret signing key (SSK) used in ECCSI.
+     *
+     * @return the SSK as a BigInteger.
+     */
     public BigInteger getSSK()
     {
         return ssk;

core/src/main/java/org/bouncycastle/crypto/params/ECCSIPublicKeyParameters.java

@@ -2,17 +2,47 @@
 
 import org.bouncycastle.math.ec.ECPoint;
 
+/**
+ * Represents the public key parameters for the Elliptic Curve-based Certificateless
+ * Signature Infrastructure (ECCSI) scheme as defined in RFC 6507.
+ * <p>
+ * This class encapsulates the Public Validation Token (PVT) required for verifying
+ * ECCSI signatures. The PVT is cryptographically bound to a user's identity and
+ * generated by the Key Management Service (KMS) as part of the key material.
+ *
+ * <p>Per RFC 6507 Section 5.1:
+ * <ul>
+ *   <li>The PVT is derived from the user's identity and KMS secret material</li>
+ *   <li>Used during signature verification to validate the signer's identity</li>
+ *   <li>Does not require certificates for authentication</li>
+ * </ul>
+ *
+ * @see <a href="https://datatracker.ietf.org/doc/html/rfc6507">RFC 6507:  Elliptic Curve-Based Certificateless
+ *  * Signatures for Identity-Based Encryption (ECCSI)</a>
+ */
+
 public class ECCSIPublicKeyParameters
     extends AsymmetricKeyParameter
 {
     private final ECPoint pvt;
 
+    /**
+     * Constructs {@code ECCSIPublicKeyParameters} with the provided Public Validation Token (PVT).
+     */
     public ECCSIPublicKeyParameters(ECPoint pvt)
     {
         super(false);
         this.pvt = pvt;
     }
 
+    /**
+     * Returns the Public Validation Token (PVT) for signature verification.
+     * <p>
+     * The PVT is used in conjunction with the KMS Public Authentication Key (KPAK)
+     * to verify signatures per RFC 6507 Section 5.2.2.
+     *
+     * @return The PVT as an elliptic curve point in uncompressed format
+     */
     public final ECPoint getPVT()
     {
         return pvt;

core/src/main/java/org/bouncycastle/crypto/signers/ECCSISigner.java

@@ -20,14 +20,6 @@
 /**
  * Implementation of Elliptic Curve-based Certificateless Signatures for Identity-Based Encryption (ECCSI)
  * as defined in RFC 6507.
- * <p>
- * This class handles both signature generation and verification using the ECCSI scheme. It supports:
- * <ul>
- *   <li>NIST P-256 (secp256r1) elliptic curve parameters</li>
- *   <li>SHA-256 hash function</li>
- *   <li>Certificateless signatures using KMS Public Authentication Key (KPAK)</li>
- *   <li>Identity-based signatures with Secret Signing Key (SSK)</li>
- * </ul>
  *
  * @see <a href="https://datatracker.ietf.org/doc/html/rfc6507">RFC 6507:  Elliptic Curve-Based Certificateless
  * Signatures for Identity-Based Encryption (ECCSI)</a>
@@ -48,7 +40,12 @@ public class ECCSISigner
     private boolean forSigning;
     private final int N;
 
-
+    /**
+     * Constructs an ECCSI signer/verifier with KMS Public Authentication Key and user identity.
+     *
+     * @param kpak KMS Public Authentication Key (KPAK) from RFC 6507 Section 2
+     * @param id   User identity byte array formatted
+     */
     public ECCSISigner(ECPoint kpak, X9ECParameters params, Digest digest, byte[] id)
     {
         this.kpak = kpak;
@@ -60,6 +57,15 @@ public ECCSISigner(ECPoint kpak, X9ECParameters params, Digest digest, byte[] id
         this.N = (params.getCurve().getOrder().bitLength() + 7) >> 3;
     }
 
+    /**
+     * Initializes the signer for either signature generation or verification.
+     *
+     * @param forSigning true for signing, false for verification
+     * @param param      Key parameters:
+     *                   - For signing: {@code ParametersWithRandom} containing {@code ECCSIPrivateKeyParameters}
+     *                   - For verification: {@code ECCSIPublicKeyParameters}
+     * @throws IllegalArgumentException if invalid parameters are provided
+     */
     @Override
     public void init(boolean forSigning, CipherParameters param)
     {
@@ -94,6 +100,17 @@ public void update(byte[] in, int off, int len)
         }
     }
 
+    /**
+     * Generates an ECCSI signature according to RFC 6507 Section 5.2.1.
+     *
+     * @return Signature structure containing:
+     *         - r (N bytes)
+     *         - s (N bytes)
+     *         - PVT (Public Validation Token)
+     * @throws CryptoException       if cryptographic operations fail
+     * @throws DataLengthException   if input data is invalid
+     * @throws IllegalArgumentException if invalid SSK or j parameter is detected
+     */
     @Override
     public byte[] generateSignature()
         throws CryptoException, DataLengthException
@@ -116,6 +133,13 @@ public byte[] generateSignature()
             params.getPublicKeyParameters().getPVT().getEncoded(false));
     }
 
+    /**
+     * Verifies an ECCSI signature according to RFC 6507 Section 5.2.2.
+     *
+     * @param signature Signature to verify (r || s || PVT)
+     * @return true if signature is valid, false otherwise
+     * @throws IllegalArgumentException if signature format is invalid
+     */
     @Override
     public boolean verifySignature(byte[] signature)
     {
@@ -141,6 +165,13 @@ public boolean verifySignature(byte[] signature)
         return rComputed.mod(q).equals(r.mod(q));
     }
 
+    /**
+     * Resets the signer/verifier state and performs initial computations:
+     * - For signing: Validates KPAK consistency (RFC 6507 Section 5.1.2)
+     * - For verification: Computes Y = HS·PVT + KPAK
+     *
+     * Also computes HS = hash(G || KPAK || ID || PVT) as per RFC 6507 Section 5.1.1
+     */
     @Override
     public void reset()
     {