Merge remote-tracking branch 'pgpainless/pkeskv6Encryption' into 1938-v6-PKESK-encryption

# Conflicts:
#	pg/src/main/java/org/bouncycastle/openpgp/operator/PublicKeyKeyEncryptionMethodGenerator.java

Author: gefeili

pg/src/main/java/org/bouncycastle/openpgp/PGPEncryptedDataGenerator.java

@@ -401,7 +401,7 @@ else if (m instanceof PublicKeyKeyEncryptionMethodGenerator)
     /**
      * Write out a {@link org.bouncycastle.bcpg.SymmetricKeyEncSessionPacket#VERSION_5 v5 SKESK} or
      * {@link org.bouncycastle.bcpg.PublicKeyEncSessionPacket#VERSION_3 v3 PKESK} packet,
-     * depending on the method generator. This method is used by what can be referred to as OpenPGP v5.
+     * depending on the method generator. This method is used by LibrePGP only.
      *
      * @param m           session key encryption method generator.
      * @param sessionInfo session info

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

@@ -22,7 +22,7 @@
  * </p>
  */
 public abstract class PBEKeyEncryptionMethodGenerator
-    extends PGPKeyEncryptionMethodGenerator
+    implements PGPKeyEncryptionMethodGenerator
 {
     private char[] passPhrase;
     private PGPDigestCalculator s2kDigestCalculator;
@@ -161,38 +161,57 @@ public byte[] getKey(int encAlgorithm)
     }
 
     /**
-     * Generates a version 4 Public-Key-Encrypted-Session-Key (PKESK) packet, encoding the encrypted
+     * Generates a version 4 Symmetric-Key-Encrypted-Session-Key (SKESK) packet, encoding the encrypted
      * session-key for this method.
-     * PKESKv4 packets are used by Symmetrically-Encrypted-Integrity-Protected-Data (SEIPD) packets
+     * SKESKv4 packets are used by Symmetrically-Encrypted-Integrity-Protected-Data (SEIPD) packets
      * of version 1, or by (deprecated) Symmetrically-Encrypted-Data (SED) packets.
-     * You can use PKESKv4 packets with OpenPGP v4 keys, but MUST NOT use them when producing
-     * SEIPDv2 packets (use {@link #generateV6(int, int, byte[])} instead in that case).
+     * You MUST NOT use them when producing SEIPDv2 packets (use {@link #generateV6(int, int, byte[])}
+     * instead in that case).
      *
-     * @param encAlgorithm the {@link SymmetricKeyAlgorithmTags encryption algorithm} being used
+     * @param kekAlgorithm the {@link SymmetricKeyAlgorithmTags encryption algorithm} being used to
+     *                    wrap the session key
      * @param sessionInfo session data generated by the encrypted data generator.
      * @return a packet encoding the provided information and the configuration of this instance.
      *
      * @throws PGPException if an error occurs constructing the packet.
+     * @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#name-version-4-symmetric-key-enc">
+     *     RFC9580 - Symmetric-Key Encrypted Session-Key Packet version 4</a>
      */
-    public ContainedPacket generateV4(int encAlgorithm, byte[] sessionInfo)
+    public ContainedPacket generateV4(int kekAlgorithm, byte[] sessionInfo)
             throws PGPException
     {
         if (sessionInfo == null)
         {
-            return SymmetricKeyEncSessionPacket.createV4Packet(encAlgorithm, s2k, null);
+            return SymmetricKeyEncSessionPacket.createV4Packet(kekAlgorithm, s2k, null);
         }
 
-        byte[] key = getKey(encAlgorithm);
+        byte[] key = getKey(kekAlgorithm);
         //
         // the passed in session info has the an RSA/ElGamal checksum added to it, for PBE this is not included.
         //
         byte[] nSessionInfo = new byte[sessionInfo.length - 2];
 
         System.arraycopy(sessionInfo, 0, nSessionInfo, 0, nSessionInfo.length);
 
-        return SymmetricKeyEncSessionPacket.createV4Packet(encAlgorithm, s2k, encryptSessionInfo(encAlgorithm, key, nSessionInfo));
+        return SymmetricKeyEncSessionPacket.createV4Packet(kekAlgorithm, s2k, encryptSessionInfo(kekAlgorithm, key, nSessionInfo));
     }
 
