Masarykovo nam. 4 Jihlava 58601 CZ +420 776 584 544 pasky@ji.cz http://pasky.ji.cz/

90 A Victoria St. N New Hamburg Ontario N0B 2G0 CA +519 662 9432 epiphani@powertrip.net

Applications IRC Internet Relay Chat CAP CAPAB Capabilities PROTOCOL Communication This memo presents a way for IRC servers and clients to negotiate optional features of the IRC protocol, mainly those which need to be explicitly supported by the client and are either backwards incompatible with the original IRC protocol or involve the format of data sent by the client.

Due to the nature of IRC development in the past decade, with most organizations expanding and altering protocol specifications at will, the protocol for communication between IRC client and server contains a lot of slight differences and special unique features depending on the particular server used. This memo aims to standardize way of announcing such optional IRC protocol capabilities to clients and way of requesting such features by clients. Due to existence of various concurrent protocols aside of IRC and because some IRC clients can support those protocols as well, this memo also covers negotiation of the protocol used for communication with the server.

Servers, when interconnected, have the ability to use various different protocol specifications, usually unique to the IRC server type. Standardizing compatible server-server communication inside of one IRC network is matter of the IRC network administration and it does not influence users. Thus, server-server protocol is not the subject of this specification.

Due to the explosive growth of IRC, many networks are experiencing serious problems with raw bandwidth usage of client servers. While optimizations have been made to the server to server protocol to reduce bandwidth usage, client side connections still make up the bulk of bandwidth usage. Due to the expanded format of original RFC 1459, there is a substantially large number of ways to address this problem without rewriting the protocol entirely.

There is a press inside of the IRC developers community to introduce non-standard but valuable and useful changes to the protocol, which could violate the original IRC specification (RFC 1459) and introduce some incompatibilities to the client-server communication, resulting in problems with some clients. Using this specification, client could select only those of these changes which it could understand. Clients supporting extensions described in this document SHOULD still be backwards compatible to the original protocol as described in RFC 1459.

The primary goals of the IRC protocol capabilities negotiation are as follows: Flexible expandable format that allows alternative capabilities negotiation systems to be put into place for further altering of the protocol. Fully transparent backwards compatibility on the both client and server side, due to the vast number of clients which will not be compliant for many years.

In order to be able to effectively set up unlimited number of capabilities in a correct way during the handshake (before user registration), special new handshake must be introduced. This handshake only differs from the regular handshake in requirement of explicitly finish. That is, the handshake MUST NOT be taken as complete by the server until the client doesn't explicitly indicate that. The special handshake involves two newly introduced commands: it is started by the HANDSHAKE command and finished by the REGISTER command.

The special handshake is started by the HANDSHAKE command. The ABNF representation for this message is:

The server responds by the HANDSHAKE message of the same format as the command has. Note that for forward compatibility, implementations SHOULD ignore any possible parameters sent along. Then, the server MUST send the CAP ENDLS message, possibly preceded by a number of CAP LS messages, as further described below. In future, some more messages MAY be inserted between the HANDSHAKE message and capabilities list.

This command is used by client to indicate that it considers its part of the handshake done and expects 001 numeric from the server. The ABNF representation for this message is: ]]>

The server responds by the 001 numeric or the appropriate error numeric if the informations sent by client were incomplete or the registration failed for some other reason. Note that for forward compatibility, implementations SHOULD ignore any possible parameters sent along the REGISTER command.

In order to preserve the backwards compatibility with the original IRC protocol, the client SHOULD send the HANDSHAKE message and then try to register using the original IRC protocol, not waiting for the HANDSHAKE reply which may not come if the server doesn't support the special handshake. If the server doesn't support HANDSHAKE, it will reply with the 001 message, otherwise it will reply with the HANDSHAKE message and it will postpone finishing of the registration until the REGISTER command will be received. Note that each server supporting the capabilities negotiation MUST support the special handshake and vice versa, thus the clients may rely on that. The client could use USER and NICK commands as many times as it wants, while the new invocation overrides settings of the previous ones. This is important because USER and NICK possibly sent before HANDSHAKE acknowledge from server count to the registration process as well, but the client may want to re-issue those commands with some of the capabilities turned on.

The capabilities negotiation is done by exchange of the CAP messages, which is usually initiated by the client. The first negotiation is expected to happen during the special handshake; obviously the client could negotiate even during the regular handshake, but it SHOULD NOT since there's no clean lag-prune method to do that while staying backwards compatible. Also, there is no known reason why the special handshake should not be used and it provides flexible base for further extensions of the registration process.

Capabilities negotiation happens through the CAP (short for CAPabilities) command. The ABNF representation for this message is: Note that the value obviously MUST NOT contain any whitespace characters.

The CAP command can be issued at any time by client, even during the client registration. Server MUST NOT send request CAP messages, only the informational ones.

This message is used to request or announce the list of supported capabilities. Only the client sends the capabilities list request and only the server sends the list of them. The list can take multiple CAP LS messages, if it would exceed the 512 characters limit; see also CAP ENDLS. When requesting the capabilities list, no extra parameters should be sent. If the message is the capabilities list announcement sent by server, a list of capability tokens is sent as third parameter, unless there are no particular capabilities supported. Note that the capabilities list can vary depending on the capabilities already selected by client, so the new capabilities list SHOULD be re-retrieved by client each time the client will turn on some capabilities successfully.

