TOPIC (EXPERIMENTAL)

transport layer security

DESCRIPTION

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

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(E), tls_deinit_connection(E), tls_error(E), tls_query_connection_info(E), tls_query_connection_state(E)).

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

  1. in telnet_neg(H)

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(E) to initiate the TLS handshake.

  1. in connect(M)

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(E) as first command after the player connected (normally in connect(M)).

  1. 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(E) 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.

Misleading

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

HISTORY

  • introduced (3.3.474)
  • backported (3.2.11)