net.i2p.router.transport.udp

## Class EstablishmentManager

- java.lang.Object
- - net.i2p.router.transport.udp.EstablishmentManager

-     class EstablishmentManager
      extends Object

  Coordinate the establishment of new sessions - both inbound and outbound. This has its own thread to add packets to the packet queue when necessary, as well as to drop any failed establishment attempts.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `EstablishmentManager.Token` Token used for SSU2 session establishment and validation.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static long` | `IB_TOKEN_EXPIRATION`
    `static int` | `MAX_IB_ESTABLISH_TIME` Kill any inbound that takes more than this One round trip (Created-Confirmed) Note: could be two round trips for SSU2 with retry
    `static int` | `MAX_IB_ESTABLISH_TIME_ATTACK`
    `static long` | `MAX_TAG_VALUE` the relay tag is a 4-byte field in the protocol
    `static int` | `OB_MESSAGE_TIMEOUT` Max wait before receiving a response to a single message during outbound establishment

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `EstablishmentManager(RouterContext ctx, UDPTransport transport)`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addOutboundToken(RemoteHostId peer, long token, long expires)` Remember a token that can be used later to connect to the peer
    `void` | `establish(OutNetMessage msg)` Send the message to its specified recipient by establishing a connection with them and sending it off.
    `(package private) InboundEstablishState` | `getInboundState(RemoteHostId from)` Grab the active establishing state
    `EstablishmentManager.Token` | `getInboundToken(RemoteHostId peer)` Get a token that can be used later for the peer to connect to us
    `EstablishmentManager.Token` | `getInboundToken(RemoteHostId peer, long expiration)` Get a token that can be used later for the peer to connect to us.
    `DatabaseStoreMessage` | `getOurInfo()` A database store message with our router info
    `(package private) OutboundEstablishState` | `getOutboundState(RemoteHostId from)` Grab the active establishing state
    `long` | `getOutboundToken(RemoteHostId peer)` Get a token to connect to the peer
    `void` | `ipChanged(boolean isIPv6)` Remove our tokens for this length
    `boolean` | `isInboundTokenValid(RemoteHostId peer, long token)` Is the token from this peer valid?
    `(package private) boolean` | `isValid(byte[] ip, int port)` Are IP and port valid? This is only for checking the relay response.
    `static String` | `parseReason(int reasonCode)`
    `void` | `portChanged()` Remove all tokens
    `(package private) PeerState` | `receiveData(OutboundEstablishState state)` A data packet arrived on an outbound connection being established, which means its complete (yay!).
    `(package private) void` | `receiveHolePunch(RemoteHostId id, UDPPacket packet)` Called from PacketHandler.
    `(package private) void` | `receiveRelayResponse(PeerState2 bob, long nonce, int code, byte[] data)` We are Alice, we sent a RelayRequest to Bob and got a RelayResponse back.
    `(package private) void` | `receiveRetry(OutboundEstablishState2 state, UDPPacket packet)` Got a Retry (in response to our outbound SessionRequest or TokenRequest) SSU 2 only.
    `(package private) void` | `receiveSessionConfirmed(InboundEstablishState2 state, UDPPacket packet)` got a SessionConfirmed (should only happen as part of an inbound establishment) SSU 2 only.
    `(package private) void` | `receiveSessionCreated(OutboundEstablishState2 state, UDPPacket packet)` Got a SessionCreated (in response to our outbound SessionRequest) SSU 2 only.
    `(package private) void` | `receiveSessionDestroy(RemoteHostId from)` Got a SessionDestroy - maybe during an inbound establish? TODO - PacketHandler won't look up inbound establishes As this packet was essentially unauthenticated (i.e.
    `(package private) void` | `receiveSessionDestroy(RemoteHostId from, OutboundEstablishState state)` Got a SessionDestroy during outbound establish SSU 2
    `(package private) void` | `receiveSessionDestroy(RemoteHostId from, PeerState state)` Got a SessionDestroy on an established conn SSU 2
    `(package private) void` | `receiveSessionOrTokenRequest(RemoteHostId from, InboundEstablishState2 state, UDPPacket packet)` Got a SessionRequest OR a TokenRequest (initiates an inbound establishment) SSU 2 only.
    `boolean` | `shouldAllowInboundEstablishment()` Should we allow another inbound establishment?
    `void` | `shutdown()`
    `void` | `startup()`
    `(package private) void` | `trackSSU2CorruptSessionConfirmed(RemoteHostId hostId)` Track SSU2 corrupt SessionConfirmed and auto-ban repeat offenders.
    `(package private) void` | `trackSSU2EstablishFailure(RemoteHostId hostId)` Track SSU2 establishment failures and auto-ban repeat offenders.

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

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### IB_TOKEN_EXPIRATION

          public static final long IB_TOKEN_EXPIRATION

      See Also:
        Constant Field Values

    - #### MAX_IB_ESTABLISH_TIME

          public static final int MAX_IB_ESTABLISH_TIME

      Kill any inbound that takes more than this One round trip (Created-Confirmed) Note: could be two round trips for SSU2 with retry

    - #### MAX_IB_ESTABLISH_TIME_ATTACK

          public static final int MAX_IB_ESTABLISH_TIME_ATTACK

    - #### MAX_TAG_VALUE

          public static final long MAX_TAG_VALUE

      the relay tag is a 4-byte field in the protocol
      See Also:
        Constant Field Values

    - #### OB_MESSAGE_TIMEOUT

          public static final int OB_MESSAGE_TIMEOUT

      Max wait before receiving a response to a single message during outbound establishment
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### EstablishmentManager

          public EstablishmentManager(RouterContext ctx,
                                      UDPTransport transport)

  - ### Method Detail

    - #### addOutboundToken

          public void addOutboundToken(RemoteHostId peer,
                                       long token,
                                       long expires)

      Remember a token that can be used later to connect to the peer
      Parameters:
        `token` - nonzero
        `expires` - absolute time

    - #### establish

          public void establish(OutNetMessage msg)

      Send the message to its specified recipient by establishing a connection with them and sending it off. This call does not block, and on failure, the message is failed. Note - if we go back to multiple PacketHandler threads, this may need more locking.

    - #### getInboundState

          InboundEstablishState getInboundState(RemoteHostId from)

      Grab the active establishing state
      Returns:
        null if none

    - #### getInboundToken

          public EstablishmentManager.Token getInboundToken(RemoteHostId peer)

      Get a token that can be used later for the peer to connect to us

    - #### getInboundToken

          public EstablishmentManager.Token getInboundToken(RemoteHostId peer,
                                                            long expiration)

      Get a token that can be used later for the peer to connect to us.
      Parameters:
        `expiration` - time from now, will be reduced if necessary based on cache eviction time.
      Returns:
        non-null

    - #### getOurInfo

          public DatabaseStoreMessage getOurInfo()

      A database store message with our router info
      Returns:
        non-null

    - #### getOutboundState

          OutboundEstablishState getOutboundState(RemoteHostId from)

      Grab the active establishing state
      Returns:
        null if none

    - #### getOutboundToken

          public long getOutboundToken(RemoteHostId peer)

      Get a token to connect to the peer
      Returns:
        0 if none available

    - #### ipChanged

          public void ipChanged(boolean isIPv6)

      Remove our tokens for this length

    - #### isInboundTokenValid

          public boolean isInboundTokenValid(RemoteHostId peer,
                                             long token)

      Is the token from this peer valid?
      Returns:
        valid

    - #### isValid

          boolean isValid(byte[] ip,
                          int port)

      Are IP and port valid? This is only for checking the relay response. Allow IPv6 as of 0.9.50. Refuse anybody in the same /16

    - #### parseReason

          public static String parseReason(int reasonCode)

    - #### portChanged

          public void portChanged()

      Remove all tokens

    - #### receiveData

          PeerState receiveData(OutboundEstablishState state)

      A data packet arrived on an outbound connection being established, which means its complete (yay!). This is a blocking call, more than I'd like...
      Returns:
        the new PeerState

    - #### receiveHolePunch

          void receiveHolePunch(RemoteHostId id,
                                UDPPacket packet)

      Called from PacketHandler. Accelerate response to RelayResponse if we haven't sent it yet. SSU 2 only.
      Parameters:
        `id` - non-null
        `packet` - header already decrypted

    - #### receiveRelayResponse

          void receiveRelayResponse(PeerState2 bob,
                                    long nonce,
                                    int code,
                                    byte[] data)

      We are Alice, we sent a RelayRequest to Bob and got a RelayResponse back. Time and version already checked by caller. SSU 2 only.
      Parameters:
        `data` - including nonce, including token if code == 0

    - #### receiveRetry

          void receiveRetry(OutboundEstablishState2 state,
                            UDPPacket packet)

      Got a Retry (in response to our outbound SessionRequest or TokenRequest) SSU 2 only.

    - #### receiveSessionConfirmed

          void receiveSessionConfirmed(InboundEstablishState2 state,
                                       UDPPacket packet)

      got a SessionConfirmed (should only happen as part of an inbound establishment) SSU 2 only.
      Parameters:
        `state` - non-null
        `packet` - header decrypted only

    - #### receiveSessionCreated

          void receiveSessionCreated(OutboundEstablishState2 state,
                                     UDPPacket packet)

      Got a SessionCreated (in response to our outbound SessionRequest) SSU 2 only.
      Parameters:
        `state` - non-null
        `packet` - header decrypted only

    - #### receiveSessionDestroy

          void receiveSessionDestroy(RemoteHostId from)

      Got a SessionDestroy - maybe during an inbound establish? TODO - PacketHandler won't look up inbound establishes As this packet was essentially unauthenticated (i.e. intro key, not session key) we just log it as it could be spoofed. SSU 2

    - #### receiveSessionDestroy

          void receiveSessionDestroy(RemoteHostId from,
                                     OutboundEstablishState state)

      Got a SessionDestroy during outbound establish SSU 2

    - #### receiveSessionDestroy

          void receiveSessionDestroy(RemoteHostId from,
                                     PeerState state)

      Got a SessionDestroy on an established conn SSU 2

    - #### receiveSessionOrTokenRequest

          void receiveSessionOrTokenRequest(RemoteHostId from,
                                            InboundEstablishState2 state,
                                            UDPPacket packet)

      Got a SessionRequest OR a TokenRequest (initiates an inbound establishment) SSU 2 only.
      Parameters:
        `state` - as looked up in PacketHandler, but null unless retransmitted or retry sent
        `packet` - header decrypted only

    - #### shouldAllowInboundEstablishment

          public boolean shouldAllowInboundEstablishment()

      Should we allow another inbound establishment?

    - #### shutdown

          public void shutdown()

    - #### startup

          public void startup()

    - #### trackSSU2CorruptSessionConfirmed

          void trackSSU2CorruptSessionConfirmed(RemoteHostId hostId)

      Track SSU2 corrupt SessionConfirmed and auto-ban repeat offenders.

    - #### trackSSU2EstablishFailure

          void trackSSU2EstablishFailure(RemoteHostId hostId)

      Track SSU2 establishment failures and auto-ban repeat offenders.