net.i2p.data

## Class KeyCertificate

- java.lang.Object
- - net.i2p.data.DataStructureImpl
  - - net.i2p.data.Certificate
    - - net.i2p.data.KeyCertificate

- All Implemented Interfaces:
    Serializable, DataStructure

      public class KeyCertificate
      extends Certificate

  Specialized certificate for defining cryptographic key types used in I2P identities.

  KeyCertificate specifies the encryption and signature algorithms for I2P identities:

  - Signature Type: Algorithm used for signing (2 bytes)
  - Encryption Type: Algorithm used for encryption (2 bytes)
  - Excess Data: Additional key-specific data if needed
  - Optimized: Frequently used, so has dedicated class for performance

  Format Structure:

  - Header: 4 bytes total (2-byte sig type + 2-byte crypto type)
  - Signature Data: Optional excess data for signature algorithm
  - Encryption Data: Optional excess data for encryption algorithm

  Supported Combinations:

  - ElGamal + DSA-SHA1: Legacy combination (crypto type 0x0000)
  - ElGamal + Ed25519: Modern signing with legacy encryption
  - ElGamal + ECDSA-P256: Modern signing with legacy encryption
  - X25519 + Ed25519: Modern combination (both algorithms)

  Predefined Certificates:

  - Ed25519: ElGamal + Ed25519 signing key
  - ECDSA256: ElGamal + ECDSA-P256 signing key
  - X25519_Ed25519: X25519 encryption + Ed25519 signing

  Usage:

  - Identity Specification: Defines algorithms for `Destination`
  - Algorithm Negotiation: Communicates supported crypto to peers
  - Backward Compatibility: Supports legacy and modern algorithms
  - Future Proofing: Extensible for new algorithm combinations

  Migration Path:

  - Legacy: ElGamal encryption (assumed 0x0000) with various signing
  - Modern: X25519 encryption with Ed25519 signing
  - Transition: Mixed combinations during migration period

  Performance Considerations:

  - Frequently Used: Every Destination contains a KeyCertificate
  - Optimized Creation: Pre-defined certificates for common combinations
  - Caching: Immutable instances can be safely shared
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `(package private) static byte[]` | `ECDSA256_PAYLOAD` ElG + P256
    `(package private) static byte[]` | `Ed25519_PAYLOAD` ElG + Ed25519
    `static KeyCertificate` | `ELG_ECDSA256_CERT` An immutable ElG/ECDSA-P256 certificate.
    `static KeyCertificate` | `ELG_Ed25519_CERT` An immutable ElG/Ed25519 certificate.
    `static int` | `HEADER_LENGTH`
    `static KeyCertificate` | `X25519_Ed25519_CERT` An immutable X25519/Ed25519 certificate.
    `(package private) static byte[]` | `X25519_Ed25519_PAYLOAD` X25519 + Ed25519

    - ### Fields inherited from class net.i2p.data.Certificate

      `_payload, _type, CERTIFICATE_LENGTH_SIGNED_WITH_HASH, CERTIFICATE_TYPE_HIDDEN, CERTIFICATE_TYPE_KEY, CERTIFICATE_TYPE_MULTIPLE, CERTIFICATE_TYPE_NULL, CERTIFICATE_TYPE_SIGNED, NULL_CERT`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `KeyCertificate(byte[] payload)`
    `KeyCertificate(Certificate cert)` Up-convert a cert to this class
    `KeyCertificate(SigningPublicKey spk)` A KeyCertificate with crypto type 0 (ElGamal) and the signature type and extra data from the given public key.
    `KeyCertificate(SigningPublicKey spk, PublicKey pk)` A KeyCertificate with enc type from the given public key, and the signature type and extra data from the given public key.
    `KeyCertificate(SigType type)` A KeyCertificate with crypto type 0 (ElGamal) and the signature type as specified.
    `KeyCertificate(SigType type, EncType etype)` A KeyCertificate with crypto type and the signature type as specified.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `getCryptoTypeCode()` Gets the crypto type code from the certificate.
    `EncType` | `getEncType()` Gets the encryption type from the certificate.
    `byte[]` | `getExtraKeyData()` Signing Key extra data, if any, is first in the array.
    `byte[]` | `getExtraSigningKeyData()` Signing Key extra data, if any.
    `SigType` | `getSigType()` Gets the signature type from the certificate.
    `int` | `getSigTypeCode()` Gets the signature type code from the certificate.
    `KeyCertificate` | `toKeyCertificate()` Up-convert this to a KeyCertificate
    `String` | `toString()`

    - ### Methods inherited from class net.i2p.data.Certificate

      `create, create, equals, getCertificateType, getPayload, hashCode, readBytes, readBytes, setCertificateType, setPayload, size, writeBytes, writeBytes`

    - ### Methods inherited from class net.i2p.data.DataStructureImpl

      `calculateHash, fromBase64, fromByteArray, read, toBase64, toByteArray`

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### ECDSA256_PAYLOAD

          static final byte[] ECDSA256_PAYLOAD

      ElG + P256

    - #### Ed25519_PAYLOAD

          static final byte[] Ed25519_PAYLOAD

      ElG + Ed25519

    - #### ELG_ECDSA256_CERT

          public static final KeyCertificate ELG_ECDSA256_CERT

      An immutable ElG/ECDSA-P256 certificate.

    - #### ELG_Ed25519_CERT

          public static final KeyCertificate ELG_Ed25519_CERT

      An immutable ElG/Ed25519 certificate.

    - #### HEADER_LENGTH

          public static final int HEADER_LENGTH

      See Also:
        Constant Field Values

    - #### X25519_Ed25519_CERT

          public static final KeyCertificate X25519_Ed25519_CERT

      An immutable X25519/Ed25519 certificate.

    - #### X25519_Ed25519_PAYLOAD

          static final byte[] X25519_Ed25519_PAYLOAD

      X25519 + Ed25519

  - ### Constructor Detail

    - #### KeyCertificate

          public KeyCertificate(byte[] payload)
                         throws DataFormatException

      Parameters:
        `payload` - 4 bytes minimum if non-null
      Throws:
        `DataFormatException` - if payload is too short

    - #### KeyCertificate

          public KeyCertificate(Certificate cert)
                         throws DataFormatException

      Up-convert a cert to this class
      Parameters:
        `cert` - payload 4 bytes minimum if non-null
      Throws:
        `DataFormatException` - if cert type != CERTIFICATE_TYPE_KEY

    - #### KeyCertificate

          public KeyCertificate(SigningPublicKey spk)

      A KeyCertificate with crypto type 0 (ElGamal) and the signature type and extra data from the given public key.
      Parameters:
        `spk` - non-null data non-null
      Throws:
        `IllegalArgumentException` - if spk or spk data is null

    - #### KeyCertificate

          public KeyCertificate(SigningPublicKey spk,
                                PublicKey pk)

      A KeyCertificate with enc type from the given public key, and the signature type and extra data from the given public key. EncType lengths greater than 256 not supported.
      Parameters:
        `spk` - non-null data non-null
        `pk` - non-null
      Throws:
        `IllegalArgumentException` - if spk, pk, or their data is null

    - #### KeyCertificate

          public KeyCertificate(SigType type)

      A KeyCertificate with crypto type 0 (ElGamal) and the signature type as specified. Payload is created. If type.getPubkeyLen() is greater than 128, caller MUST fill in the extra key data in the payload.
      Parameters:
        `type` - non-null
      Throws:
        `IllegalArgumentException` - if type is null

    - #### KeyCertificate

          public KeyCertificate(SigType type,
                                EncType etype)

      A KeyCertificate with crypto type and the signature type as specified. Payload is created. If type.getPubkeyLen() is greater than 128, caller MUST fill in the extra key data in the payload. EncType lengths greater than 256 not supported.
      Parameters:
        `type` - non-null
        `etype` - non-null
      Throws:
        `IllegalArgumentException` - if type or etype is null

  - ### Method Detail

    - #### getCryptoTypeCode

          public int getCryptoTypeCode()

      Gets the crypto type code from the certificate.
      Returns:
        -1 if unset

    - #### getEncType

          public EncType getEncType()

      Gets the encryption type from the certificate.
      Returns:
        null if unset or unknown

    - #### getExtraKeyData

          public byte[] getExtraKeyData()

      Signing Key extra data, if any, is first in the array. Crypto Key extra data, if any, is second in the array, at offset max(0, getSigType().getPubkeyLen() - 128)
      Returns:
        null if unset or none

    - #### getExtraSigningKeyData

          public byte[] getExtraSigningKeyData()

      Signing Key extra data, if any.
      Returns:
        null if unset or none
      Throws:
        `UnsupportedOperationException` - if the sig type is unsupported

    - #### getSigType

          public SigType getSigType()

      Gets the signature type from the certificate.
      Returns:
        null if unset or unknown

    - #### getSigTypeCode

          public int getSigTypeCode()

      Gets the signature type code from the certificate.
      Returns:
        -1 if unset

    - #### toKeyCertificate

          public KeyCertificate toKeyCertificate()

      Description copied from class: `Certificate`
      Up-convert this to a KeyCertificate
      Overrides:
        `toKeyCertificate` in class `Certificate`

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Certificate`