java.lang.Object
net.i2p.data.SimpleDataStructure
net.i2p.data.PublicKey
All Implemented Interfaces:
DataStructure
Direct Known Subclasses:
NextSessionKey
public class PublicKeyextends SimpleDataStructure
Cryptographic public key for asymmetric encryption in I2P.

PublicKey provides the encryption 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 public exponent
  • Constants: Prime numbers defined in crypto specification

Supported Algorithms:

  • ElGamal 2048: Legacy algorithm, 256-byte keys
  • ECIES X25519: Modern elliptic curve, 32-byte keys
  • Unknown Types: Forward-compatible support for future algorithms

Key Format:

  • ElGamal: 256-byte public exponent only
  • Elliptic Curve: Variable length based on curve parameters
  • Type Encoding: Algorithm type stored with key data
  • Validation: Length and format checking per algorithm

Usage:

  • Encryption: Encrypt messages for corresponding PrivateKey
  • Key Exchange: Participate in ElGamal key exchange
  • Identity: Part of Destination cryptographic identity
  • Verification: Public key validation and distribution

Performance Features:

  • LRU Caching: Frequently used keys cached for efficiency
  • Factory Methods: Static creation methods for cache access
  • Efficient Storage: Optimized byte representation
  • Fast Comparison: Optimized equals(Object) and hashCode()

Security Considerations:

  • Algorithm Choice: Prefer modern algorithms (X25519)
  • Key Validation: Verify key parameters before use
  • Key Distribution: Safely transmit public keys
  • Size Limits: Currently limited to 256 bytes maximum

Migration Path:

  • Legacy: ElGamal 2048-bit for backward compatibility
  • Modern: ECIES X25519 for better performance
  • Future: Extensible design for new algorithms

Implementation Notes:

  • Size Limitation: Support for keys >256 bytes not yet implemented
  • Cache Index: First 4 bytes used for LRU cache lookup
  • Type Safety: Algorithm type validation on creation

Thread Safety:

  • Immutable Data: Key data cannot be modified after creation
  • Thread-Safe Cache: Static factory methods are thread-safe
  • Safe Sharing: Instances can be safely shared between threads

  • Field Details

    • DEF_TYPE

      private static final EncType DEF_TYPE
      Type assumed when a key names none.

    • KEYSIZE_BYTES

      public static final int KEYSIZE_BYTES
      Default key size in bytes (256 for ElGamal).

    • EMPTY

      private static final byte[] EMPTY
      Shared result for the no-padding case. Zero-length arrays cannot be mutated, so a single instance may be handed to every caller.

    • CACHE_SIZE

      private static final int CACHE_SIZE
      Keys held in the shared cache.
      See Also:

    • _cache

      private static final SDSCache<PublicKey> _cache
      Shared cache of parsed keys.

    • _type

      private final EncType _type
      The encryption type of this key.

    • _unknownTypeCode

      private final int _unknownTypeCode
      The type number when the type is not known.

  • Constructor Details

    • PublicKey

      public PublicKey()
      Creates a new PublicKey with the default ElGamal type.

    • PublicKey

      public PublicKey(EncType type)
      New public key with the given encryption type.
      Parameters:
      type - if null, type is unknown

    • PublicKey

      public PublicKey(byte[] data)
      Public key from raw key data.
      Parameters:
      data - must be non-null

    • PublicKey

      public PublicKey(EncType type, byte[] data)
      New public key with the given encryption type and raw key data.
      Parameters:
      type - if null, type is unknown
      data - must be non-null

    • PublicKey

      public PublicKey(int typeCode, byte[] data)
      Unknown type only.
      Parameters:
      typeCode - must not match a known type. 1-255
      data - must be non-null

    • PublicKey

      public PublicKey(String base64Data) throws DataFormatException
      Public key from a string of base64 data. ElGamal only.
      Parameters:
      base64Data - a string of base64 data (the output of .toBase64() called on a prior instance of PublicKey
      Throws:
      DataFormatException - if the data is malformed

  • Method Details

    • create

      public static PublicKey create(byte[] data, int off)
      Pull from cache or return new. ELGAMAL_2048 only! Deprecated - used only by deprecated Destination.readBytes(data, off).
      Parameters:
      data - the data to decrypt
      off - the offset into the data
      Returns:
      the public key read from data, from the cache when possible

    • create

      public static PublicKey create(InputStream in) throws IOException
      Pull from cache or return new. ELGAMAL_2048 only!
      Parameters:
      in - the input stream
      Returns:
      the public key read from in, from the cache when possible
      Throws:
      IOException - if an I/O error occurs

    • length

      public int length()
      Key length in bytes, determined by the encryption type.
      Specified by:
      length in class SimpleDataStructure
      Returns:
      the legal length of the byte array

    • getType

      public EncType getType()
      Encryption type of this public key.
      Returns:
      null if unknown

    • getUnknownTypeCode

      public int getUnknownTypeCode()
      Type code for unknown encryption types.

      Only valid if getType() returns null.

      Returns:
      the unknown type code

    • toTypedKey

      PublicKey toTypedKey(KeyCertificate kcert)
      Up-convert this from an untyped (type 0) PK to a typed PK based on the Key Cert given. The type of the returned key will be null if the kcert sigtype is null.
      Parameters:
      kcert - the key certificate
      Returns:
      the typed public key
      Throws:
      IllegalArgumentException - if this is already typed to a different type

    • getPadding

      public byte[] getPadding(KeyCertificate kcert)
      Padding portion of this (type 0) PK based on the Key Cert type given, if any.
      Parameters:
      kcert - the key certificate
      Returns:
      the trailing padding, or a shared empty array if there is no padding or the type is unknown
      Throws:
      IllegalStateException - if this is already typed to a different type

    • clearCache

      public static void clearCache()
      Clears the public key cache.

    • toString

      public String toString()
      String representation showing type and data size.
      Overrides:
      toString in class SimpleDataStructure

    • hashCode

      public int hashCode()
      Hash code combining the type and data.
      Overrides:
      hashCode in class SimpleDataStructure
      Returns:
      the hash code

    • equals

      public boolean equals(Object obj)
      Compares this public key with another object for equality.
      Overrides:
      equals in class SimpleDataStructure
      Parameters:
      obj - the object to compare
      Returns:
      true if the data arrays are equal