1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
|
<!DOCTYPE html>
<html lang="en" data-content_root="../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>TLS support — Eggdrop 1.10.1rc2 documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=03e43079" />
<link rel="stylesheet" type="text/css" href="../_static/eggdrop.css?v=ab48a1b6" />
<script src="../_static/documentation_options.js?v=290de6c6"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="IRCv3 support" href="ircv3.html" />
<link rel="prev" title="IPv6 support" href="ipv6.html" />
</head><body>
<div class="header-wrapper" role="banner">
<div class="header">
<div class="headertitle"><a
href="../index.html">Eggdrop 1.10.1rc2 documentation</a></div>
<div class="rel" role="navigation" aria-label="related navigation">
<a href="ipv6.html" title="IPv6 support"
accesskey="P">previous</a> |
<a href="ircv3.html" title="IRCv3 support"
accesskey="N">next</a>
</div>
</div>
</div>
<div class="content-wrapper">
<div class="content">
<div class="sidebar">
<h3>Table of Contents</h3>
<p class="caption" role="heading"><span class="caption-text">Installing Eggdrop</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../install/readme.html">README</a></li>
<li class="toctree-l1"><a class="reference internal" href="../install/install.html">Installing Eggdrop</a></li>
<li class="toctree-l1"><a class="reference internal" href="../install/upgrading.html">Upgrading Eggdrop</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Using Eggdrop</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="features.html">Eggdrop Features</a></li>
<li class="toctree-l1"><a class="reference internal" href="core.html">Eggdrop Core Settings</a></li>
<li class="toctree-l1"><a class="reference internal" href="partyline.html">The Party Line</a></li>
<li class="toctree-l1"><a class="reference internal" href="autoscripts.html">Eggdrop Autoscripts</a></li>
<li class="toctree-l1"><a class="reference internal" href="users.html">Users and Flags</a></li>
<li class="toctree-l1"><a class="reference internal" href="bans.html">Bans, Invites, and Exempts</a></li>
<li class="toctree-l1"><a class="reference internal" href="botnet.html">Botnet Sharing and Linking</a></li>
<li class="toctree-l1"><a class="reference internal" href="ipv6.html">IPv6 support</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">TLS support</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#about">About</a></li>
<li class="toctree-l2"><a class="reference internal" href="#installation">Installation</a></li>
<li class="toctree-l2"><a class="reference internal" href="#usage">Usage</a></li>
<li class="toctree-l2"><a class="reference internal" href="#keys-certificates-and-authentication">Keys, certificates and authentication</a></li>
<li class="toctree-l2"><a class="reference internal" href="#ssl-tls-settings">SSL/TLS Settings</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="ircv3.html">IRCv3 support</a></li>
<li class="toctree-l1"><a class="reference internal" href="accounts.html">Account tracking in Eggdrop</a></li>
<li class="toctree-l1"><a class="reference internal" href="pbkdf2info.html">Encryption/Hashing</a></li>
<li class="toctree-l1"><a class="reference internal" href="python.html">Using the Python Module</a></li>
<li class="toctree-l1"><a class="reference internal" href="twitchinfo.html">Twitch</a></li>
<li class="toctree-l1"><a class="reference internal" href="tricks.html">Advanced Tips</a></li>
<li class="toctree-l1"><a class="reference internal" href="text-sub.html">Textfile Substitutions</a></li>
<li class="toctree-l1"><a class="reference internal" href="tcl-commands.html">Eggdrop Tcl Commands</a></li>
<li class="toctree-l1"><a class="reference internal" href="twitch-tcl-commands.html">Eggdrop Twitch Tcl Commands</a></li>
<li class="toctree-l1"><a class="reference internal" href="patch.html">Patching Eggdrop</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Tutorials</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../tutorials/setup.html">Setting Up Eggdrop</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tutorials/firststeps.html">Common First Steps</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tutorials/tlssetup.html">Enabling TLS Security on Eggdrop</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tutorials/userfilesharing.html">Sharing Userfiles</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tutorials/firstscript.html">Writing an Eggdrop Tcl Script</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tutorials/module.html">Writing a Basic Eggdrop Module</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Eggdrop Modules</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../modules/index.html">Eggdrop Module Information</a></li>
<li class="toctree-l1"><a class="reference internal" href="../modules/included.html">Modules included with Eggdrop</a></li>
<li class="toctree-l1"><a class="reference internal" href="../modules/writing.html">How to Write an Eggdrop Module</a></li>
<li class="toctree-l1"><a class="reference internal" href="../modules/internals.html">Eggdrop Bind Internals</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">About Eggdrop</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../about/about.html">About Eggdrop</a></li>
<li class="toctree-l1"><a class="reference internal" href="../about/legal.html">Boring legal stuff</a></li>
</ul>
<div role="search">
<h3 style="margin-top: 1.5em;">Search</h3>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<p>TLS support
Last revised: Mar 1, 2025</p>
<section id="tls-support">
<h1>TLS support<a class="headerlink" href="#tls-support" title="Link to this heading">¶</a></h1>
<p>This document provides information about TLS support which is a new
Eggdrop feature since version 1.8.0.</p>
<section id="about">
<h2>About<a class="headerlink" href="#about" title="Link to this heading">¶</a></h2>
<p>Eggdrop can be optionally compiled with TLS support. This requires OpenSSL
0.9.8 or later installed on your system.
TLS support includes encryption for IRC, DCC, botnet, telnet and scripted
connections as well as certificate authentication for users and bots.</p>
</section>
<section id="installation">
<h2>Installation<a class="headerlink" href="#installation" title="Link to this heading">¶</a></h2>
<p>./configure and install as usual, the configure script will detect if your
system meets the requirements and will enable TLS automatically. You can
override the autodetection and manually disable TLS with
./configure –disable-tls. You can’t forcefully enable it though.
The configure script will look for OpenSSL at the default system locations.
If you have it installed at a non-standard location or locally in your
home directory, you’ll need to specify the paths to header and library
files with the –with-sslinc and –with-ssllib options. You can also use
these if you want to override the default OpenSSL installation with a
custom one, as they take precedence over any system-wide paths.</p>
</section>
<section id="usage">
<h2>Usage<a class="headerlink" href="#usage" title="Link to this heading">¶</a></h2>
<p>As of v1.9.0, TLS support must be requested explicitly for botnet links.
To create a TLS-enabled listening port or connect to a TLS-enabled listening
port, you must prefix the port with a plus sign (+). If a port number could
normally be omitted as part of a command syntax must be included (and prefixed)
to enable TLS.</p>
<p>Scripts can also upgrade a regular plaintext connection to TLS via STARTTLS
using the starttls Tcl command.</p>
<p>Prior to v1.9.0, Eggdrop would use STARTTLS to automatically attempt to upgrade a
plain connection to an encrypted connection for botnet links, without any
additional configuration (This was changed to provide users the flexibility
to configure their own environments and assist in debugging).</p>
<section id="irc">
<h3>IRC<a class="headerlink" href="#irc" title="Link to this heading">¶</a></h3>
<p>To connect to IRC using SSL, specify the port number and prefix it with
a plus sign. Example: .jump irc.server.com +6697. The same goes for
the server list in the config file.</p>
<p>Some NickServ services allow you to authenticate with a certificate.
Eggdrop will use the certificate pair specified in ssl-privatekey/
ssl-certificate for authentication.</p>
</section>
<section id="botnet">
<h3>Botnet<a class="headerlink" href="#botnet" title="Link to this heading">¶</a></h3>
<p>Eggdrop can use TLS connections to protect botnet links if it is compiled with TLS support. As of version 1.9.0, only raw TLS sockets are used to protect a connection. By prefixing a listen port in the Eggdrop configuration with a plus (+), that specifies that port as a TLS-enabled port, and will only accept TLS connections (no plain text connections will be allowed). With two TLS-enabled Eggdrops, it graphically looks like this:</p>
<table class="docutils align-default">
<tbody>
<tr class="row-odd"><td><p>Leaf bot sets hub port as…</p></td>
<td><p>and Hub bot config uses…</p></td>
<td><p>the connection will…</p></td>
</tr>
<tr class="row-even"><td><p>port</p></td>
<td><p>listen port</p></td>
<td><p>be plain, but can be upgraded
to TLS manually with the
starttls Tcl/bot command</p></td>
</tr>
<tr class="row-odd"><td><p>+port</p></td>
<td><p>listen +port</p></td>
<td><p>connect with TLS</p></td>
</tr>
<tr class="row-even"><td><p>port</p></td>
<td><p>listen +port</p></td>
<td><p>fail as hub only wants TLS</p></td>
</tr>
<tr class="row-odd"><td><p>+port</p></td>
<td><p>listen port</p></td>
<td><p>fail as leaf only wants TLS</p></td>
</tr>
</tbody>
</table>
<p>In short, a bot added to your Eggdrop with a +port in the address can only connect to a bot listening with a +port in the config. Conversely, a bot added to your Eggdrop without a + prefix can only connect to a bot listening without a + prefix in the config.</p>
<p>If TLS negotiation fails, the connection is deliberately aborted and no clear text is ever sent by the TLS-requiring party.</p>
<p>Eggdrop can also upgrade a plaintext connection with the starttls Tcl command. To use this, a plaintext connection is first made to a non-TLS port (ie, one that is not prefixed with a plus), then the starttls command is issued to upgrade that link to a TLS connection. In the Eggdrop 1.8 series, Eggdrop automatically attempted a starttls upgrade on all botnet connections. As such, if a 1.8 Eggdrop connects to a plain listening port on a 1.9.0 or later Eggdrop, it will automatically attempt to upgrade the link to TLS.</p>
</section>
<section id="secure-dcc">
<h3>Secure DCC<a class="headerlink" href="#secure-dcc" title="Link to this heading">¶</a></h3>
<p>Eggdrop supports the SDCC protocol, allowing you to establish DCC chat
and file transfers over SSL. Example: /ctcp bot schat
Note, that currently the only IRC client supporting SDCC is KVIrc. For
information on how to initiate secure DCC chat from KVIrc (rather than
from the bot with /ctcp bot chat), consult the KVIrc documentation.</p>
</section>
<section id="scripts">
<h3>Scripts<a class="headerlink" href="#scripts" title="Link to this heading">¶</a></h3>
<p>Scripts can open or connect to TLS ports the usual way specifying the
port with a plus sign. Alternatively, the connection could be
established as plaintext and later switched on with the starttls Tcl
command. (Note that the other side should also switch to TLS at the same
time - the synchronization is the script’s job, not Eggdrop’s.)</p>
</section>
</section>
<section id="keys-certificates-and-authentication">
<h2>Keys, certificates and authentication<a class="headerlink" href="#keys-certificates-and-authentication" title="Link to this heading">¶</a></h2>
<p>You need a private key and a digital certificate whenever your bot will
act as a server in a connection of any type. Common examples are hub
bots and TLS listening ports. General information about certificates and
public key infrastructure can be obtained from Internet. This document
only contains eggdrop-specific information on the subject.
The easy way to create a key and a certificate is to type ‘make sslcert’
after compiling your bot (If you installed Eggdrop to a non-standard
location, use make sslcert DEST=/path/to/eggdrop). This will generate a
4096-bit private key (eggdrop.key) and a certificate (eggdrop.crt) after
you fill in the required fields. Alternatively, you can use ‘make sslsilent’
to generate a key and certificate non-interactively, using pre-set values.
This is useful when installing Eggdrop via a scripted process.</p>
<p>To authenticate with a certificate instead of using password, you should
make a ssl certificate for yourself and enable ssl-cert-auth in the config
file. Then either connect to the bot using TLS and type “.fprint +” or
enter your certificate fingerprint with .fprint SHA1-FINGERPRINT.
To generate a ssl certificate for yourself, you can run the following
command from the Eggdrop source directory:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">openssl</span> <span class="n">req</span> <span class="o">-</span><span class="n">new</span> <span class="o">-</span><span class="n">x509</span> <span class="o">-</span><span class="n">nodes</span> <span class="o">-</span><span class="n">keyout</span> <span class="n">my</span><span class="o">.</span><span class="n">key</span> <span class="o">-</span><span class="n">out</span> <span class="n">my</span><span class="o">.</span><span class="n">crt</span> <span class="o">-</span><span class="n">config</span> <span class="n">ssl</span><span class="o">.</span><span class="n">conf</span>
</pre></div>
</div>
<p>When asked about bot’s handle, put your handle instead. How to use your
new certificate to connect to Eggdrop, depends on your irc client.
To connect to your bot from the command line using the key/cert files
generated in the previous step, you can use the OpenSSL ssl client</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">openssl</span> <span class="n">s_client</span> <span class="o">-</span><span class="n">cert</span> <span class="n">my</span><span class="o">.</span><span class="n">crt</span> <span class="o">-</span><span class="n">key</span> <span class="n">my</span><span class="o">.</span><span class="n">key</span> <span class="o">-</span><span class="n">connect</span> <span class="n">host</span><span class="p">:</span><span class="n">sslport</span>
</pre></div>
</div>
</section>
<section id="ssl-tls-settings">
<h2>SSL/TLS Settings<a class="headerlink" href="#ssl-tls-settings" title="Link to this heading">¶</a></h2>
<p>There are some new settings allowing control over certificate
verification and authorization.</p>
<blockquote>
<div><p>ssl-privatekey</p>
<blockquote>
<div><p>file containing Eggdrop’s private key, required for the certificate.</p>
</div></blockquote>
<p>ssl-certificate</p>
<blockquote>
<div><p>Specify the filename where your SSL certificate is located.
if your bot will accept SSL connections, it must have a certificate.</p>
</div></blockquote>
<p>ssl-verify-depth</p>
<blockquote>
<div><p>maximum verification depth when checking certificate validity.
Determines the maximum certificate chain length to allow.</p>
</div></blockquote>
<div class="line-block">
<div class="line">ssl-capath</div>
<div class="line">ssl-cafile</div>
</div>
<blockquote>
<div><p>specify the location of certificate authorities certificates. These
are used for verification. Both can be active at the same time.
If you don’t set this, validation of the issuer won’t be possible and
depending on verification settings, the peer certificate might fail
verification.</p>
</div></blockquote>
<p>ssl-ciphers</p>
<blockquote>
<div><p>specify the list of ciphers (in order of preference) allowed for
use with ssl.</p>
</div></blockquote>
<p>ssl-cert-auth</p>
<blockquote>
<div><p>enables or disables certificate authorization for partyline/botnet.
This works only for SSL connections (SDCC or telnet over SSL).
A setting of 1 means optional authorization: If the user/bot has a
fingerprint set and it matches the certificate SHA1 fingerprint,
access is granted, otherwise ordinary password authentication takes
place.</p>
<p>If you set this to 2 however, users without a fingerprint set or
with a fingerprint not matching the certificate, will not be
allowed to enter the partyline with SSL. In addition to this user and
bot certificates will be required to have an UID field matching the
handle of the user/bot.</p>
</div></blockquote>
<div class="line-block">
<div class="line">ssl-verify-dcc</div>
<div class="line">ssl-verify-bots</div>
<div class="line">ssl-verify-server</div>
<div class="line">ssl-verify-clients</div>
</div>
<blockquote>
<div><p>control ssl certificate verification. A value of 0 disables
verification completely. A value of 1 enables full verification.
Higher values enable specific exceptions like allowing self-signed
or expired certificates. Details are documented in eggdrop.conf.</p>
</div></blockquote>
</div></blockquote>
<p>Copyright (C) 2010 - 2025 Eggheads Development Team</p>
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
</div>
<div class="footer-wrapper">
<div class="footer">
<div class="left">
<div role="navigation" aria-label="related navigaton">
<a href="ipv6.html" title="IPv6 support"
>previous</a> |
<a href="ircv3.html" title="IRCv3 support"
>next</a>
</div>
<div role="note" aria-label="source link">
</div>
</div>
<div class="right">
<div class="footer" role="contentinfo">
© Copyright 2025, Eggheads.
Last updated on Aug 15, 2025.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.
</div>
</div>
<div class="clearer"></div>
</div>
</div>
</body>
</html>
|
