Getting OpenSSL to work with hybrid-7
=====================================
$Id: README.openssl 33 2005-10-02 20:50:00Z knight $

PREFACE
=======
  As an administrator, you more than likely are looking at this because
  you wish to enable what are known as "cryptlinks" -- server-to-server
  encryption (via OpenSSL) with RSA key authentication.

  The intention of this document is to make administrators aware of
  what issues can come forth from attempting to use this newfangled
  technology, and how to properly get it "up and going."

  In the following sections, we hope to address this issue, so that
  OpenSSL can be (hopefully) used on all systems where available.

  Other sections include more technical descriptions, such as issues
  pertaining to ciphers (encryption methods/algorithms) and other
  related information.


OBTAINING OPENSSL
=================
  If you are looking to obtain OpenSSL, be sure to visit their official
  home page at:

    http://www.openssl.org/

  Be sure to download the non-engine version of OpenSSL; the engine
  release is OpenSSL with hardware SSL accelerator support.  It is
  presently in alpha stages (and even in the engine release, is disabled
  by default as a safety precaution).

  The present stable release of OpenSSL, as of the authoring of this
  document, is 0.9.7b (old stable 0.9.6j.)


GETTING IT TO WORK
==================
  OpenSSL is enabled by default when running configure. If the script
  cannot locate a working version of OpenSSL, you may specify one on
  the command line:

    ./configure --enable-openssl=/usr/local/openssl

  To explicitly disable it, use --disable-openssl.

  For multiple versions of OpenSSL installed on the same system,
  please read the "MULTIPLE OPENSSL INSTALLATIONS" section within
  this document.

  If no directory is specified, OpenSSL will check for the proper
  installation tree in the following directories (by default), and
  in this order:

    /usr/local/ssl
    /usr/pkg
    /usr/local
    /usr/local/openssl

  Please make a note of this, as if you have multiple OpenSSL install-
  ations, this will decide precedence.


SERVER CONFIGURATION
====================
  Step 1:  Create your private and public keys.  Read how in the
           example.conf file, or use the tools/mkkeypair utility.
  Step 2:  Place the keys where your IRC daemon can access them.
  Step 3:  Provide your *PUBLIC* key to another server.
  Step 4:  Obtain another servers' *PUBLIC* key and place it in a
           file where your IRC daemon can access it.
  Step 5:  Edit ircd.conf and specify your private key location via
           the "rsa_private_key_file" directive in serverinfo {}.
  Step 6:  Edit ircd.conf and specify the public key location via
           the "rsa_public_key_file" directive in the appropriate
           connect {} block.
  Step 7:  /REHASH or send a SIGHUP to the daemon
  Step 8:  Check ircd.log to make sure no errors showed up.
  Step 9:  Try to connect to one another.

  More to come later.


OPENSSL VERSION REQUIREMENT
===========================
  OpenSSL 0.9.6 (or above) is required for cryptlinks to work.

  The reason for this is severe: prior to OpenSSL 0.9.6, none of the
  encryption/decryption functions did any form of error handling.  The
  reasons for this are unknown, but the reasons behind not supporting
  0.9.5 or below should be self-explanatory at this point.

  To find out what OpenSSL version you have, try the following:

    $ openssl version
    OpenSSL 0.9.6 24 Sep 2000


MULTIPLE OPENSSL INSTALLATIONS
==============================
  Some systems may have multiple copies of OpenSSL installed for any of
  (but not limited to) the following reasons:

    1.  The OpenSSL which came with the system is outdated.
    2.  The OpenSSL which came with the system is broken.
    3.  The administrator wanted a more recent version.
    4.  Another software package automatically installed another copy
        of OpenSSL based upon dependencies.

  *******************************************************************
  **  HAVING MULTIPLE COPIES OF OpenSSL ON THE SAME SYSTEM IS NOT  **
  **           RECOMMENDED BY THE HYBRID DEVELOPMENT TEAM          **
  *******************************************************************

  If you are attempting to use hybrid-7 on a system where you do not
  have root access, it is recommended that you communicate with your
  system administrator or ISP (whichever the case may be) and request
  that a newer version of OpenSSL be installed.

  This disclaimer enforces the "clean system" concept.  Keeping a system
  up-to-date with software releases and fixes (vendor-specific or free-lance)
  is part of a system administrators job (professionally or socially).  It
  is not a tedious task if the application is small and generally compact
  (in comparison to, say, XFree86).

  In the case of FreeBSD, you may either rebuild world (make buildworld)
  or use the OpenSSL version provided in /usr/ports/security/openssl.


