doc/technical/README.openssl

Getting OpenSSL to work with hybrid-7
=====================================
$Id: README.openssl,v 1.9 2003/05/31 07:01:39 lusky Exp $

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
Revision:	30
Committed:	Sun Oct 2 20:03:27 2005 UTC (20 years, 9 months ago) by adx
File size:	9441 byte(s)
Log Message:	- imported sources - can be moved later according to the directory/branching scheme, but we need the svn up
#	User	Rev	Content
1	adx	30	Getting OpenSSL to work with hybrid-7
2			=====================================
3			$Id: README.openssl,v 1.9 2003/05/31 07:01:39 lusky Exp $
4
5			PREFACE
6			=======
7			As an administrator, you more than likely are looking at this because
8			you wish to enable what are known as "cryptlinks" -- server-to-server
9			encryption (via OpenSSL) with RSA key authentication.
10
11			The intention of this document is to make administrators aware of
12			what issues can come forth from attempting to use this newfangled
13			technology, and how to properly get it "up and going."
14
15			In the following sections, we hope to address this issue, so that
16			OpenSSL can be (hopefully) used on all systems where available.
17
18			Other sections include more technical descriptions, such as issues
19			pertaining to ciphers (encryption methods/algorithms) and other
20			related information.
21
22
23			OBTAINING OPENSSL
24			=================
25			If you are looking to obtain OpenSSL, be sure to visit their official
26			home page at:
27
28			http://www.openssl.org/
29
30			Be sure to download the non-engine version of OpenSSL; the engine
31			release is OpenSSL with hardware SSL accelerator support. It is
32			presently in alpha stages (and even in the engine release, is disabled
33			by default as a safety precaution).
34
35			The present stable release of OpenSSL, as of the authoring of this
36			document, is 0.9.7b (old stable 0.9.6j.)
37
38
39			GETTING IT TO WORK
40			==================
41			OpenSSL is enabled by default when running configure. If the script
42			cannot locate a working version of OpenSSL, you may specify one on
43			the command line:
44
45			./configure --enable-openssl=/usr/local/openssl
46
47			To explicitly disable it, use --disable-openssl.
48
49			For multiple versions of OpenSSL installed on the same system,
50			please read the "MULTIPLE OPENSSL INSTALLATIONS" section within
51			this document.
52
53			If no directory is specified, OpenSSL will check for the proper
54			installation tree in the following directories (by default), and
55			in this order:
56
57			/usr/local/ssl
58			/usr/pkg
59			/usr/local
60			/usr/local/openssl
61
62			Please make a note of this, as if you have multiple OpenSSL install-
63			ations, this will decide precedence.
64
65
66			SERVER CONFIGURATION
67			====================
68			Step 1: Create your private and public keys. Read how in the
69			example.conf file, or use the tools/mkkeypair utility.
70			Step 2: Place the keys where your IRC daemon can access them.
71			Step 3: Provide your PUBLIC key to another server.
72			Step 4: Obtain another servers' PUBLIC key and place it in a
73			file where your IRC daemon can access it.
74			Step 5: Edit ircd.conf and specify your private key location via
75			the "rsa_private_key_file" directive in serverinfo {}.
76			Step 6: Edit ircd.conf and specify the public key location via
77			the "rsa_public_key_file" directive in the appropriate
78			connect {} block.
79			Step 7: /REHASH or send a SIGHUP to the daemon
80			Step 8: Check ircd.log to make sure no errors showed up.
81			Step 9: Try to connect to one another.
82
83			More to come later.
84
85
86			OPENSSL VERSION REQUIREMENT
87			===========================
88			OpenSSL 0.9.6 (or above) is required for cryptlinks to work.
89
90			The reason for this is severe: prior to OpenSSL 0.9.6, none of the
91			encryption/decryption functions did any form of error handling. The
92			reasons for this are unknown, but the reasons behind not supporting
93			0.9.5 or below should be self-explanatory at this point.
94
95			To find out what OpenSSL version you have, try the following:
96
97			$ openssl version
98			OpenSSL 0.9.6 24 Sep 2000
99
100
101			MULTIPLE OPENSSL INSTALLATIONS
102			==============================
103			Some systems may have multiple copies of OpenSSL installed for any of
104			(but not limited to) the following reasons:
105
106			1. The OpenSSL which came with the system is outdated.
107			2. The OpenSSL which came with the system is broken.
108			3. The administrator wanted a more recent version.
109			4. Another software package automatically installed another copy
110			of OpenSSL based upon dependencies.
111
112			*******************************************************************
113			HAVING MULTIPLE COPIES OF OpenSSL ON THE SAME SYSTEM IS NOT
114			RECOMMENDED BY THE HYBRID DEVELOPMENT TEAM
115			*******************************************************************
116
117			If you are attempting to use hybrid-7 on a system where you do not
118			have root access, it is recommended that you communicate with your
119			system administrator or ISP (whichever the case may be) and request
120			that a newer version of OpenSSL be installed.
121
122			This disclaimer enforces the "clean system" concept. Keeping a system
123			up-to-date with software releases and fixes (vendor-specific or free-lance)
124			is part of a system administrators job (professionally or socially). It
125			is not a tedious task if the application is small and generally compact
126			(in comparison to, say, XFree86).
127
128			In the case of FreeBSD, you may either rebuild world (make buildworld)
129			or use the OpenSSL version provided in /usr/ports/security/openssl.
130
131
132			OPENSSL INSTALLATION PATHS
133			==========================
134			The stock source-code release of OpenSSL is written to install itself,
135			by default, in /usr/local/ssl. This can be changed using the
136			"--prefix" and "--openssldir" arguments of OpenSSL's "config" stage.
137
138			The Hybrid team has verified the directory structure of stock OpenSSL
139			installations. Here are some examples of OpenSSL configurations, and
140			how to get hybrid-7 to work with them:
141
142			OpenSSL: ./config --prefix=/usr/local
143			hybrid-7: ./configure --enable-openssl=/usr/local
144
145			OpenSSL: ./config --openssldir=/usr/local
146			hybrid-7: ./configure --enable-openssl=/usr/local
147
148			OpenSSL: ./config --prefix=/usr/local --openssldir=/usr/local/ssl
149			hybrid-7: ./configure --enable-openssl=/usr/local
150
151			We recommend that administrators install OpenSSL using the "--openssldir"
152			argument, rather than the "--prefix" argument. The reason for this is
153			purely cosmetical; it's nice to keep everything in one place, and keeps
154			a clean directory tree.
155
156			Finally, please verify that your OpenSSL installation was installed
157			properly, otherwise you will be unable to compile hybrid-7. A proper
158			installation should have an include/openssl/ directory, and a
159			lib/ directory. Both (and the files within) are needed for hybrid-7
160			to properly work with OpenSSL.
161
162
163			CIPHERS
164			=======
165			Ciphers can be selected specifically in hybrid-7, per connect {}
166			block (using 'cipher_preference'), as well as a default cipher
167			method defined in general {} ('default_cipher_preference'). Please
168			consult doc/example.conf or doc/ircd.conf for more information.
169
170			hybrid-7 chooses and checks ciphers in the following order:
171
172			Name Cipher type Cipher information
173			----------------------------------------------------
174			BF/168 Blowfish 168-bit
175			BF/128 Blowfish 128-bit
176			CAST/128 CAST 128-bit
177			IDEA/128 IDEA 128-bit
178			RC5.16/128 RC5 16 round 128-bit
179			RC5.12/128 RC5 12 round 128-bit
180			RC5.8/128 RC5 8 round 128-bit
181			3DES/168 3DES 168-bit
182			DES/56 Standard DES 56-bit
183			----------------------------------------------------
184
185			On most systems, Blowfish will be secure and fast enough for most
186			IRC networks and general transmissions. Use the "encspeed" utility
187			(tools/encspeed) provided with hybrid-7 to find out which cipher may
188			work best on your system. Naturally, you may want to pick a more
189			secure cipher depending upon the sensitivity of the data being
190			transmitted/received. Also, be sure to pick something the remote
191			end (server) is able to handle well as well. Communicate with your
192			administrators!
193
194			Some systems may lack the IDEA cipher (such is the case with FreeBSD
195			versions which originate in the USA). The reason for this is simple:
196			there are licensing issues regarding this cipher (export regulations).
197			OpenSSL does support the IDEA cipher, but it cannot be provided with
198			this system for legal reasons.
199
200
201			SOLARIS CAVEATS
202			===============
203			Some versions of Solaris lack /dev/random or /dev/urandom. These
204			are practically considered pre-requisites for OpenSSL to function
205			properly.
206
207			If you're using a version of Solaris which lacks /dev/random or
208			/dev/urandom, the OpenSSL authors provide two (2) possible
209			solutions. Please read the following section of the OpenSSL FAQ:
210
211			http://www.openssl.org/support/faq.html#USER1
212
213			It is recommended that Solaris users choose one of the following
214			options:
215
216			1. Install the EGD (Entropy Gathering Daemon) from:
217
218			http://sourceforge.net/projects/egd/
219
220			2. If EGD does not work, use PRNGD (which is compatible with the
221			EGD interface for OpenSSL). PRNGD can be obtained via:
222
223			http://www.aet.tu-cottbus.de/personen/jaenicke/postfix_tls/prngd.html
224
225			3. For Solaris 2.6 users, install Sun vendor patch 105710-0 (known
226			as "SUNWski") and use the $RANDFILE environment variable to
227			specify /dev/random. There are known caveats when using this
228			method (blocking vs. non-blocking).
229
230			4. For Solaris 2.5.1, Solaris 2.6, Solaris 7, and Solaris 8, the
231			ANDIrand package can be used to emulate /dev/random and
232			/dev/urandom. Check out the ANDIrand page at:
233
234			http://www.cosy.sbg.ac.at/~andi/
235
236
237
238			END OF DOCUMENT