Install Libraries

  Make sure that the run-time and development files for the following
  libraries are installed:
    - openssl
    - vanessa_logger 0.0.5 or newer
    - vanessa_socket 0.0.4 or newer
    - vanessa_adt 0.0.6 or newer

  For Debian the vanessa libraries are part of the distribution.
  For other distributions, go to www.vergenet.net/linux/vanessa/

Build and Install Kernel

  A patch is provided for the 2.4.21-27.0.2.EL kernel
  from Red Hat enterprise Linux 3.0
  Make sure kernel is 2.4.22 or a later 2.4 kernel which
  includes the kernel-crypto code.

  Apply patch/linux-2.4.21-27.0.2.EL-crypto_cpy.patch
  from the kssl source tree to the kernel.
  cd linux-2.4.21/
  patch -p1 < ../kssl-0.1.0/patches/linux-2.4.21-27.0.2.EL-crypto_cpy.patch

  There are a few different versions of the patch in the
  patches directory for versions of the kernel from kernel.org.
  For Kernel.Org kernsl, make sure you have at least version 2.4.22, 
  as versions prior to this do not include the kernel-crypto API.

  Make sure kernel-crypto is compiled in 
    - it is safe to compile all the crypo algorithms as modules.

  Configure, build and install the kernel

Build and install kssl

  Locate kernel souce tree, e.g. /usr/src/linux-2.4.21

  In the kssl source tree
  make KERNELSOURCE=/usr/src/linux-2.4.21

Run kssld

  A sample script is provided to start up KSSLD.
  This can be run from the KSSL source tree.

  ./kssld/kssld_start.software

  This assumes that a service is listening on 127.0.0.1 port 80.
  Edit the script to change this.

  The script will generate an RSA key and certificate pair the first time
  that it is run. You can update these by replacing
  ./key_tool/pem/key.rsa.pem and ./key_tool/pem/cert.rsa.pem respectively.
  Alternatively you can remove them and re-run ./kssld/kssld_start.software
  to generate a new key and certificate pair.

  The script then inserts various modules and runs ./key_tool/kssl_key_tool
  to configure the server. For more details please inspect ./kssld/kssld_start

  A separate script, ./kssld/kssld_start.aep_user} is provided
  to configure KSSLD to use the AEP~1000. You should read
  INSTALL.aep, which is found in the KSSL source tree, before
  using kssld_start.aep_user.

Configuring KSSL Using kssl_key_tool

  You can change the configuration of KSSLD on the fly using
  ./key_tool/kssl_key_tool.

  REAL_SERVER and VIRTUAL_SERVER are of the form:
    IP_ADDRESS|HOSTNAME:PORT_NUMBER|PORT_NAME
    e.g. 172.16.4.222:443
          tabatha.lab.ultramonkey.org:https

Get Daemons

  List all the configured daemons

kssl_key_tool get daemons


Flush Daemons

  Delete all of the configured daemons, closing all active connections

kssl_key_tool set flush


Add Daemon

   Create a daemon in the stopped state

kssl_key_tool set add_daemon VIRTUAL_SERVER


Delete Daemon

   Delete a daemon, closing any active connections

kssl_key_tool set del_daemon VIRTUAL_SERVER


Set RSA

  Set the RSA key and certificate pair to use. Input must be in PEM format.
 
kssl_key_tool set rsa VIRTUAL_SERVER RSA_KEY_FILE RSA_CERTIFICATE_FILE


Get RSA

  Get the RSA key and certificate pair to use. Output will be in PEM format.

kssl_key_tool get rsa VIRTUAL_SERVER RSA_KEY_FILE RSA_CERTIFICATE_FILE


Set the Real Server

  Set the IP address and Port to open plain-text connections to.
  Typically this will be a web server running either on the localhost
  (127.0.0.1) or some other host.

kssl_key_tool set real VIRTUAL_SERVER IP_ADDRESS|HOSTNAME PORT_NUMBER|PORT_NAME


