Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add documentation to ECDH,ECDSA,EdDSA BCPGKeys #1655

Closed
wants to merge 3 commits into from
Closed

Add documentation to ECDH,ECDSA,EdDSA BCPGKeys #1655

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
81eea49
Add documentation to ECDH,ECDSA,EdDSA BCPGKeys
vanitasvitae May 8, 2024
f23fc36
Document reversed MPI encoding / little-endian native encoding
vanitasvitae May 21, 2024
9c97d4a
Fix javadoc reference to ECSecretBCPGKey
vanitasvitae May 21, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 11 additions & 1 deletion pg/src/main/java/org/bouncycastle/bcpg/ECDHPublicBCPGKey.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 5 additions & 1 deletion pg/src/main/java/org/bouncycastle/bcpg/ECDSAPublicBCPGKey.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 2 additions & 1 deletion pg/src/main/java/org/bouncycastle/bcpg/ECPublicBCPGKey.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
19 changes: 18 additions & 1 deletion pg/src/main/java/org/bouncycastle/bcpg/ECSecretBCPGKey.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
11 changes: 11 additions & 0 deletions pg/src/main/java/org/bouncycastle/bcpg/Ed25519PublicBCPGKey.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
11 changes: 11 additions & 0 deletions pg/src/main/java/org/bouncycastle/bcpg/Ed25519SecretBCPGKey.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
11 changes: 11 additions & 0 deletions pg/src/main/java/org/bouncycastle/bcpg/Ed448PublicBCPGKey.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
11 changes: 11 additions & 0 deletions pg/src/main/java/org/bouncycastle/bcpg/Ed448SecretBCPGKey.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
9 changes: 8 additions & 1 deletion pg/src/main/java/org/bouncycastle/bcpg/EdDSAPublicBCPGKey.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
9 changes: 8 additions & 1 deletion pg/src/main/java/org/bouncycastle/bcpg/EdSecretBCPGKey.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
11 changes: 11 additions & 0 deletions pg/src/main/java/org/bouncycastle/bcpg/X25519PublicBCPGKey.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
13 changes: 13 additions & 0 deletions pg/src/main/java/org/bouncycastle/bcpg/X25519SecretBCPGKey.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
11 changes: 11 additions & 0 deletions pg/src/main/java/org/bouncycastle/bcpg/X448PublicBCPGKey.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
11 changes: 11 additions & 0 deletions pg/src/main/java/org/bouncycastle/bcpg/X448SecretBCPGKey.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down