Add documentation to ECDH,ECDSA,EdDSA BCPGKeys

bcgit · May 8, 2024 · 81eea49 · 81eea49
1 parent d7ffa8b
commit 81eea49
Show file tree

Hide file tree

Showing 14 changed files with 135 additions and 6 deletions.
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,19 @@
 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:
+ * 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>
  */
 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,20 @@
 
 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 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 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)