Add java doc for the two main classes of Mayo

Author: gefeili

core/src/main/java/org/bouncycastle/pqc/crypto/mayo/MayoKeyPairGenerator.java

@@ -9,6 +9,22 @@
 import org.bouncycastle.util.Arrays;
 import org.bouncycastle.util.Longs;
 
+/**
+ * Implementation of the MAYO asymmetric key pair generator following the MAYO signature scheme specifications.
+ * <p>
+ * This generator produces {@link MayoPublicKeyParameters} and {@link MayoPrivateKeyParameters} based on the
+ * MAYO algorithm parameters. The implementation follows the specification defined in the official MAYO
+ * documentation and reference implementation.
+ * </p>
+ *
+ * <p>References:</p>
+ * <ul>
+ *   <li><a href="https://pqmayo.org/">MAYO Official Website</a></li>
+ *   <li><a href="https://pqmayo.org/assets/specs/mayo.pdf">MAYO Specification Document</a></li>
+ *   <li><a href="https://github.com/PQCMayo/MAYO-C">MAYO Reference Implementation (C)</a></li>
+ * </ul>
+ *
+ */
 public class MayoKeyPairGenerator
     implements AsymmetricCipherKeyPairGenerator
 {
@@ -21,6 +37,23 @@ public void init(KeyGenerationParameters param)
         this.random = param.getRandom();
     }
 
+    /**
+     * Generates a new asymmetric key pair following the MAYO algorithm specifications.
+     * <p>
+     * The key generation process follows these steps:
+     * </p>
+     * <ol>
+     *   <li>Initializes parameter dimensions from {@link MayoParameters}</li>
+     *   <li>Generates secret key seed using a secure random generator</li>
+     *   <li>Derives public key seed using SHAKE-256</li>
+     *   <li>Expands matrix parameters P1 and P2</li>
+     *   <li>Performs GF(16) matrix operations for key material generation</li>
+     *   <li>Assembles and packages the public key components</li>
+     *   <li>Securely clears temporary buffers containing sensitive data</li>
+     * </ol>
+     *
+     * @return A valid MAYO key pair containing public and private key parameters
+     */
     @Override
     public AsymmetricCipherKeyPair generateKeyPair()
     {

core/src/main/java/org/bouncycastle/pqc/crypto/mayo/MayoSigner.java

@@ -3,6 +3,7 @@
 import java.security.SecureRandom;
 
 import org.bouncycastle.crypto.CipherParameters;
+import org.bouncycastle.crypto.CryptoServicesRegistrar;
 import org.bouncycastle.crypto.digests.SHAKEDigest;
 import org.bouncycastle.crypto.params.ParametersWithRandom;
 import org.bouncycastle.pqc.crypto.MessageSigner;
@@ -12,6 +13,21 @@
 import org.bouncycastle.util.Longs;
 import org.bouncycastle.util.Pack;
 
+/**
+ * Implementation of the MAYO digital signature scheme as specified in the MAYO documentation.
+ * This class provides functionality for both signature generation and verification.
+ *
+ * <p>MAYO is a candidate in the <b>NIST Post-Quantum Cryptography: Additional Digital Signature Schemes</b> project,
+ * currently in Round 2 of evaluations. For more details about the NIST standardization process, see:
+ * <a href="https://csrc.nist.gov/Projects/pqc-dig-sig">NIST PQC Additional Digital Signatures</a>.</p>
+ *
+ * <p>References:</p>
+ * <ul>
+ *   <li><a href="https://pqmayo.org/">MAYO Official Website</a></li>
+ *   <li><a href="https://pqmayo.org/assets/specs/mayo.pdf">MAYO Specification Document</a></li>
+ *   <li><a href="https://github.com/PQCMayo/MAYO-C">MAYO Reference Implementation (C)</a></li>
+ * </ul>
+ */
 public class MayoSigner
     implements MessageSigner
 {
@@ -20,6 +36,17 @@ public class MayoSigner
     private MayoPublicKeyParameters pubKey;
     private MayoPrivateKeyParameters privKey;
 
+    /**
+     * Initializes the signer for either signature generation or verification.
+     *
+     * @param forSigning {@code true} for signing mode, {@code false} for verification
+     * @param param      CipherParameters containing:
+     *                   <ul>
+     *                     <li>{@link ParametersWithRandom} with {@link MayoPrivateKeyParameters} (for signing)</li>
+     *                     <li>{@link MayoPublicKeyParameters} (for verification)</li>
+     *                   </ul>
+     * @throws IllegalArgumentException if invalid parameters are provided
+     */
     @Override
     public void init(boolean forSigning, CipherParameters param)
     {
@@ -37,7 +64,7 @@ public void init(boolean forSigning, CipherParameters param)
             else
             {
                 privKey = (MayoPrivateKeyParameters)param;
-                random = null;
+                random = CryptoServicesRegistrar.getSecureRandom();
             }
             params = privKey.getParameters();
         }
@@ -50,6 +77,14 @@ public void init(boolean forSigning, CipherParameters param)
         }
     }
 
