Method Details

• getSession

  public I2PSession getSession()

  Return the session this packet belongs to.

  Returns:

  the session the packet is sent or received on

• getSendStreamId

  public long getSendStreamId()

  Stream we send data to the peer on.

  Returns:

  stream ID we use to send data

• setSendStreamId

  public void setSendStreamId(long id)

  Stream the peer will receive data on.

  Parameters:

  id - the send stream ID to set

  Throws:

  RuntimeException - if the send stream ID has already been set to a different value

• getReceiveStreamId

  public long getReceiveStreamId()

  Stream the replies should be sent on. This should be 0 if the connection is still being built.

  Returns:

  stream ID we use to get data, zero if the connection is still being built.

• setReceiveStreamId

  public void setReceiveStreamId(long id)

  Stream the peer will send replies on.

  Parameters:

  id - the receive stream ID to set

  Throws:

  RuntimeException - if the receive stream ID has already been set to a different value

• getSequenceNum

  public long getSequenceNum()

  0-indexed sequence number for this Packet in the sendStream.

  Returns:

  0-indexed sequence number for current Packet in current sendStream

• setSequenceNum

  public void setSequenceNum(long num)

  Sequence number to set.

  Parameters:

  num - the sequence number to set

• getAckThrough

  public long getAckThrough()

  The highest packet sequence number that received on the receiveStreamId. This field is ignored on the initial connection packet (where receiveStreamId is the unknown id) or if FLAG_NO_ACK is set.

  Returns:

  The highest packet sequence number received on receiveStreamId, or -1 if FLAG_NO_ACK

• setAckThrough

  public void setAckThrough(long id)

  ACK-through value to set; if < 0, sets FLAG_NO_ACK.

  Parameters:

  id - the ack through value to set, if < 0 sets FLAG_NO_ACK

• getNacks

  public long[] getNacks()

  List of packet sequence numbers below the getAckThrough() value have not been received. this may be null.

  Warning: This is different than getNACKs() in PacketLocal.

  Returns:

  List of packet sequence numbers not ACKed, or null if there are none.

• setNacks

  public void setNacks(long[] nacks)

  NACK list to set.

  Parameters:

  nacks - list of packet sequence numbers not ACKed, or null if there are none.

