ViewVC Help
View File | Revision Log | Show Annotations | View Changeset | Root Listing
root/svn/ircd-hybrid/doc/technical/README.openssl
Revision: 30
Committed: Sun Oct 2 20:03:27 2005 UTC (18 years, 5 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

File Contents

# Content
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

Properties

Name Value
svn:eol-style native
svn:keywords "Id Revision"