<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title>TLS support — Eggdrop 1.8.4 documentation</title> <link rel="stylesheet" href="../_static/eggdrop.css" type="text/css" /> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" /> <script type="text/javascript"> var DOCUMENTATION_OPTIONS = { URL_ROOT: '../', VERSION: '1.8.4', COLLAPSE_INDEX: false, FILE_SUFFIX: '.html', HAS_SOURCE: true }; </script> <script type="text/javascript" src="../_static/jquery.js"></script> <script type="text/javascript" src="../_static/underscore.js"></script> <script type="text/javascript" src="../_static/doctools.js"></script> <link rel="top" title="Eggdrop 1.8.4 documentation" href="../index.html" /> <link rel="up" title="<no title>" href="index.html" /> <link rel="next" title="<no title>" href="../coreDocs/index.html" /> <link rel="prev" title="IPv6 support" href="ipv6.html" /> </head> <body> <div class="header-wrapper"> <div class="header"> <p class="logo"><a href="../index.html"> <img class="logo" src="../_static/eggman.png.gif" alt="Logo"/> </a></p> <div class="headertitle"><a href="../index.html">Eggdrop 1.8.4 documentation</a></div> <div class="rel"> <a href="ipv6.html" title="IPv6 support" accesskey="P">previous</a> | <a href="../coreDocs/index.html" title="<no title>" accesskey="N">next</a> </div> </div> </div> <div class="content-wrapper"> <div class="content"> <div class="document"> <div class="documentwrapper"> <div class="bodywrapper"> <div class="body"> <p>TLS support Last revised: Oct 17, 2010</p> <div class="section" id="tls-support"> <h1>TLS support<a class="headerlink" href="#tls-support" title="Permalink to this headline">¶</a></h1> <p>This document provides information about TLS support which is a new eggdrop feature since version 1.8.0.</p> <div class="section" id="about"> <h2>About<a class="headerlink" href="#about" title="Permalink to this headline">¶</a></h2> <p>Eggdrop can be optionally compiled with TLS support. This requires OpenSSL 0.9.8 or more recent 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> </div> <div class="section" id="installation"> <h2>Installation<a class="headerlink" href="#installation" title="Permalink to this headline">¶</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> </div> <div class="section" id="usage"> <h2>Usage<a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h2> <p>By default, without additional configuration, TLS support will provide opportunistic encryption for botnet links. For other connection types, TLS must be requested explicitly.</p> <p>Secure connections are created the same way as plaintext ones. The only difference is that you must prefix the port number with a plus sign. A port number that could be normally omitted, would have to be included to enable TLS. Scripts can also switch a regular, plaintext connection to TLS, using the starttls Tcl command.</p> <div class="section" id="irc"> <h3>IRC<a class="headerlink" href="#irc" title="Permalink to this headline">¶</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 certificte pair specified in ssl-privatekey/ ssl-certificate for authentication.</p> </div> <div class="section" id="botnet"> <h3>Botnet<a class="headerlink" href="#botnet" title="Permalink to this headline">¶</a></h3> <p>Eggdrop can use TLS connections to protect botnet links if it is compiled with TLS support. TLS-enabled 1.8 bots are backwards compatible with bots that do not have TLS, whether because they are an earlier version or they were not compiled with TLS libraries. Depending on how the user configures the botnet, Eggdrop will use one of two methods to create a TLS connection: raw TLS sockets, and starttls. The difference is that a socket listening for TLS will first create a TLS connection before exchanging any eggdrop-specific data; a starttls connection will first establish the botnet link in the clear, then upgrade to a TLS connection (This means the nickname and, since v1.3.29, a challenge/response password hash are sent before TLS negotiation takes place- not the actual plaintext password).</p> <p>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). Additionally, Eggdrop 1.8 has starttls functionality, where a plain text connection can first be made to a non-TLS port (ie, one that is not prefixed with a plus) and then upgraded to a TLS connection. Currently, Eggdrop automatically attempts a starttls upgrade on all botnet connections. With two TLS-enabled Eggdrops, it graphically looks like this:</p> <table border="1" class="docutils"> <colgroup> <col width="34%" /> <col width="32%" /> <col width="34%" /> </colgroup> <tbody valign="top"> <tr class="row-odd"><td>Leaf bot sets hub port as...</td> <td>and Hub bot config uses...</td> <td>the connection will...</td> </tr> <tr class="row-even"><td>port</td> <td>listen port</td> <td>upgrade to TLS with starttls</td> </tr> <tr class="row-odd"><td>port</td> <td>listen +port</td> <td>connect with TLS</td> </tr> <tr class="row-even"><td>+port</td> <td>listen port</td> <td>fail. This is a known issue.</td> </tr> <tr class="row-odd"><td>+port</td> <td>listen +port</td> <td>connect with TLS</td> </tr> </tbody> </table> <ul class="simple"> <li>Currently, adding a bot with +port and connecting to a hub listening on port does not work. This will be remedied in a future release.</li> </ul> <p>To explicitly require all links to a hub be TLS-only (ie, prevent any plain text connection from being allowed), prefix the listen port in the hub configuration file with a plus (+) sign. Conversely, to force a leaf to only allow TLS (not plain text) connections with a hub, you must prefix the hub's listen port with a plus when adding it to the leaf via +bot/chaddr commands. If TLS negotiation fails and either the hub or leaf is set to require TLS, the connection is deliberately aborted and no clear text is ever sent by the TLS-requiring party.</p> </div> <div class="section" id="secure-dcc"> <h3>Secure DCC<a class="headerlink" href="#secure-dcc" title="Permalink to this headline">¶</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> </div> <div class="section" id="scripts"> <h3>Scripts<a class="headerlink" href="#scripts" title="Permalink to this headline">¶</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> </div> </div> <div class="section" id="keys-certificates-and-authentication"> <h2>Keys, certificates and authentication<a class="headerlink" href="#keys-certificates-and-authentication" title="Permalink to this headline">¶</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 therequired fields.</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-python"><div class="highlight"><pre>openssl req -new -x509 -nodes -keyout my.key -out my.crt -config ssl.conf </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, you can use the OpenSSL ssl client:</p> <div class="highlight-python"><div class="highlight"><pre>openssl s_client -cert my.crt -key my.key -connect host:sslport </pre></div> </div> </div> <div class="section" id="ssl-tls-settings"> <h2>SSL/TLS Settings<a class="headerlink" href="#ssl-tls-settings" title="Permalink to this headline">¶</a></h2> <p>There are some new settings allowing control over certificate verification and authorization.</p> <blockquote> <div><p>ssl-privatekey</p> <blockquote> <div>file containing Eggdrop's private key, required for the certificate.</div></blockquote> <p>ssl-certificate</p> <blockquote> <div>Specify the filename where your SSL certificate is located. if your bot will accept SSL connections, it must have a certificate.</div></blockquote> <p>ssl-verify-depth</p> <blockquote> <div>maximum verification depth when checking certificate validity. Determines the maximum certificate chain length to allow.</div></blockquote> <div class="line-block"> <div class="line">ssl-capath</div> <div class="line">ssl-cafile</div> </div> <blockquote> <div>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.</div></blockquote> <p>ssl-ciphers</p> <blockquote> <div>specify the list of ciphers (in order of preference) allowed for use with ssl.</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>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.</div></blockquote> </div></blockquote> <p>Copyright (C) 2010 - 2018 Eggheads Development Team</p> </div> </div> </div> </div> </div> </div> <div class="sidebar"> <h3>Table Of Contents</h3> <ul> <li class="toctree-l1"><a class="reference internal" href="../installAndSetup/readme.html">README</a></li> <li class="toctree-l1"><a class="reference internal" href="../installAndSetup/install.html">Installing Eggdrop</a></li> <li class="toctree-l1"><a class="reference internal" href="../installAndSetup/faq.html">Frequently Asked Questions</a></li> </ul> <ul class="current"> <li class="toctree-l1"><a class="reference internal" href="about.html">About Eggdrop</a></li> <li class="toctree-l1"><a class="reference internal" href="features.html">Eggdrop Features</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="partyline.html">The Party Line</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="patch.html">Patch How-To</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="ipv6.html">IPv6 support</a></li> <li class="toctree-l1 current"><a class="current reference internal" href="">TLS support</a></li> </ul> <ul> <li class="toctree-l1"><a class="reference internal" href="../coreDocs/core.html">Eggdrop Core Settings</a></li> <li class="toctree-l1"><a class="reference internal" href="../coreDocs/modules.html">Eggdrop Module Information</a></li> <li class="toctree-l1"><a class="reference internal" href="../coreDocs/assoc.html">Assoc Module</a></li> <li class="toctree-l1"><a class="reference internal" href="../coreDocs/blowfish.html">Blowfish Module</a></li> <li class="toctree-l1"><a class="reference internal" href="../coreDocs/channels.html">Channels Module</a></li> <li class="toctree-l1"><a class="reference internal" href="../coreDocs/compress.html">Compress Module</a></li> <li class="toctree-l1"><a class="reference internal" href="../coreDocs/console.html">Console Module</a></li> <li class="toctree-l1"><a class="reference internal" href="../coreDocs/ctcp.html">CTCP Module</a></li> <li class="toctree-l1"><a class="reference internal" href="../coreDocs/dns.html">DNS Module</a></li> <li class="toctree-l1"><a class="reference internal" href="../coreDocs/filesys.html">Filesys Module</a></li> <li class="toctree-l1"><a class="reference internal" href="../coreDocs/irc.html">IRC Module</a></li> <li class="toctree-l1"><a class="reference internal" href="../coreDocs/notes.html">Notes Module</a></li> <li class="toctree-l1"><a class="reference internal" href="../coreDocs/seen.html">Seen Module</a></li> <li class="toctree-l1"><a class="reference internal" href="../coreDocs/server.html">Server Module</a></li> <li class="toctree-l1"><a class="reference internal" href="../coreDocs/share.html">Share Module</a></li> <li class="toctree-l1"><a class="reference internal" href="../coreDocs/transfer.html">Transfer Module</a></li> <li class="toctree-l1"><a class="reference internal" href="../coreDocs/uptime.html">Uptime Module</a></li> <li class="toctree-l1"><a class="reference internal" href="../coreDocs/woobie.html">Woobie Module</a></li> </ul> <ul> <li class="toctree-l1"><a class="reference internal" href="../appendices/known-probs.html">Known Problems</a></li> <li class="toctree-l1"><a class="reference internal" href="../appendices/tricks.html">Eggdrop Tricks</a></li> <li class="toctree-l1"><a class="reference internal" href="../appendices/text-sub.html">Textfile Substitutions</a></li> <li class="toctree-l1"><a class="reference internal" href="../appendices/weird-msgs.html">Weird Messages That Get Logged</a></li> <li class="toctree-l1"><a class="reference internal" href="../appendices/first-script.html">Your First Eggdrop Script</a></li> </ul> <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" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> <p class="searchtip" style="font-size: 90%"> Enter search terms or a module, class or function name. </p> </div> <div class="clearer"></div> </div> </div> <div class="footer-wrapper"> <div class="footer"> <div class="left"> <a href="ipv6.html" title="IPv6 support" >previous</a> | <a href="../coreDocs/index.html" title="<no title>" >next</a> </div> <div class="right"> <div class="footer"> © Copyright 2018, Eggheads. Last updated on Dec 27, 2018. Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.3. </div> </div> <div class="clearer"></div> </div> </div> </body> </html>