Netlib NetLayer

Abstract: This page describes the Java interfaces NetLayer, NetAddress, NetSocket and NetServerSocket of the silvertunnel.org Netlib API.

Introduction

The NetLayer is the general interface to all network and transport layer implementations provided by silvertunnel-ng.org [Netlib]. The common feature of all implementations of NetLayer is to support a bidirectional byte stream. In standard Java the class java.net.Socket provides access to the most relevant network+transport layer combination (TCP/IP). The NetLayer and its related interfaces want to be a more flexible replacement of standard Java sockets.

Main Ideas

• the API provides a common interfaces to the specific protocol and service implementations
• definition of the API using Java interfaces instead of Java classes to avoid unneeded dependencies
  • therefore we don't use the classes java.net.Socket/java.net.ServerSocket in the API
  • access to network connections is very similar to the usage of standard sockets
  • Netlib API's interfaces NetLayer and NetSocket/NetServerSocket can be seen as natural replacement of classes java.net.Socket/java.net.ServerSocket
• several protocols and services are already supported: TCP/IP, TLS/SSL, stream tunneling through the Tor network, socks proxy, transparent logging, ...
  • Netlib NetLayer Implementations page provides a good overview
• separate network protocols/layers are implemented separately, all implementing the NetLayer interface
• network protocols/layers can be combined in a way that the constructor of a NetLayer implementation class can by parameterized by one or more sub-layers
  • this allows easy recombination of multiple NetLayer implementations, e.g.:
    • use LoggingNetLayer to add logging to any NetLayer implementation
    • class TLSNetLayer can be parameterized by TcpipNetLayer, LoggingNetLayer or another layer
  • this can easily be combined with dependency injection

Hint: Here we are not talking about higher layer protocols as for instance as HTTP/HTTPS (see Netlib HTTP for details).

NetLayer

• each separate network protocol/layer implements the NetLayer interface
  • for instance: TcpipNetLayer (TCP/IP), TLSNetLayer (TLS/SSL), TorNetLayer (stream tunneling through the Tor network), SocksNetLayer (socks proxy), LoggingNetLayer (transparent logging)
  • Netlib NetLayer Implementations page provides a good overview

• interface org.silvertunnel.netlib.api.NetLayer definition:

  public interface NetLayer {
  
     /
  
      * Create a client connection.
  
      * Similar to SocketFactory.createSocket()
  
  
  
      * @param localProperties    e.g. property "timeoutInMs"; can also be used to handle a "security profile"; is optional and can be null
  
      * @param localAddress       is optional and can be null
  
      * @param remoteAdress       usually one NetAddress, but can be null for layers without address
  
      * @return a new NetSocket, not null
  
      * 
  
      * @thrown UnsupportedOperationException    if not available or not allowed for this NetLayer instance
  
      * @throws IOException                      in the case of any other error
  
  /
  
      NetSocket createNetSocket(Map<String,Object> localProperties, NetAddress localAddress, NetAddress remoteAddress) throws IOException;
  
  <span class="cm">/**
   * Create a server connection (e.g. a hidden service endpoint).
   * Methods similar to ServerSocketFactory.createServerSocket().
   *
   * @param localProperties       e.g. property "backlog"; can also be used to handle a "security profile"; is optional and can be null
   * @param localListenAddress    usually one NetAddress, but can be null for layers without address
   * @return a new NetServerSocket, not null
   * 
   * @thrown UnsupportedOperationException    if not available or not allowed for this NetLayer instance
   * @throws IOException                      in the case of any other error
   */</span>
  NetServerSocket <span class="nf">createNetServerSocket</span><span class="o">(</span>Map<span class="o"><</span>String<span class="o">,</span>Object<span class="o">></span> properties<span class="o">,</span> NetAddress localListenAddress<span class="o">)</span> <span class="kd">throws</span> IOException<span class="o">;</span>
  
  <span class="cm">/**
   * @return    retrieve the status of the NetLayer - can be used to display it to the user in a proper way
   */</span>
  NetLayerStatus <span class="nf">getStatus</span><span class="o">();</span>
  
  <span class="cm">/**
   * Wait (block the current thread) until this NetLayer instance is up and ready,
   * i.e. wait until this NetLayer is in status NetLayerStatus.READY.
   */</span>
  <span class="kt">void</span> <span class="nf">waitUntilReady</span><span class="o">();</span>
  
  <span class="cm">/**
   * Delete all history information stored in this NetLayer instance.
   * Depending on the implementation, this method can close open Net(Server)Sockets that 
   * 
   * @thrown UnsupportedOperationException    if not available or not allowed for this NetLayer instance
   * @throws IOException                      in the case of any other error
   */</span>
  <span class="kt">void</span> <span class="nf">clear</span><span class="o">()</span> <span class="kd">throws</span> IOException<span class="o">;</span>
  
  <span class="cm">/**
   * @return the NetAddressNameService instance that belongs to this NetLayer instance.
   * 
   * @thrown UnsupportedOperationException    if not available or not allowed for this NetLayer instance
   * @throws IOException                      in the case of any other error
   */</span>
  NetAddressNameService <span class="nf">getNetAddressNameService</span><span class="o">();</span>
  
  
  
  

• interface NetAddressNameService is decribed on an extra page: Netlib NetAddressNameService

• to get an instance of a NetLayer implementation call the constructor or use the NetFactory

NetAddress

• generic address or address part (e.g. IP or transport protocol + port or hostname or test-specific format or public key or ...) for source or destination addresses

• interface org.silvertunnel.netlib.api.NetAddress definition:

  public interface NetAddress {
  
      // yes, it is empty and very generic }
  
  

• most important implementations are:

  • org.silvertunnel.netlib.api.util.IpNetAddress:
    • one IP address address
  • org.silvertunnel.netlib.api.util.TcpipNetAddress:
    • one IP address or hostname + TCP port number
  • org.silvertunnel.netlib.layer.tor.TorHiddenServicePortPrivateNetAddress:
    • all needed to create (the server-side of) one hidden service in the Tor network, inclusive private key, public key and port number

NetSocket

• each NetSocket object represents an open connection of a NetLayer
• this is Netlib's replacement of java.net.Socket

• interface org.silvertunnel.netlib.api.NetSocket definition:

  public interface NetSocket {
  
      InputStream getInputStream() throws IOException;
  
      OutputStream getOutputStream() throws IOException;
  
      void close() throws IOException;
  
  }
  
  

NetServerSocket

• each NetServerSocket object represents a listening server-side port of a NetLayer
• this is Netlib's replacement of java.net.ServerSocket

• interface org.silvertunnel.netlib.api.NetServerSocket definition:

  public interface NetServerSocket {
  
      NetSocket accept() throws IOException;
  
      void close() throws IOException;
  
  }
  
  

• Attention: currently, most NetLayer implementation only support the client-side NetSockets.

---

Top: [Netlib], Next: [Netlib NetLayer Implementations]