Package net.i2p.router.transport.udp

Class PacketBuilder

java.lang.Object
net.i2p.router.transport.udp.PacketBuilder
class PacketBuilder extends Object
Big ol' class to do all our packet formatting. The UDPPackets generated are fully authenticated, encrypted, and configured for delivery to the peer. The following is from udp.html on the website:

All UDP datagrams begin with a 16 byte MAC (Message Authentication Code) and a 16 byte IV (Initialization Vector followed by a variable size payload encrypted with the appropriate key. The MAC used is HMAC-MD5, truncated to 16 bytes, while the key is a full 32 byte AES256 key. The specific construct of the MAC is the first 16 bytes from:

  HMAC-MD5(payload || IV || (payloadLength ^ protocolVersion), macKey)

The protocol version is currently 0.

The payload itself is AES256/CBC encrypted with the IV and the sessionKey, with replay prevention addressed within its body, explained below. The payloadLength in the MAC is a 2 byte unsigned integer in 2s complement.

The protocolVersion is a 2 byte unsigned integer in 2s complement, and currently set to 0. Peers using a different protocol version will not be able to communicate with this peer, though earlier versions not using this flag are.

Payload

Within the AES encrypted payload, there is a minimal common structure to the various messages - a one byte flag and a four byte sending timestamp (*seconds* since the unix epoch). The flag byte contains the following bitfields:

Bit order: 76543210
  bits 7-4: payload type
     bit 3: rekey?
     bit 2: extended options included
  bits 1-0: reserved

If the rekey flag is set, 64 bytes of keying material follow the timestamp. If the extended options flag is set, a one byte option size value is appended to, followed by that many extended option bytes, which are currently uninterpreted.

When rekeying, the first 32 bytes of the keying material is fed into a SHA256 to produce the new MAC key, and the next 32 bytes are fed into a SHA256 to produce the new session key, though the keys are not immediately used. The other side should also reply with the rekey flag set and that same keying material. Once both sides have sent and received those values, the new keys should be used and the previous keys discarded. It may be useful to keep the old keys around briefly, to address packet loss and reordering.

NOTE: Rekeying is currently unimplemented.

 Header: 37+ bytes
 +----+----+----+----+----+----+----+----+
 |                  MAC                  |
 |                                       |
 +----+----+----+----+----+----+----+----+
 |                   IV                  |
 |                                       |
 +----+----+----+----+----+----+----+----+
 |flag|        time       | (optionally  |
 +----+----+----+----+----+              |
 | this may have 64 byte keying material |
 | and/or a one+N byte extended options) |
 +---------------------------------------|

  • Field Details

  • Constructor Details

    • PacketBuilder

      public PacketBuilder(RouterContext ctx, UDPTransport transport)
      No state, all methods are thread-safe.
      Parameters:
      transport - may be null for unit testing only

  • Method Details

    • getMaxAdditionalFragmentSize

      public static int getMaxAdditionalFragmentSize(PeerState peer, int numFragments, int curDataSize)
      Will a packet to 'peer' that already has 'numFragments' fragments totalling 'curDataSize' bytes fit another fragment of size 'newFragSize' ?? This doesn't leave anything for acks.
      Parameters:
      numFragments - >= 1
      Since:
      0.9.16

    • buildPacket

      public UDPPacket buildPacket(OutboundMessageState state, int fragment, PeerState peer, Collection<Long> ackIdsRemaining, int newAckCount, List<ACKBitfield> partialACKsRemaining)
      This builds a data packet (PAYLOAD_TYPE_DATA). See the methods below for the other message types. Note that while the UDP message spec allows for more than one fragment in a message, this method writes exactly one fragment. For no fragments use buildAck(). Multiple fragments in a single packet is not supported. Rekeying and extended options are not supported. Packet format: 
          16 byte MAC
    16 byte IV
     1 byte flag
     4 byte date
     1 byte flag
     1 byte explicit ack count IF included
   4*n byte explict acks IF included
     1 byte ack bitfield count IF included
   4*n + ?? ack bitfields IF included
     1 byte fragment count (always 1)
     4 byte message ID
     3 byte fragment info
     n byte fragment
  0-15 bytes padding
      So ignoring the ack bitfields, and assuming we have explicit acks, it's (47 + 4*explict acks + padding) added to the fragment length.
      Parameters:
      ackIdsRemaining - list of messageIds (Long) that should be acked by this packet. The list itself is passed by reference, and if a messageId is transmitted it will be removed from the list. Not all message IDs will necessarily be sent, there may not be room. non-null.
      newAckCount - the number of ackIdsRemaining entries that are new. These must be the first ones in the list
      partialACKsRemaining - list of messageIds (ACKBitfield) that should be acked by this packet. The list itself is passed by reference, and if a messageId is included, it should be removed from the list. Full acks in this list are skipped, they are NOT transmitted. non-null. Not all acks will necessarily be sent, there may not be room.
      Returns:
      null on error

    • buildPacket

      public UDPPacket buildPacket(List<PacketBuilder.Fragment> fragments, PeerState peer, Collection<Long> ackIdsRemaining, int newAckCount, List<ACKBitfield> partialACKsRemaining)

    • buildPing

      public UDPPacket buildPing(PeerState peer)
      An ACK packet with no acks. We use this for keepalive purposes. It doesn't generate a reply, but that's ok.

    • buildACK

      public UDPPacket buildACK(PeerState peer, List<ACKBitfield> ackBitfields)
      Build the ack packet. The list need not be sorted into full and partial; this method will put all fulls before the partials in the outgoing packet. An ack packet is just a data packet with no data. See buildPacket() for format. TODO MTU not enforced. TODO handle huge number of acks better
      Parameters:
      ackBitfields - list of ACKBitfield instances to either fully or partially ACK

    • buildSessionCreatedPacket

      public UDPPacket buildSessionCreatedPacket(InboundEstablishState state, int externalPort, SessionKey ourIntroKey)
      Build a new SessionCreated packet for the given peer, encrypting it as necessary.
      Returns:
      ready to send packet, or null if there was a problem

    • buildSessionRequestPacket

      public UDPPacket buildSessionRequestPacket(OutboundEstablishState state)
      Build a new SessionRequest packet for the given peer, encrypting it as necessary.
      Returns:
      ready to send packet, or null if there was a problem

    • buildSessionConfirmedPackets

      public UDPPacket[] buildSessionConfirmedPackets(OutboundEstablishState state, RouterIdentity ourIdentity)
      Build a new series of SessionConfirmed packets for the given peer, encrypting it as necessary. Note that while a SessionConfirmed could in theory be fragmented, in practice a RouterIdentity is 387 bytes and a single fragment is 512 bytes max, so it will never be fragmented.
      Returns:
      ready to send packets, or null if there was a problem TODO: doesn't really return null, and caller doesn't handle null return (null SigningPrivateKey should cause this?) Should probably return null if buildSessionConfirmedPacket() returns null for any fragment

    • buildSessionDestroyPacket

      public UDPPacket buildSessionDestroyPacket(PeerState peer)
      Build a destroy packet, which contains a header but no body. Session must be established or this will NPE in authenticate(). Unused until 0.8.9.
      Since:
      0.8.1

    • buildSessionDestroyPacket

      public UDPPacket buildSessionDestroyPacket(OutboundEstablishState peer)
      Build a destroy packet, which contains a header but no body. If the keys and ip/port are not yet set, this will return null.
      Returns:
      packet or null
      Since:
      0.9.2

    • buildSessionDestroyPacket

      public UDPPacket buildSessionDestroyPacket(InboundEstablishState peer)
      Build a destroy packet, which contains a header but no body. If the keys and ip/port are not yet set, this will return null.
      Returns:
      packet or null
      Since:
      0.9.2

    • buildPeerTestFromAlice

      public UDPPacket buildPeerTestFromAlice(InetAddress toIP, int toPort, SessionKey toIntroKey, long nonce, SessionKey aliceIntroKey)
      Build a packet as if we are Alice and we either want Bob to begin a peer test or Charlie to finish a peer test.
      Returns:
      ready to send packet, or null if there was a problem

    • buildPeerTestFromAlice

      public UDPPacket buildPeerTestFromAlice(InetAddress toIP, int toPort, SessionKey toCipherKey, SessionKey toMACKey, long nonce, SessionKey aliceIntroKey)
      Build a packet as if we are Alice and we either want Bob to begin a peer test or Charlie to finish a peer test.
      Returns:
      ready to send packet, or null if there was a problem

    • buildPeerTestToAlice

      public UDPPacket buildPeerTestToAlice(InetAddress aliceIP, int alicePort, SessionKey aliceIntroKey, SessionKey charlieIntroKey, long nonce)
      Build a packet as if we are either Bob or Charlie and we are helping test Alice. Not for use as Bob, as of 0.9.52; use in-session cipher/mac keys instead.
      Returns:
      ready to send packet, or null if there was a problem

    • buildPeerTestToAlice

      public UDPPacket buildPeerTestToAlice(InetAddress aliceIP, int alicePort, SessionKey aliceCipherKey, SessionKey aliceMACKey, SessionKey charlieIntroKey, long nonce)
      Build a packet as if we are either Bob or Charlie and we are helping test Alice.
      Parameters:
      aliceCipherKey - the intro key if we are Charlie
      aliceMACKey - the intro key if we are Charlie
      Returns:
      ready to send packet, or null if there was a problem
      Since:
      0.9.52

    • buildPeerTestToCharlie

      public UDPPacket buildPeerTestToCharlie(InetAddress aliceIP, int alicePort, SessionKey aliceIntroKey, long nonce, InetAddress charlieIP, int charliePort, SessionKey charlieCipherKey, SessionKey charlieMACKey)
      Build a packet as if we are Bob sending Charlie a packet to help test Alice.
      Returns:
      ready to send packet, or null if there was a problem

    • buildPeerTestToBob

      public UDPPacket buildPeerTestToBob(InetAddress bobIP, int bobPort, InetAddress aliceIP, int alicePort, SessionKey aliceIntroKey, long nonce, SessionKey bobCipherKey, SessionKey bobMACKey)
      Build a packet as if we are Charlie sending Bob a packet verifying that we will help test Alice.
      Returns:
      ready to send packet, or null if there was a problem

    • buildRelayRequest

      public List<UDPPacket> buildRelayRequest(UDPTransport transport, EstablishmentManager emgr, OutboundEstablishState state, SessionKey ourIntroKey)
      build intro packets for each of the published introducers
      Parameters:
      emgr - only to call emgr.isValid()
      Returns:
      empty list on failure

    • buildRelayIntro

      UDPPacket buildRelayIntro(RemoteHostId alice, PeerState charlie, UDPPacketReader.RelayRequestReader request)

    • buildRelayResponse

      UDPPacket buildRelayResponse(RemoteHostId alice, PeerState charlie, long nonce, SessionKey cipherKey, SessionKey macKey)

    • buildHolePunch

      public UDPPacket buildHolePunch(InetAddress to, int port)
      Creates an empty unauthenticated packet for hole punching. Parameters must be validated previously.

    • buildPacket

      public UDPPacket buildPacket(byte[] data, InetAddress to, int port)
      TESTING ONLY. Creates an arbitrary packet for unit testing. Null transport in constructor OK.
      Since:
      IPv6