This site is deprecated; docs have moved to docs.inspircd.org!

STARTTLS Documentation

From the makers of InspIRCd.
Revision as of 13:00, 31 December 2008 by Brain (Talk | contribs)

Jump to: navigation, search

What Is STARTTLS?

STARTTLS is a protocol feature commonly found in e-mail protocols, which allows SSL and plaintext connections to co-exist on the same port. This is useful as it simplifies firewall rules (only requiring one port to be opened rather than two) and adds user-friendliness as the user must only know one port (in IRC's case, port 6667). On InspIRCd, the STARTTLS extension requires m_cap.so and m_ssl_gnutls.so.

IRC STARTTLS is an open standard, and we encourage all client developers and IRC Daemon developers to implement it where possible, to provide more choice for users. This protocol is very easy to implement if your client/ircd already supports SSL, and even easier if it also already supports the CAP extension.

How does it work?

To use STARTTLS a client simply sends STARTTLS to the server before the client registers with the server using the NICK and USER commands. After sending this command both client and server switch to TLS/SSL mode, based upon the plaintext numeric reply generated by the STARTTLS command, and cannot switch back to plain text mode. The client must then send an SSL/TLS handshake to the server and the connection continues in the same manner as one on a dedicated SSL port (such as 6697).

What is TLS, compared to SSL?

TLS is a newer name for the SSL protocol suite. Both protocols are inter-operable and a client may use OpenSSL, for example, to implement the STARTTLS protocol.

How does an IRC client know that TLS is available?

There is a somewhat standardised method of determining server capabilities, called the CAP extension which is implemented in ratbox and all derivatives, and InspIRCd and derivatives. CAP is also under consideration by the Undernet and IRCNet developers. Sending 'CAP LS' to enumerate the capabilities of the server (before client registration) will return the tls capability in the list if STARTTLS is available. For this to function, the InspIRCd server must load the m_cap module.

It is important to note that if m_cap is not loaded or a server does not support CAP at all, then CAP LS will generate no output. In this case a client should implement some form of time-out or error handling for this situation. The details of implementing this behaviour are left to the client author.

Example CAP negotiation where TLS is available

<< :test2.chatspike.net NOTICE Auth :*** Looking up your hostname...
<< :test2.chatspike.net NOTICE Auth :*** Found your hostname (brainwave.brainbox.cc) -- cached
>> CAP LS
<< :test2.chatspike.net CAP * LS :sasl userhost-in-names tls multi-prefix
>> STARTTLS
<< :test2.chatspike.net 670 nickname :STARTTLS successful, go ahead with TLS handshake

           (tls handshake goes here)

>> CAP END

It is worth noting here that a client may request the tls capability with CAP REQ, but this won't affect that client's ability to later send the STARTTLS command. The STARTTLS command will always operate on servers which advertise the capability regardless of if the client requests the capability or not.

If there was a failure initialising TLS, you would instead receive the 671 numeric:

<< :test2.chatspike.net 691 nickname :STARTTLS failure
>> CAP END

After receiving the 670 numeric, the client immediately sends the TLS handshake, which will cause the server to respond in a similar fashion. In the case that the 671 error numeric is received, the client should take action to warn the user that their connection will not be secured, or potentially take other automatic action such as disconnecting from the server to avoid plaintext, or reconnecting to a dedicated SSL port.

It is relatively safe for the client to wait after STARTTLS for one of the 670 or 671 numerics, as one or the other can always be guaranteed as a response from the STARTTLS command if it exists.

Handling errors

  • In the case that the STARTTLS command fails (e.g. the user has ticked some client checkbox to enable STARTTLS, but the CAP command does not respond at all, or responds without the tls capability) then it is the client author's responsibility to make the user completely aware that their connection is still plaintext and they should exercise caution. It is recommended that an option to disconnect (even so far as to be made the default behaviour) should be provided in this case.
  • If a client tries to send STARTTLS twice, the second request (and third, etc) will generate the 671 numeric for TLS failure.
  • If a client tries to send STARTTLS after USER, NICK or PASS, then the client connection will be closed and sent a plaintext ERROR string.
  • If an error occurs and the user has specified an absolute requirement on TLS/SSL, then the client should reconnect to a dedicated SSL port if available, or not connect at all without the user reconfiguring the client.

Clients With STARTTLS Support

External references