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..a5b498f985 100644 --- 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 + * 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/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..17043353af 100644 --- 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 + * 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)