Javadoc and comment corrections for WKS format, SlhDsa, LMS verify, AES-CBC and Fips.DhAgree()

jni/jni_lms.c

@@ -230,7 +230,8 @@ JNIEXPORT jboolean JNICALL Java_com_wolfssl_wolfcrypt_Lms_wc_1LmsKey_1verify
         result = JNI_TRUE;
     }
     else if (ret != SIG_VERIFY_E && ret != SIG_TYPE_E && ret != BUFFER_E) {
-        /* Treat these returns as failed verification */
+        /* Verify error, type does not match, and wrong sig length leave result
+         * false. Other returns are an error. */
         throwWolfCryptExceptionFromError(env, ret);
     }
 

src/main/java/com/wolfssl/provider/jce/WolfSSLKeyStore.java

@@ -118,42 +118,48 @@
  *     [WKSPrivateKey]
  *       entryId                         (int / 1)
  *       alias                           (UTF String)
- *       creationDate.getTime()          (long)
- *       kdfSalt.length                  (int)
- *       kdfSalt                         (byte[])
- *       kdfIterations                   (int)
- *       iv.length                       (int)
- *       iv                              (byte[])
- *       encryptedKey.length             (int)
- *       encryptedKey                    (byte[])
- *       chain.length                    (int)
- *       FOR EACH CERT:
- *         chain[i].getType()            (UTF String)
- *         chain[i].getEncoded().length  (int)
- *         chain[i].getEncoced()         (byte[])
- *       hmac.length                     (int)
- *       hmac (HMAC-SHA512)              (byte[])
+ *       encodedEntry.length             (int)
+ *       encodedEntry                    (byte[]), containing:
+ *         creationDate.getTime()        (long)
+ *         kdfSalt.length                (int)
+ *         kdfSalt                       (byte[])
+ *         kdfIterations                 (int)
+ *         iv.length                     (int)
+ *         iv                            (byte[])
+ *         encryptedKey.length           (int)
+ *         encryptedKey                  (byte[])
+ *         chain.length                  (int)
+ *         FOR EACH CERT:
+ *           chain[i].getType()          (UTF String)
+ *           chain[i].getEncoded().length (int)
+ *           chain[i].getEncoded()       (byte[])
+ *         hmac.length                   (int)
+ *         hmac (HMAC-SHA512)            (byte[])
  *     [WKSSecretKey]
  *       entryId                         (int / 3)
  *       alias                           (UTF String)
- *       creationDate.getTime()          (long)
- *       key.getAlgorithm()              (UTF String)
- *       kdfSalt.length                  (int)
- *       kdfSalt                         (byte[])
- *       kdfIterations                   (int)
- *       iv.length                       (int)
- *       iv                              (byte[])
- *       encryptedKey.length             (int)
- *       encryptedKey                    (byte[])
- *       hmac.length                     (int)
- *       hmac (HMAC-SHA512)              (byte[])
+ *       encodedEntry.length             (int)
+ *       encodedEntry                    (byte[]), containing:
+ *         creationDate.getTime()        (long)
+ *         key.getAlgorithm()            (UTF String)
+ *         kdfSalt.length                (int)
+ *         kdfSalt                       (byte[])
+ *         kdfIterations                 (int)
+ *         iv.length                     (int)
+ *         iv                            (byte[])
+ *         encryptedKey.length           (int)
+ *         encryptedKey                  (byte[])
+ *         hmac.length                   (int)
+ *         hmac (HMAC-SHA512)            (byte[])
  *     [WKSCertificate]
  *       entryId                         (int / 2)
  *       alias                           (UTF String)
- *       creationDate.getTime()          (long)
- *       cert.getType()                  (UTF String)
- *       cert.getEncoded().length        (int)
- *       cert.getEncoced()               (byte[])
+ *       encodedEntry.length             (int)
+ *       encodedEntry                    (byte[]), containing:
+ *         creationDate.getTime()        (long)
+ *         cert.getType()                (UTF String)
+ *         cert.getEncoded().length      (int)
+ *         cert.getEncoded()             (byte[])
  *   HMAC PBKDF2 salt length             int
  *   HMAC PBKDF2 salt                    (byte[])
  *   HMAC PBKDF2 iterations              int