Each chain of CAP LS MUST be terminated by a CAP ENDLS message, indicating that no more CAP LS messages will come, as the one list can take more than one CAP LS message. Note that this message MUST be sent even if only one message is going to take the whole list; then, the server can send only the CAP ENDLS message standalone, without any preceding CAP LS messages. The syntax of the CAP ENDLS message is same as the syntax of CAP LS message.

This message is used by client exclusively to turn on certain IRC protocol capabilities. The client sends a list of capability tokens. The server replies with either CAP ACK or CAP NAK. Note that if tokens already set are included in the list, the capability value is updated, if it's relevant for the value type (no value means that the old value is kept and the token is silently ignored).

This message is used by server to acknowledge the CAP RQ command previously issued by client. It contains a list of capability tokens acknowledged by the server (same or subset of the list of capability tokens in client's CAP RQ). The server starts sending of the messages using the new capability tokens immediately after sending the <crlf> terminating this CAP ACK message. The client has to respond to this message by another CAP ACK message which MUST contain the same list of capability tokens; then, it MUST start using those capabilities immediately after sending the <crlf> terminating this CAP ACK message.

This message is used by server to indicate some problem with the list client sent along the CAP RQ command. It means that none of these capabilities become effective, and no changes in the active capabilities list are not made by the server. The server SHOULD send the list of capabilities with unknown name (or conflicting with another capability being set already) or inappropriate value along this message, with same restrictions of their list as in CAP LS, unless the server couldn't properly parse the list received from client.

These tokens are formed by optional prefix, capability name and optional capability value, as described in the ABNF above. The name length MUST NOT exceed 20 characters nor be shorter than 3 characters. It SHOULD be chosen as short as possible, while staying meaningful. Only one prefix is defined now - a dash ('-'). If it is specified, it means that the capability MUST be reset to the default value (and the "boolean" capability MUST be turned off, as all boolean capabilities are off by default). Note that it may not be possible to turn off some capabilities (probably for example TLS) once they are turned on - server then MUST send a CAP NAK for that capability (obviously not including the dash in the capability token). Note that some capabilities may not be available all the time, but could be offered by the server only when some other capability(ies) is (are) already turned on. So, the capabilities can be theoretically formed in a virtual tree. The list of tokens is limited only by the 512 characters maximal IRC message length (thus, the effective length is 512 without the length of the message preceding it (ie. 502 characters for "CAP LS :...\r\n")). The usual 15 parameters limit for IRC message does not apply, as the whole capabilities list is prefixed by a ':', thus should be recognized as a single string by the current IRC message parsers. The concrete tokens (names and possibly value types) will be defined in further documents published by the IRC development community.

The basic example of the complete negotiation with the conforming server: HANDSHAKE CLIENT> USER foo - - :text CLIENT> NICK bar SERVER> HANDSHAKE SERVER> CAP LS :cap1 cap2 cap3 cap4 SERVER> CAP ENDLS :cap5 cap6 CLIENT> CAP RQ :cap2 cap3=11,cap7 SERVER> CAP NAK CLIENT> CAP RQ :cap2 cap3=11 cap7 SERVER> CAP NAK :cap7 CLIENT> CAP RQ :cap2 cap3=11 SERVER> CAP ACK :cap2 cap3=11 CLIENT> CAP ACK :cap2 cap3=11 CLIENT> CAP LS SERVER> CAP ENDLS :cap1 cap2 xcap1 xcap2 xcap3 CLIENT> REGISTER SERVER> :irc.xy.com 001 bar :Welcome ]]>

The basic example of the complete negotiation with an old server: HANDSHAKE CLIENT> USER foo - - :test CLIENT> NICK bar SERVER> :irc.xy.com 001 bar :Welcome ]]>

The secondary purpose of this document is to provide a framework for definition of protocol enhancements. Documents will be published as Internet Drafts and possibly RFCs, after a careful review by the IRC development community. The actual list of PROTOCOL and CAP tokens will be published by Internet Assigned Numbers Authority (IANA). The IRC development community, as used in this document, is defined as the authors of prominent software in use. Currently, this consists of - but is not limited to - the development teams for the major IRC networks (including DALnet, EFnet, IRCnet and Undernet), as well as the development teams for the client packages - currently irssi, BitchX, EPIC, IRCle, and mIRC. These people (as now) are listed below.

All further specifications MUST be reviewed by the development community. In order for this review to take place, the author MUST contact the protocol discussion email list. The current list address is proto-desc@dal.net. The administrative contact for this list is epiphani@dal.net.

In order to prevent possible disclosure of any confidential information, any security-related capabilities SHOULD be issued as soon as possible, preferably already during the client registration. This involves for example TLS setup.

There SHOULD be set some alias for the administrative contact for the proto-desc mailing list; RFCs are hard to update. --cras (editor's note: they are impossible to update except typos which can be covered by errata)

Tuirantie 17 as 9 Oulu 90500 FI jto@tolsun.oulu.fi

4 Pateman Street Watsonia Victoria 3087 AU avalon@coombs.anu.edu.au

dcrocker@imc.org

paulo@turnpike.com

The authors especially gratefully acknowledge the contributions of: Lee Hardy, Timo Sirainen, Kurt Roecx, Simon Butcher, Piotr Kucharski, Jakub Vlasek and others.