Merge branch 'pgpainless-documentBCPGKeys'

dghgit · dghgit · commit 1bae99bfbc4b · 2024-05-22T20:30:48.000+10:00
diff --git a/pg/src/main/java/org/bouncycastle/bcpg/ECDHPublicBCPGKey.java b/pg/src/main/java/org/bouncycastle/bcpg/ECDHPublicBCPGKey.java
@@ -7,7 +7,17 @@
 import org.bouncycastle.math.ec.ECPoint;
 
 /**
- * base class for an ECDH Public Key.
+ * Base class for an ECDH Public Key.
+ * This type is for use with {@link PublicKeyAlgorithmTags#ECDH}.
+ * The specific curve is identified by providing an OID.
+ * Regarding X25519, X448, consider the following:
+ * Modern implementations use dedicated key types {@link X25519PublicBCPGKey}, {@link X448PublicBCPGKey} along with
+ * dedicated algorithm tags {@link PublicKeyAlgorithmTags#X25519}, {@link PublicKeyAlgorithmTags#X448}.
+ * If you want to be compatible with legacy applications however, you should use this class instead.
+ * Note though, that for v6 keys, {@link X25519PublicBCPGKey} or {@link X448PublicBCPGKey} MUST be used for X25519, X448.
+ *
+ * @see <a href="https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-13.html#name-algorithm-specific-part-for-ecd">
+ *     Crypto-Refresh - Algorithm-Specific Parts for ECDH Keys</a>
  */
 public class ECDHPublicBCPGKey
     extends ECPublicBCPGKey
diff --git a/pg/src/main/java/org/bouncycastle/bcpg/ECDSAPublicBCPGKey.java b/pg/src/main/java/org/bouncycastle/bcpg/ECDSAPublicBCPGKey.java
@@ -7,7 +7,11 @@
 import org.bouncycastle.math.ec.ECPoint;
 
 /**
- * base class for an ECDSA Public Key.
+ * Base class for an ECDSA Public Key.
+ * This type is used with {@link PublicKeyAlgorithmTags#ECDSA} and the curve is identified by providing an OID.
+ *
+ * @see <a href="https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-13.html#name-algorithm-specific-part-for-ec">
+ *     Crypto-Refresh - Algorithm-Specific Parts for ECDSA Keys</a>
  */
 public class ECDSAPublicBCPGKey
     extends ECPublicBCPGKey
diff --git a/pg/src/main/java/org/bouncycastle/bcpg/ECPublicBCPGKey.java b/pg/src/main/java/org/bouncycastle/bcpg/ECPublicBCPGKey.java
@@ -8,7 +8,8 @@
 import org.bouncycastle.math.ec.ECPoint;
 
 /**
- * base class for an EC Public Key.
+ * Base class for an EC Public Key.
+ * For subclasses, see {@link ECDHPublicBCPGKey}, {@link ECDSAPublicBCPGKey} or {@link EdDSAPublicBCPGKey}.
  */
 public abstract class ECPublicBCPGKey
     extends BCPGObject
diff --git a/pg/src/main/java/org/bouncycastle/bcpg/ECSecretBCPGKey.java b/pg/src/main/java/org/bouncycastle/bcpg/ECSecretBCPGKey.java
@@ -4,7 +4,24 @@
 import java.math.BigInteger;
 
 /**
- * base class for an EC Secret Key.
+ * Base class for an EC Secret Key.
+ * This type is for use with {@link PublicKeyAlgorithmTags#ECDH} or {@link PublicKeyAlgorithmTags#ECDSA}.
+ * The specific curve is identified by providing an OID.
+ * Regarding X25519, X448, consider the following:
+ * ECDH keys using curve448 are unspecified.
+ * ECDH secret keys using curve25519 use big-endian MPI encoding, contrary to {@link X25519SecretBCPGKey} which uses
+ * native encoding.
+ * Modern implementations use dedicated key types {@link X25519SecretBCPGKey}, {@link X448SecretBCPGKey} along with
+ * dedicated algorithm tags {@link PublicKeyAlgorithmTags#X25519}, {@link PublicKeyAlgorithmTags#X448}.
+ * If you want to be compatible with legacy applications however, you should use this class instead.
+ * Note though, that for v6 keys, {@link X25519SecretBCPGKey} or {@link X448SecretBCPGKey} MUST be used for X25519, X448.
+ *
+ * @see <a href="https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-13.html#name-algorithm-specific-part-for-ecd">
+ *     Crypto-Refresh - Algorithm-Specific Parts for ECDH Keys</a>
+ * @see <a href="https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-13.html#name-algorithm-specific-part-for-ec">
+ *     Crypto-Refresh - Algorithm-Specific Parts for ECDSA Keys</a>
+ * @see <a href="https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-13.html#name-curve25519legacy-ecdh-secre">
+ *     Crypto-Refresh - Curve25519Legacy ECDH Secret Key Material (deprecated)</a>
  */
 public class ECSecretBCPGKey
     extends BCPGObject
