Netlib Direct API Usage

Netlib Direct API Usage

Abstract: This page describes how to establish network connections using the Netlib API with NetLayer.

Client-Side Implementation with NetSocket

The typical direct Netlib API usage means using NetLayer to establish network connections. It works as follows:

• clarify the remote address

      // define remote address
  
      String remoteHostname = "httptest.silvertunnel.org";
  
      int remotePort = 80;
  
      TcpipNetAddress remoteAddress = new TcpipNetAddress(remoteHostname, remotePort);
  
  

• get a NetLayer implementation instance:

      // get TorNetLayer instance and wait until it is ready
  
      NetLayer netLayer = NetFactory.getInstance().getNetLayerById(NetLayerIDs.TOR);
  
      netLayer.waitUntilReady();
  
  

• connect to the remote address, get a NetSocket that represents the connection:

      // open connection to remote address - this connection is tunneled through the TOR anonymity network
  
      NetSocket netSocket = netLayer.createNetSocket(null, null, remoteAddress);
  
  

• send and receive data by writing data to an OutputStream and reading data from an InputStream:

      // send and receive data
  
      // hint: to avoid dead locks: use separate threads for each direction
  
      OutputStream os = netSocket.getOutputStream();
  
      InputStream is = netSocket.getInputStream();
  
      // ... 
  
  

• close the connection:

      // close connection
  
      // hint: this should be done in a finally block
  
      netSocket.close();
  
  

Server-Side Implementation with NetServerSocket

The typical direct [Netlib API] usage means using NetLayer to establish network connections. It works as follows:

• clarify the local listen address

  • for a Tor hidden server (which we use here as example) the local listen address comprises the private+public hidden service key and the listen port number

    • create a new private+public hidden service key and save it to the file system (only needed for first start of the service):

          // create new private+public hidden service key
      
          TorNetLayerUtil torNetLayerUtil = torNetLayerUtil.getInstance()
      
          TorHiddenServicePrivateNetAddress newNetAddress = torNetLayerUtil.createNewTorHiddenServicePrivateNetAddress();
      
      // write new private+public hidden service key to directory
      File directory = new File("/dir/to/the/hidden/service"); 
      directory.mkdir();
      torNetLayerUtil.writeTorHiddenServicePrivateNetAddressToFiles(directory, newNetAddress);
      
      
      
      

    • read an existing private+public hidden service key from file system and define listing port:

          // read private+public hidden service key from directory
      
          TorHiddenServicePrivateNetAddress netAddress = torNetLayerUtil.readTorHiddenServicePrivateNetAddressFromFiles(directory, true);
      
      // define local listening address inclusive port
      int port = 80;
      TorHiddenServicePortPrivateNetAddress netAddressWithPort =
          new TorHiddenServicePortPrivateNetAddress(netAddress, port);
      
      
      
      

• get a [NetLayer implementation] instance:

      // get TorNetLayer instance and wait until it is ready
  
      NetLayer netLayer = NetFactory.getInstance().getNetLayerById(NetLayerIDs.TOR);
  
      netLayer.waitUntilReady();
  
  

• create a listening socket, i.e. create/publish the hidden service

      TorNetServerSocket netServerSocket = (TorNetServerSocket)torNetLayer.createNetServerSocket(null, netAddressWithPort);
  
  

• now wait for incoming connections (same as with java.net.ServerSocket)

      while (true) {
  
          final NetSocket netSocket = netServerSocket.accept();
  
  

• each incoming connection should be handled in an own thread to avoid congestion (same as with java.net.ServerSocket):

          // handle the new connection in an extra thread
  
          new Thread() {
  
              @Override
  
              public void run() {
  
                  try {
  
                      // receive data (e.g. HTTP request) and send data (e.g. HTTP response)
  
                      // hint: to avoid dead locks: use separate threads for each direction
  
                      InputStream is = netSocket.getInputStream();
  
                      OutputStream os = netSocket.getOutputStream();
  
                      // ... 
  
              } catch (Exception e) {
                  ...
              } finally {
                  netSocket.close();
              }
          }
      }.start();
  }
  
  
  
  

• the example should be extended by exception handling and finally block to close the netServerSocket

More Examples

See:

• NetlibTcpIpUsageExamplesRemoteTest.java to find examples for plain TCP/IP connection and for TCP/IP streams tunneled through the Tor anonymity network.
• TorHiddenServiceServerRemoteTest.java to find examples how to public and how to consume Tor hidden services

Alternatives

If you want to handle HTTP network connections alternatives to direct API usage allow simpler usage. Consider using [Netlib HTTP].

---

Top: [Netlib], Up: [Netlib Tools], Next: [Netlib HTTP]