Document reversed MPI encoding / little-endian native encoding

Author: vanitasvitae

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</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

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 <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>