From 81eea49eceb7d1c053be57df57cae02480757e43 Mon Sep 17 00:00:00 2001 From: Paul Schaub Date: Wed, 8 May 2024 11:07:31 +0200 Subject: [PATCH 1/3] Add documentation to ECDH,ECDSA,EdDSA BCPGKeys --- .../org/bouncycastle/bcpg/ECDHPublicBCPGKey.java | 12 +++++++++++- .../org/bouncycastle/bcpg/ECDSAPublicBCPGKey.java | 6 +++++- .../org/bouncycastle/bcpg/ECPublicBCPGKey.java | 3 ++- .../org/bouncycastle/bcpg/ECSecretBCPGKey.java | 14 +++++++++++++- .../bouncycastle/bcpg/Ed25519PublicBCPGKey.java | 11 +++++++++++ .../bouncycastle/bcpg/Ed25519SecretBCPGKey.java | 11 +++++++++++ .../org/bouncycastle/bcpg/Ed448PublicBCPGKey.java | 11 +++++++++++ .../org/bouncycastle/bcpg/Ed448SecretBCPGKey.java | 11 +++++++++++ .../org/bouncycastle/bcpg/EdDSAPublicBCPGKey.java | 9 ++++++++- .../org/bouncycastle/bcpg/EdSecretBCPGKey.java | 9 ++++++++- .../org/bouncycastle/bcpg/X25519PublicBCPGKey.java | 11 +++++++++++ .../org/bouncycastle/bcpg/X25519SecretBCPGKey.java | 11 +++++++++++ .../org/bouncycastle/bcpg/X448PublicBCPGKey.java | 11 +++++++++++ .../org/bouncycastle/bcpg/X448SecretBCPGKey.java | 11 +++++++++++ 14 files changed, 135 insertions(+), 6 deletions(-) diff --git a/pg/src/main/java/org/bouncycastle/bcpg/ECDHPublicBCPGKey.java b/pg/src/main/java/org/bouncycastle/bcpg/ECDHPublicBCPGKey.java index 65f408d8e3..b0d83b7684 100644 --- 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 + * Crypto-Refresh - Algorithm-Specific Parts for ECDH Keys */ 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 index cf0965185a..87bfa6f334 100644 --- 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 + * Crypto-Refresh - Algorithm-Specific Parts for ECDSA Keys */ 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 index 38e1b0e4a9..b0631e3766 100644 --- 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 index c595fa4b5f..dd70dab1d7 100644 --- 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 + * Crypto-Refresh - Algorithm-Specific Parts for ECDH Keys + * @see + * Crypto-Refresh - Algorithm-Specific Parts for ECDSA Keys */ 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 index e85d3a8377..14507dca2c 100644 --- 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 + * Crypto-Refresh - Algorithm-Specific Part for Ed25519 Keys + */ 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 index 386ed6e348..56f7bb815d 100644 --- 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 + * Crypto-Refresh - Algorithm-Specific Part for Ed25519 Keys + */ 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 index 93b0021a34..426f9d909c 100644 --- 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 + * Crypto-Refresh - Algorithm-Specific Part for Ed448 Keys + */ 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 index ee5ba7c949..76ac630b64 100644 --- 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 + * Crypto-Refresh - Algorithm-Specific Part for Ed448 Keys + */ 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 index 32767ba152..9bbcf710b4 100644 --- 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 + * Crypto-Refresh - Algorithm-Specific Parts for EdDSALegacy Keys (deprecated) */ 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 index 084ce8cd16..6862fc6298 100644 --- 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 + * Crypto-Refresh - Algorithm-Specific Parts for EdDSALegacy Keys (deprecated) */ 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 index 298ebd9098..a0db01b01e 100644 --- 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 + * Crypto-Refresh - Algorithm-Specific Part for X25519 Keys + */ 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 index 81f54a77c0..c023d7abbc 100644 --- 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 + * Crypto-Refresh - Algorithm-Specific Part for X25519 Keys + */ 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 index 48b88cf211..6881b276ba 100644 --- 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 + * Crypto-Refresh - Algorithm-Specific Part for X448 Keys + */ 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 index 65140dc8f5..8bcf0332e1 100644 --- 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 + * Crypto-Refresh - Algorithm-Specific Part for X448 Keys + */ public class X448SecretBCPGKey extends OctetArrayBCPGKey { + // 56 octets of the native secret key public static final int LENGTH = 56; public X448SecretBCPGKey(BCPGInputStream in) From f23fc367e6aded2d2aaea37583695ab7c8ddd878 Mon Sep 17 00:00:00 2001 From: Paul Schaub Date: Tue, 21 May 2024 15:02:47 +0200 Subject: [PATCH 2/3] Document reversed MPI encoding / little-endian native encoding --- pg/src/main/java/org/bouncycastle/bcpg/ECSecretBCPGKey.java | 5 +++++ .../main/java/org/bouncycastle/bcpg/X25519SecretBCPGKey.java | 2 ++ 2 files changed, 7 insertions(+) diff --git a/pg/src/main/java/org/bouncycastle/bcpg/ECSecretBCPGKey.java b/pg/src/main/java/org/bouncycastle/bcpg/ECSecretBCPGKey.java index dd70dab1d7..a5b498f985 100644 --- a/pg/src/main/java/org/bouncycastle/bcpg/ECSecretBCPGKey.java +++ b/pg/src/main/java/org/bouncycastle/bcpg/ECSecretBCPGKey.java @@ -8,6 +8,9 @@ * 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. @@ -17,6 +20,8 @@ * Crypto-Refresh - Algorithm-Specific Parts for ECDH Keys * @see * Crypto-Refresh - Algorithm-Specific Parts for ECDSA Keys + * @see + * Crypto-Refresh - Curve25519Legacy ECDH Secret Key Material (deprecated) */ public class ECSecretBCPGKey extends BCPGObject diff --git a/pg/src/main/java/org/bouncycastle/bcpg/X25519SecretBCPGKey.java b/pg/src/main/java/org/bouncycastle/bcpg/X25519SecretBCPGKey.java index c023d7abbc..0840663fb1 100644 --- a/pg/src/main/java/org/bouncycastle/bcpg/X25519SecretBCPGKey.java +++ b/pg/src/main/java/org/bouncycastle/bcpg/X25519SecretBCPGKey.java @@ -8,6 +8,8 @@ * 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}. + * 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 * Crypto-Refresh - Algorithm-Specific Part for X25519 Keys From 9c97d4a0c7023f8b6b23fb822af58bb88436b50a Mon Sep 17 00:00:00 2001 From: Paul Schaub Date: Tue, 21 May 2024 15:04:43 +0200 Subject: [PATCH 3/3] Fix javadoc reference to ECSecretBCPGKey --- pg/src/main/java/org/bouncycastle/bcpg/X25519SecretBCPGKey.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pg/src/main/java/org/bouncycastle/bcpg/X25519SecretBCPGKey.java b/pg/src/main/java/org/bouncycastle/bcpg/X25519SecretBCPGKey.java index 0840663fb1..17043353af 100644 --- a/pg/src/main/java/org/bouncycastle/bcpg/X25519SecretBCPGKey.java +++ b/pg/src/main/java/org/bouncycastle/bcpg/X25519SecretBCPGKey.java @@ -6,7 +6,7 @@ * 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 + * 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.