java.lang.Object
net.i2p.data.DataStructureImpl
net.i2p.data.Payload
All Implemented Interfaces:
Serializable, DataStructure
public class Payloadextends DataStructureImpl
Message payload container for I2P communications with encryption support.

Payload provides message content delivery in I2P:

  • Message Content: Contains actual data being delivered
  • Encryption Support: Standard encryption wrapping per I2P spec
  • I2CP Protocol: Primarily used in client-router communication
  • Legacy Feature: Previously supported end-to-end encryption

Historical Context:

  • End-to-End Encryption: Previously encrypted messages between clients
  • Protocol Change: End-to-end encryption removed in I2P
  • Current Usage: Use get/setEncryptedData(byte[]) methods instead
  • I2CP Focus: Now mainly used for I2CP message transport

Current Structure:

  • Encrypted Data: Primary payload content for transmission
  • Unencrypted Data: Legacy support for decrypted content access
  • Size Limits: Maximum 64KB to prevent OOM attacks
  • Format Compliance: Follows I2P data structure specification

Usage Patterns:

  • Modern Usage: Use getEncryptedData()/setEncryptedData() for payload
  • I2CP Messages: Transport messages between client and router
  • Legacy Support: getUnencryptedData() for backward compatibility
  • Size Management: Monitor payload size to prevent resource exhaustion

Security Considerations:

  • Size Validation: Enforce 64KB maximum payload size
  • Memory Protection: Prevent OOM attacks through large payloads
  • Content Validation: Verify payload integrity and format
  • Encryption Context: Understand current encryption model in I2P

Performance Aspects:

  • Efficient Storage: Minimal overhead for payload data
  • Fast Access: Direct byte array access methods
  • Memory Management: Careful allocation and cleanup
  • Size Checking: Quick validation of payload limits

Migration Notes:

  • From End-to-End: Previously handled client-to-client encryption
  • To Transport Only: Now focuses on message transport
  • API Simplification: Use encrypted data methods for clarity
  • Backward Compatibility: Legacy methods still available
See Also:

  • Field Details

    • _encryptedData

      private byte[] _encryptedData
      Encrypted payload data.

    • _unencryptedData

      private byte[] _unencryptedData
      Unencrypted payload data.

    • MAX_LENGTH

      private static final int MAX_LENGTH
      So we don't OOM on I2CP protocol errors. Actual max is smaller.
      See Also:

  • Constructor Details

    • Payload

      public Payload()
      Required for deserialization.

  • Method Details

    • getUnencryptedData

      public byte[] getUnencryptedData()
      Retrieve the unencrypted body of the message.

      Deprecated. Unless you are doing encryption, use getEncryptedData() instead.

      Returns:
      body of the message, or null if the message has either not been decrypted yet or if the hash is not correct

    • setUnencryptedData

      public void setUnencryptedData(byte[] data)
      Populate the message body with data. This does not automatically encrypt yet.

      Deprecated. Unless you are doing encryption, use setEncryptedData() instead.

      Parameters:
      data - the plaintext message body, at most 64KB
      Throws:
      IllegalArgumentException - if bigger than 64KB

    • getEncryptedData

      public byte[] getEncryptedData()
      Encrypted data, or null.
      Returns:
      the encrypted data, or null

    • setEncryptedData

      public void setEncryptedData(byte[] data)
      The encrypted data.
      Parameters:
      data - the encrypted message body, at most 64KB
      Throws:
      IllegalArgumentException - if bigger than 64KB

    • getSize

      public int getSize()
      Size in bytes.
      Returns:
      the size in bytes

    • readBytes

      public void readBytes(InputStream in) throws DataFormatException, IOException
      Reads this payload from an input stream (4-byte length-prefixed data).
      Parameters:
      in - stream to read from
      Throws:
      DataFormatException - if the data is improperly formatted
      IOException - if there was a problem reading the stream

    • writeBytes

      public void writeBytes(OutputStream out) throws DataFormatException, IOException
      Writes this payload to an output stream (4-byte length-prefixed data).
      Parameters:
      out - stream to write to
      Throws:
      DataFormatException - if the data was incomplete or not yet ready to be written
      IOException - if there was a problem writing to the stream

    • writeBytes

      public int writeBytes(byte[] target, int offset)
      Writes the encrypted payload to the target array.
      Parameters:
      target - the array to write the 4-byte length prefix and encrypted body into
      offset - the index in target where the 4-byte length prefix is written
      Returns:
      the written length (NOT the new offset)

    • equals

      public boolean equals(Object object)
      Compares this payload with another object for equality.
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Hash code based on the encrypted or unencrypted data.
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Returns a string representation of this payload.
      Overrides:
      toString in class Object