diff --git a/pg/src/main/java/org/bouncycastle/bcpg/Ed25519PublicBCPGKey.java b/pg/src/main/java/org/bouncycastle/bcpg/Ed25519PublicBCPGKey.java
@@ -2,9 +2,20 @@
 
 import java.io.IOException;
 
+/**
+ * Public key of type {@link PublicKeyAlgorithmTags#Ed25519}.
+ * This type was introduced with Crypto-Refresh and can be used with v4, v6 keys.
+ * Note however, that legacy implementations might not understand this key type yet.
+ * For a key type compatible with legacy v4 implementations, see {@link EdDSAPublicBCPGKey} with
+ * {@link PublicKeyAlgorithmTags#EDDSA_LEGACY}.
+ *
+ * @see <a href="https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-13.html#name-algorithm-specific-part-for-ed2">
+ *     Crypto-Refresh - Algorithm-Specific Part for Ed25519 Keys</a>
+ */
 public class Ed25519PublicBCPGKey
         extends OctetArrayBCPGKey
 {
+    // 32 octets of the native public key
     public static final int LENGTH = 32;
 
     public Ed25519PublicBCPGKey(BCPGInputStream in)
diff --git a/pg/src/main/java/org/bouncycastle/bcpg/Ed25519SecretBCPGKey.java b/pg/src/main/java/org/bouncycastle/bcpg/Ed25519SecretBCPGKey.java
@@ -2,9 +2,20 @@
 
 import java.io.IOException;
 
+/**
+ * Secret key of type {@link PublicKeyAlgorithmTags#Ed25519}.
+ * This type was introduced with Crypto-Refresh and can be used with v4, v6 keys.
+ * Note however, that legacy implementations might not understand this key type yet.
+ * For a key type compatible with legacy v4 implementations, see {@link EdDSAPublicBCPGKey} with
+ * {@link PublicKeyAlgorithmTags#EDDSA_LEGACY}.
+ *
+ * @see <a href="https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-13.html#name-algorithm-specific-part-for-ed2">
+ *     Crypto-Refresh - Algorithm-Specific Part for Ed25519 Keys</a>
+ */
 public class Ed25519SecretBCPGKey
     extends OctetArrayBCPGKey
 {
+    // 32 octets of the native secret key
     public static final int LENGTH = 32;
 
     public Ed25519SecretBCPGKey(BCPGInputStream in)
diff --git a/pg/src/main/java/org/bouncycastle/bcpg/Ed448PublicBCPGKey.java b/pg/src/main/java/org/bouncycastle/bcpg/Ed448PublicBCPGKey.java
@@ -2,9 +2,20 @@
 
 import java.io.IOException;
 
+/**
+ * Public key of type {@link PublicKeyAlgorithmTags#Ed448}.
+ * This type was introduced with Crypto-Refresh and can be used with v4, v6 keys.
+ * Note however, that legacy implementations might not understand this key type yet.
+ * For a key type compatible with legacy v4 implementations, see {@link EdDSAPublicBCPGKey} with
+ * {@link PublicKeyAlgorithmTags#EDDSA_LEGACY}.
+ *
+ * @see <a href="https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-13.html#name-algorithm-specific-part-for-ed4">
+ *     Crypto-Refresh - Algorithm-Specific Part for Ed448 Keys</a>
+ */
 public class Ed448PublicBCPGKey
     extends OctetArrayBCPGKey
 {
+    // 57 octets of the native public key
     public static final int LENGTH = 57;
 
     public Ed448PublicBCPGKey(BCPGInputStream in)
diff --git a/pg/src/main/java/org/bouncycastle/bcpg/Ed448SecretBCPGKey.java b/pg/src/main/java/org/bouncycastle/bcpg/Ed448SecretBCPGKey.java
@@ -2,9 +2,20 @@
 
 import java.io.IOException;
 
+/**
+ * Secret key of type {@link PublicKeyAlgorithmTags#Ed448}.
+ * This type was introduced with Crypto-Refresh and can be used with v4, v6 keys.
+ * Note however, that legacy implementations might not understand this key type yet.
+ * For a key type compatible with legacy v4 implementations, see {@link EdDSAPublicBCPGKey} with
+ * {@link PublicKeyAlgorithmTags#EDDSA_LEGACY}.
+ *
+ * @see <a href="https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-13.html#name-algorithm-specific-part-for-ed4">
+ *     Crypto-Refresh - Algorithm-Specific Part for Ed448 Keys</a>
+ */
 public class Ed448SecretBCPGKey
         extends OctetArrayBCPGKey
 {
+    // 57 octets of the native secret key
     public static final int LENGTH = 57;
 
     public Ed448SecretBCPGKey(BCPGInputStream in)
diff --git a/pg/src/main/java/org/bouncycastle/bcpg/EdDSAPublicBCPGKey.java b/pg/src/main/java/org/bouncycastle/bcpg/EdDSAPublicBCPGKey.java
@@ -7,7 +7,14 @@
 import org.bouncycastle.math.ec.ECPoint;
 
 /**
- * base class for an EdDSA Public Key.
+ * Base class for an EdDSA Public Key.
+ * Here, the curve is identified by an OID and the key is MPI encoded.
+ * This class is used with {@link PublicKeyAlgorithmTags#EDDSA_LEGACY} only and MUST NOT be used with v6 keys.
+ * Modern OpenPGP uses dedicated key types:
+ * For {@link PublicKeyAlgorithmTags#Ed25519} see {@link Ed25519PublicBCPGKey} instead.
+ * For {@link PublicKeyAlgorithmTags#Ed448} see {@link Ed448PublicBCPGKey} instead.
+ * @see <a href="https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-13.html#name-algorithm-specific-part-for-ed">
+ *     Crypto-Refresh - Algorithm-Specific Parts for EdDSALegacy Keys (deprecated)</a>
  */
 public class EdDSAPublicBCPGKey
     extends ECPublicBCPGKey
diff --git a/pg/src/main/java/org/bouncycastle/bcpg/EdSecretBCPGKey.java b/pg/src/main/java/org/bouncycastle/bcpg/EdSecretBCPGKey.java
@@ -4,7 +4,14 @@
 import java.math.BigInteger;
 
 /**
- * base class for an Edwards Curve Secret Key.
+ * Base class for an Edwards Curve (EdDSA) Secret Key.
+ * This class is used with {@link PublicKeyAlgorithmTags#EDDSA_LEGACY} only and MUST NOT be used with v6 keys.
+ * Modern OpenPGP uses dedicated key types:
+ * For {@link PublicKeyAlgorithmTags#Ed25519} see {@link Ed25519SecretBCPGKey} instead.
+ * For {@link PublicKeyAlgorithmTags#Ed448} see {@link Ed448SecretBCPGKey} instead.
+ *
+ * @see <a href="https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-13.html#name-algorithm-specific-part-for-ed">
+ *     Crypto-Refresh - Algorithm-Specific Parts for EdDSALegacy Keys (deprecated)</a>
  */
 public class EdSecretBCPGKey
     extends BCPGObject
diff --git a/pg/src/main/java/org/bouncycastle/bcpg/X25519PublicBCPGKey.java b/pg/src/main/java/org/bouncycastle/bcpg/X25519PublicBCPGKey.java
@@ -2,9 +2,20 @@
 
 import java.io.IOException;
 
+/**
+ * Public key of type {@link PublicKeyAlgorithmTags#X25519}.
+ * This type was introduced with Crypto-Refresh and can be used with v4, v6 keys.
+ * Note however, that legacy implementations might not understand this key type yet.
+ * For a key type compatible with legacy v4 implementations, see {@link ECDHPublicBCPGKey} with
+ * {@link PublicKeyAlgorithmTags#ECDH}.
+ *
+ * @see <a href="https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-13.html#name-algorithm-specific-part-for-x">
+ *     Crypto-Refresh - Algorithm-Specific Part for X25519 Keys</a>
+ */
 public class X25519PublicBCPGKey
         extends OctetArrayBCPGKey
 {
+    // 32 octets of the native public key
     public static final int LENGTH = 32;
 
     public X25519PublicBCPGKey(BCPGInputStream in)
diff --git a/pg/src/main/java/org/bouncycastle/bcpg/X25519SecretBCPGKey.java b/pg/src/main/java/org/bouncycastle/bcpg/X25519SecretBCPGKey.java
@@ -2,9 +2,22 @@
 
 import java.io.IOException;
 
+/**
+ * Secret key of type {@link PublicKeyAlgorithmTags#X25519}.
+ * This type was introduced with Crypto-Refresh and can be used with v4, v6 keys.
+ * Note however, that legacy implementations might not understand this key type yet.
+ * For a key type compatible with legacy v4 implementations, see {@link ECSecretBCPGKey} with
+ * {@link PublicKeyAlgorithmTags#ECDH}.
+ * Note: Contrary to {@link ECSecretBCPGKey} using {@link PublicKeyAlgorithmTags#ECDH}, which uses big-endian
+ * MPI encoding to encode the secret key material, {@link X25519SecretBCPGKey} uses native little-endian encoding.
+ *
+ * @see <a href="https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-13.html#name-algorithm-specific-part-for-x">
+ *     Crypto-Refresh - Algorithm-Specific Part for X25519 Keys</a>
+ */
 public class X25519SecretBCPGKey
     extends OctetArrayBCPGKey
 {
+    // 32 octets of the native secret key
     public static final int LENGTH = 32;
 
     public X25519SecretBCPGKey(BCPGInputStream in)
diff --git a/pg/src/main/java/org/bouncycastle/bcpg/X448PublicBCPGKey.java b/pg/src/main/java/org/bouncycastle/bcpg/X448PublicBCPGKey.java
@@ -2,9 +2,20 @@
 
 import java.io.IOException;
 
+/**
+ * Public key of type {@link PublicKeyAlgorithmTags#X448}.
+ * This type was introduced with Crypto-Refresh and can be used with v4, v6 keys.
+ * Note however, that legacy implementations might not understand this key type yet.
+ * For a key type compatible with legacy v4 implementations, see {@link ECDHPublicBCPGKey} with
+ * {@link PublicKeyAlgorithmTags#ECDH}.
+ *
+ * @see <a href="https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-13.html#name-algorithm-specific-part-for-x4">
+ *     Crypto-Refresh - Algorithm-Specific Part for X448 Keys</a>
+ */
 public class X448PublicBCPGKey
         extends OctetArrayBCPGKey
 {
+    // 56 octets of the native public key
     public static final int LENGTH = 56;
 
     public X448PublicBCPGKey(BCPGInputStream in)
diff --git a/pg/src/main/java/org/bouncycastle/bcpg/X448SecretBCPGKey.java b/pg/src/main/java/org/bouncycastle/bcpg/X448SecretBCPGKey.java
@@ -2,9 +2,20 @@
 
 import java.io.IOException;
 
+/**
+ * Secret key of type {@link PublicKeyAlgorithmTags#X448}.
+ * This type was introduced with Crypto-Refresh and can be used with v4, v6 keys.
+ * Note however, that legacy implementations might not understand this key type yet.
+ * For a key type compatible with legacy v4 implementations, see {@link ECDHPublicBCPGKey} with
+ * {@link PublicKeyAlgorithmTags#ECDH}.
+ *
+ * @see <a href="https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-13.html#name-algorithm-specific-part-for-x4">
+ *     Crypto-Refresh - Algorithm-Specific Part for X448 Keys</a>
+ */
 public class X448SecretBCPGKey
     extends OctetArrayBCPGKey
 {
+    // 56 octets of the native secret key
     public static final int LENGTH = 56;
 
     public X448SecretBCPGKey(BCPGInputStream in)
