JavaDoc from 1857 branch: PBESecretKeyEncryptor, CryptlibObjectIdentifiers, and GNUObjectIdentifiers

Author: gefeili

pg/src/main/java/org/bouncycastle/openpgp/operator/PBESecretKeyEncryptor.java

@@ -5,6 +5,52 @@
 import org.bouncycastle.bcpg.S2K;
 import org.bouncycastle.openpgp.PGPException;
 
+/**
+ * Class responsible for encrypting secret key material or data packets using a passphrase.
+ * <p>
+ * RFC9580 recommends the following S2K specifiers + usages:
+ * <table border="1">
+ * <tr>
+ *     <th>S2K Specifier</th>
+ *     <th>S2K Usage</th>
+ *     <th>Note</th>
+ * </tr>
+ * <tr>
+ *     <td>{@link S2K#ARGON_2}</td>
+ *     <td>{@link org.bouncycastle.bcpg.SecretKeyPacket#USAGE_AEAD}</td>
+ *     <td>RECOMMENDED; Argon2 MUST be used with AEAD</td>
+ * </tr>
+ * <tr>
+ *     <td>{@link S2K#SALTED_AND_ITERATED}</td>
+ *     <td>{@link org.bouncycastle.bcpg.SecretKeyPacket#USAGE_SHA1}</td>
+ *     <td>MAY be used if Argon2 is not available; Take care to use high octet count + strong passphrase</td>
+ * </tr>
+ * <tr>
+ *     <td>none</td>
+ *     <td>{@link org.bouncycastle.bcpg.SecretKeyPacket#USAGE_NONE}</td>
+ *     <td>Unprotected</td>
+ * </tr>
+ * </table>
+ * <p>
+ * Additionally, implementations MAY use the following combinations with caution:
+ * <table>
+ * <tr>
+ *     <th>S2K Specifier</th>
+ *     <th>S2K Usage</th>
+ *     <th>Note</th>
+ * </tr>
+ * <tr>
+ *     <td>{@link S2K#SALTED_AND_ITERATED}</td>
+ *     <td>{@link org.bouncycastle.bcpg.SecretKeyPacket#USAGE_AEAD}</td>
+ *     <td>Does not provide memory hardness</td>
+ * </tr>
+ * <tr>
+ *     <td>{@link S2K#SIMPLE}</td>
+ *     <td>{@link org.bouncycastle.bcpg.SecretKeyPacket#USAGE_SHA1}</td>
+ *     <td>Only for reading secret keys in backwards compatibility mode</td>
+ * </tr>
+ * </table>
+ */
 public abstract class PBESecretKeyEncryptor
 {
     protected int encAlgorithm;
@@ -80,8 +126,8 @@ public S2K getS2K()
      * Key encryption method invoked for V4 keys and greater.
      *
      * @param keyData raw key data
-     * @param keyOff offset into raw key data
-     * @param keyLen length of key data to use.
+     * @param keyOff  offset into raw key data
+     * @param keyLen  length of key data to use.
      * @return an encryption of the passed in keyData.
      * @throws PGPException on error in the underlying encryption process.
      */

util/src/main/java/org/bouncycastle/asn1/cryptlib/CryptlibObjectIdentifiers.java

@@ -8,5 +8,11 @@ public class CryptlibObjectIdentifiers
 
     public static final ASN1ObjectIdentifier ecc = cryptlib.branch("1").branch("5");
 
+    /**
+     * Curve25519Legacy for use with ECDH.
+     *
+     * @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#ec-curves">
+     * RFC9580 - ECC Curves for OpenPGP</a>
+     */
     public static final ASN1ObjectIdentifier curvey25519 = ecc.branch("1");
 }

util/src/main/java/org/bouncycastle/asn1/gnu/GNUObjectIdentifiers.java

@@ -65,7 +65,7 @@ public interface GNUObjectIdentifiers
      */
     ASN1ObjectIdentifier Serpent_192_ECB = new ASN1ObjectIdentifier("1.3.6.1.4.1.11591.13.2.21"); // Serpent-192-ECB
     /**
-     * 1.3.6.1.4.1.11591.13.2.22 -- Serpent-192-CCB
+     * 1.3.6.1.4.1.11591.13.2.22 -- Serpent-192-CBC
      */
     ASN1ObjectIdentifier Serpent_192_CBC = new ASN1ObjectIdentifier("1.3.6.1.4.1.11591.13.2.22"); // Serpent-192-CBC
     /**
@@ -107,5 +107,11 @@ public interface GNUObjectIdentifiers
      */
     ASN1ObjectIdentifier ellipticCurve = new ASN1ObjectIdentifier("1.3.6.1.4.1.11591.15");
 
+    /**
+     * Ed25519Legacy for use with EdDSALegacy.
+     *
+     * @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#ec-curves">
+     * RFC9580 - ECC Curves for OpenPGP</a>
+     */
     ASN1ObjectIdentifier Ed25519 = ellipticCurve.branch("1");
 }