1 |
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 |