• getResendDelay

  public int getResendDelay()

  How long is the creator of this packet going to wait before resending this packet (if it hasn't yet been ACKed). The value is seconds since the packet was created.

  Unused. Broken before release 0.7.8 Not to be used without sanitizing for huge values. Setters from options did not divide by 1000, and the options default is 1000, so the value sent in the 1-byte field was always 1000 & 0xff = 0xe8 = 232.

  Returns:

  Delay before resending a packet in seconds.

• setResendDelay

  public void setResendDelay(int numSeconds)

  Unused. Broken before release 0.7.8 See above.

  Parameters:

  numSeconds - the resend delay in seconds, ignored by this release

• getPayload

  public ByteArray getPayload()

  Actual payload of the message, may be null.

  Returns:

  the payload of the message, null if none.

• setPayload

  public void setPayload(ByteArray payload)

  Payload to set.

  Parameters:

  payload - the payload to set, or null to clear

  Throws:

  IllegalArgumentException - if the payload exceeds MAX_PAYLOAD_SIZE

• getPayloadSize

  public int getPayloadSize()

  Payload size in bytes.

  Returns:

  the size of the payload in bytes, or 0 if no payload

• releasePayload

  public void releasePayload()

  No-op, payload buffers are garbage-collected, not pooled.

• acquirePayload

  public ByteArray acquirePayload()

  Allocate a MAX_PAYLOAD_SIZE buffer for this packet.

  Returns:

  a new ByteArray of MAX_PAYLOAD_SIZE for this packet

• isFlagSet

  public boolean isFlagSet(int flag)

  Is a particular flag set on this packet?

  Parameters:

  flag - bitmask of any flag(s)

  Returns:

  true if set, false if not.

• setFlag

  public void setFlag(int flag)

  Marks the flag(s) set.

  Parameters:

  flag - bitmask of any flag(s)

• setFlag

  public void setFlag(int flag, boolean set)

  Marks the flag(s) set or clear.

  Parameters:

  flag - bitmask of any flag(s)

  set - true to set, false to clear

• getOptionalSignature

  public Signature getOptionalSignature()

  The signature on the packet (only included if the flag for it is set)

  Warning, may be typed wrong on incoming packets for EdDSA before verifySignature() is called.

  Returns:

  signature on the packet if the flag for signatures is set

• setOptionalSignature

  public void setOptionalSignature(Signature sig)

  This also sets flag FLAG_SIGNATURE_INCLUDED.

  Parameters:

  sig - the signature to attach to the packet, or null to clear it and drop the flag

• getOptionalFrom

  public Destination getOptionalFrom()

  Sender of the packet, only included if the flag for it is set.

  Returns:

  the sending Destination

• getTransientSPK

  public SigningPublicKey getTransientSPK()

  Transient signing public key, only if an offline signing block was included, else null.

  Returns:

  the transient signing public key

• getOptionalDelay

  public int getOptionalDelay()

  How many milliseconds the sender of this packet wants the recipient to wait before sending any more data (only valid if the flag for it is set).

  Returns:

  How long the sender wants the recipient to wait before sending any more data in ms.

• setOptionalDelay

  public void setOptionalDelay(int delayMs)

  Caller must also call setFlag(FLAG_DELAY_REQUESTED).

  Parameters:

  delayMs - how long the sender should be asked to wait in ms, clamped to 0..MAX_DELAY_REQUEST

• getOptionalMaxSize

  public int getOptionalMaxSize()

  What is the largest payload the sender of this packet wants to receive?

  Returns:

  Maximum payload size sender can receive (MRU) or zero if unset

• setOptionalMaxSize

  public void setOptionalMaxSize(int numBytes)

  This also sets flag FLAG_MAX_PACKET_SIZE_INCLUDED.

  Parameters:

  numBytes - the largest payload the sender should be told it may receive, or 0 to unset the flag

• getLocalPort

  public int getLocalPort()

  Local port.

  Returns:

  Default I2PSession.PORT_UNSPECIFIED (0) or PORT_ANY (0)

• setLocalPort

  public void setLocalPort(int port)

  Must be called to change the port, not set by readPacket() as the port is out-of-band in the I2CP header.

  Parameters:

  port - the local port to record, I2PSession.PORT_UNSPECIFIED (0) for unspecified or PORT_ANY (0) for any

• getRemotePort

  public int getRemotePort()

  Remote port.

  Returns:

  Default I2PSession.PORT_UNSPECIFIED (0) or PORT_ANY (0)

• setRemotePort

  public void setRemotePort(int port)

  Must be called to change the port, not set by readPacket() as the port is out-of-band in the I2CP header.

  Parameters:

  port - the remote port to record, I2PSession.PORT_UNSPECIFIED (0) for unspecified or PORT_ANY (0) for any

• writePacket

  public int writePacket(byte[] buffer, int offset) throws IllegalStateException

  Write the packet to the buffer (starting at the offset) and return the number of bytes written.

  Parameters:

  buffer - bytes to write to a destination

  offset - starting point in the buffer to send

  Returns:

  Count actually written

  Throws:

  IllegalStateException - if a required option is missing

• writePacket

  protected int writePacket(byte[] buffer, int offset, int fakeSigLen) throws IllegalStateException

  Write the packet to the buffer, leaving room for a fake signature if requested.

  Parameters:

  buffer - bytes to write to a destination

  offset - starting point in the buffer to send

  fakeSigLen - if 0, include the real signature in _optionSignature; if nonzero, leave space for that many bytes

  Returns:

  the number of bytes written

  Throws:

  IllegalStateException - if a required option is missing

• writtenSize

  int writtenSize(SigType keyType)

  Size of this packet if written to a buffer.

  Parameters:

  keyType - the signing key's type, or null when it is not known yet

  Returns:

  How large the current packet would be the same way writePacket(byte[], int) will write it

• signatureSpaceLen

  int signatureSpaceLen(SigType keyType)

  How many option bytes to reserve for the signature when this packet is written, which is also how many bytes the signature covers.

  For a packet read from the network this is the number of option bytes the signature really occupied. That can be more than the signature length: without a FROM field the type is guessed from the option bytes left over (streaming spec, "Flags and Option Data Fields"), so a sender that padded the signature region makes the region look like a longer signature type. The padding is not signature data, but it is covered by the signature and has to be reproduced for verification to succeed.

  Parameters:

  keyType - the signing key's type, or null when it is not known yet

  Returns:

  option bytes to reserve for the signature, 0 if there is none

• alignSignatureToType

  boolean alignSignatureToType(SigType type)

  Recast the signature to the signing key's type when the bytes we read are long enough to be a signature of that type.

  readPacket(byte[], int, int) cannot know the signature type when the packet carries no FROM field - a stray CLOSE or RESET packet - and guesses it from the option length. That guess is wrong whenever another type shares the length (ECDSA_SHA256_P256 and all the EdDSA types are 64 bytes) and whenever the sender padded the signature region, in which case the signature is the leading type.getSigLen() bytes and the rest is signed padding.

  Parameters:

  type - the signing key's type, non-null

  Returns:

  true if _optionSignature is of that type afterwards, false if the bytes read cannot be a signature of that type

• readPacket

  public void readPacket(byte[] buffer, int offset, int length) throws IllegalArgumentException

  Read the packet from the buffer (starting at the offset) and return the number of bytes read.

  Parameters:

  buffer - packet buffer containing the data

  offset - index into the buffer to start reading

  length - how many bytes within the buffer past the offset are part of the packet?

  Throws:

  IllegalArgumentException - if the buffer is too small for the declared length, or the header is shorter than the minimum

  IndexOutOfBoundsException - if the data ends mid-packet

• verifySignature

  public boolean verifySignature(I2PAppContext ctx, byte[] buffer)

  Determine whether the signature on the data is valid. Packet MUST have a FROM option or will return false.

  Parameters:

  ctx - the context supplying the DSA engine and logger

  buffer - data to validate with signature, or null to use our own buffer.

  Returns:

  true if the signature exists and validates against the data, false otherwise.

• verifySignature

  public boolean verifySignature(I2PAppContext ctx, SigningPublicKey altSPK, byte[] buffer)

  Determine whether the signature on the data is valid.

  Parameters:

  ctx - the context supplying the DSA engine and logger

  altSPK - Signing key to verify with, ONLY if there is no FROM field in this packet. May be the SPK from a FROM field or offline sig field from a previous packet on this connection. Ignored if this packet contains a FROM option block. Null ok if none available.

  buffer - data to validate with signature, or null to use our own buffer.

  Returns:

  true if the signature exists and validates against the data, false otherwise.

• toString

  public String toString()

  String representation of this packet.

  Overrides:

  toString in class Object

• formatAsString

  protected StringBuilder formatAsString()

  Format as a string builder for logging, full form.

  Not gated on the log level: every caller builds this from inside a log message that has already passed its own shouldXxx() test, so gating the description on INFO meant a WARN or ERROR about a packet logged an empty string - the one thing that makes such a message useless. The bulky parts (the NACK list, offline key material) stay behind shouldDebug(). The description is two lines: the header (stream IDs and sequence number), then one " * " continuation line carrying the flags, options and payload size together.

  Returns:

  a buffer holding the human readable form of this packet, ready to be appended to a log message

• formatAsString

  protected StringBuilder formatAsString(boolean withContext)

  Format as a string builder for logging.

  Parameters:

  withContext - when false, omit the facts the caller's own message already carries - the stream-ID header and the sequence number here, the send count and the connection pair in PacketLocal: a caller that leads with the connection prefix must not print them a second time

  Returns:

  a buffer holding the human readable form of this packet, ready to be appended to a log message

• toId

  static final String toId(long id)

  Format a stream ID for display.

  Parameters:

  id - the stream ID to format

  Returns:

  base64-encoded stream ID without trailing '='

• logTCPDump

  public void logTCPDump(Connection con)

  Generate a pcap/tcpdump-compatible format, so we can use standard debugging tools.

  Parameters:

  con - the connection, may be null for unknown connections