/[cvs]/eggdrop1.8/doc/TLS
ViewVC logotype

Contents of /eggdrop1.8/doc/TLS

Parent Directory Parent Directory | Revision Log Revision Log | View Revision Graph Revision Graph


Revision 1.2 - (show annotations) (download)
Wed Oct 20 13:07:13 2010 UTC (8 years, 6 months ago) by pseudo
Branch: MAIN
CVS Tags: HEAD
Branch point for: gettext
Changes since 1.1: +3 -3 lines
Clarified the OpenSSL version requirements.
Rewrote open_telnet() to make it more useful.
Replaced some calls to open_telnet_raw() with open_telnet().

1 $Id: TLS,v 1.1 2010/10/19 12:13:32 pseudo Exp $
2
3 TLS support
4 Last revised: Oct 17, 2010
5 _____________________________________________________________________
6
7 TLS support
8
9
10 This document provides information about TLS support which is a new
11 eggdrop feature since version 1.8.0.
12
13 Contents:
14 1. About
15 2. Installation
16 3. Usage
17 3a. IRC
18 3b. Botnet
19 3c. Secure DCC
20 3d. Scripts
21 4. Keys, certificates and authentication
22 5. SSL settings
23
24
25 1. About
26
27 Eggdrop can be optionally compiled with TLS support. This requires OpenSSL
28 0.9.8 or more recent installed on your system.
29 TLS support includes encryption for IRC, DCC, botnet, telnet and scripted
30 connections as well as certificate authentication for users and bots.
31
32
33 2. Installation
34
35 ./configure and install as usual, the configure script will detect if your
36 system meets the requirements and will enable TLS automatically. You can
37 override the autodetection and manually disable TLS with
38 ./configure --disable-tls. You can't forcefully enable it though.
39 The configure script will look for OpenSSL at the default system locations.
40 If you have it installed at a non-standard location or locally in your
41 home directory, you'll need to specify the paths to header and library
42 files with the --with-sslinc and --with-ssllib options. You can also use
43 these if you want to override the default OpenSSL installation with a
44 custom one, as they take precedence over any system-wide paths.
45
46
47 3. Usage
48
49 By default, without additional configuration, TLS support will provide
50 opportunistic encryption for botnet links. For other connection types,
51 TLS must be requested explicitly.
52 Secure connections are created the same way as plaintext ones. The only
53 difference is that you must prefix the port number with a plus sign.
54 A port number that could be normally omitted, would have to be included
55 to enable TLS. Scripts can also switch a regular, plaintext connection
56 to TLS, using the starttls Tcl command.
57
58 3a. IRC
59
60 To connect to IRC using SSL, specify the port number and prefix it with
61 a plus sign. Example: .jump irc.server.com +6697. The same goes for
62 the server list in the config file.
63
64 3b. Botnet
65
66 Botnet links between TLS-enabled bots will automatically switch to SSL.
67 In this case however, the nickname and password will be sent before SSL
68 negotiation takes place (the password is not send as cleartext anyway).
69 If one of the bots doesn't support TLS, the connection will fall back to
70 plain text. To require SSL explicitly, you need to open a ssl telnet
71 port on your hub and prefix the port number with + when adding it on your
72 leafs. For SSL-only bot links, all communication is encrypted, including
73 sending the nickname and password. If SSL negotiation fails, the
74 connection is deliberately aborted and no clear text is ever sent.
75
76 3c. Secure DCC
77
78 Eggdrop supports the SDCC protocol, allowing you to establish DCC chat
79 and file transfers over SSL. Example: /ctcp bot schat
80 Note, that currently the only IRC client supporting SDCC is KVIrc. For
81 information on how to initiate secure DCC chat from KVIrc (rather than
82 from the bot with /ctcp bot chat), consult the KVIrc documentation.
83
84 3d. Scripts
85
86 Scripts can open or connect to SSL ports the usual way specifying the
87 port with a plus sign. Alternatively, the connection could be
88 established as plaintext and later switched on with the starttls Tcl
89 command. (Note that the other side should also switch to SSL at the same
90 time - the synchronization is the script's job, not eggdrop's.)
91
92
93 4. Keys, certificates and authentication
94
95 You need a private key and a digital certificate whenever your bot will
96 act as a server in a connection of any type. Common examples are hub
97 bots and SSL listening ports. General information about certificates and
98 public key infrastructure can be obtained from Internet. This document
99 only contains eggdrop-specific information on the subject.
100 The easy way to create a key and a certificate is to type 'make sslcert'
101 after compiling your bot. This will generate a 2048-bit private key
102 (eggdrop.key) and a certificate (eggdrop.crt) after you fill in the
103 required fields.
104 To authenticate with a certificate instead of using password, you should
105 make a ssl certificate for yourself and enable ssl-cert-auth in the config
106 file. Then either connect to the bot using SSL and type ".fprint +" or
107 enter your certificate fingerprint with .fprint SHA1-FINGERPRINT.
108 To generate a ssl certificate for yourself, you can run the following
109 command from the eggdrop source directory:
110
111 openssl req -new -x509 -nodes -keyout my.key -out my.crt -config ssl.conf
112
113 When asked about bot's handle, put your handle instead. How to use your
114 new certificate to connect to eggdrop, depends on your irc client.
115 To connect to your bot from the command line, you can use the OpenSSL
116 ssl client:
117
118 openssl s_client -cert my.crt -key my.key -connect host:sslport
119
120
121 5. SSL Settings
122
123 There are some new settings allowing control over certificate
124 verification and authorization.
125
126 ssl-privatekey
127 file containing Eggdrop's private key, required for the certificate.
128
129 ssl-certificate
130 Specify the filename where your SSL certificate is located.
131 if your bot will accept SSL connections, it must have a certificate.
132
133 ssl-verify-depth
134 maximum verification depth when checking certificate validity.
135 Determines the maximum certificate chain length to allow.
136
137 ssl-capath
138 ssl-cafile
139 specify the location of certificate authorities certificates. These
140 are used for verification. Both can be active at the same time.
141 If you don't set this, validation of the issuer won't be possible and
142 depending on verification settings, the peer certificate might fail
143 verification.
144
145 ssl-ciphers
146 specify the list of ciphers (in order of preference) allowed for
147 use with ssl.
148
149 ssl-cert-auth
150 enables or disables certificate authorization for partyline/botnet.
151 This works only for SSL connections (SDCC or telnet over SSL).
152 A setting of 1 means optional authorization: If the user/bot has a
153 fingerprint set and it matches the certificate SHA1 fingerprint,
154 access is granted, otherwise ordinary password authentication takes
155 place.
156 If you set this to 2 however, users without a fingerprint set or
157 with a fingerprint not matching the certificate, will not be
158 allowed to enter the partyline with SSL. In addition to this user and
159 bot certificates will be required to have an UID field matching the
160 handle of the user/bot.
161
162 ssl-verify-dcc
163 ssl-verify-bots
164 ssl-verify-server
165 ssl-verify-clients
166 control ssl certificate verification. A value of 0 disables
167 verification completely. A value of 1 enables full verification.
168 Higher values enable specific exceptions like allowing self-signed
169 or expired certificates. Details are documented in eggdrop.conf.
170
171 _____________________________________________________________________
172
173 Copyright (C) 2010 Eggheads Development Team

webmaster@eggheads.org
ViewVC Help
Powered by ViewVC 1.1.23