$Id: TLS,v 1.2 2010/10/20 13:07:13 pseudo Exp $

TLS support
Last revised: Oct 17, 2010
    _____________________________________________________________________

                         TLS support


  This document provides information about TLS support which is a new
  eggdrop feature since version 1.8.0.

  Contents:
    1. About
    2. Installation
    3. Usage
       3a. IRC
       3b. Botnet
       3c. Secure DCC
       3d. Scripts
    4. Keys, certificates and authentication
    5. SSL settings


  1. About

    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.


  2. Installation

    ./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.


  3. Usage

    By default, without additional configuration, TLS support will provide
    opportunistic encryption for botnet links. For other connection types,
    TLS must be requested explicitly.
    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.

  3a. IRC

    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.

  3b. Botnet

    Botnet links between TLS-enabled bots will automatically switch to SSL.
    In this case however, the nickname and password will be sent before SSL
    negotiation takes place (the password is not send as cleartext anyway).
    If one of the bots doesn't support TLS, the connection will fall back to
    plain text. To require SSL explicitly, you need to open a ssl telnet
    port on your hub and prefix the port number with + when adding it on your
    leafs. For SSL-only bot links, all communication is encrypted, including
    sending the nickname and password. If SSL negotiation fails, the
    connection is deliberately aborted and no clear text is ever sent.

  3c. Secure DCC

    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.

  3d. Scripts

    Scripts can open or connect to SSL 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 SSL at the same
    time - the synchronization is the script's job, not eggdrop's.)


  4. Keys, certificates and authentication

    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 SSL 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. This will generate a 2048-bit private key
    (eggdrop.key) and a certificate (eggdrop.crt) after you fill in the
    required fields.
    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 SSL 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:

      openssl req -new -x509 -nodes -keyout my.key -out my.crt -config ssl.conf

    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:

      openssl s_client -cert my.crt -key my.key -connect host:sslport 
    

  5. SSL Settings
 
    There are some new settings allowing control over certificate
    verification and authorization.

       ssl-privatekey
         file containing Eggdrop's private key, required for the certificate.

       ssl-certificate
         Specify the filename where your SSL certificate is located.
         if your bot will accept SSL connections, it must have a certificate.

       ssl-verify-depth
         maximum verification depth when checking certificate validity.
         Determines the maximum certificate chain length to allow.

       ssl-capath
       ssl-cafile
         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.

       ssl-ciphers
         specify the list of ciphers (in order of preference) allowed for
         use with ssl.

       ssl-cert-auth
         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.
         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.

       ssl-verify-dcc
       ssl-verify-bots
       ssl-verify-server
       ssl-verify-clients
         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.

    _____________________________________________________________________
	
  Copyright (C) 2010 Eggheads Development Team
