net.i2p.data

## Class PrivateKey

- java.lang.Object
- - net.i2p.data.SimpleDataStructure
  - - net.i2p.data.PrivateKey

- All Implemented Interfaces:
    Destroyable, DataStructure

      public class PrivateKey
      extends SimpleDataStructure
      implements Destroyable

  Cryptographic private key for asymmetric encryption in I2P.

  PrivateKey provides the decryption component of I2P's asymmetric cryptography:

  - Default Algorithm: ElGamal 2048-bit (256 bytes)
  - Modern Support: Variable length and type support since 0.9.38
  - Key Structure: Contains only the private exponent
  - Security: Implements `Destroyable` for secure cleanup

  Supported Algorithms:

  - ElGamal 2048: Legacy algorithm, 256-byte keys
  - ECIES X25519: Modern elliptic curve, 32-byte keys
  - Future Types: Extensible design for new algorithms

  Key Format:

  - ElGamal: 256-byte private exponent only
  - Constants: Prime numbers defined in crypto specification
  - Efficiency: Only stores variable private component
  - Validation: Type-specific length and format checking

  Usage:

  - Decryption: Decrypt messages encrypted with corresponding `PublicKey`
  - Key Exchange: Participate in ElGamal key exchange protocols
  - Identity: Part of `Destination` cryptographic identity
  - Storage: Securely stored in keyring or keystore

  Security Considerations:

  - Confidentiality: Private keys must never be exposed
  - Secure Destruction: Call `destroy()` when no longer needed
  - Memory Protection: Zeroize memory after use
  - Algorithm Choice: Prefer modern algorithms (X25519) when possible

  Performance Features:

  - Caching: LRU cache for frequently used keys
  - Public Key Derivation: Cached derived public key
  - Efficient Storage: Optimized byte representation
  - Factory Methods: Static creation methods for cache access

  Migration Path:

  - Legacy: ElGamal 2048-bit for backward compatibility
  - Modern: ECIES X25519 for better performance and security
  - Transition: Mixed algorithm support during migration

  Thread Safety:

  - Immutable Data: Key data cannot be modified after creation
  - Safe Destruction: Thread-safe key zeroization
  - Cache Access: Thread-safe factory methods

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `KEYSIZE_BYTES`

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

      `_data`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `PrivateKey()`
    `PrivateKey(byte[] data)`
    `PrivateKey(EncType type)`
    `PrivateKey(EncType type, byte[] data)`
    `PrivateKey(EncType type, byte[] data, PublicKey pubKey)`
    `PrivateKey(String base64Data)` constructs from base64

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `destroy()` javax.security.auth.Destroyable interface
    `boolean` | `equals(Object obj)` Warning - this returns true for two different classes with the same size and same data, e.g.
    `EncType` | `getType()` Gets the encryption type of this private key.
    `int` | `hashCode()` We assume the data has enough randomness in it, so use the last 4 bytes for speed.
    `boolean` | `isDestroyed()` javax.security.auth.Destroyable interface
    `int` | `length()` The legal length of the byte array in this data structure
    `PublicKey` | `toPublic()` Derives a new PublicKey object derived from the secret contents of this PrivateKey.
    `String` | `toString()`

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

      `calculateHash, fromBase64, fromByteArray, getData, read, readBytes, setData, toBase64, toByteArray, writeBytes`

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

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

- - ### Field Detail

    - #### KEYSIZE_BYTES

          public static final int KEYSIZE_BYTES

  - ### Constructor Detail

    - #### PrivateKey

          public PrivateKey()

    - #### PrivateKey

          public PrivateKey(byte[] data)

    - #### PrivateKey

          public PrivateKey(EncType type)

      Parameters:
        `type` - non-null

    - #### PrivateKey

          public PrivateKey(EncType type,
                            byte[] data)

      Parameters:
        `type` - non-null
        `data` - must be non-null

    - #### PrivateKey

          public PrivateKey(EncType type,
                            byte[] data,
                            PublicKey pubKey)

      Parameters:
        `type` - non-null
        `data` - must be non-null
        `pubKey` - corresponding pubKey to be cached

    - #### PrivateKey

          public PrivateKey(String base64Data)
                     throws DataFormatException

      constructs from base64
      Parameters:
        `base64Data` - a string of base64 data (the output of .toBase64() called on a prior instance of PrivateKey
      Throws:
        `DataFormatException`

  - ### Method Detail

    - #### destroy

          public void destroy()

      javax.security.auth.Destroyable interface
      Specified by:
        `destroy` in interface `Destroyable`

    - #### equals

          public boolean equals(Object obj)

      Description copied from class: `SimpleDataStructure`
      Warning - this returns true for two different classes with the same size and same data, e.g. SessionKey and SessionTag, but you wouldn't put them in the same Set, would you?
      Overrides:
        `equals` in class `SimpleDataStructure`

    - #### getType

          public EncType getType()

      Gets the encryption type of this private key.
      Returns:
        non-null

    - #### hashCode

          public int hashCode()

      We assume the data has enough randomness in it, so use the last 4 bytes for speed. Overridden since we use short exponents, so the first 227 bytes are all zero.
      Overrides:
        `hashCode` in class `SimpleDataStructure`

    - #### isDestroyed

          public boolean isDestroyed()

      javax.security.auth.Destroyable interface
      Specified by:
        `isDestroyed` in interface `Destroyable`

    - #### length

          public int length()

      Description copied from class: `SimpleDataStructure`
      The legal length of the byte array in this data structure
      Specified by:
        `length` in class `SimpleDataStructure`

    - #### toPublic

          public PublicKey toPublic()

      Derives a new PublicKey object derived from the secret contents of this PrivateKey. As of 0.9.44, the PublicKey is cached.
      Returns:
        a PublicKey object
      Throws:
        `IllegalArgumentException` - on bad key

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `SimpleDataStructure`