Package org.microproxy

Interface MitmManager

All Known Implementing Classes:
CertificateAuthorityMitmManager
public interface MitmManager
Enables man-in-the-middle interception of CONNECT tunnels. The proxy opens its own TLS connection to the server, then completes the client's handshake with a certificate supplied here, and finally proxies the decrypted requests through the normal HttpFilters.

The proxy calls the overloads that take a FlowContext; by default they delegate to the ones without it. Override them to decide per client connection (by its authenticated user, FlowContext.getClientDetails(), or its address, FlowContext.getClientAddress()) which CA impersonates servers, how servers are validated, or which client certificate is presented to them. To keep a separate manager per tenant instead, see perConnection(java.util.function.Function<? super org.microproxy.FlowContext, ? extends org.microproxy.MitmManager>).

With HttpProxyServerBootstrap.withPoolSharedMitmConnections(boolean), a server connection made for one client may serve another. A manager that overrides serverSslContext(String, int, FlowContext) or configureServerSocket(SSLSocket, FlowContext) may make different decisions for different clients, so its server connections are kept per client connection rather than pooled; managers chosen by forConnection(org.microproxy.FlowContext) only share pooled connections with clients that were given the same manager.

See Also:

  • Method Details

    • serverSslContext

      SSLContext serverSslContext(String peerHost, int peerPort)
      TLS configuration for the proxy's connection to the real server (proxy is TLS client).
      Parameters:
      peerHost - the real server host name
      peerPort - the real server port
      Returns:
      the TLS context used towards the real server

    • serverSslContext

      default SSLContext serverSslContext(String peerHost, int peerPort, FlowContext flow)
      TLS configuration for the proxy's connection to the real server, for the client connection flow: the trust store servers are validated against, and the key the proxy authenticates with when a server asks for a client certificate. Defaults to serverSslContext(String, int).
      Parameters:
      peerHost - the real server host name
      peerPort - the real server port
      flow - a FullFlowContext naming the server and the chained proxy, if any
      Returns:
      the TLS context used towards the real server

    • serverTrustManager

      default X509TrustManager serverTrustManager(String peerHost, int peerPort, FlowContext flow)
      How servers are validated where the proxy's TLS is not the JDK's: on QUIC connections to HTTP/3 servers (HttpProxyServerBootstrap.withHttp3Upstream(boolean)). The default is the trust manager of serverSslContext(String, int, FlowContext) when that context came from SslContexts (as CertificateAuthorityMitmManager's do), and null otherwise, which keeps the server on TCP, where the context applies. Server names are checked as HTTPS does, unless the trust manager trusts every server (SslContexts.trustAll()).
      Parameters:
      peerHost - the real server host name
      peerPort - the real server port
      flow - a FullFlowContext naming the server
      Returns:
      the trust manager, or null to keep the server on TCP

    • clientSslContextFor

      SSLContext clientSslContextFor(HttpRequest connectRequest, SSLSession serverSslSession)
      TLS configuration presented to the client (proxy is TLS server), typically holding a certificate for the requested host signed by a CA the client trusts.
      Parameters:
      connectRequest - the client's CONNECT request
      serverSslSession - the established session with the real server
      Returns:
      the TLS context presented to the client

    • clientSslContextFor

      default SSLContext clientSslContextFor(HttpRequest connectRequest, SSLSession serverSslSession, FlowContext flow)
      TLS configuration presented to the client connection flow, e.g. with a certificate from that client's CA. Defaults to clientSslContextFor(HttpRequest, SSLSession).
      Parameters:
      connectRequest - the CONNECT request naming the server
      serverSslSession - the established session with the real server, or null when intercepting without one (HttpFilters.proxyToServerAllowOfflineMitm())
      flow - the client connection's context
      Returns:
      the TLS context presented to the client

    • configureServerSocket

      default void configureServerSocket(SSLSocket socket)
      Customizes the socket to the real server before its handshake. By default the proxy enables SNI and HTTPS host-name verification; override to relax that.
      Parameters:
      socket - the TLS socket to configure

    • configureServerSocket

      default void configureServerSocket(SSLSocket socket, FlowContext flow)
      Customizes the socket to the real server for the client connection flow. Defaults to configureServerSocket(SSLSocket).
      Parameters:
      socket - the TLS socket to configure
      flow - a FullFlowContext naming the server and the chained proxy, if any

    • shouldIntercept

      default boolean shouldIntercept(ClientHello clientHello, FlowContext flow)
      Whether to intercept a TLS connection, once its client's ClientHello is known: return false to tunnel it untouched, so the client sees the real server's certificate. Decide by the server name the client asked for (ClientHello.sni()), its ALPN protocols, or the client (flow). Called on the manager chosen for the connection (forConnection(org.microproxy.FlowContext)), after the host rules (HttpProxyServerBootstrap.withIgnoreHosts(java.lang.String...), HttpProxyServerBootstrap.withAllowHosts(java.lang.String...)) and before HttpFilters.proxyToServerAllowMitm(ClientHello). True by default.
      Parameters:
      clientHello - the client's ClientHello
      flow - the client connection's context; FlowContext.getClientHello() returns clientHello
      Returns:
      whether to intercept the connection

    • forConnection

      default MitmManager forConnection(FlowContext flow)
      The manager that intercepts for the client connection flow; this one by default. The proxy asks once per client connection, when it is about to intercept the connection's first CONNECT (after proxy authentication, so the user is known), and uses the answer for every interception on that connection. null declines: the connection's CONNECTs are tunnelled without interception.
      Parameters:
      flow - the client connection or exchange context
      Returns:
      the manager to use for this client connection

    • perConnection

      static MitmManager perConnection(Function<? super FlowContext,? extends MitmManager> choose)
      A manager that lets choose pick the manager for each client connection (see forConnection(org.microproxy.FlowContext)), e.g. a CertificateAuthorityMitmManager per tenant with its own CA and upstream trust store. Return the same instance for clients that may share pooled server connections; a null answer declines interception.

      The returned manager only selects: its own methods throw UnsupportedOperationException.

      Parameters:
      choose - the function selecting a manager for each client connection
      Returns:
      the manager delegating selection to choose