+    /**
+     * Generates a version 5 Symmetric-Key-Encrypted-Session-Key (SKESK) packet, encoding the encrypted
+     * session-key for this method.
+     * SKESKv5 packets are used with {@link org.bouncycastle.bcpg.AEADEncDataPacket OCB-Encrypted Data (OED) packets}
+     * only.
+     *
+     * @param kekAlgorithm the {@link SymmetricKeyAlgorithmTags encryption algorithm} being used to
+     *                    wrap the session key
+     * @param aeadAlgorithm AEAD algorithm ID (MUST be {@link org.bouncycastle.bcpg.AEADAlgorithmTags#OCB})
+     * @param sessionInfo session data generated by the encrypted data generator.
+     * @return a packet encoding the provided information and the configuration of this instance.
+     *
+     * @throws PGPException if an error occurs constructing the packet.
+     * @see <a href="https://www.ietf.org/archive/id/draft-koch-librepgp-02.html#section-5.3-8">
+     *     LibrePGP - Symmetric-Key Encrypted Session-Key Packet version 5</a>
+     */
     public ContainedPacket generateV5(int kekAlgorithm, int aeadAlgorithm, byte[] sessionInfo)
             throws PGPException
     {
@@ -216,6 +235,23 @@ public ContainedPacket generateV5(int kekAlgorithm, int aeadAlgorithm, byte[] se
         return SymmetricKeyEncSessionPacket.createV5Packet(kekAlgorithm, aeadAlgorithm, iv, s2k, esk, tag);
     }
 
+    /**
+     * Generates a version 6 Symmetric-Key-Encrypted-Session-Key (SKESK) packet, encoding the encrypted
+     * session-key for this method.
+     * SKESKv6 packets are used with Symmetrically-Encrypted Integrity-Protected Data (SEIPD) packets of
+     * version 2 only.
+     * A SKESKv6 packet MUST NOT precede a SEIPDv1, OED or SED packet.
+     *
+     * @param kekAlgorithm the {@link SymmetricKeyAlgorithmTags encryption algorithm} being used to
+     *                     wrap the session key
+     * @param aeadAlgorithm AEAD algorithm ID
+     * @param sessionInfo session data generated by the encrypted data generator.
+     * @return a packet encoding the provided information and the configuration of this instance.
+     *
+     * @throws PGPException if an error occurs constructing the packet.
+     * @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#name-version-6-symmetric-key-enc">
+     *     RFC9580 - Symmetric-Key Encrypted Session-Key Packet version 6</a>
+     */
     public ContainedPacket generateV6(int kekAlgorithm, int aeadAlgorithm, byte[] sessionInfo)
         throws PGPException
     {

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

@@ -5,7 +5,7 @@
 /**
  * An encryption method that can be applied to encrypt data in a {@link PGPEncryptedDataGenerator}.
  */
-public abstract class PGPKeyEncryptionMethodGenerator
+public interface PGPKeyEncryptionMethodGenerator
 {
 
 }

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

@@ -17,7 +17,7 @@
  * The purpose of this class is to allow subclasses to decide, which implementation to use.
  */
 public abstract class PublicKeyKeyEncryptionMethodGenerator
-    extends PGPKeyEncryptionMethodGenerator
+    implements PGPKeyEncryptionMethodGenerator
 {
     public static final String SESSION_KEY_OBFUSCATION_PROPERTY = "org.bouncycastle.openpgp.session_key_obfuscation";
     public static final long WILDCARD_KEYID = 0L;
@@ -164,8 +164,22 @@ private byte[] convertToEncodedMPI(byte[] encryptedSessionInfo)
         }
     }
 
+    /**
+     * Generate a Public-Key Encrypted Session-Key (PKESK) packet of version 3.
+     * PKESKv3 packets are used with Symmetrically-Encrypted-Integrity-Protected Data (SEIPD) packets of
+     * version 1 or with Symmetrically-Encrypted Data (SED) packets and MUST NOT be used with SEIPDv2 packets.
+     * PKESKv3 packets are used with keys that do not support {@link org.bouncycastle.bcpg.sig.Features#FEATURE_SEIPD_V2}
+     * or as a fallback.
+     *
+     * @param sessionInfo session-key algorithm + session-key + checksum
+     * @return version 3 PKESK packet
+     *
+     * @throws PGPException
+     * @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#name-version-3-public-key-encryp">
+     *     RFC9580 - Version 3 Public Key Encrypted Session Key Packet</a>
+     */
     public ContainedPacket generateV3(byte[] sessionInfo)
-        throws PGPException
+            throws PGPException
     {
         long keyId;
         if (useWildcardRecipient)
@@ -181,6 +195,19 @@ public ContainedPacket generateV3(byte[] sessionInfo)
         return PublicKeyEncSessionPacket.createV3PKESKPacket(keyId, pubKey.getAlgorithm(), encodedEncSessionInfo);
     }
 
+    /**
+     * Generate a Public-Key Encrypted Session-Key (PKESK) packet of version 6.
+     * PKESKv6 packets are used with Symmetrically-Encrypted Integrity-Protected Data (SEIPD) packets
+     * of version 2 only.
+     * PKESKv6 packets are used with keys that support {@link org.bouncycastle.bcpg.sig.Features#FEATURE_SEIPD_V2}.
+     *
+     * @param sessionInfo session-key algorithm id + session-key + checksum
+     * @return PKESKv6 packet
+     *
+     * @throws PGPException if the PKESK packet cannot be generated
+     * @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#name-version-6-public-key-encryp">
+     *     RFC9580 - Version 6 Public Key Encrypted Session Key Packet</a>
+     */
     public ContainedPacket generateV6(byte[] sessionInfo)
         throws PGPException
     {