Merge branch '1857-1-javadoc' into 'main'

JavaDoc from 1857 branch: PBESecretKeyEncryptor, CryptlibObjectIdentifiers,...

See merge request root/bc-java!45

Author: dghgit

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

@@ -7,6 +7,8 @@
 
 /**
  * A factory for performing PBE decryption operations.
+ * The purpose of this class is to act as an abstract factory, whose subclasses can decide, which concrete
+ * implementation to use for symmetric decryption of SKESK (symmetric-key-encrypted session-key) packets.
  */
 public abstract class PBEDataDecryptorFactory
     implements PGPDataDecryptorFactory

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.
      */

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

@@ -3,6 +3,11 @@
 import org.bouncycastle.openpgp.PGPException;
 import org.bouncycastle.openpgp.PGPPrivateKey;
 
+/**
+ * Builder for {@link PGPContentSigner} objects.
+ * The purpose of this class is to act as an abstract factory, whose subclasses can decide, which concrete
+ * implementation to use for the {@link PGPContentSigner}.
+ */
 public interface PGPContentSignerBuilder
 {
     PGPContentSigner build(final int signatureType, final PGPPrivateKey privateKey)

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

@@ -2,6 +2,12 @@
 
 import org.bouncycastle.openpgp.PGPException;
 
+/**
+ * Provider for {@link PGPContentVerifierBuilder} instances.
+ * The purpose of this class is to act as an abstract factory, whose subclasses can decide, which concrete
+ * implementation of {@link PGPContentVerifierBuilder} (builder for objects check signatures for correctness)
+ * to provide.
+ */
 public interface PGPContentVerifierBuilderProvider
 {
     PGPContentVerifierBuilder get(int keyAlgorithm, int hashAlgorithm)

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

@@ -5,6 +5,8 @@
 
 /**
  * A factory for digest algorithms.
+ * The purpose of this class is to act as an abstract factory, whose subclasses can decide, which concrete
+ * implementation to use for calculating PGP digests.
  */
 public interface PGPDigestCalculatorProvider
 {

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

@@ -4,6 +4,11 @@
 import org.bouncycastle.bcpg.PublicKeyEncSessionPacket;
 import org.bouncycastle.openpgp.PGPException;
 
+/**
+ * Factory for public-key based {@link PGPDataDecryptor PGPDataDecryptors}.
+ * The purpose of this class is to act as an abstract factory, whose subclasses can decide, which concrete
+ * implementation to use to decrypt OpenPGP messages that were encrypted to a public-key.
+ */
 public interface PublicKeyDataDecryptorFactory
     extends PGPDataDecryptorFactory
 {

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

@@ -11,6 +11,11 @@
 import java.io.IOException;
 import java.math.BigInteger;
 
+/**
+ * Abstract generator class for encryption methods that produce PKESK (public-key encrypted session key) packets.
+ * PKESKs are used when encrypting a message for a recipients public key.
+ * The purpose of this class is to allow subclasses to decide, which implementation to use.
+ */
 public abstract class PublicKeyKeyEncryptionMethodGenerator
     extends PGPKeyEncryptionMethodGenerator
 {

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

@@ -2,6 +2,12 @@
 
 import org.bouncycastle.openpgp.PGPSessionKey;
 
+/**
+ * Factory for {@link PGPDataDecryptor} objects that use a {@link PGPSessionKey} to decrypt the content of an
+ * OpenPGP message.
+ * The purpose of this class is to act as an abstract factory, whose subclasses can decide, which concrete
+ * implementation to use for message decryption.
+ */
 public interface SessionKeyDataDecryptorFactory
     extends PGPDataDecryptorFactory
 {

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");
 }