doc/concepts/tls

PRELIMINARY
CONCEPT
        tls (transport layer security)

DESCRIPTION
        TLS stands for Transport Layer Security which is the successor
        of the well known SSL (Secure Socket Layer). Both techniques
        provide a way to authenticate and encrypt the data send through
        a network connection.

        By enabling TLS during compilation of the driver you can provide
        a secure channel into the mud to your players.

        In difference to other solutions as "sslwrap" or "stunnel" the
        driver integrated approach has the advantage that the mud sees
        the real IP of the player, not the IP of the local mud host.

USAGE
        To use TLS configure your driver with --enable-tls option.
        After starting your driver you have five new efuns
        (tls_init_connection(), tls_deinit_connection(), tls_error(),
        tls_query_connection_info(), tls_query_connection_state()).

        You can switch on TLS by calling tls_init_connection().
        This can happen in three ways:

        1) in telnet_neg()

            Advantage of this method is that you can offer TLS on a normal
            mud port. If you have a limited number of ports this can
            become important. The TLS connection will be started by
            the client with help of telnet option STARTTLS. Currently
            there are no mudclients that support this method.

            You will have to implement the telnet option STARTTLS (46) for
            this method. The draft for this can be found here:
            http://www.ietf.org/proceedings/99mar/I-D/draft-ietf-tn3270e-telnet-tls-01.txt
            Call tls_init_connection() to initiate the TLS handshake.


        2) in master_ob->connect()

            Advantage of this method is that your users can connect with
            any program that supports TLS/SSL. Examples are telnet-ssl,
            sslwrap or stunnel. Disadvantage is that you have to spend
            a dedicated port for this.

            You have to call tls_init_connection() as first command
            after the player connected (normally in master_ob->connect())

        3) in an interactive object using a callback.

            This method is similar to method (1), but not limited to
            telnet: it is useful for implementing protocols that use
            STARTTLS like SMTP or IMAP. tls_init_connection() can be
            called at any time by the interactive object.

            You must not write to the connection after calling this
            efun until the callback is executed (the prompt will
            be supressed automatically during this time).

        To test your code, you can use the openssl binary.
        `openssl s_client -connect host:port' should display your certificate
        and anything you write after the callback is executed. If you
        encounter the error message `SSL3_GET_RECORD: wrong version number'
        you're probably writing to the connection while you should not.

BUG
        This manpage might be not quite up to date with the implementation.

HISTORY
        Introduced in LDMud 3.3.474 and following, backported to 3.2.11.

SEE ALSO
        tls_* efuns