src/main/java/com/wolfssl/wolfcrypt/Aes.java

@@ -26,6 +26,16 @@
 /**
  * Wrapper for the native WolfCrypt AES implementation.
  *
+ * <p>Operates in AES-CBC mode. As with native wc_AesCbcEncrypt() and
+ * wc_AesCbcDecrypt(), the length passed to update() must be a multiple of
+ * {@link #BLOCK_SIZE}. Native wolfCrypt always rejects other lengths when
+ * decrypting. When encrypting it rejects them only when built with
+ * WOLFSSL_AES_CBC_LENGTH_CHECKS, otherwise it processes whole blocks only,
+ * and output bytes past the last whole block are not written, although
+ * update() still returns the full length. Pad input with
+ * {@link BlockCipher#padPKCS7(byte[], int)} or buffer partial blocks before
+ * calling update().</p>
+ *
  * @author wolfSSL Inc.
  */
 public class Aes extends BlockCipher {

src/main/java/com/wolfssl/wolfcrypt/Fips.java

@@ -1823,9 +1823,14 @@ public static int DhGenerateKeyPair(Dh key, Rng rng, byte[] priv,
      * Creates the agreement agree of size agreeSz using Dh key private priv of
      * size privSz and peer's public key otherPub of size pubSz.
      *
+     * As with native wc_DhAgree(), agree must hold the full shared secret,
+     * which can be as long as the DH prime p. Native does not check agreeSz
+     * against the secret length.
+     *
      * @param key the Dh object.
      * @param agree the agree buffer.
-     * @param agreeSz the agree length.
+     * @param agreeSz on input the size of agree, on output the length of the
+     *        shared secret.
      * @param priv the private part buffer.
      * @param privSz the private part length.
      * @param otherPub the peer's public part buffer.
@@ -1845,9 +1850,14 @@ public static int DhAgree(Dh key, ByteBuffer agree, long[] agreeSz,
      * Creates the agreement agree of size agreeSz using Dh key private priv of
      * size privSz and peer's public key otherPub of size pubSz.
      *
+     * As with native wc_DhAgree(), agree must hold the full shared secret,
+     * which can be as long as the DH prime p. Native does not check agreeSz
+     * against the secret length.
+     *
      * @param key the Dh object.
      * @param agree the agree buffer.
-     * @param agreeSz the agree length.
+     * @param agreeSz on input the size of agree, on output the length of the
+     *        shared secret.
      * @param priv the private part buffer.
      * @param privSz the private part length.
      * @param otherPub the peer's public part buffer.

src/main/java/com/wolfssl/wolfcrypt/SlhDsa.java

@@ -26,9 +26,12 @@
  *
  * <p>Mirrors the native wolfCrypt {@code wc_SlhDsaKey_*} API. SLH-DSA is a
  * stateless hash-based signature scheme (formerly SPHINCS+). The parameter
- * set is fixed at construction and maps directly to the native
- * {@code enum SlhDsaParam} integer value. An empty FIPS 205 context is used
- * by default.</p>
+ * set maps directly to the native {@code enum SlhDsaParam} integer value. It
+ * is given to {@link #SlhDsa(int)}, or left unset by {@link #SlhDsa()} until
+ * {@link #importPublicKeyDer(byte[])} or {@link #importPrivateKeyDer(byte[])}
+ * detects it from the key's AlgorithmIdentifier OID. DER import always uses
+ * the OID's parameter set, replacing one given at construction. An empty
+ * FIPS 205 context is used by default.</p>
  *
  * <p>Parameter set constants match the native {@code enum SlhDsaParam}: the
  * six SHAKE sets are 0-5, the six SHA2 sets are 6-11. Note this ordering is