OPENSSL INSTALLATION PATHS
==========================
  The stock source-code release of OpenSSL is written to install itself,
  by default, in /usr/local/ssl.  This can be changed using the
  "--prefix" and "--openssldir" arguments of OpenSSL's "config" stage.

  The Hybrid team has verified the directory structure of stock OpenSSL
  installations.  Here are some examples of OpenSSL configurations, and
  how to get hybrid-7 to work with them:

    OpenSSL:  ./config --prefix=/usr/local
    hybrid-7: ./configure --enable-openssl=/usr/local

    OpenSSL:  ./config --openssldir=/usr/local
    hybrid-7: ./configure --enable-openssl=/usr/local

    OpenSSL:  ./config --prefix=/usr/local --openssldir=/usr/local/ssl
    hybrid-7: ./configure --enable-openssl=/usr/local

  We recommend that administrators install OpenSSL using the "--openssldir"
  argument, rather than the "--prefix" argument.  The reason for this is
  purely cosmetical; it's nice to keep everything in one place, and keeps
  a clean directory tree.

  Finally, please verify that your OpenSSL installation was installed
  properly, otherwise you will be unable to compile hybrid-7.  A proper
  installation should have an include/openssl/ directory, and a
  lib/ directory.  Both (and the files within) are needed for hybrid-7
  to properly work with OpenSSL.


CIPHERS
=======
  Ciphers can be selected specifically in hybrid-7, per connect {}
  block (using 'cipher_preference'), as well as a default cipher
  method defined in general {} ('default_cipher_preference').  Please
  consult doc/example.conf or doc/ircd.conf for more information.

  hybrid-7 chooses and checks ciphers in the following order:

    Name           Cipher type        Cipher information
    ----------------------------------------------------
    BF/168         Blowfish           168-bit
    BF/128         Blowfish           128-bit
    CAST/128       CAST               128-bit
    IDEA/128       IDEA               128-bit
    RC5.16/128     RC5 16 round       128-bit
    RC5.12/128     RC5 12 round       128-bit
    RC5.8/128      RC5 8 round        128-bit
    3DES/168       3DES               168-bit
    DES/56         Standard DES       56-bit
    ----------------------------------------------------

  On most systems, Blowfish will be secure and fast enough for most
  IRC networks and general transmissions.  Use the "encspeed" utility
  (tools/encspeed) provided with hybrid-7 to find out which cipher may
  work best on your system.  Naturally, you may want to pick a more
  secure cipher depending upon the sensitivity of the data being
  transmitted/received.  Also, be sure to pick something the remote
  end (server) is able to handle well as well.  Communicate with your
  administrators!

  Some systems may lack the IDEA cipher (such is the case with FreeBSD
  versions which originate in the USA).  The reason for this is simple:
  there are licensing issues regarding this cipher (export regulations).
  OpenSSL does support the IDEA cipher, but it cannot be provided with
  this system for legal reasons.


SOLARIS CAVEATS
===============
  Some versions of Solaris lack /dev/random or /dev/urandom.  These
  are practically considered pre-requisites for OpenSSL to function
  properly.

  If you're using a version of Solaris which lacks /dev/random or
  /dev/urandom, the OpenSSL authors provide two (2) possible
  solutions.  Please read the following section of the OpenSSL FAQ:

    http://www.openssl.org/support/faq.html#USER1

  It is recommended that Solaris users choose one of the following
  options:

    1.  Install the EGD (Entropy Gathering Daemon) from:

      http://sourceforge.net/projects/egd/

    2.  If EGD does not work, use PRNGD (which is compatible with the
        EGD interface for OpenSSL).  PRNGD can be obtained via:

      http://www.aet.tu-cottbus.de/personen/jaenicke/postfix_tls/prngd.html

    3.  For Solaris 2.6 users, install Sun vendor patch 105710-0 (known
        as "SUNWski") and use the $RANDFILE environment variable to
        specify /dev/random.  There are known caveats when using this
        method (blocking vs. non-blocking).

    4.  For Solaris 2.5.1, Solaris 2.6, Solaris 7, and Solaris 8, the
        ANDIrand package can be used to emulate /dev/random and
        /dev/urandom.  Check out the ANDIrand page at:

      http://www.cosy.sbg.ac.at/~andi/



END OF DOCUMENT