+    /**
+     * Generates a MAYO signature for the given message using the initialized private key.
+     * Follows the signature generation process outlined in the MAYO specification document.
+     *
+     * @param message The message to be signed
+     * @return The signature bytes concatenated with the original message
+     * @see <a href="https://pqmayo.org/assets/specs/mayo.pdf">MAYO Spec Algorithm 8 and 10</a>
+     */
     @Override
     public byte[] generateSignature(byte[] message)
     {
@@ -192,7 +227,7 @@ public byte[] generateSignature(byte[] message)
 
                 Utils.decode(V, k * vbytes, r, ok);
 
-                if (sampleSolution(params, A, y, r, x))
+                if (sampleSolution(A, y, r, x))
                 {
                     break;
                 }
@@ -235,6 +270,15 @@ public byte[] generateSignature(byte[] message)
         }
     }
 
+    /**
+     * Verifies a MAYO signature against the initialized public key and message.
+     * Implements the verification process specified in the MAYO documentation.
+     *
+     * @param message     The original message
+     * @param signature   The signature to verify
+     * @return {@code true} if the signature is valid, {@code false} otherwise
+     * @see <a href="https://pqmayo.org/assets/specs/mayo.pdf">MAYO Spec Algorithm 9 and 11</a>
+     */
     @Override
     public boolean verifySignature(byte[] message, byte[] signature)
     {
@@ -554,7 +598,17 @@ private static void transpose16x16Nibbles(long[] M, int offset)
         }
     }
 
-    boolean sampleSolution(MayoParameters params, byte[] A, byte[] y, byte[] r, byte[] x)
+    /**
+     * Samples a solution for the MAYO signature equation using the provided parameters.
+     *
+     * @param A      Coefficient matrix
+     * @param y      Target vector
+     * @param r      Randomness vector
+     * @param x      Output solution vector
+     * @return {@code true} if a valid solution was found, {@code false} otherwise
+     * @see <a href="https://pqmayo.org/assets/specs/mayo.pdf">MAYO Spec Algorithm 2</a>
+     */
+    boolean sampleSolution(byte[] A, byte[] y, byte[] r, byte[] x)
     {
         final int k = params.getK();
         final int o = params.getO();
@@ -641,6 +695,7 @@ boolean sampleSolution(MayoParameters params, byte[] A, byte[] y, byte[] r, byte
      * @param A     the input matrix, stored rowwise; each element is in [0,15]
      * @param nrows the number of rows
      * @param ncols the number of columns (GF(16) elements per row)
+     * @see <a href="https://pqmayo.org/assets/specs/mayo.pdf">MAYO Spec Algorithm 1</a>
      */
     void ef(byte[] A, int nrows, int ncols)
     {