Get the Real Server

kssl_key_tool get real


Set Ciphers

  Set the cipher suites that will be accepted.
  This is a comma (,) delimited list in order of preference.

kssl_key_tool set ciphers VIRTUAL_SERVER CIPHER[,CIPHER...]


Get Ciphers

  List the ciphers that are currently being accepted.

kssl_key_tool get ciphers VIRTUAL_SERVER


Get Available Ciphers

  List the cipher suites that are supported by the daemon.
  These are as per the SSL/TLS standard. Please
  see "SSL and TLS" by Eric Rescorla for more information.

kssl_key_tool get available_ciphers


Set Daemon Mode

   Set the mode that the server is currently operating in.

   start      Server is running, accepting and processing connections.

   stop       The server is not running, no connections will be accepted.
              Existing connections, if any will be closed.
              This is the default state.

   quiescent  No new connections will be accepted.
              Existing connections will be processed.

kssl_key_tool set mode VIRTUAL_SERVER start|stop|quiescent

  If this command is run for a virtual-server that does not exist
  it will be created. There is currently no way to delete a virtual-server.

Get Daemon Mode

  Show the mode that the server is currently operating in.

kssl_key_tool get mode VIRTUAL_SERVER


Set Asymmetric Encryption Methods

  Set the list of asymmetric encryption (RSA) methods that are currently in
  use.  This is a comma (,) delimited list. The methods will be tried in
  order. That is if one fails, then the next will be tried until one succeeds
  or there are none left. In this way the server can be configured to try
  hardware-accelerated encryption and then software if it doesn't work
  (because there is no accelerator card in the machine).

kssl_key_tool set asym_methods VIRTUAL_SERVER METHOD[,METHOD...]


Get Asymmetric Encryption Methods

  List the asymmetric encryption methods currently being used.

kssl_key_tool get asym_methods VIRTUAL_SERVER


Get Available Asymmetric Encryption Methods

  Show the list of asymmetric encryption methods currently supported.
  
  software:   Use software routines
  AEP_user:   Use the AEP 1000 via the user-space daemon
  AEP_kernel: Use the AEP directly from within the kernel. Not implemented!

kssl_key_tool get available_asym_methods VIRTUAL_SERVER


Checking the Version

  The version of KSSLD can be checked by inspecting /proc/net/kssld

cat /proc/net/kssld 


Viewing Connections

  Active connections can be checked by inspecting 
  /proc/net/kssld_conn

cat /proc/net/kssld_conn


The format is one line per connection.


<src_ip>:<src_port>-><dst_ip>:<dst_port> in=<rx_bytes> out=<tx_bytes> (<s>)


  s is the connection state.
  It may be one of ssl, pt or none 
  for SSL/TLS, plain text and not connected respectively.

  This information is shown twice, separated by a vertical line.
  The left-hand side is the connection from the end-user.
  The right-hand side is the connection to the real-server.

Viewing Sessions

The sessions that are currently available for resumption can be checked
by inspecting 
/proc/net/kssld_session


cat /proc/net/kssld_session


The format is one line per session.


<hash_bucket> <session_id> <cipher_suite> <master_secret>


Debugging

The verbosity of debugging messages logged by the kernel can
be controlled using /proc/sys/net/ipv4/kssld/debug_level


  The default value is 0, which means no debugging.
  The useful range is from 0 - 12. The higher the level,
  the more messages. All messages for lower levels are
  included in the higher levels. As a guide this is
  how debugging messages are classified. 

  0:      No messages
  1:      Bugs and statistics
  2-3:    Errors caused by user or network derived input
  4-6:    Internal errors.
  7-9:    Internal warnings.
  10-12:  Information about entering and leaving functions.


Note that debugging is only available when KSSLD is compiled with 
CONFIG_KSSL_DEBUG defined. This is the default.

