Network Working Group A. Church Request For Comments: nnnn February, 2002 Obsoletes: 1459 Category: Experimental The Internet Relay Chat Protocol, Version 3 Status of this Memo This memo defines an Experimental Protocol for the Internet community. This memo does not specify an Internet standard of any kind. Discussion and suggestions for improvement are requested. Distribution of this memo is unlimited. Abstract Internet Relay Chat (IRC) is a client/server protocol allowing Internet users to engage in realtime "conversation". It has existed for a number of years, and the use of IRC has grown rapidly during that time. IRC has classically been a purely text-based protocol allowing for simple text-based interaction, as described in RFC 1459 [1]; however, current usage and trends demand a more efficient method for allowing IRC servers to communicate with each other than defined by the original protocol, as well as more stability than that protocol allows. In addition, as bandwidth availability increases, IRC should be extensible enough to allow other forms of communication, such as audio and/or video. Finally, the wide range of incompatible changes made to the protocol suggest that a new, extensible standard be defined to alleviate these incompatibilities. This protocol was given the name "version 3" due to the reference RFC1459 implementation being known as "ircII" (IRC 2). Table of Contents 0. Preface 0.1 Acknowledgements 0.2 Terminology 1. About IRC 1.1 Servers 1.2 Clients 1.2.1 IRC operators 1.3 Requirements for clients and servers 1.4 Channels 1.4.1 Channel operators 1.5 Unicode 1.6 Communication 1.6.1 The shortest-path algorithm 1.6.2 Network topology changes 1.6.3 One-to-one messages 1.6.3.1 Inter-network messages 1.6.4 One-to-many messages 2. The IRC specification 2.1 Strings 2.2 Messages 2.2.1 Client messages (commands) 2.2.2 Server messages 2.2.3 Replies 2.2.4 Acknowledgements and acknowledgement requests 2.3 Summary of message flag bits 2.4 Timestamps 2.5 Text transmission 3. Message details 3.1 Connection registration and cancellation 3.1.1 Password message 3.1.2 User message 3.1.2.1 A note on the Ident Protocol 3.1.3 Server message 3.1.4 Remote server message 3.1.5 Network message 3.1.6 Quit message 3.1.7 Server quit message 3.2 Message sending 3.2.1 Public messages 3.2.2 Private messages 3.2.3 Notices 3.2.4 Server notices 3.2.5 Operator messages 3.2.6 Global messages 3.3 Channel operations 3.3.1 Join message 3.3.2 Part message 3.3.3 Channel mode message 3.3.4 Topic message 3.3.5 Channel operator message 3.3.6 Channel voice message 3.3.7 Kick message 3.3.8 Channel ban message 3.3.9 Invite message 3.4 User control messages 3.4.1 Nick message 3.4.2 Away message 3.4.3 Silence message 3.4.4 User mode message 3.4.5 Operator message 3.4.6 Kill message 3.4.7 Server ban message 3.4.8 Network ban message 3.5 Server control messages 3.5.1 Connect message 3.5.2 Disconnect message 3.5.3 Rehash message 3.5.4 Restart message 3.5.5 Die message 3.6 Query messages 3.6.1 Who message 3.6.2 Names message 3.6.3 List message 3.6.4 Whois message 3.6.5 Whowas message 3.6.6 Ison message 3.6.7 Users message 3.6.8 Message of the Day message 3.6.9 Administrative information message 3.6.10 Server information message 3.6.11 Server version message 3.6.12 Statistics message 3.6.13 Links message 3.6.14 Trace message 3.6.15 Time message 3.7 Miscellaneous messages 3.7.1 Ping message 3.7.2 Pong message 3.8 Reserved message codes 3.9 Erroneous messages 3.10 Use of experimental message codes 4. Replies 4.1 Command responses 4.2 Error messages 4.2.1 Syntactical errors 4.2.2 Functional errors 4.3 Reserved reply codes 5. Problems and limitations 5.1 Scalability 5.2 Name collisions 5.2.1 Nickname collisions 5.2.2 Server name or ID collisions 5.2.3 Channel collisions 5.2.4 Network name collisions 5.3 Timekeeping 5.4 Connection desynchronization 5.5 Cyclic networks 6. Security considerations 6.1 IP spoofing 6.2 DNS spoofing 6.3 Network sniffing 6.4 Time overflow 6.5 Special characters in names 7. Author's address 8. References and notes 9. Copyright notice Appendix A: Dijkstra's algorithm Appendix B: Alphabetical index of message and reply elements Appendix C: Conversion table for the RFC 1459 protocol 0. PREFACE 0.1 Acknowledgements The author wishes to acknowledge the assistance of Ian Justman, Andrew Kempe, and Trevor Talbot, among many others, for offering suggestions on this document and the protocol defined therein. The author also wishes to acknowledge an IRC protocol proposal by Steven Arnold [2] for providing the idea for inter-network communication. 0.2 Terminology This document describes a number of requirements for the Internet Relay Chat protocol. It also explains the reasoning behind those requirements; the author realizes that there may be reasons for or against including particular elements of the specification in a particular implementation, and the explanations will help in making those decisions. At the same time, implementors cannot have complete freedom in choosing what parts of the protocol to implement, or there would be little to no compatibility between different versions -- as has already been demonstrated by the wide variety of IRC server implementations currently available, many of which cannot communicate with each other due to changes introduced into the protocol by each particular implementation [3]; the author is personally aware of no less than six variant protocols, none of which are compatible with each other or with the original RFC 1459 [1] specification. Hence, this document uses the terms "MUST", "SHOULD", "MAY", "SHOULD NOT", and "MUST NOT" to indicate elements of the protocol are required and which are merely suggested. Whenever these words are used in this sense, they are capitalized. These terms are to be interpreted as defined in RFC 2119 [4]. Additionally, the terms "old protocol" and "original protocol" refer to the IRC protocol described in RFC 1459 [1]. The word "iff" (as opposed to "if") has its standard logical meaning of "if and only if." 1. ABOUT IRC The Internet Relay Chat (IRC) protocol has been designed over a number of years as a text-based realtime communication protocol. This document describes a new protocol intended to replace the original IRC protocol; this protocol is designed to achieve better performance and more flexibility than the original protocol. The author recognizes the well-tested principle that extending an old protocol is better than designing a new one; however, with the many IRC implementations in existence that are not compliant--or even compatible--with the original protocol, and with the inherent limitations of the text-based communication model of that protocol, it is the author's belief that creating a new protocol, using many of the concepts from the old one but providing a different, more flexible structure, would be more beneficial than simply revising the old protocol. While this document stands on its own, it is assumed that many of the readers of this document, at least in its early days, will be familiar with the old protocol, and thus notes are made occasionally on similarities and differences between the old protocol and the protocol defined by this document. IRC uses the client-server model; it is best suited to running in a distributed environment, with individual systems acting as servers for the users' clients and for other servers. An IRC client may be any program capable of sending data through a data network to an IRC server, though due to the binary nature of this protocol, it is assumed that users will use some sort of client program to mediate between the raw protocol data and more easily human-viewable information, such as text, audio, or video. 1.1 Servers The backbone of the IRC network is the server. Servers act as central points for IRC clients to connect to, and also for other servers to connect to, forming an IRC network. If each server on the network is a vertex of a graph, then the entire network forms a graph which is fully connected; i.e. there is at least one path from any server to any other server. Note that there may be multiple paths between any two given servers, but there may be no more than one direct connection between any two servers. See Figure 1 for an example IRC network. 14 15 1 9 / \ / \______ | / \ / \|/ 3----2-----------8-----10 \ ___/| \ ,---' _| 4-----5-' /| \ / | \ 6 | _,--11----12 7---' \ \ 13 [Figure 1: Sample IRC network] Servers have the responsibility of maintaining a complete image of the IRC environment -- the sum of the information about all clients and servers connected to the IRC network -- and ensuring that it remains consistent and obeys certain rules. Under this protocol, each server is identified by a unique 16-bit integer sent in the server registration message (see section 3.1.3). This identifier is included in all server-to-server messages. Each server is also assigned a name; this name MUST be no more than 63 characters in length, and MUST NOT contain the character with value zero (ASCII NUL). All other characters are legal; however, for compatibility with older clients, servers SHOULD NOT use names with the space (" ", ASCII 0x20), comma (",", ASCII 0x2C), or CR/LF (ASCII 0x0D and 0x0A) characters, as those are delimiters under the old protocol. Note that this identification scheme only allows up to 65,536 servers to exist in a single network. While the author believes this to be more than sufficient for the foreseeable future, the server ID value 65,535 (hexadecimal FFFF) is reserved for future use should the need arise. Servers MUST NOT use this value when registering, and a which receives a server registration message with this value MUST reject it. 1.2 Clients A client (also known as a user) is essentially anything connected to the IRC network that is not a server. Each client, when it registers its connection (see section 3.1.2), is assigned a 16-bit non-zero identifier which is unique among all clients connected to the same server (zero is used to represent the server itself). Thus, any client or server on the IRC network can be uniquely identified by a combination of the client's ID (zero in the case of a server) and the ID of the server that the client is connected to (the server's own ID in the case of a server). This client ID is used only by servers, and is not seen by clients. Note that this identification scheme only allows for 65,535 clients to be connected to a single server. While the author believes this to be sufficient for the near future, the client ID 65,535 (hexadecimal FFFF) is reserved for future use should the need arise. Servers MUST NOT assign this ID to any client. (This reduces the maximum number of clients per server to 65,534.) Under this scheme, the maximum number of clients on a network is 65,535 (servers) * 65,534 (clients per server) = 4,294,780,690. As this number is currently greater than 2/3 of the world's population, it is considered sufficient for the foreseeable future. Furthermore, should it be necessary to split clients among two or more networks, those clients can still communicate with each other via inter-network messages (see section 1.6.3.1). When a client registers its connection, it gives a "nickname" by which it will be known to all other clients. This allows a particular client to be known by a single identifier regardless of the server to which the client connects or the client ID assigned by that server. The nickname MUST be no longer than 31 characters, and has the same restrictions (except for length) as server names; again, for compatibility with older clients, newer clients SHOULD NOT allow users to select nicknames with the space, comma, or CR/LF characters, as those are delimiters under the old protocol. The character "!" (ASCII 0x21) also SHOULD NOT be permitted, since it is used to delimit nicknames from usernames in the old protocol. Additionally, clients SHOULD NOT allow nicknames that begin with "#" or "&", as those are used at the beginning of channel names (see section 1.4), and while this protocol has no ambiguity between nicknames and channel names, it may be difficult for a human user to distinguish between the two. Case is not relevant in nicknames. (Compatibility note: The old protocol required three pairs of non-alphabetic characters to be pairwise equivalent: "[" and "{"; "]" and "}"; and "\" and "|". These six characters are all distinct in this protocol.) Each client also has an address in the form "user@host" associated with it, where "user" is the username of the client (e.g. a Unix login name) and "host" is the fully-qualified domain name or IP address of the host from which the client connected. The hostname is determined by the server; the username is sent by the client, and obeys the same restrictions as the nickname. 1.2.1 IRC operators In an ideal world, IRC would be a completely automated system; users would be able to connect, converse, and disconnect with no troubles or interruptions. However, the real world is far from ideal, and human intervention is often required to keep the IRC network in optimal condition. These users are known as "IRC operators", and have the ability to make changes which affect the IRC environment, including disconnecting and reconnecting servers (see sections 3.5.1 and 3.5.2) and forcibly removing troublesome users from the IRC network (see sections 3.4.6 and 3.4.7). Obviously, IRC operators should be chosen with care, as a malevolent IRC operator could potentially disrupt the entire IRC network. Note that, while this document only specifies two levels of client privilege -- normal client and IRC operator -- a particular server MAY define additional privilege levels. In addition, servers MAY define additional authentication methods for accessing any privilege level (see section 3.8 on command codes which are designated for experimental or local use). If a network successfully implements such a scheme and finds it useful, the author would appreciate a well-written description of that scheme for possible inclusion in a revision of this protocol. However, regardless of how many or what privilege levels exist on a server, normal (unprivileged) clients MUST NOT be able to execute any functions which require IRC operator privileges in this protocol description. 1.3 Requirements for clients and servers Both clients and servers MUST be capable of sending and receiving arbitrary data octets. Servers MUST use the current protocol (the protocol defined in this document) for transmitting data to other servers compatible with this protocol; servers SHOULD recognize both the old and current protocols, and MUST communicate with a client or server using the same protocol the client or server registered with. 1.4 Channels A channel is a named group of one or more clients which will all receive messages addressed to that channel. A channel is implicitly created when the first client joins it, and it ceases to exist when the last client leaves it. A channel name is a string which consists of up to 63 characters. Channel names MUST obey the same restrictions as server names: no NUL, space, comma and CR/LF are discouraged, names are case-insensitive. However, the first character of a channel name has certain limitations; see below. There are two distinct types of channels defined by this protocol: distributed channels and local channels. Distributed channels are are broadcast to all servers in the IRC network, and must therefore have names that are unique among all distributed channels on all servers. Local channels are not broadcast to any servers; only clients on the same server will be in the same local channel. Two or more servers may have local channels with exactly the same names, but clients in one server's channel will know nothing of clients in another server's channel, as the two channels are completely separate. The type of channel (distributed or local) is determined by the first character of the channel name; if the first character is "#" (ASCII 0x23), the channel is distributed, and if "&" (ASCII 0x26), the channel is local. Implementations MAY define meanings for other initial characters, but MUST treat a channel with an unrecognized first character exactly as if the channel's first character was a "#". In order to become part of a channel, a client sends a "join" command (see section 3.3.1). If the channel does not already exist, it is created, and the client becomes a channel operator. If the channel does exist, the client's request to join the channel may be denied depending on the channel status; the channel may be invite-only, for example, or the client may be banned from the channel. See section 3.3.3 for a full description of channel modes. 1.4.1 Channel operators As IRC operators are to the IRC network, so are channel operators to their channels. A channel operator (also called "chanop" or simply "op") has full control of his or her channel, including the ability to set channel modes, invite users into the channel, and forcibly remove ("kick") users from the channel. There may be multiple channel operators for a single channel. As with network-level privileges, individual servers or implementations MAY define additional privilege levels or authentication schemes, but MUST obey the restrictions set forth in this document as to what unprivileged users are permitted and not permitted to do. Furthermore, individual servers or implementations MAY allow users with IRC operator privileges or other locally-defined privileges to perform channel actions which are normally restricted to channel operators and/or clients in the channel, even when the privileged user is not a channel operator or is not in the channel. 1.5 Unicode As of the writing of this document, the most common system for encoding characters in digital form is to use an eight-bit encoding system such as ASCII or ISO 8859; some languages, such as Japanese, which require more than eight bits to represent characters use a 16-bit system such as ISO-2022-JP. Currently, there is a movement to establish a wide-character standard, known as Unicode, to allow encoding text in all major languages using a single character set. However, problems with this encoding are emerging; in particular, users of the so-called "CJK" languages (Chinese, Japanese, and Korean, all of which use ideographs numbering in the thousands) have noted that the Unicode definition does not include all characters necessary for their languages, or has in some cases inappropriately combined characters from different languages into a single glyph. Moreover, the incredible amount of text that currently exists in 8-bit format and tools which process and/or display them suggest that even if a 16-bit standard such as Unicode were to be accepted worldwide, it would take a good deal of time before such a system became standard. Nonetheless, it is desirable to at minimum provide a framework for such a character set should it come into use. Therefore, two flags in the message structure (see section 2.2) are reserved for this purpose, although their meaning is left undefined. Should such a character set become widely accepted and used, this protocol will be revised to include concrete support for that character set. 1.6 Communication Messages in the IRC protocol take one of two general forms: one-to-one (one sender, one recipient) or one-to-many (one sender, multiple recipients). All messages travel via the shortest path from the sender to each recipient. 1.6.1 The shortest-path algorithm For any message from or to a directly connected client, the shortest path is obvious; however, in order for a message between servers (or from a server to a remote client) to traverse the IRC network, the servers need to know what path to send it along. Servers MAY use any method they choose to calculate the shortest path to other servers; a description of Dijkstra's algorithm, an algorithm for finding the shortest path from one node in a graph to all others, is presented in Appendix A. Typically, all links will be assigned equal weight, although in some circumstances, it may be preferable to assign a larger weight to a server on a slow link, or to assign weights based on round-trip packet times. However, every server on a network MUST use the same method for computing weights, so that all servers compute the same shortest paths. (Otherwise, some messages may be sent in cycles and ultimately discarded without reaching their destinations.) When sending a message to another server, the sender MUST append its server ID to the path field of the message (this is described in detail in section 2.2); a server MUST NOT send a message to a server which is listed in the message's path field, and a server receiving a message with its own ID in the path field MUST discard the message. Note that only the first server on the path is relevant, as that server will determine where next to pass the message (to another server or to a client on that server). When there are two or more equivalent paths, any of them may be chosen. Servers MAY precalculate the first server on the shortest path to every other server on the IRC network; however, servers that do this MUST update their tables whenever a server is added to or removed from the network. The following examples are based on the sample network in Figure 1, above. All links are assumed to have the same weight. Example: Message from server 2 to server 8. Servers 2 and 8 are directly connected, so the shortest path is simply 2->8 (server 2 sends the message to server 8). Example: Message from server 3 to server 8. There are several distinct paths from server 3 to server 8. However, the shortest one is 3->2->8. Note that server 2, when it receives the message from server 3, considers the message to now be one from itself to server 8 for the purpose of routing, and sends the message to server 8 as described in the previous example. Example: Message from server 4 to server 11. Here, there are two shortest routes: 4->5->11 and 4->7->11. Server 4 may send the message either to server 5 or to server 7; whichever it chooses will then forward the message to server 11. 1.6.2 Network topology changes Over the course of time, the topology of an IRC network will change. New servers may join the network, servers may leave the network, routing faults between servers may disrupt connections between servers. In these situations, servers must adjust their routing tables to compensate for the new or removed servers. One important effect of such network topology changes is that they may change the route taken by messages from one server to another. Consider, for example, the simple network shown in Figure 2: 1 3 \ / \ / 2 [Figure 2: Small network with no cycles] In this network, messages from server 1 to server 3 are passed through server 2. Now suppose that server 1 decides to establish a direct connection to server 3, resulting in the network shown in Figure 3: 1-----3 \ / \ / 2 [Figure 3: Small network with a cycle] If server 1 then immediately sends a message over the direct connection to server 3, that message may reach server 3 before a message sent earlier via server 2. Alternatively, in the state shown in Figure 3, the connection between servers 1 and 3 may be broken, either deliberately or as the result of network problems; in this case, any messages in transit between servers 1 and 3 at that instant would have to be retransmitted via server 2. In order to ensure that all information is properly transmitted, all servers MUST retain a copy of each message in local storage until all recipients of the message have acknowledged it; MUST request an acknowledgement (see section 2.2.4) from any server for which a direct connection has been established, before sending any messages over the connection, and for which a direct connection has been terminated, through the remaining shortest path; and MUST retransmit (via the new shortest route) any messages the remote server indicates it has not received. *** FIXME: this is basically redoing TCP, can we do any better without requiring a fully interconnected network? 1.6.3 One-to-one messages There are three types of one-to-one messages: client-to-server, server-to-client, and server-to-server. Messages travel from the sending server (or the sending client's server) to the destination server (or the destination client's server) using the shortest-path algorithm described in section 1.5.1. - Client-to-server: All mesages from clients. While some messages from clients will actually have other clients as their destinations, such messages are only ever sent to the server to which the client is connected. - Server-to-client, server-to-server: Ping messages to determine whether an inactive link is still connected. 1.6.3.1 Inter-network messages A special subset of one-to-one messages are messages sent between a server on one IRC network and a server on another IRC network. This type of communication alleviates the scalability problem with this protocol (see section 5.1) by allowing clients from different networks to communicate with each other. This inter-network communication is accomplished through "border servers" which connect to other networks and identify themselves as such. In Figure 4, below, servers A4 and B1 are border servers for networks A and B, respectively. Network C is currently isolated from the other networks. Network A Network B Network C A1----A3---A5 B2---B3 C1----C3 | / | / | | / | / | | / | / | A2----A4------------B1 C2----C4 [Figure 4: Three IRC Networks with Border Servers] To identify networks, a simple arbitrary string, obeying the same restrictions as for server names (see section 1.1), is used, since if a numeric identifier (as for servers and clients) were used, it would be difficult to ensure that every network in existence used a different identifier, while network names are generally better known. To establish an inter-network connection, a server on one network sends a "remote server" message (see section 3.1.4) to a server on another network. If the connection is permitted, both the sender and the receiver of the message send out "new network" messages to the rest of the servers on their own networks identifying themselves as border servers (see section 3.1.5). If server B3 in Figure 4 were now to make a connection as a remote server to server C1, then it would inform all servers on network B of the new connection; likewise, server C1 would inform all servers on network C of the connection to network B. However, note that server B1 would not pass the remote network message along to server A4; in order to pass messages from network A to network C, a server on network A would have to connect directly to a server on network C. See section 5.1 for a discussion of the reasoning behind this decision. If a client on network A wishes to send a message to a client on network B, the client would include the name of network B in its message and set a flag bit marking the message as for a remote network (see section 2 for information about the message format). The client's server would then forward that to the nearest border server for network B (A4), which would forward it to the server on network B to which it was connected (B1). That server would then either deliver the message to the destination client or return an error message (which would be returned via the border server on network A). Likewise, a client on network B could join a channel on network A; any messages then sent to the channel by clients on network A would be sent to server A4, which would forward them to server B1 for the client on network B. In all cases the messages would include the "remote network" flag to distinguish the client on network B from any client on network A which shared the same server and client identification numbers and might otherwise be confused with the client on network B. 1.6.4 One-to-many messages There are two types of one-to-many messages: server-to-clients and server-to-servers. The former includes all messages sent to a channel by a client, all channel state changes (which are sent to all clients on the channel), and global messages sent by IRC operators; the latter includes all state changes and all messages with targets on servers other than the one the message originated from. In the latter case, the message is sent from the source server to all servers along the shortest paths to all destination servers / destination clients' servers, using the shortest-path algorithm described in section 1.5.1. In order to prevent messages from travelling in cycles, a message from one server to another includes a hop list containing the ID numbers of the servers through which the message has passed. Also, to prevent a server from processing a message twice which reaches it through two different paths, a message sequence number method is employed similar to TCP [5] sequence numbers. See section 2.2.2 for detailed information on this component of a message. The following examples, which use Figure 5 below, should help make this more clear. Note that those examples begin from a client action which causes servers to generate this type of message. H / / A---1------5 ,--4-----F / \ ,--' / \ / \ ,--' / \ B \ ,--' / G 2-----------3----E |`--D | C #mychannel: A, C, E, F, H #otherchannel: B, D, F, G #secret: C, D [Figure 5: Small IRC Network with Clients and Channels] Example: Message from client A to channel #mychannel. In this example, there are clients in the destination channel on each of the five servers. Server 1 receives the message from client A and passes it on to server 2, the first server in the shortest path to servers 2, 3, and 4, and to server 5. When server 2 receives the message, it sends the message to servers 3 and 4, which are directly connected to it. It does NOT return the message to server 1, even though a client on server 1 is in the destination channel, because server 1 has put its ID in the hop list. Likewise, neither server 3 nor server 4 will send the message back to server 2. Servers 3 and 4 will each send the message to each other, but they will each drop the second copy because of the sequence number check (see section 2.2.2 for details). Example: Message from client D to channel #otherchannel. In this example, the message will be directed to clients on servers 1, 2, and 4. Server 2 forwards the message to servers 1 and 4, but not to server 3, since no clients on server 3 are in the destination channel. Example: Message from client C to channel #secret. The only clients on the destination channel are on server 2, so when server 2 receives the message, it does not send it to any servers, but instead simply sends it to client D. (Note that client C, the sender, does not get a copy of the message back.) This algorithm is also used when sending messages to clients on a local channel. 2. THE IRC SPECIFICATION Communication over the IRC network takes place via messages and replies. Messages can be sent over any connection in any direction, while replies are always sent from a server (to a client or server). "Augmented BNF", used below to provide formats of message and reply elements, refers to the modified Backus-Naur Form used in RFC 822 [6]. All messages and replies consist of a string of arbitrary 8-bit values (data octets). Many message and reply fields contain values with a width greater than one octet; such values are transmitted in big-endian order, i.e. with the most significant octet first. Bits in a value are always numbered starting from the right (lowest-order bit), with the lowest-order bit being bit 0. All values are unsigned unless otherwise specified. 2.1 Strings Of particular interest is the format used to transmit strings of ASCII text or other data intended for display to a user, since such strings are potentially found in nearly every message and reply sent. Since these strings can be of widely varying lengths, and transmitting all strings in a fixed-width field would be a tremendous waste of bandwidth, the length of the string in octets is transmitted first, as a 16-bit or 32-bit value, followed by the octets which comprise the string itself. A zero-length string is valid, and there is no limitation on the values of the octets in the string. If the length of a string is greater than 32,767 octets, a 32-bit length MUST be used to represent the string length; otherwise, a 16-bit length SHOULD be used. Note that since strings may contain any binary information, they can be used for any variable-length information which is sent over the IRC network. The augmented BNF representation for a string is: length16 = <16-bit count of octets in the remainder of the object which the rule describes> string16 = length16 *32767 length32 = string32 = length32 *2147483647 string = string16 / string32 2.2 Messages There are two distinct formats for messages: messages sent from a client to a server or from a server to a client (called client messages), and messages sent from a server to another server (called server messages). Both formats contain similar information, but are each optimized for their specific purpose. A separate type of message -- the server reply -- also uses the client message format. Both message formats begin with an 8-bit start-of-message indicator, followed by a 16-bit flag parameter, followed by a 32-bit value containing the length of the remaining data in the message in octets (except for acknowledgement and acknowledgement request messages; see section 2.2.4). The start-of-message indicator is an octet with decimal value 253. If the first octet of a supposed message does not have this value, the client or server MUST discard the octet as belonging to a previous message. This makes it less likely that a transmission error will cause complete desynchronization of a connection, which could otherwise be possible due to the lack of an end-of-message delimiter such as the CR/LF pair used in the old protocol; the value 253 was chosen for the start-of-message indicator because it is believed relatively unlikely to appear in an actual message. Bit 15 of the flag parameter is reserved; it MUST be set to zero when sending a message. Bit 14 of the flag parameter is cleared (zero) for client messages and set (one) for server messages. If a client or server receives a message in an inappropriate format, it MUST discard that message, though it MAY log the message or in some other way record the fact that it received such an erroneous message. Bits 13 and 12 of the flag parameter are reserved for multi-byte character set use in future versions of the protocol (see section 1.5), and MUST be cleared (zero) in all messages. Bits 7 and 6 of the flag parameter are reserved for experimental or local use. Bits 5 and 4 of the flag parameter are set iff the message's source or destination, respectively is a remote network. The source and dest fields listed in the message grammar MUST use the remote-name format instead of the id-set format iff the relevant flag is set. Messages between border servers on different networks MUST have bits 5 and 4 both set (and use the remote-name format for both sender and target) to ensure that sender information is correctly propogated to the remote network; border servers forwarding a message received from a remote network MUST convert the target information to an id-set and clear bit 4 in the message to be forwarded (or return an error reply to the sender if the target does not exist). Additional bits are defined below, and all of the flag bits are summarized in section 2.3. All flag bits not defined by this protocol MUST be set to zero when sending a message. Both clients and servers MUST read exactly the number of octets given by the length parameter, regardless of the validity of the message, and MUST send exactly the number of octets they specify in the length parameter. However, servers MAY discard a message if it is not received completely within a certain time period (10 seconds is recommended), to prevent malicious or accidental resource starvation by sending large messages through multiple clients. Servers MAY disconnect the remote client or server in this instance, but if not, the number of octets specified by the length parameter MUST be read from the input stream before beginning to process another message from the remote server or client, even though the input will be immediately discarded, to prevent desynchronization. If the message length field is not completely received within the timeout period, the server MUST disconnect the remote client or server if they do not wish to wait for the length field to be completely received. Servers and clients MAY also limit the length of a message they will accept, and MAY terminate a connection upon receipt of a message exceeding that length, but MUST read the specified number of octets if they do not terminate the connection. 2.2.1 Client messages (commands) Client messages consist of the aforementioned flag and length, followed by a message code, possibly a sender (whether the sender is present depends on the direction the message is traveling), and a parameter list. Each parameter is a string, though for the sake of clarity parameters will only be referred to as strings when they are not integer values. The end of the parameter list is implicitly determined by the length of the message. If the length given for a parameter would exceed the length of the message, the server or client receiving the message MUST truncate the parameter when the message's length is reached and, in the case of a server, MUST send an ERR_NEED_MORE_PARAMS error reply (see section 2.2.3) and discard the message if there are fewer parameters than expected. The behavior of a client upon receiving a such a message is undefined by this protocol. The sender field is present only in messages sent from a server to a client; clients MUST NOT include a sender field, as the server would misinterpret this as the beginning of the parameter list. The sender field consists of a a string containing the sender's network's name (iff bit 5 of the flag parameter is set), followed by a string containing the sender's nickname (or the server name, if the sender is a server), possibly followed by a string containing the sender's user@host address (if the sender is a client). If the address is included, bit 11 of the flag parameter MUST be set. The address MUST be sent on all client join, leave, and quit messages which are broadcast to other clients, and MAY be sent with any other client-generated message. (Obviously, the address makes no sense for server-generated messages.) Clients MUST accept any length string in the sender address field, though they MAY discard a string longer than a certain length depending on display and other requirements. The augmented BNF description of a client message is: client-message = flag length (cli-serv-msg / serv-cli-msg) length = length16 / length32 ;chosen as appropriate flag = shortint shortint = <16-bit integer> cli-serv-msg = code [network] * ;message from client to server code = shortint network = string ;destination network parameter = string octet = serv-cli-msg = code [network] sendername [senderaddr] * ;message from server to client sendername = string ;sender's nick / servername senderaddr = addr-string | addr-unistring ;sender's user@host address addr-string = length * "@" * addr-octet = addr-unistring = length * "@" * addr-unichar = 2.2.2 Server messages Server messages are similar to client messages, with the following differences: All server-to-server messages include a message sequence number, used to ensure that no message is processed twice by the same server. When a server registers itself (see section 3.1.3), it provides an initial message sequence number. Whenever that server generates a new server-to-server message, for example when a directly-connected client requests a mode change, it increments its current message sequence number and stores that number in the seqnum field of the server-to-server message (immediately after the message length). When a server receives a message from another server, it compares the sequence number in the message with the last sequence number seen from the originating server (the server in the source parameter). If the sequence number of the received message is less than or equal to the last sequence number seen from the given server, the message is a duplicate and is therefore ignored. Specifically, if the signed 32-bit difference (message sequence number) - (source's last seen sequence number) is less than or equal to zero, the server MUST discard the message. Note that, since not all messages are sent to all servers, it is theoretically possible for a server to generate 2**31 = 2,147,483,648 consecutive messages such that at least one other server sees none of them; that server would then ignore the next 2**31 messages from the sending server as being duplicates. However, the author does not believe this situation will ever occur in practice, since, among others, all state change messages (including client connections and disconnections and channel joins and parts) are transmitted to all servers. Should this situation occur, it could be resolved by breaking all connections between the two servers and establishing a new connection. Note also that this algorithm assumes that all data is transmitted in sequence along all paths. Without this assumption, it is possible for a later message to overtake an earlier one, causing some messages to be inappropriately discarded. For this reason, IRC servers MUST use a transport protocol that guarantees in-order delivery of data, such as TCP [5], or explicitly implement such a protocol on top of an existing transport protocol. (Note that out-of-order message arrival caused by establishment of a redundant connection is discussed in section 1.6.2.) All server-to-server messages also include a "trace" of hops (servers) the message has already passed through. When a server generates a message, it sets the length of the hop list to 1 and inserts its own server ID as the sole element in the hop list. When forwarding a message from a server to another server, the forwarding server increments the length of the hop list by 1 and inserts its server ID as the first element in the hop list. See section 1.6.4 for more discussion of the hop list and server-to-server messages. The original sender of the message is always included, and both the source and destination are encoded using the server and client ID values. The reserved client ID 0 (zero) is used to indicate that the source of a message is the server itself and not a particular client on that server; or that the message has a special destination, depending on the value of the lowest two bits of the flag parameter: 0 - indicates that a message is destined for all servers, rather than any particular client or set of clients. 1 - indicates that a message is destined for a channel; the name name of the channel is the first parameter of the message. (This mode is only used with messages which can have a channel name as the first parameter, such as public messages (see section 3.2.1).) 2 - indicates that a message is destined for only the server to which it was sent. 3 - indicates that a message is destined for all clients on the server. Furthermore, all server messages MAY include a timestamp that indicates when the original message was sent. Servers MUST include a timestamp for the user registration (section 3.1.2) and nickname change (section 3.4.1) messages. If a timestamp is included, bit 8 of the flag parameter MUST be set. See section 2.4 for information on timestamps, including the reasons for using a 64-bit integer. In augmented BNF, the server message format is as follows: server-message = flag length seqnum hop-list code source dest [timestamp] * seqnum = longint hop-list = hop-count *32767 hop-count = shortint ;number of servers in hop-list source = id-set / remote-name id-set = serverid clientid remote-name = network sendername senderaddr serverid = shortint clientid = shortint dest = id-set / remote-name timestamp = <64-bit integer> 2.2.3 Replies Replies are a special type of message sent by servers in response to messages from clients or other servers. Replies are used when there is no information to be sent other than a status code and possibly a descriptive string. A server is the only legal source for a reply; if a server receives a reply from a client, it MUST ignore the reply. Replies use the same format as server-to-client messages as described above, except: bit 10 of the flag parameter is set to indicate a reply as opposed to a standard message; the "code" refers to a reply code instead of a message code; and only one parameter (an optional one) is allowed: a string describing the reply. Servers SHOULD NOT include descriptive strings when sending replies to other servers, but MAY include strings when sending replies to clients. (However, if a server receives a string in a reply, it MUST pass that string along unmodified.) Interactive clients (as opposed to automated scripts or programs) SHOULD display a default description if one is not sent with the reply. The augmented BNF description of a reply: reply = flag length code sendername [string] 2.2.4 Acknowledgements and acknowledgement requests Acknowledgment messages are used to allow servers to determine which messages have been properly received by other servers. Acknowledgements and acknowledgement requests are sent only by servers and only to other servers; an acknowledgement or acknowledgement request received from a client MUST be discarded. Servers SHOULD send an acknowledgement periodically, such as after a certain number of messages have been received, and this period SHOULD be configurable by the server administrator; however, at minimum, servers MUST send an acknowledgement immediately upon receiving an acknowledgement request. Additionally, servers SHOULD send an acknowledgement request when the number of unacknowledged messages exceeds a certain amount, which SHOULD be configurable by the server administrator. In order to reduce the network bandwidth used by acknowledgements, a special format is used, which does not include a length or message code. The augmented BNF description of acknowledgements and acknowledgement requests is: ack = flag serverid serverid seqnum ; first serverid is source, ; second is destination ack-request = flag serverid serverid To differentiate these messages from others which do have a length and message code, bit 10 of the flag parameter (indicating a reply) is set to 1, while bit 14 (indicating a message from a server) is set to zero, an otherwise illegal combination. Bit 11 is set to 0 for acknowledgements and 1 for acknowledgement requests. The flag parameter is followed immediately by the 16-bit server ID of the server sending the message, followed by the server ID of the destination server. In the case of an acknowledgement, these parameters are followed by the 32-bit sequence number of the last message from the destination server which the source server (the server generating the message) has received. 2.3 Summary of message flag bits Bit 15: Reserved, set to 0. 14: 1 if the message is from a server and is not an acknowledgement or acknowledgement request, else 0. 13: Reserved, set to 0. 12: Reserved, set to 0. 11: For acknowledgements and acknowledgement requests, 1 if the message is an acknowledgement request, 0 if it is an acknowledgement. For other messages, 1 if the message includes a sender address field, else 0. 10: 1 if the message is a reply, acknowledgement, or acknowledgement request, else 0. 9: Reserved, set to 0. 8: 1 if the message includes a timestamp, else 0. 7-6: Reserved for experimental or local use; values undefined. 5: 1 if the message's source is on a remote network, else 0. 4: 1 if the message's target is on a remote network, else 0. 3-2: Unused, set to 0. 1-0: Identify the destination of a message with destination client ID equal to zero; see section 2.2.2. 2.4 Timestamps A number of messages require timestamps (numerical values indicating a particular instant int time) to be sent. All servers on a network MUST assign the same meaning to this time value; servers SHOULD use the current de-facto standard (seconds since 1 January 1970 00:00 GMT, used in most if not all current IRC servers and also the return value of the standard Unix time(2) system call), to reduce for clients in determining what timestamp system is in use. Since servers that use the time system described above will run into problems beginning in January 2038 if a 32-bit signed integer is used to store the time, and 32 bits is a considerable restriction on the range of times representable in many other conceivable time systems (such as systems using milliseconds as the base unit), all timestamps, when sent in binary format, MUST be sent using 64 bits. Clients and servers MUST be prepared to properly handle any timestamp value, including values outside the range of a 32-bit integer. Additionally, clients which process decimal time values (particularly in response to query messages; see section 3.6) MUST be prepared to handle values outside the range of a 32-bit integer. 2.5 Text transmission There are many different computer systems in use on the Internet, often with differing methods of encoding text. While resolving the problems associated with differing character sets (such as the ISO-8859 sets, 16-bit Asian character sets, and Unicode) is outside the scope of this document, in order to avoid certain difficulties between operating systems, this document makes the following requirements: * Clients and servers SHOULD send only one line of text per string parameter. When sending multiple lines in a single string, clients and servers MUST use the single character 0x0A (ASCII LF) to separate individual lines (this character is not required after the last line). Here, "character" refers to the smallest unit of storage which can represent a character; this is typically an octet, but in some systems may be two or more octets. Note: The author is aware that the two-character sequence 0x0D 0x0A (ASCII CR, LF) is in common use in other Internet protocols, but does not see the need to use two octets for a single terminator. Furthermore, 0x0A alone is already used as a line terminator in many existing systems. * Clients and servers SHOULD NOT use the character 0xA0 as a substitute for the ASCII space character (0x20). Some systems use the 0xA0 character to indicate a "non-breaking space", i.e. a space character at which a line of text cannot be wrapped, but that character may be displayed differently on different systems; the author himself has experienced this problem on many occasions. 3. MESSAGE DETAILS This section describes in detail each of the different messages defined for this protocol. Unless otherwise noted, all of the messages described below MUST be implemented by all servers. Note that messages are also called "commands", particularly when referring to the act of a client sending a message to a server to request a certain action on the part of the server. Parameters are listed below in the following format: tag (type) where "tag" is a text string describing the parameter and "type" is one of the types described in previous sections (string, shortint, etc.) or a new type which is defined immediately after the parameter list. Brackets ("[" and "]") around a parameter (or more than one parameter) indicate that the parameter is optional. An ellipsis ("...") following a parameter indicates that that parameter may be repeated as many times as desired. A few messages have different formats depending on whether the message is sent by a client or a server. For such messages, two parameter lists are given, one preceded by "" and the other preceded by "", for messages generated by clients and servers respectively. If a server encounters a fatal error while parsing a message, it MUST immediately stop parsing that message and return an error reply to the source of the message. Fatal errors include: an invalid command code, an insufficient number of parameters, and insufficient privileges for the given command. A full list of error conditions in messages is given in section 3.9. If a server successfully parses a message, it MUST act on all of the parameters, sending appropriate replies for each. In the descriptions below, a string is represented by characters inside double quotes (i.e. the length word is omitted). The example messages are given without the flag and length parameters, and are prefixed by one of: "CS:" for a client-to-server message, "SC:" for a server-to-client message, or "SS:" for a server-to-server message. In server-to-client examples, the sender's address is not included unless required. In general, only one example is given unless another is needed to illustrate a particular point. The list of replies indicates all of the possible replies that can be generated by that message. A particular message may cause none, one, some, or all of those replies to be sent. Note that this list only includes server-to-client messages which fall under the "replies" category (section 2.2.3); they do not include "command" messages (section 2.2.1) sent back to the client. Conditions under which each reply is to be sent are in general not listed for each individual command; if not otherwise specified, the conditions listed for the reply in the reply's definition (section 4) are to be used. The reply code ERR_NOT_REGISTERED is not listed; see section 3.9 for conditions under which it is to be generated. Note that in general, servers MUST NOT reject messages from other servers on permission or other grounds; for example, while a channel join message (see section 3.3.1) sent by a client directly connected to a server indicates a request by the client to join the channel, and may be rejected by the server for various reasons, the same message coming from another server indicates an event that has _already happened_, and if the server were to reject the message, its copy of the network state would become desynchronized from the rest of the servers on the network, quite likely resulting in total chaos. Where a server is permitted to reject a message from another server, this is explicitly stated. Servers MAY generate messages to nullify the effect of another message--for example, generating a kick message (section 3.3.7) to nullify the effect of a join message--if they do not wish to permit a certain action to occur; however, this does not nullify any requirement to pass (forward) the original message on to other servers, where such a requirement exists. Where a description refers to "forwarding" a message received by a server and is not otherwise qualified, the term refers to the server sending, to all other servers on the network, a server-server message containing the same message code and parameters as the original message. In any message including a target, the message MUST be sent to that target as described under section 1.6 unless otherwise noted. "Wildcards" in a string refer to the characters "*" (asterisk, ASCII 0x2A) and "?" (question mark, ASCII 0x3F). The former matches any sequence of zero or more characters, and the latter matches exactly one character. These are the same meanings as used in many Unix shells, VAX/VMS, and MS-DOS, among others. Except as otherwise specified, all implementations MUST implement all messages below with exactly the behavior listed. Message codes, parameters, or bits in parameters listed as reserved for experimentation have undefined behavior for the purpose of the protocol definition. 3.1 Connection registration and cancellation These commands are concerned with establishing and breaking client-server and server-server connections. All messages in this group except the password and remote server messages MUST be forwarded; those two message types MUST NOT be forwarded. 3.1.1 Password message Code: 0x0000 Parameters: password (string) Establishes a "connection password" for a new connection. This allows greater certainty about the identity of the remote side of the connection. If a password message is sent, it MUST be sent before the connection registration message (see section 3.1.2 and 3.1.3). The password message is client-server only. Examples: CS: 0x0000 "secret" The initiator of a remote connection is sending the password "secret" to verify his identity. Replies: ERR_NEED_MORE_PARAMS ERR_ALREADY_REGISTERED 3.1.2 User message Code: 0x0001 Client-server parameters: version-id (shortint), nickname (string), username (user-string), real-name (string) Server-server parameters: client-id (shortint), nickname (string), username (user-string), real-name (string), hostname (string), network-address (string), time (timestamp) user-string = * Registers a connection as a client. The nickname parameter indicates what name the client will be known by to other clients. The username is the login identifier used by the client on its host; typically, this will be the username portion of an E-mail address. The real-name is an arbitrary string giving the actual identity of the client; typically, this is the real name of the user running the client program. Note that the client's hostname, as appears in the source address of server-client messages generated (indirectly) by the registering client, is not given in this command; instead, it is determined from the address of the host on the remote side of the connection. (See section 6.2 for a note on this procedure.) The version-id parameter is used to identify the version of the protocol in use; the value 0x0100 is assigned to represent the protocol defined by this document. Future revisions of this protocol will be assigned version-id values in strictly increasing order and will be less than 0x8000; the range 0x8000-0xFFFF is reserved for local and experimental use, and implementors which add or modify features of this protocol MUST choose a new version-id value in that range for their revised protocol. If the nickname given by the client is longer than the maximum length (31 characters), the server MUST return ERR_NAME_TOO_LONG and ignore the message. If the nickname given by the client is already in use, the server MUST return ERR_NICKNAME_IN_USE and ignore the message. If the username given by the client contains the "@" character (ASCII 0x40), the server MUST return ERR_INVALID_NAME and discard the message. Servers MAY limit the set of characters they accept in client nicknames and usernames (in addition to the limitation above on usernames). If a nickname is determined to be invalid, the server MUST return ERR_INVALID_NAME and discard the message. If a username is determined to be invalid, the server MAY modify the username and accept the rest of the message as-is instead of returning ERR_INVALID_NAME and discarding it; in this case, the server SHOULD send a notice to the client (see section 3.2.3) explaining what was done. (For example, the server might remove all invalid characters, or replace them with an innocuous character such as "x".) See section 6.5 for a discussion of potential security problems with allowing any character to be used in a name. Servers SHOULD NOT modify the real-name parameter. Once the user message has been successfully processed, the server generates a new user message to forward to other servers. The nickname, username, and real-name parameters are retained from the client's original message, except when modified as described above. The client-id parameter is a 16-bit value used to identify the client (see section 1.2) and may be assigned arbitrarily by the server. The hostname parameter is the client's hostname as determined by the server; see section 6.2 for security notes on address-to-hostname resolution. The network-address parameter is the client's network address; for Internet connections, this is the client's IP address in binary, using network byte order. The time parameter is the time at which the client connected to the server, or alternatively the time at which the message is generated (either are acceptable). Servers MUST NOT send a hostname containing the "@" character. Examples: CS: 0x0001 "Alcan" "achurch" "Andrew Church" The author's client registers its connection using the nickname "Alcan". SS: 0x0001 0x00000000 0x00000000 843254181 "Alcan" "achurch" "Andrew Church" "localhost.example.org" "\x7F\x00\x00\x01" 843254181 Server 0 informing the network of the connection described above; note that a timestamp is included. The network address consists of the four bytes with values 127, 0, 0, and 1 in that order. Replies: ERR_NEED_MORE_PARAMS RPL_WELCOME ERR_ALREADY_REGISTERED RPL_WELCOME2 ERR_BAD_PASSWORD ERR_CLIENT_DENIED ERR_NICKNAME_IN_USE ERR_NAME_TOO_LONG ERR_INVALID_NAME 3.1.2.1 A note on the Ident Protocol Earlier versions of the IRC protocol took advantage of the Ident Protocol [7] to obtain a username from a (supposedly) more reliable source than the client connection. Many implementations of the protocol included a special character at the beginning of a username when an ident reply could not be obtained, and some implementations even refused client connections when ident service was not available. However, to quote from RFC 1413, which defines the Ident Protocol: "The Identification Protocol is not intended as an authorization or access control protocol. At best, it provides some additional auditing information with respect to TCP connections. At worst, it can provide misleading, incorrect, or maliciously incorrect information. "The use of the information returned by this protocol for other than auditing is strongly discouraged. Specifically, using Identification Protocol information to make access control decisions - either as the primary method (i.e. no other checks) or as an adjunct to other methods MAY RESULT IN A WEAKENING OF NORMAL HOST SECURITY." (emphasis added) Indeed, in the author's experience, a very great majority of users use personal computers for Internet connectivity, and thus have the ability to send an arbitrary identifier in response to an ident request. Some of the multi-user systems (including the author's own) on which clients may be run do not run an ident server -- thus preventing such clients from connecting to any servers which require ident -- and in any case, the most common IRC clients used on multi-user systems will send the user's true user identifier when connecting. Moreover, the author has observed numerous occurrences of a malicious user usurping the identity or privileges of another user despite the supposed added security of the Ident Protocol. Therefore, IRC servers SHOULD NOT use the Ident Protocol for any purpose directly related to the implementation of this protocol, including but not limited to access control decisions. However, the result of an ident lookup MAY be stored as auxiliary information lookup as auxiliary information, for possible use by the server administrator in (for example) tracking malicious users. If an identification protocol with the purpose of returning _authenticated_ user identifiers is developed and gains wide acceptance, this section will be re-evaluated with respect to that protocol. Such a protocol would necessarily be completely inaccessible to the user, whether the user was on a multi-user system or his/her own personal computer. 3.1.3 Server message Code: 0x0002 Parameters: version-id (shortint), server-id (shortint), server-name (string), server-desc (string), initial-seqnum (longint) Registers a connection as a server. The server-name parameter is the name of the server, as described in section 1.1. Server-desc is an arbitrary string describing the server; it may identify the organization responsible for maintaining the server, for example. Server-id is a 16-bit integer uniquely identifying the server, as described in section 1.2. The initial-seqnum parameter gives the server's initial message sequence number (see section 2.2.2). The version-id parameter is as described for the user registration message (see section 3.1.2). Servers MAY limit the set of characters they accept in server names, as described for the user registration message. Servers MUST reject registration attempts with invalid server names with ERR_INVALID_NAME. A server MUST reject an attempted registration with ERR_WRONG_VERSION if it is not prepared to support the version supplied. Servers compliant with this protocol MUST accept connections which supply the value 0x0100 in that field. Upon successful registration of a server, both the registering server and the server to which it connected MUST send all state information, using server messages, network messages (section 3.1.5 below), user messages (section 3.1.2 above), join messages (section 3.3.1), and channel mode, topic, operator, voice, and ban messages (sections 3.3.3-6 and 3.3.8). The order of the messages is subject to the following constraints: - All server messages must come before all other messages. - All network messages must come immediately after all server messages. - No join message may be sent for a client for whom a user message has not yet been sent. - No channel message may be sent before at least one client has joined the channel. Unlike all other messages between servers except the remote server message (see section 3.1.4 below), this message, when used to register a server connection, is sent in client-server message format. This message may be rejected by the receiving server when used to register a connection. Examples: SS: 0x0002 0x0100 0 "dragonfire.esper.net" "Dragonfire's EsperNet IRC server" Server 0 (dragonfire.esper.net) registers itself as a server after connecting to server 1, using version code 0x0100. SS: 0x0002 0x00010000 0x00020000 0x0100 0 "dragonfire.esper.net" "Dragonfire's EsperNet IRC server" Server 1 informs server 2 of the new server connection. Replies: ERR_NEED_MORE_PARAMS RPL_SERVER_WELCOME ERR_ALREADY_REGISTERED ERR_BAD_PASSWORD ERR_SERVER_DENIED ERR_NAME_TOO_LONG ERR_INVALID_NAME ERR_WRONG_VERSION 3.1.4 Remote server message Code: 0x0042 Parameters: network-name (string), server-id (shortint), server-name (string), server-desc (string) Similar to the server message (described above), this message registers a connection as a server. The difference is that a server using this message is registering itself as a border server from an outside network. Such a server will, if the connection is allowed, then be able to pass messages from its own network to the network to which it is connecting, and will receive messages from that network destined for its own network. See section 1.6.3.1 for more information on inter-network messages. The network-name parameter is a string containing the name of the network, as described in section 1.6.3.1. The other parameters are as described for the normal server registration message in section 3.1.3. Note that servers MUST NOT send state information to remote networks. Servers MAY limit the set of characters they accept in server names and network names, as described for the user registration message (section 3.1.2). Servers MUST reject registration attempts with invalid server or network names with ERR_INVALID_NAME. Unlike all other messages between servers except the server message, this message is sent in client-server message format. This message may be rejected by the receiving server when used to register a connection. Examples: SS: 0x0042 "EsperNet" 0 "dragonfire.esper.net" "Dragonfire's EsperNet IRC server" Server 0 from the network "EsperNet" connects to a server on another network and announces itself as a remote server. Replies: ERR_NEED_MORE_PARAMS RPL_BSERVER_WELCOME ERR_ALREADY_REGISTERED ERR_BAD_PASSWORD ERR_SERVER_DENIED ERR_NETWORK_DENIED ERR_NAME_TOO_LONG ERR_INVALID_NAME 3.1.5 Network message Code: 0x0043 (add), 0x00C3 (remove) Parameters: network (string) Indicates that the server has become (0x0043) or is no longer (0x00C3) a border server for the specified network. Examples: SS: 0x0043 0x00010000 0x00020000 "EFNet" Server 1 sends a message to server 2 indicating that it is now a border router for the network "EFNet". Replies: ERR_NEED_MORE_PARAMS ERR_NOT_SERVER ERR_NAME_TOO_LONG 3.1.6 Quit message Code: 0x0004 Parameters: [reason (string)] Terminates a client connection. The "reason" is an arbitrary text string sent by the client which, as the name implies, is intended to reflect the reason for the quit. Normally, a quit message will be sent to the server by the client just before it closes the connection. However, certain circumstances may cause a server to forcibly close a client's connection. Such circumstances SHOULD be limited to a "ping timeout", as described in section 3.6.2; a kill message, as described in section 3.4.5; a nickname collision, as described in section 5.2.1; an operating system error which prevents the server from reading data from the client's connection; and administrative restrictions on client connections (such as host address, connection length, or idle time). When a server forcibly closes a connection, it MUST generate a quit message on the client's behalf, it MUST include a "reason" describing why the connection was closed, and it MUST send that quit message to the client whose connection is being closed (if possible). Any server receiving a quit message, whether from a directly-connected client or from another server, MUST send that message to all clients connected to it who are on any channel the quitting client was on. Examples: CS: 0x0004 "Off to work" A client closes its connection with the message "off to work". SC: 0x0004 "Alcan" "Connection reset by peer" The server has closed Alcan's client connection due to the operating system error "Connection reset by peer". Replies: None. 3.1.7 Server quit message Code: 0x0005 Parameters: server-id (shortint), [reason (string)] Terminates a server connection. The server-id is the ID number of the server which is disconnecting; the reason is, as with the quit message, intended to describe why the server is quitting. Upon receipt of a server quit message, the server removes the quitting server from its internal server list, and if the quitting server is connected directly to the receiving server, the connection is closed. In addition, the server also removes from its internal lists any server which can no longer be reached because of the broken connection. If any now-unreachable clients were on channels that any clients local to the server are also on, then the server MUST generate and send quit messages on their behalf as described in the previous section; the reason in those quit messages SHOULD be of the form "server1 server2", where server1 and server2 are the servers at either end of the severed connection: server1 is the server which is still on the IRC network, and server2 is the server which is no longer on the network. As with the quit message, connections may be closed either voluntarily or forcibly. In the former case, the server which is disconnecting sends its own ID in the server-id parameter. In the latter case, the server closing the connection sends a server quit message to the server whose connection is being closed, which MUST include an explanation of why the connection is being closed. Examples: SS: 0x0005 0x00000000 0x00010000 0 "Terminated" Server 0 closes its connection to server 1 for the reason "Terminated". Replies: ERR_NEED_MORE_PARAMS 3.2 Message sending These messages, which send strings to a client or a set of clients (such strings are also called "messages"), form the core of the IRC protocol. Note that these strings need not be only readable text; they may contain any arbitrary series of octets, and could be used, for example, to send special client-oriented commands between clients, such as the "CTCP" protocol ("Client To Client Protocol") in use on current IRC networks, or to send multimedia data on high-speed local area networks. However, such protocols are beyond the scope of this document. 3.2.1 Public messages Code: 0x0100 Parameters: target (string), message (string) Sends a string (message) to a target channel. Whether the message is actually delivered depends on the channel modes (see section 3.3.3) and whether the sender is in the channel. This message is forwarded to any servers on which there is a client in the channel, and to any clients in the channel on that server, including the sender. Servers MAY discard a message and reply with ERR_INVALID_NAME if the message is from a directly-connected client and the first character of the channel name is not recognized by the server (see section 3.9). Examples: CS: 0x0100 "#dragonweyr" "Hi, all." A client sends a message to channel #dragonweyr. Replies: ERR_NEED_MORE_PARAMS ERR_NAME_TOO_LONG ERR_INVALID_NAME ERR_NO_SUCH_CHANNEL ERR_CANNOT_SEND 3.2.2 Private messages Code: 0x0101 Parameters: nickname (string), message (string) Sends a string (message) to a target client (nickname). Whether the message is delivered depends on the target client's "silence" list (see section 3.4.3). Examples: CS: 0x0101 "Alcan" "How are you?" A client sends a private message to client Alcan. Replies: ERR_NEED_MORE_PARAMS ERR_NAME_TOO_LONG ERR_NO_SUCH_USER ERR_CANNOT_SEND 3.2.3 Notices Code: 0x0102 (channel), 0x0103 (private) Parameters: target (string), message (string) These two commands are similar to the public and private message commands, with one difference: A client or server which receives a notice MUST NOT generate any other messages (including server error messages) in response to the notice. This makes notices ideal for responses from automated clients, to prevent possible message loops. Examples: CS: 0x0103 "Alcan" "Your nickname has been registered." A client sends a notice to client Alcan. The sending client is automated, and therefore sends only notices to prevent another automated client from replying to it. Replies: None. 3.2.4 Server notices Code: 0x0104 Parameters: message (string) Sends a string to all clients on the server with the user mode UMODE_SERVER_NOTICES set (see section 3.4.4). This is typically used to broadcast server-specific status messages; status messages relevant to the entire network SHOULD be sent as operator messages (section 3.2.5). This message is only sent by servers, and MUST be ignored when received from a client. Examples: SC: 0x0104 "Client exiting: Alcan (Leaving)" The server reports a client's disconnecting. Replies: None. 3.2.5 Operator messages Code: 0x0105 Parameters: message (string) Sends a string to all IRC operators who are currently online (and who have not disabled their ability to receive such messages; see section 3.4.4). Only IRC operators may send this message. This message is not sent directly from the receiving server to all target clients; instead, it is forwarded to all servers, and each server sends the message to any target clients directly connected to it. Servers MAY generate operator messages to inform IRC operators of network events, such as the establishing or breaking of a server-to- server connection. For events local to a single server, servers SHOULD use server notices (see section 3.2.4). Examples: CS: 0x0105 "Watch out for clones from lame.org." An IRC operator sends a message to all other online operators. Replies: ERR_NEED_MORE_PARAMS ERR_PERMISSION_DENIED 3.2.6 Global messages Code: 0x0106 Parameters: message (string), [target-server (string)] Sends a string to all clients on a given server. If the target-server parameter is omitted, the string is sent to all users on the IRC network. Only IRC operators may send this message. This message is not sent directly from the receiving server to all target clients; instead, it is forwarded to all servers, and each server sends the message to any target clients directly connected to it. Examples: CS: 0x0106 "This server will be shutting down in 2 minutes." "dragonfire.esper.net" An IRC operator sends a message to all clients on server dragonfire.esper.net. Replies: ERR_NEED_MORE_PARAMS ERR_PERMISSION_DENIED ERR_NAME_TOO_LONG 3.3 Channel operations These messages affect channels and the access privileges of clients in channels. All messages in this group MUST be forwarded except as noted, and MUST be sent by each server to all clients connected to that server on the channel sent in the message. 3.3.1 Join message Code: 0x0200, 0x0280 Parameters: (0x0200) channel-name (string) [...] (0x0280) channel-name (string), key (string) Adds the sender to the list of clients in the given channel(s), assuming the sender is allowed to join those channels. If any of the channels specified do not exist, they are created and the sender is given channel-operator status in those channels (see section 3.3.5). New channels do not have any modes active (see section 3.3.3). If a client is not allowed to join a channel, the reply ERR_CANNOT_JOIN is sent for each such channel. Rejected join messages MUST NOT be forwarded. The second form of the join message is used when a channel has a key associated with it (see section 3.3.3); only one channel may be joined per message in this form. When broadcasting join messages to clients in the joined channel(s), the server MUST send a separate join message for each channel using message code 0x0200, and MUST NOT include any key used in the original join message. Upon joining, the server SHOULD send to the client the channel topic, current channel modes, and a list of all clients on the channel, as if the user had sent a topic message (section 3.3.4), mode message (section 3.3.3), and names message (section 3.6.2) for the channel. Servers SHOULD NOT accept join messages from directly-connected clients with channel names whose first character is unrecognized; however, servers MUST accept such messages if received from another server. Examples: CS: 0x0200 "#dragonweyr" "#help" A client joins channel #dragonweyr and #help. CS: 0x0280 "#mychannel" "mykey" A client joins channel #mychannel, sending the key "mykey" to be allowed to join. SC: 0x0200 "Alcan" "achurch@achurch.org" "#mychannel" The server broadcasts the previous join message to the channel. Note that code 0x0200 is always used, and the key is not sent. Replies: ERR_NEED_MORE_PARAMS ERR_NAME_TOO_LONG ERR_INVALID_NAME ERR_CANNOT_JOIN 3.3.2 Part message Code: 0x0201, 0x0281 Parameters: (0x0201) channel (string) ... (0x0281) channel (string), reason (string) Removes the sender from the list of clients in the given channel(s). If no clients are left in any of the channels specified, those channels are deleted. In the second form, the client may send a reason with the part message. Only one channel per message may be left with this form. When broadcasting the part message to clients in the parted channel(s), the server MUST use message code 0x0281, and MUST send an empty string for the "reason" parameter if one was not given in the original message. Examples: CS: 0x0281 "#dragonweyr" "Be back later" A client leaves channel #dragonweyr for the reason "Be back later". CS: 0x0201 "#dragonweyr" "#help" A client leaves channels #dragonweyr and #help. SC: 0x0281 "#help" "" The server informs clients in #help of the previous message. Replies: ERR_NEED_MORE_PARAMS ERR_NAME_TOO_LONG ERR_INVALID_NAME ERR_NOT_IN_CHANNEL 3.3.3 Channel mode message Code: 0x0202 Parameters: channel (string), [new-modes (bits-32), new-modes-mask (bits-32), [mode-parameter ...]] bits-32 = longint This command sets binary modes for the channel or returns the current channel modes. If only a channel name is given, the current modes of the channel are returned, using the same message code with server-client format (assuming the channel is not secret, see below). Otherwise, the new-modes parameter lists the new values for the channel modes, and the new-modes-mask parameter indicates which modes are actually to be changed. This allows changing channel modes one at a time without having to specify the entire set of channel modes each time. Channel modes may only be set by a channel operator. When this message is used to change channel modes, the server's reply includes only those modes which were changed in the new-modes-mask parameter; to obtain a full list of channel modes, a query message must be sent. A query message is simply a channel mode message with no mode parameters; the server replies with the current set of modes for the channel, and sets all bits in the new-modes-mask parameter. Some modes require parameters when they are set active; these are given in increasing bit order -- i.e. the parameter for the lowest bit set in new-modes is given first, and so on. See the second example below. If a client which does not have channel operator privileges attempts to change channel modes, the server MUST reply with ERR_PERMISSION_DENIED and discard the message without processing it. Compatibility note: some operations which were considered "mode changes" in the original IRC protocol, setting channel operators for example, have been separated into distinct commands in this protocol. The channel mode message is only for changing channel flags. The following channel modes are currently defined: 0x00000001 CMODE_PRIVATE A channel marked PRIVATE can only be queried by clients outside the channel if they know the exact name of the channel. "Querying" a channel includes sending any messages which would return information about the channel, i.e. the channel mode message, who message (section 3.6.1), names message (section 3.6.2), and list message (section 3.6.3). 0x00000002 CMODE_SECRET A channel marked SECRET cannot be queried by clients outside the channel at all. A superset of CMODE_PRIVATE -- i.e., setting CMODE_PRIVATE in addition to this flag will have no effect. 0x00000004 CMODE_EXTERN_MSGS If a channel has this mode active, clients do not need to be in the channel in order to send messages to it. 0x00000008 CMODE_TOPIC_OPS This mode limits the ability to change the channel's topic (see section 3.3.4) to channel operators. 0x00000010 CMODE_INVITE_ONLY If this mode is set, clients can only enter the channel if they have been invited (see section 3.3.9). 0x00000020 CMODE_MODERATED If this mode is set, clients in the channel can only send messages to the channel if they are channel operators or have been "given a voice" (see section 3.3.6). Note that this does not affect the operation of CMODE_EXTERN_MSGS. 0x00000040 CMODE_USER_LIMIT (parameter: limit (shortint)) If this mode is set, the number of clients which can be in the channel is limited to the given value. 0x00000080 CMODE_KEY (parameter: key (string)) If this mode is set, the channel may only be entered by clients sending a join message with a key parameter identical to the key given with the mode message. Note that the key is never sent to any client in a mode status or change message. 0x00800000 CMODE_LOCKED If this mode is set, the channel mode is "locked", i.e. may not be changed. Specifically, if a client without IRC operator privileges attempts to change channel modes on a channel which has the CMODE_LOCKED flag set, the server MUST return ERR_CANNOT_CHANGE_LOCKED and discard the entire message. A server MAY allow IRC operators, or a certain subset of IRC operators, to change modes when the CMODE_LOCKED mode is active. The upper eight bits of the mode parameter are reserved for experimental and/or local use. All other bits are reserved for future expansion of the protocol and MUST NOT be used by any client or server. If any mode change in a mode change request is disallowed, the entire mode change request MUST be discarded. Examples: CS: 0x0202 "#dragonweyr" 0x00000008 0x00000008 Channel #dragonweyr is given the CMODE_TOPIC_OPS mode. CS: 0x0202 "#mychannel" 0x000000C0 0x000000D0 30 "mykey" For channel #mychannel, the CMODE_INVITE_ONLY flag is removed, and the CMODE_USER_LIMIT and CMODE_KEY flags are set. The client limit is set to 30, and the channel key is set to "mykey". SC: 0x0202 "#mychannel" 0x000000C0 0x000000D0 30 The server sends this message back to all clients in the channel. Note that the key has been removed from the mode parameter list. CS: 0x0202 "#mychannel" A client queries the modes in channel #mychannel. SC: 0x0202 "#mychannel" 0x000000C9 0xFFFFFFFF 30 A response to the above mode query, indicating the modes CMODE_PRIVATE, CMODE_TOPIC_OPS, CMODE_USER_LIMIT, and CMODE_KEY are set, with a limit of 30 clients in the channel. Again, the key is not included. The new-mode-mask will always have all bits set in this type of response. Replies: ERR_NEED_MORE_PARAMS ERR_NAME_TOO_LONG ERR_INVALID_NAME ERR_NO_SUCH_CHANNEL ERR_NOT_IN_CHANNEL ERR_PERMISSION_DENIED ERR_CANNOT_CHANGE_DIST_LOCAL ERR_CANNOT_CHANGE_LOCKED 3.3.4 Topic message Code: 0x0203 Parameters: channel-name (string), [topic (string)] Sets (or retrieves) the "topic" for the given channel; this is a string displayed to clients when they join the channel, and typically indicates the nature of discussion in the channel. A server MUST NOT permit topic changes by unprivileged clients not in the channel, and MUST NOT permit topic changes by unprivileged clients in the channel iff the CMODE_TOPIC_OPS flag is set. Examples: CS: 0x0203 "#help" "General help channel" The topic for #help is set to "General help channel". CS: 0x0203 "#help" SC: 0x0203 "#help" "General help channel" A client requests the topic for #help, and the server returns it. Replies: ERR_NEED_MORE_PARAMS ERR_NAME_TOO_LONG ERR_INVALID_NAME ERR_NO_SUCH_CHANNEL ERR_NOT_IN_CHANNEL ERR_PERMISSION_DENIED 3.3.5 Channel operator message Code: 0x0204 (add), 0x0284 (remove) Parameters: channel-name (string), nickname (string) ... Gives (takes away) channel operator privileges to (from) the given nickname(s) on the given channel. The sender MUST be a channel operator. Code 0x0204 is used to give privileges, and code 0x0284 is used to take them away. Examples: CS: 0x0204 "#dragonweyr" "Alcan" Gives channel operator privileges to Alcan on channel #dragonweyr. Replies: ERR_NEED_MORE_PARAMS ERR_NAME_TOO_LONG ERR_INVALID_NAME ERR_NO_SUCH_CHANNEL ERR_NOT_IN_CHANNEL ERR_PERMISSION_DENIED ERR_NO_SUCH_USER 3.3.6 Channel voice message Code: 0x0205 (add), 0x0285 (remove) Parameters: channel-name (string), nickname (string) ... Gives (takes away) "voice" (permission to send messages on a moderated channel; see section 3.3.3) to (from) the given nickname(s) on the given channel. The sender MUST be a channel operator. Code 0x0205 is used to give privileges, and code 0x0285 is used to take them away. Examples: CS: 0x0205 "#dragonweyr" "Alcan" Gives a voice to Alcan on channel #dragonweyr. Replies: ERR_NEED_MORE_PARAMS ERR_NAME_TOO_LONG ERR_INVALID_NAME ERR_NO_SUCH_CHANNEL ERR_NOT_IN_CHANNEL ERR_PERMISSION_DENIED ERR_NO_SUCH_USER 3.3.7 Kick message Code: 0x0206 Parameters: channel-name (string), reason (string), nickname (string) ... Forcibly removes one or more clients from a channel. The sender MUST be a channel operator. Examples: CS: 0x0206 "#dragonweyr" "Flooding is not permitted." "LaMeR" Forcibly removes the client with the nickname "LaMeR" from channel #dragonweyr with the reason "Flooding is not permitted." Replies: ERR_NEED_MORE_PARAMS ERR_NAME_TOO_LONG ERR_INVALID_NAME ERR_NO_SUCH_CHANNEL ERR_NOT_IN_CHANNEL ERR_PERMISSION_DENIED ERR_NO_SUCH_USER 3.3.8 Channel ban message Code: 0x0207 (add), 0x0247 (list), 0x0287 (remove) Parameters: channel-name (string), [nickname-mask (string), username-mask (string), hostname-mask (string)] Adds or removes bans on clients joining channels. If a client attempts to join a channel, and its nickname, username, and hostname match any of the bans for that channel (i.e. all three strings match the respective masks for a particular ban entry), the client's join request is denied. The ban strings may contain wildcards. For the list message (0x0247), if masks are given, then only those bans matching all masks are returned, otherwise all bans on the given channel are returned. The server MUST send exactly one ban per response message. For the add (0x0207) and remove (0x0287) messages, the masks MUST be given, and the sender MUST be a channel operator. Examples: CS: 0x0207 "#dragonweyr" "*@*.lame.org" Bans any client from any system in the lame.org domain from joining channel #dragonweyr. CS: 0x0247 "#dragonweyr" A request for the list of bans for channel "#dragonweyr". SC: 0x0247 "#dragonweyr" "*@*.lame.org" A response to the request for the list of bans. Replies: ERR_NEED_MORE_PARAMS ERR_NAME_TOO_LONG ERR_INVALID_NAME ERR_NO_SUCH_CHANNEL ERR_NOT_IN_CHANNEL ERR_PERMISSION_DENIED 3.3.9 Invite message Code: 0x0208 Parameters: channel-name (string), nickname (string)... Invites the given client(s) to the given channel. If the channel is invite-only (see section 3.3.3), this allows the client(s) to join the channel. The sender MUST be a channel operator. Examples: CS: 0x0208 "#dragonweyr" "Alcan" Invites client Alcan to channel #dragonweyr. Replies: ERR_NEED_MORE_PARAMS ERR_NAME_TOO_LONG ERR_INVALID_NAME ERR_NO_SUCH_CHANNEL ERR_NO_SUCH_USER ERR_NOT_IN_CHANNEL ERR_PERMISSION_DENIED 3.4 Client control messages These messages allow a client to set information about itself, and allow privileged clients to control other clients' access to the IRC network. These messages MUST be forwarded except as specified. 3.4.1 Nick message Code: 0x0300 Parameters: nickname (string) Allows a client to change its nickname. If the nickname is already in use, the server MUST return ERR_NICK_IN_USE and MUST NOT forward the message. If the nickname is longer than the maximum length (31 characters), the server MUST return ERR_NAME_TOO_LONG and ignore the message. This message may also be generated by a server to cause a client to change its nickname. A client receiving a nick message for itself MUST change its nickname to that specified in the message. The server generating the message MUST also forward the message to all other servers. Examples: CS: 0x0300 "NewNick" A client requests a change of nickname to "NewNick". Replies: ERR_NEED_MORE_PARAMS ERR_NAME_TOO_LONG ERR_NICK_IN_USE 3.4.2 Away message Code: 0x0301 Parameters: [reason (string)] Marks a client as "away" (if the reason parameter is included) or not away (if the parameter is omitted). Any client which sends a private message to a client marked away MUST be sent an away message with the sender field set to the nickname of the client to which the message was sent. (Note that servers MUST NOT discard any messages sent to a client marked away.) Examples: CS: 0x0301 "Getting food" A client marks itself away because of "Getting food". SC: 0x0301 "Alcan" "Getting food" A client tried to send a private message to Alcan, who was marked away, and the server responded with Alcan's current away message. CS: 0x0301 A client marks itself as no longer away. Replies: RPL_MARKED_AWAY RPL_MARKED_UNAWAY 3.4.3 Silence message Code: 0x0302,0x0382 (add), 0x0342,0x03C2 (remove), 0x0362,0x03E2 (list) Parameters: (0x0302,0x0342) nickname (string) client-id (longint) (0x0382,0x03C2) nickname-mask (string), username-mask (string), hostname-mask (string) (0x0362) none nickname (string) (0x03E2) none nickname-mask (string), username-mask (string), hostname-mask (string) Adds a nickname or nick/user/host mask to, removes a nickname or mask from, or displays a client's "silence list". If the client would normally receive a message from a client on the silence list, such messages will be discarded. Specifically, if client B matches an entry on client A's silence list, then: - Any private messages or notices from client B to client A MUST be discarded by both client B's server and (if it receives any) client A's server. (Intermediate servers are not required to discard the messages, but MAY do so.) - Any other type of message or notice sent by client B which client A would normally receive MUST NOT be sent to client A by client A's server. For the list messages, the server returns the nickname (0x0362) or mask (0x03E2) entries on the client's silence list, one per message, followed by RPL_SILENCE_END. For the nickname form of the add and remove messages (message codes 0x0302 and 0x0342), the nickname is converted into a 32-bit integer with the server ID of the client currently using the target nickname in the high 16 bits and the client ID of that client on its server in the lower 16 bits before being forwarded to other servers. If the nickname is not currently in use, the server returns ERR_NO_SUCH_USER; for 0x0342 (remove), if the client is not on the silence list, the server returns ERR_NOT_ON_SILENCE_LIST. For the mask form (message codes 0x0382 and 0x03C2), the nickname, username, and hostname masks are used as in the channel ban message (section 3.3.8); a client is considered to match a silence list entry iff all three strings match the respective masks in the entry. For message code 0x03C2 (remove), if the mask is not on the silence list, the server returns ERR_NOT_ON_SILENCE_LIST. When a client which is listed on another client's silence list disconnects from the IRC network, that silence list entry is automatically removed by the server. Examples: CS: 0x0302 "lamer" Adds the nickname "lamer" to the client's silence list. If the client with this nickname changes nicknames, it will still be silenced until it disconnects from the IRC network. CS: 0x0382 "*" "*" "*.lame.com" Adds the mask "*!*@*.lame.com" to the client's silence list. Any client matching this mask (any client with a hostname ending in ".lame.com", regardless of nickname or username) will be silenced. Replies: ERR_NEED_MORE_PARAMS RPL_SILENCE_ADD ERR_NO_SUCH_USER RPL_SILENCE_DEL ERR_NOT_ON_SILENCE_LIST RPL_SILENCE_END 3.4.4 Client mode message Code: 0x0303 Parameters: [new-modes (bits-32), new-modes-mask (bits-32), [mode-parameter ...]] Similar to the channel mode message (section 3.3.3), this sets various binary modes for a client. "new-modes" and "new-modes-mask" operate as with the channel mode message. Server responses to this command are also as defined for the channel mode message, except where noted below. The following client modes are currently defined: 0x00000001 UMODE_OPERATOR Indicates that the client is an IRC operator. Note that the client may not set this mode directly; if a client attempts to do so, the server MUST return ERR_PERMISSION_DENIED and discard the entire client mode message. Clients may clear (unset) this mode, however. 0x00000002 UMODE_INVISIBLE If this mode is set, the client will not appear in any channel name lists (unless the querying client and this client are both in the same channel, and that channel is the target of the query) or "who" command results unless the querying client is an IRC operator. 0x00000004 UMODE_OPER_MESSAGES If this mode is set and the client is an IRC operator, the client will receive operator messages (see section 3.2.5). Normal clients MUST NOT receive operator messages regardless of the setting of this mode. 0x00800000 UMODE_SERVER_NOTICES (parameter: types (bits-32)) If this mode is set, the server should send to the client informational messages (see section 3.2.4) regarding network and server activity. The parameter indicates which types of messages the client wishes to receive. The meaning of the particular bits in the "types" parameter are not specified here and are left to the implementors, except that a "1" bit MUST indicate a request that messages of a particular type be sent, and a "0" bit MUST indicate that messages of that type should not be sent. Clients SHOULD default to sending a parameter containing all bits set, to allow for a consistent meaning across servers for this mode's default function. Servers MAY limit this mode to IRC operators only. Servers that do so MUST return ERR_PERMISSION_DENIED and discard the entire mode message if sent from a non-privileged client, and MUST unset the UMODE_SERVER_NOTICES mode whenever the UMODE_OPERATOR mode is unset. This mode is also special in that it is server-specific; a client can never receive server notices from any server except that to which it is directly connected. Servers MUST NOT send this mode when reporting client modes to other servers. The upper eight bits of the mode parameter are reserved for experimental and/or local use. All other bits are reserved for future expansion of the protocol and MUST NOT be used by any client or server. If any mode change in a mode change request is disallowed, the entire mode change request MUST be discarded. For example, if a (non-operator, non-invisible) client tries to set both UMODE_OPERATOR and UMODE_INVISIBLE in the same message, the server MUST discard the message without changing any modes, even though the UMODE_INVISIBLE flag by itself would have been permitted. Note that this message may be generated by the server in response to other types of messages as well (in particular, it is generated in response to an operator message; see section 3.4.5 below). Examples: CS: 0x0303 0x00800004 0x00800006 0xFFFFFFFF A client requests that it receive all types of server notices as well as operator messages, and disables the UMODE_INVISIBLE mode. SC: 0x0303 0x00800004 0x00800006 0xFFFFFFFF The server replies, showing the client's new modes. CS: 0x0303 The client requests its current modes. SC: 0x0303 0x00800005 0xFFFFFFFF 0xFFFFFFFF The server informs the client of its current modes. Note that the UMODE_OPERATOR flag is set here, while it was not set in the previous message from the server (because it was not changed by the client's client mode message). CS: 0x0303 0x00000000 0x00000001 The client gives up IRC operator status. SC: 0x0303 0x00000000 0x00800001 The server replies. Note that the server has unset the UMODE_SERVER_NOTICES mode as well as the UMODE_OPERATOR mode. Replies: ERR_PERMISSION_DENIED 3.4.5 Operator message Code: 0x0304 Parameters: password (string), [nickname (string)] Requests that the client be given IRC operator status. Depending on the value of the password parameter and other site-dependent parameters, the client's request may be accepted (in which case RPL_NOW_OPERATOR is sent) or denied (in which case ERR_PERMISSION_DENIED is sent). If the "nickname" parameter is given, the server MUST treat the request as if it had come from the given nickname (though the actual sender, not the named client, will receive operator privileges), and SHOULD allow the request even if another client has gained operator privileges under that nickname. (Consider the not-uncommon scenario in which an IRC operator's connection fails, and the operator reconnects to the server before the server recognizes that the earlier connection has been severed.) This message MUST NOT be forwarded; instead, a client mode message MUST be generated which sets the UMODE_OPERATOR flag and forwarded. The client mode message MUST also be sent to the client (in addition to RPL_NOW_OPERATOR). A server MAY set or unset additional client modes after a successful operator message; for example, a server might set the UMODE_OPER_MESSAGES and UMODE_SERVER_NOTICES flags. Examples: CS: 0x0304 "mypassword" A client requests IRC operator privileges with the password "mypassword". Replies: ERR_NEED_MORE_PARAMS RPL_NOW_OPERATOR ERR_NAME_TOO_LONG ERR_PERMISSION_DENIED 3.4.6 Kill message Code: 0x0305 Parameters: nickname (string), reason (string) target-id (longint), reason (string) Forcibly terminates a client's connection to the IRC network. The server to which the named client is connected MUST send the kill message to the client and then immediately terminate the connection upon receipt of the message. When forwarding this message to other servers, the nickname is first translated to its corresponding server/client ID pair. Non-operator clients MUST NOT be permitted to use this command. Examples: CS: 0x0305 "lamer" "Flooding is not permitted" Removes the client with nickname "lamer" from the network with the reason "Flooding is not permitted". Replies: ERR_NEED_MORE_PARAMS ERR_PERMISSION_DENIED ERR_NAME_TOO_LONG ERR_NO_SUCH_USER 3.4.7 Server ban message Code: 0x0306 (add), 0x0386 (remove) Parameters: username (string), hostname (string) Adds or removes a ban on clients connecting to the server which receives the message. The username and hostname given may contain wildcards. If a client connects and sends a user message with a username and hostname which match those of any ban, the client is rejected by the server. In the special case where the username is "*", which matches any string, the server MAY immediately close a connection whose source address matches the hostname mask without waiting for a registration message. Non-operator clients MUST NOT be permitted to use this command. This message MUST NOT be forwarded. Examples: CS: 0x0306 "lamer" "*.lame.com" Add a ban on any client connecting with the username "lamer" and a hostname ending in ".lame.com". Replies: ERR_NEED_MORE_PARAMS ERR_PERMISSION_DENIED 3.4.8 Network ban message Code: 0x0307 (add), 0x0387 (remove) Parameters: username (string), hostname (string) Adds or removes a ban on clients connectiong to any server on the network. The username and hostname are interpreted as described for the server ban message in section 3.4.7 above. As with the server ban, a client who tries to register with a banned username and hostname will be rejected. If a server receives a user message from another server for a client whose username and hostname match such a ban, it MUST issue a kill message for that client, generate a network ban message from the banned username and hostname masks which the client matched, and forward that message to all servers. If the client matches multiple username/hostname masks, the server may choose any of the matching pairs. Non-operator clients MUST NOT be permitted to use this command. Examples: CS: 0x0306 "lamer" "*.lame.com" Add a ban on any client connecting to any server with the username "lamer" and a hostname ending in ".lame.com". Replies: ERR_NEED_MORE_PARAMS ERR_PERMISSION_DENIED 3.5 Server control messages These messages allow IRC operators to control servers on the IRC network. Each of these messages can take an optional "dest-server" parameter; this is the name of a server on the IRC network to which the message is to be forwarded (if present and if the sender is an IRC operator, the server receiving the message from the client MUST forward it to the specified server and MUST NOT act on it). Other than the above, these messages MUST NOT be forwarded. The dest-server parameter for these messages, if supplied, MUST be a server name. Non-operator clients MUST NOT be permitted to use any of these functions. 3.5.1 Connect message Code: 0x0400 Parameters: server-to-connect (string), [dest-server (string)] This message is sent by an IRC operator to cause a server to attempt to establish a connection to the given "server-to-connect". If the dest-server parameter is given, the messages is forwarded to that server, which acts on it; otherwise, the server receiving the message from the client attempts to make the connection. The server-to-connect parameter SHOULD be a server name as given in the server registration message (section 3.1.3), but may be any arbitrary string which a server can use to identify another server and how to connect to it. The error ERR_ALREADY_CONNECTED is returned only when a direct connection exists between the server executing the command and the server named in the server-to-connect parameter. A server without such a connection MUST attempt to establish one even if the server-to-connect is already present on the network (i.e. by being connected to a different server). Examples: CS: 0x0400 "weyr.esper.net" A client instructs its server to connect to the server "weyr.esper.net". CS: 0x0400 "weyr.esper.net" "dragonfire.esper.net" A client instructs the server "dragonfire.esper.net" to connect to the server "weyr.esper.net". Replies: ERR_NEED_MORE_PARAMS ERR_ALREADY_CONNECTED ERR_PERMISSION_DENIED ERR_NAME_TOO_LONG 3.5.2 Disconnect message Code: 0x0401 Parameters: server-to-disconnect (string), [dest-server (string)] This message instructs a server to terminate the connection to another server. The dest-server parameter functions as with the connect message, described above. The server-to-disconnect parameter MUST be the name of a server; if the server is not on the network or is not directly connected to the server receiving and acting on the message, the error ERR_NO_SUCH_SERVER is returned. Examples: CS: 0x0401 "weyr.esper.net" A client instructs its server to disconnect the server named "weyr.esper.net". Replies: ERR_NEED_MORE_PARAMS ERR_NO_SUCH_SERVER ERR_PERMISSION_DENIED ERR_NAME_TOO_LONG 3.5.3 Rehash message Code: 0x0402 Parameters: [dest-server (string)] Instructs the dest-server or the server receiving the message to reread any configuration information. The implementation of this message is server-dependent; this message may not be applicable to all servers. This command MAY be unimplemented, or MAY be implemented for use by directly connected clients only. Replies: ERR_NOT_IMPLEMENTED ERR_PERMISSION_DENIED ERR_NAME_TOO_LONG 3.5.4 Restart message Code: 0x0403 Parameters: [dest-server (string)] Instructs the dest-server or the server receiving the message to restart itself. If implemented, the use of this command MUST terminate all connections to the server, clear all state information, and re-read any configuration information. This command MAY be unimplemented, or MAY be implemented for use by directly connected clients only. Replies: ERR_NOT_IMPLEMENTED ERR_PERMISSION_DENIED ERR_NAME_TOO_LONG 3.5.5 Die message Code: 0x0404 Parameters: [dest-server (string)] Instructs the dest-server or the server receiving the message to terminate. If implemented, receipt of this message MUST cause the server to terminate all connections and free all system resources it owns. This command MAY be unimplemented, or MAY be implemented for use by directly connected clients only. Replies: ERR_NOT_IMPLEMENTED ERR_PERMISSION_DENIED ERR_NAME_TOO_LONG 3.6 Query messages These messages return information about the state of a client, a server, or the IRC network as a whole. These messages MUST not be forwarded, except to the target server (where appropriate). 3.6.1 Who message Code: 0x0500 Parameters: who (string), [target-server (string)] nickname (string), status (bits-16), userhost (addr-string), real-name (string), servername (string), channel (string), [extra (string)] bits-16 = shortint Requests information about the given "who". The string may contain wildcards. The string is matched against the nicknames, usernames, hostnames, real-names, server names, and currently joined channels for each client on the network, and any matches are returned in a message (one for each match) with the same message code and the following parameters: nickname: The nickname of the client. status: A 16-bit word with bits set as follows: Bit 3: 1 if the client has UMODE_INVISIBLE set (see section 3.4.4). Bit 2: 1 if the client is marked away (see section 3.4.2). Bit 1: 1 if the client is a channel operator on at least one channel. Bit 0: 1 if the client is an IRC operator. userhost: The address of the client in "user@host" format. real-name: The "real name" provided by the client. servername: The name of the server to which the client is connected. channel: If the client is in a channel matching the "who" mask, the name of that channel, else an empty string. If the client is in multiple channels matching the mask, the server may return any one of them. extra: Any other information on the client (format is implementation- and server-dependent). The upper four bits of the status parameter are reserved for experimental and/or local use. All other bits are reserved for future expansion of the protocol and MUST NOT be used by any client or server. Clients with UMODE_INVISIBLE set do not match any string (even one without wildcards) unless the sender is an IRC operator, in which case they match as normal clients do. Servers MUST send a RPL_WHO_END reply after the last response message. This reply is sent even when no response messages are generated (i.e. no clients match the given wildcard). If a target-server parameter is provided, the message MUST be forwarded to the given server, which will then respond from its point of view. Examples: CS: 0x0500 "achurch" A client requests information on any clients matching the string "achurch". SC: 0x0500 "Alcan" 0x0005 "achurch@achurch.org" "Andrew Church" The server replies with the author's client information. Replies: ERR_NEED_MORE_PARAMS RPL_WHO_END 3.6.2 Names message Code: 0x0501 Parameters: channel (string), [target-server (string)] channel (string), status-nickname (string) ... Requests a list of clients in channels matching the given channel string, which may contain wildcards. For each channel matching the given string, a message is returned with the first parameter set to the channel name and subsequent parameters set to the nicknames of the clients in the channel; each nickname is prefixed by an 8-bit value with bits set as follows: Bits 7-6: Reserved for experimental or local use. Bits 5-2: Reserved, all clear (0). Bit 1: Set (1) if the client is a channel operator, else clear (0) Bit 0: Set (1) if the client has been "given a voice" (see section 3.3.6), else clear (0) If the sending client is not in the channel, clients with UMODE_INVISIBLE set (see section 3.4.4) are not included in the generated message. Private channels (channels with CMODE_PRIVATE set; see section 3.3.3) are not returned unless the given string is an exact (case-insensitive) match for the channel name; secret channels are not returned unless the preceding condition is satisfied and the client is in the channel. Servers MUST return a RPL_NAMES_END reply after all responses (if any) have been sent. Examples: CS: 0x0501 "#dragon*" A client requests a list of the clients in any channels matching the string "#dragon*". SC: 0x0501 "#dragonweyr" "\x02Alcan" The server returns a list of nicknames in channel "#dragonweyr", showing that Alcan is a channel operator in that channel. (The notation "\x02" is used to indicate an octet with hexadecimal value 02.) Replies: ERR_NEED_MORE_PARAMS RPL_NAMES_END ERR_NAME_TOO_LONG ERR_INVALID_NAME 3.6.3 List message Code: 0x0502 Parameters: channel (string), [target-server (string)] channel (string), clients (longint), topic (string) Requests information on any channels matching the given channel string, which may contain wildcards. In responses, the clients parameter is set to the total number of clients (including clients with UMODE_INVISIBLE set; see section 3.4.4) in the channel, and the topic parameter is set to the channel's current topic. Private channels (channels with CMODE_PRIVATE set; see section 3.3.3) are not listed unless the given string is an exact (case-insensitive) match for the channel name; secret channels are not listed unless the preceding condition is satisfied and the client is in the channel. One response message is sent for each channel matching the query; after all responses have been sent, a RPL_LIST_END reply is sent indicating the end of the list. Examples: SC: "#dragonweyr" 1 "Channel #dragonweyr's topic" A server replies to a list request for channel "#dragonweyr". Replies: ERR_NEED_MORE_PARAMS RPL_LIST_END ERR_NAME_TOO_LONG ERR_INVALID_NAME 3.6.4 Whois message Code: 0x0503 Parameters: nickname (string), [target-server (string)] nickname (string), userhost (string), name (string), servername (string), serverdesc (string), signon (timestamp), idle (longint), status (bits-16), [away (string)] Requests information on a particular client. The fields in the reply are as follows: nickname: Nickname of the client, as sent in the query. userhost: Address of the client, in "user@host" format. name: Name given by the client at registration time. servername: The name of the server the client is connected to. serverdesc: The description of the server the client is connected to. signon: Time when the client connected to its server. idle: Time in seconds since the client last send a public or private message (see sections 3.2.1 and 3.2.2). If the client is not directly connected to the responding server, the value is -1 (all bits set); clients should interpret this value as "unknown". status: A 16-bit word with bits set as follows: Bit 1: 1 iff the client is marked away. Bit 0: 1 iff the client is an IRC operator. away: The client's away message (see section 3.4.2). Sent iff the client is marked away. The upper four bits of the status parameter are reserved for experimental and/or local use. All other bits are reserved for future expansion of the protocol and MUST NOT be used by any client or server. Examples: SC: 0x0503 "Alcan" "achurch@achurch.org" "Andrew Church" "dragonfire.esper.net" "Dragonfire's IRC server" 879185792 1234 0x0003 "not here" Replies: ERR_NEED_MORE_PARAMS ERR_NO_SUCH_USER ERR_NAME_TOO_LONG 3.6.5 Whowas message Code: 0x0504 Parameters: nickname, [target-server (string)] nickname (string), userhost (string), real-name (string), servername (string), signoff (timestamp) Requests information on previous users of a nickname. One response message is returned for each user, starting from the most recent. The number of responses returned is implementation-dependent; however, a RPL_WHOWAS_END reply MUST be sent after the last response. The values of the parameters in the reply are: nickname: Nickname of the client, as sent in the query. userhost: Address of the client, in "user@host" format. real-name: "Real name" given by the client at registration time. servername: The name of the server the client was connected to. signoff: Time when the client disconnected from its server. This command MAY be unimplemented. Examples: SC: 0x0504 "Alcan" "achurch@achurch.org" "Andrew Church" "dragonfire.esper.net" 879085832 The server sends information about a previous instance of the author's client. Replies: ERR_NOT_IMPLEMENTED RPL_WHOWAS_END ERR_NEED_MORE_PARAMS ERR_NAME_TOO_LONG 3.6.6 Ison message Code: 0x0505 Parameters: [nickname (string) ...] This message, when sent by the client, requests a reply from the server indicating which of the nicknames given is currently connected to the IRC network. The server sends back the a message with the same message code and a parameter list containing only those nicknames originally specified which are currently connected to the network (which may be an empty list). This message MUST be parsed by the client's server and MUST NOT be forwarded to any other server. Note that an ERR_NAME_TOO_LONG reply MUST NOT be generated by this message even if a nickname given in the list is longer than the allowable length. Examples: CS: 0x0505 "xhdslas" "Alcan" A client asks whether any of the nicknames "xhdslas" and "Alcan" are currently online. SC: 0x0505 "Alcan" The server replies that the nickname "Alcan" is currently online (and it can thus be deduced that the nickname "xhdslas" is not currently online). Replies: None. 3.6.7 Users message Code: 0x0506 Parameters: [server (string)] clients (longint), channels (shortint), servers (shortint), my-clients (shortint), my-servers (shortint) Requests information on the number of clients connected to the IRC network and the client's server. If the server parameter is given, the message is forwarded to that server, which replies from its point of view. The server MUST send a users message back to the client with the following numeric information: clients : Number of clients connected to the network. channels : Number of channels existing on the network. servers : Number of servers connected to the network. my-clients: Number of clients connected to the responding server. my-servers: Number of servers connected to the responding server. In addition, the server MUST send one or more RPL_USERS replies to the client. A server MAY send a single RPL_USERS with no descriptive string, or MAY send one or more RPL_USERS replies with descriptive strings included; in the latter case, the server SHOULD include in the reply strings all information included in the numeric response, and MAY include any other information considered relevant. If an interactive client receives a reply without a descriptive string, it SHOULD display the information received from the server in an appropriate format; otherwise, it SHOULD display only the text included in the RPL_USERS replies and use the numeric responses for updating internal information only. This command MAY be unimplemented. Examples: CS: 0x0506 A client requests information on the number of clients connected to the network. Replies: ERR_NOT_IMPLEMENTED RPL_USERS_END ERR_NAME_TOO_LONG 3.6.8 Message of the Day message Code: 0x0507 Parameters: [server (string)] text (string) Requests the "Message of the Day" from the client's server or the specified server. The text of this message is server-dependent. The server MAY either send a single response with the entire text or split the text into multiple responses (for example, one response per line); in either case, the server MUST send a RPL_MOTD_END reply after the last response. Examples: CS: 0x0507 A client requests the Message of the Day from the server to which it is connected. SC: 0x0507 "This is the Message of the Day." The server responds with its Message of the Day. CS: 0x0507 "dragonfire.esper.net" A client requests the Message of the Day from the server "dragonfire.esper.net". Replies: ERR_NAME_TOO_LONG RPL_MOTD_END 3.6.9 Administrative information message Code: 0x0508 Parameters: [server (string)] text (string) Requests administrative information from the client's server or the specified server. The server MUST respond with at least one message, though it MAY send more. The server MUST sent a RPL_ADMININFO_END reply after the last response message. The format of the response text is implementation- and server-dependent. Examples: See section 3.6.8. Replies: ERR_NAME_TOO_LONG RPL_ADMININFO_END 3.6.10 Server information message Code: 0x0509 Parameters: [server (string)] text (string) Requests information about the client's server or the specified server. The server MUST respond with at least one message, though it MAY send more. The server MUST sent a RPL_SERVERINFO_END reply after the last response message. The format of the response text is implementation- and server-dependent. Examples: See section 3.6.8. Replies: ERR_NAME_TOO_LONG RPL_SERVERINFO_END 3.6.11 Server version message Code: 0x050A Parameters: [server (string)] version (string), [extra (string)] Requests version information for the client's server or the specified server. In the response, the version parameter MUST contain a string giving only the server's version number; any additional information, such as the software build date, should be included in the second parameter (extra). Examples: SC: 0x050A "1.3.10" "build 159, compiled Oct 31 1999" A server replies with its version information to a client. Replies: ERR_NAME_TOO_LONG 3.6.12 Statistics message Code: 0x050B Parameters: type (byte), [server (string)] type (byte), text (string) ... byte = octet Requests server statistics of the given type from the client's server or the named server. The server responds with zero or more messages using the same code and the same value for the type parameter, followed by a RPL_STATS_*_END message in which the 8 bits of the reply code sent are equal to the type value. However, a server MUST generate ERR_BAD_STATS_TYPE_* (with the low 8 bits of the reply code equal to the type value) if it is not prepared to handle a given type request. The actual statistics information is included in the text parameter or parameters. All parameters (other than the first parameter, type) MUST be strings; numeric information SHOULD be encoded in a human-readable format, such as decimal or hexadecimal values. Servers MAY limit all or some type requests to operators only. Servers MAY generate ERR_BAD_STATS_TYPE_* instead of ERR_PERMISSION_DENIED when denying a particular request type, but SHOULD generate ERR_PERMISSION_DENIED if all types are denied to unprivileged users. For the purpose of this protocol, the meaning of the type parameter and the format of the replies are implementation- and server-dependent. However, the following values of "type" are recommended by this document; all implementations SHOULD support these types when possible, to provide a common set of statistics requests. For implementations supporting these requests as described, replies are defined to have the following format: * All items listed MUST be sent in the order listed. Additional items MAY be appended after the required information. * The format of remote addresses in statistics information is implementation- and server-dependent, but addresses MUST NOT contain the comma character (ASCII 0x2C). * All numeric values MUST be represented as decimal values using the characters "0" through "9" (ASCII 0x30 through 0x39), except where otherwise specified; hexadecimal values MUST be represented using the characters "0" through "9", "A" through "F", and "a" through "f" (ASCII 0x30 through 0x39, 0x41 through 0x46, and 0x61 through 0x66). Implementations SHOULD consistently use either upper case or lower case letters for all hexadecimal values in responses. * For requests on connection restrictions and bans, rules MUST be listed in the order in which they are applied. 0x61: Network ban information Requests a list of active network bans, including: * Remote address to which the ban applies. * Username to which the ban applies (possibly including wildcards). * Nickname to which the ban applies (possibly including wildcards). 0x63: Server connection information Requests a list of what servers the server will attempt to connect to or allow to connect, including: * The character "B" for a border server or "S" for a regular server. * Server name. * Comma-separated list of remote addresses to which this server will attempt to connect upon receiving a connect message for the given server. * Comma-separated list of remote addresses from which this server will allow the given server to register itself. * The character "*" if a password is required for connection, "-" otherwise. 0x69: Client connection restrictions Requests a list of restrictions upon client connections, including: * Comma-separated list of remote addresses to which this rule applies. * The character "*" if a client matching the rule is required to enter a password, "-" otherwise. 0x6B: Server ban information Requests a list of active server bans, including: * Remote address to which the ban applies. * Username to which the ban applies (possibly including wildcards). * Nickname to which the ban applies (possibly including wildcards). 0x6C: Active connection statistics Requests information on all active connections, including: * The character "B" if the connection is a border server, "S" if it is a regular server, "C" if it is a client. * Remote address. * Total number of octets sent. * Total number of messages sent. * Total number of octets received. * Total number of messages received. * Absolute time at which the connection was established. 0x6D: Message statistics Requests usage information for each message code supported by the server, including: * Message code, represented as a 4-digit hexadecimal number. * Number of times the message has been received. * Total number of octets included in all received instances of the message. Servers MAY omit message codes which have never been received. 0x6F: Operator restrictions Requests information on restrictions on clients becoming IRC operators, including: * Remote addresses from which the client may become an operator. * Username under which the client may become an operator (possibly including wildcards). * Nickname under which the client may become an operator (possibly including wildcards). 0x75: Server uptime Requests information on how long the server has been active, as well as the maximum number of connections reached, including: * Number of seconds since the server was started. * Maximum number of connections. * Number of clients connected when the maximum number of connectoins was first reached. Examples: CS: 0x050B 0x75 A client requests statistics of type 0x75 from the server to which it is connected. Replies: ERR_NEED_MORE_PARAMS RPL_STATS_*_END ERR_NAME_TOO_LONG ERR_PERMISSION_DENIED ERR_BAD_STATS_TYPE_* 3.6.13 Links message Code: 0x050C (servers only), 0x058C (all connections) Parameters: [server (string)] type (octet), established (timestamp), active (timestamp), writebuf (longint), readbuf(longint), ipaddr (string), hostname (string), username (string), [extra (string)] Requests information on active connections for the client's server or the specified server. If the sender is an IRC operator or another server and the message code is 0x058C, information on all connections is sent; otherwise, only information on server connections is sent. The server MUST respond with the same message code as was used in the request. A RPL_LINKS_END is sent after all responses have been sent. The parameters are as follows: * type One character (octet) representing the connection type: "S" (ASCII 0x53) for a server on the same network, "B" (ASCII 0x42) for a border server of another network, "O" (ASCII 0x4F) for an IRC operator, "C" (ASCII 0x42) for a non-IRC-operator client, or "?" (ASCII 0x3F) for a connection which has not yet registered. Servers MAY use other values to indicate special types of connections, but SHOULD restrict those values to values which are printable as characters in ASCII. * established The timestamp when the connection was established. * active The timestamp when data was most recently received from the remote end of the connection. * writebuf The number of octets of data which have been scheduled to be sent to the remote host but have not yet been passed to the transport layer (i.e. write buffer length). If the implementation does not support a write buffer, this value is zero. * readbuf The number of octets of data which have been received from the remote host but not yet processed by the server (i.e. read buffer length). If the implementation does not support a read buffer, this value is zero. * ipaddr The raw address of the remote host (dotted-quad format, e.g. 123.45.67.89, for IPv4). * hostname The hostname as determined by the server (which may be the same as the raw address; see section 6.2). * username If the connection is a client, the client's username, otherwise an empty string. * extra Any other information considered relevant. The format of this information is implementation- and server-dependent. Servers MAY limit the use of this command to IRC operators, or MAY limit the information returned to non-operator clients. Examples: See section 3.6.8. Replies: ERR_NAME_TOO_LONG RPL_LINKS_END ERR_PERMISSION_DENIED 3.6.14 Trace message Code: 0x050D (server), 0x058D (client) Parameters: target (string) [text (string)] Requests information on the route through the IRC network to a particular target (which may be a client nickname or a server name). Any server receiving this message which is not the target (including the server to which a target client is connected) MUST send a RPL_TRACE reply back to the source. The target server (in the case of a client target, the server to which the client is connected) sends a response using the same message code as the original request used; in the case of a client target, this response MUST be sent after the RPL_TRACE reply from the server itself. Servers MUST NOT send trace messages to clients. The format of any text message included with either the RPL_TRACE reply or the message response is implementation- and server-dependent. Servers MAY limit the use of this command to IRC operators. Examples: CS: 0x050D "dragonfire.esper.net" A client requests information on the route to the server "dragonfire.esper.net". Replies: ERR_NEED_MORE_PARAMS RPL_TRACE ERR_NAME_TOO_LONG ERR_PERMISSION_DENIED 3.6.15 Time message Code: 0x050E Parameters: [server (string)] time (timestamp) Requests the server's current time. The server MUST send a response containing the server's idea of the current time. (This need not be the same as, for example, the current time returned by the system on which the server is running; servers may have a method, not defined in this protocol, to synchronize their clocks with each other or otherwise adjust their idea of the current time.) Examples: See section 3.6.8. Replies: None. 3.7 Miscellaneous messages These messages do not fit easily into any other category. 3.7.1 Ping message Code: 0x7FFE Parameters: [text (string), [target-server (string)]] The ping message is designed to test the integrity of a client or server connection. A client or server which receives a ping message MUST reply by sending a pong message (see section 3.7.2) to the sender as soon as possible. If the optional text parameter is included in the ping message, an identical text parameter MUST be sent with the corresponding pong message. The ping message can be sent by clients as well as servers. If sent by a client, the optional target-server parameter specifies that the message should not be interpreted by the client's server itself, but should be sent to the named server. Only servers can be pinged by clients in this fashion; servers MUST NOT send (or forward) ping messages to clients which are not directly connected to them. Clients may implement a protocol on top of the IRC protocol, using the standard message and notice commands (section 3.2), to allow a client to ping another client (CTCP [8] is an example of such a protocol). Examples: SC: 0x7FFE A server tests whether a client's link is active. CS: 0x7FFE "879150517" "dragonfire.esper.net" A client sends a ping message with the text "879150517" to the server "dragonfire.esper.net". A message such as this one, with a timestamp in the text parameter (the timestamp could just as easily be in binary), can be used to test the round-trip delay between a client and a server. Replies: ERR_NO_SUCH_SERVER 3.7.2 Pong message Code: 0x7FFF Parameters: [text (string)] Sent in reply to a ping message (see section 3.7.1). Servers and clients MUST NOT generate any messages or replies upon receiving a pong message, with the exception that a server MAY generate server notices (see section 3.2.4) indicating the status of a particular link. Examples: CS: 0x7FFF A client responds to a ping message sent by its server. Replies: None. 3.8 Reserved message codes To allow for testing and implementation of features specific to a single IRC network or potential additions to the IRC protocol, one-half of the message code space is allocated for custom use. Specifically, all message codes in the range 0x8000-0xFFFF (i.e. those with bit 15 set) are reserved for this purpose. All other command codes not listed in this section are reserved for future expansion of the IRC protocol. Clients and servers MUST NOT generate any such messages, and MUST discard any such message received. 3.9 Erroneous messages There are two types of erroneous messages: syntactically invalid messages and functionally invalid messages. Syntactically invalid messages are those which do not conform to the definitions in this protocol; these include messages with undefined message codes, messages with insufficient numbers of parameters, and messages containing names (for clients, channels, servers, or networks) with either invalid characters or too many characters. Error messages corresponding to these conditions are listed in section 4.2.1. Of the syntactic errors, the only ones whose generation is not mandatory are ERR_NAME_TOO_LONG and ERR_INVALID_NAME. In the case of a name which is longer than the maximum allowable length, a server MAY send this reply and discard the message; if it does not do so, it MUST truncate the offending name to the maximum allowable length and continue processing the message normally. In the case of a channel name whose first character is not recognized by the server, the server MAY generate ERR_INVALID_NAME and discard the message if the message is from a directly-connected client, but MUST accept the channel name and continue processing the message normally, without altering the channel name, otherwise. All other syntactic errors MUST be generated as soon as the corresponding condition occurs, and the server generating the error MUST discard the message. Functional errors are much more numerous, and which messages can generate which errors varies from message to message. There is, however, one functional error which can be generated by nearly all messages: ERR_NOT_REGISTERED. If a client sends any message other than the password message before sending a registration message, the server receiving the message MUST discard it and generate an ERR_NOT_REGISTERED reply. 3.10 Use of experimental message codes In an effort to preserve compatibility between clients and servers which utilize experimental message codes, the following guidelines are provided regarding the use of such message codes. If an implementor wishes to modify or enhance a message described in this document, s/he has two options: 1) Add functionality to the processing of the message to support the modification or enhancement. 2) Utilize an experimental message code (see section 3.8) to support the modification or enhancement, and leave the original message processing as is. In case 1, the implementor may add, remove, or rearrange parameters for the experimental version of the message; the server can then determine, based either on the number of parameters provided or on some earlier agreement with the remote client or server to use the experimental format, whether to process the message using the implementor's new method or the method defined in this document. For example, an implementor may add a parameter to the user registration messages specifying a homepage URL for the client; a client aware of the new functionality can provide the extra parameter, while an unaware client which does not provide the parameter will have its message processed according to this document. In case 2, the implementor defines a new message code for each modified message, and alters its behavior depending on whether the original or new message code is used. When possible, implementors SHOULD select new message code numbers by adding 8000 hexadecimal (i.e. by setting bit 15) to an existing message number; for example, a modified user message (section 3.1.2) would have code 8001 hexadecimal. In this case, a client which sends an experimental message code and receives an ERR_UNKNOWN_COMMAND response MUST resend the message according to the protocol defined in this document when possible. Since there are no message ID numbers associated with messages to or from clients, the client needs to make a "best guess" as to which message caused a particular error response. Implementors MUST ensure that, regardless of any modifications or enhancements made to this protocol, the messages specified in this section function exactly as described when used in the manner described. For example, a server with a modified user registration message as described in the example for case 1 above MUST ensure that a client which sends a user registration message according to the specification given in this document has that message processed as specified in this document. 4. REPLIES This section lists all reply codes and their names and meanings. (The names are intended merely as mnemonics, and do not necessarily need to be included in an IRC implementation.) 4.1 Command responses These replies are sent when a command completes successfully. All responses have bit 15 clear. Note that in many cases, the successful completion of a command will generate one or more new messages, and thus no reply is needed for those cases. 0x0000 RPL_WELCOME Sent to acknowledge a successful client registration request. 0x0001 RPL_WELCOME2 This reply may be sent zero, one, or multiple times to (for example) provide the client with information about the server. 0x0080 RPL_SERVER_WELCOME Sent to acknowledge a successful server registration request. 0x00C0 RPL_BSERVER_WELCOME Sent to acknowledge a successful remote (border) server registration request. 0x0100 RPL_NOW_OPERATOR Sent to acknowledge a successful client request to be given IRC operator status. 0x0110 RPL_MARKED_AWAY Sent to acknowledge that a client has been marked away. 0x0111 RPL_MARKED_UNAWAY Sent to acknowledge that a client is no longer marked away. 0x0120 RPL_SILENCE_ADD Sent to confirm addition of a mask to the client's silence list. 0x0121 RPL_SILENCE_DEL Sent to confirm deletion of a mask from the client's silence list. 0x0122 RPL_SILENCE_END Sent after the last entry of a client's silence list has been sent (see section 3.4.3). 0x0200 RPL_WHO_END Sent in response to a who message (see section 3.6.1). 0x0201 RPL_NAMES_END Sent in response to a names message (see section 3.6.2). 0x0202 RPL_LIST_END Sent in response to a list message (see section 3.6.3). 0x0204 RPL_WHOWAS_END Sent in response to a whowas message (see section 3.6.5). 0x0206 RPL_USERS_END Sent in response to a users message (see section 3.6.7). 0x0207 RPL_MOTD_END Sent in response to a Message of the Day request (see section 3.6.8). 0x0208 RPL_ADMININFO_END Sent in response to an administrative information request (see section 3.6.9). 0x0209 RPL_SERVERINFO_END Sent in response to a server information request (see section 3.6.10). 0x020C RPL_LINKS_END Sent in response to a links request (see section 3.6.13). 0x02FF RPL_TRACE Sent in response to a trace request (see section 3.6.14). 0x0300 RPL_STATS_00_END through 0x03FF RPL_STATS_FF_END Sent in response to statistics requests (see section 3.6.12). 4.2 Error messages Error messages can be divided into two categories: syntactical errors and functional errors. The former indicate errors in the format of the message; the latter indicate failure to carry out an otherwise valid command. All error codes have bit 15 set; all functional error codes also have bit 14 set, while syntactical error codes have bit 14 clear. 4.2.1 Syntactical errors 0x8000 ERR_UNKNOWN_COMMAND A command was received that was not understood. 0x8001 ERR_NEED_MORE_PARAMS Required parameters for the given command were missing. 0x8002 ERR_TOO_MANY_PARAMS More parameters were provided for the given command than were expected. 0x8100 ERR_INVALID_NAME A name (nickname, channel name, server name) that included invalid characters was given in a message. 0x8101 ERR_NAME_TOO_LONG A name (nickname, channel name, server name, or network name) given in a message was longer than the maximum allowed length. 4.2.2 Functional errors 0xC000 ERR_ALREADY_REGISTERED A connection may only be registered once; if a second registration command is sent over an already-registered connection, this error is returned. 0xC001 ERR_NOT_REGISTERED Other than the password message (see section 3.1.1), the first message sent across a connection must be a registration message. Any other message causes this error. 0xC002 ERR_BAD_PASSWORD An entity attempted to register a connection but failed to supply the correct password. 0xC003 ERR_NICKNAME_IN_USE A client tried to register with or change to a nickname which was already being used by another client. 0xC040 ERR_WRONG_VERSION The version number sent in a registration message was not accepted. 0xC080 ERR_ALREADY_CONNECTED A connect message was issued for a server-server link which already exists. 0xC081 ERR_NOT_SERVER A client tried to issue a message that is limited to servers. 0xC100 ERR_NO_SUCH_CHANNEL The target channel given for a channel-based command does not exist. 0xC101 ERR_NO_SUCH_USER The target nickname given for a command does not exist. 0xC102 ERR_NOT_IN_CHANNEL A client tried to send a part message for a channel or make changes (mode, etc.) to a channel without being in that channel. 0xC103 ERR_WAS_NO_SUCH_USER A client requested "whowas" information for a nickname (see section 3.6.5), but the server did not have any information on previous users of the nickname. 0xC104 ERR_ALREADY_IN_CHANNEL A client in a channel tried to join that channel again. 0xC105 ERR_NOT_ON_SILENCE_LIST A client tried to remove an entry from its silence list that was not found on the list. 0xC180 ERR_NO_SUCH_SERVER A named server does not exist. 0xC200 ERR_PERMISSION_DENIED A client without sufficient privileges tried to execute a privileged command. (For example, a non-privileged client tried to send a kill message, or a non-channel operator tried to send an invite message.) 0xC201 ERR_CLIENT_DENIED A client sent a user message (see section 3.1.2) which was rejected by the server. 0xC210 ERR_CANNOT_SEND A message cannot be sent to its target. 0xC211 ERR_CANNOT_JOIN A join message was disallowed. 0xC213 ERR_CANNOT_CHANGE_LOCKED A client tried to change channel modes while the CMODE_LOCKED mode (see section 3.3.3) was set. 0xC280 ERR_SERVER_DENIED A server registration message (see section 3.1.3) was sent which was rejected by the receiving server. 0xC281 ERR_NETWORK_DENIED A remote server registration message (see section 3.1.4) was sent which was rejected by the receiving server. 0xC300 ERR_BAD_STATS_TYPE_00 through 0xC3FF ERR_BAD_STATS_TYPE_FF Sent in response to statistics requests (see section 3.6.12) when the server cannot handle the requested type. 0xDFFE ERR_INTERNAL_ERROR An internal error prevented the server from carrying out a function. 0xDFFF ERR_NOT_IMPLEMENTED A message was received which was understood but was not implemented. 4.3 Reserved reply codes To allow for testing and implementation of features specific to a single IRC network or potential additions to the IRC protocol, one-half of the reply code space is allocated for custom use. Specifically, all reply codes with bit 13 set, i.e. 0x2000-0x3FFF, 0x6000-0x7FFF, 0xA000-0xBFFF, and 0xE000-0xFFFF, are reserved for this purpose. All other reply codes not listed in this section are reserved for future expansion of the IRC protocol, and servers MUST NOT generate any such replies. 5. PROBLEMS AND LIMITATIONS There are a number of recognized problems and limitations of this protocol, some carrying over from the earlier IRC protocol. 5.1 Scalability Within the network context, this protocol, like the old protocol, scales poorly due to the requirement that all servers maintain state information for the entire network. As more clients and servers join a network, the load on every server will increase, degrading communications between servers and ultimately between clients. While the use of a single "state server" was considered as an alternative to the current approach, it was deemed unacceptable, since a failure of either the state server itself or its connection to the rest of the network would render the entire network nonfunctional. Instead, a set of commands was added to the protocol to allow a server from one network to communicate with a server from another network while keeping the two networks distinct. In this model, servers are only required to maintain information about the network of which they are a part, and networks can remain relatively small while allowing communication with other entities outside of the network. The inter-network communications protocol introduces a scalability problem of its own: namely, the fact that to allow N networks to communicate with each other, there must be O(N^2) connections between the networks. While a "relay" approach similar to the server relay method of sending messages within networks was considered, it was deemed not worth the additional effort required to implement such a second-level relay given the current sizes and numbers of networks. This may be re-evaluated in the future. 5.2 Name collisions Like the earlier IRC protocol, there exists the possibility of name collisions. These are caused by race conditions which are unavoidable due to the distributed nature of IRC; for example, two clients may connect to two different servers at exactly the same time and choose the same nickname, resulting in a nickname collision when the two messages' paths intersect. The following sections detail the procedures for resolving collisions of the different categories of names. 5.2.1 Nickname collisions If a server receives a client registration or nickname change message from another server, and the nickname for the new client matches the nickname of a client already present on the IRC network, the server receiving the colliding message MUST remove from its internal list of nicknames whichever has the more recent nickname change time (which is the registration time for a client registration message). If that client is directly connected to the server, then the server MUST terminate the connection with an appropriate quit message (see section 3.1.6). In the case where both nicknames have the same change time, the server MUST remove both nicknames (and terminate connections as necessary). FIXME: compare this with TS8 5.2.2 Server name or ID collisions If a server receives a server registration message from another (already-connected) server, and either the name or the ID number (but not both) match those of another server present on the network, the server receiving the message MUST issue a server-quit message for the ID number(s) of both servers, thus removing both colliding servers from the network. However, servers SHOULD NOT issue a server-quit message for the forwarder of a colliding server message; doing so could easily cause more havoc than necessary. In the case of a malicious server intentionally issuing colliding server messages or a misconfigured server being abused for the same purpose, IRC operators can intervene and disconnect that server. 5.2.3 Channel collisions Channel collisions present something of a greater problem than do nickname and server collisions. Unlike those, a channel is not a single concrete entity; rather, it is an alias for a list of clients. There is no way to determine, in fact, whether a channel on a new server has collided with a channel on the network or whether clients on the new server just happened to join the channel immediately after the server connected to the network. Thus, channel collisions are treated inclusively. When a server receives a channel mode message or join message from another server, it MUST act on that message regardless of any other state information; for example, if a server sends a join message for a client which is banned from the channel on another server, the second server must allow the client to join despite the ban. One possible consequence of this collision resolution method is that a malicious user could take advantage of data transmission delay between servers to set a channel's modes such that the channel's ordinary users would be unable to use the channel. To avoid this situation, server implementors may want to consider allowing users with IRC operator privileges (or some other local privilege level) to circumvent channel mode and ban restrictions, or including support for a special "network service" server which would have the ability to change channel modes on request by sufficiently privileged users (Services for IRC Networks [9], originally developed by the author of this document, is an example of such a "network service" server). 5.2.4 Network name collisions If two servers on a network announce themselves as border routers (see section 3.1.5) for the same network, the servers are assumed to have connected to the same network. Servers sending remote messages to that network SHOULD choose the shortest path to a border server. Note that if two servers connect to different networks each of which claims to have the same name, it is unspecified which network will receive messages; this is similar to, for example, the case of two nodes on a physical network claiming to have the same IP address. Server and network administrators must take care to ensure that no duplication of network names occurs. 5.3 Timekeeping Because parts of this protocol -- in particular, the collision resolution methods described above -- depend on knowing the time at which an event happened, and because timestamps may be generated by different servers, it is important that the servers' clocks be as closely synchronized as possible. A server with a clock which differs significantly from those of other servers may cause unexpected results if collisions occur. Therefore, servers SHOULD use a method such as the Network Time Protocol [10] to keep their clocks synchronized. 5.4 Connection desynchronization Since there is no specific marker for the end of a message, a communication error can cause complete desynchronization of a connection. If, for example, noise on a network link resulted in a series of "1" bits being sent in the length field of a client's message, the server would then attempt to read 4,294,967,295 bytes of data, which in all likelihood would not be sent before the server dropped the connection due to a ping timeout (see section 3.7.1). For this reason, servers SHOULD use a reliable transport protocol (such as TCP [5]) to minimize the possibility of desynchronization. (Also, see section 5.5 below for additional reasons for the use of a reliable transport protocol.) 5.5 Cyclic networks While the introduction of cycles into IRC networks increases their reliability, it also adds some complexity to the process of message passing. In the non-cyclic tree structure of networks under the old IRC protocol, it was sufficient for a server forwarding a message to simply send the message to all directly-connected servers other than the one from which it received the message; the non-cyclic nature of the network guaranteed that each server would receive the message exactly once. However, in a cyclic network, this approach would result in a message being sent endlessly in circles. To avoid this problem, two methods are used, as described in section 2.2.2: sequence numbers and a hop list. While sequence numbers are sufficient to prevent messages from being processed more than once by any given server, a hop list is also used to reduce network traffic at the expense of additional computation, since the former is seen as the more severe bottleneck. (This may be reevaluated in the future.) When a server generates a server-to-server message, it inserts its next sequence number in the message. Servers receiving a message check that the received sequence number is greater than the last sequence number seen from the originating server (modulo 2**32), and discard messages that do not meet this test as duplicates. Note that the sequence numbers generated by one server as seen from the viewpoint of another server are guaranteed only to be strictly increasing, not to be monotonically increasing. Some messages (in particular, messages to channels or clients on other servers) will not be sent to all servers, so some servers will see "gaps" in sequence numbers between messages. When a server sends a message (whether generated or forwarded) to another server, it inserts itself at the head of the server hop list in the message. Servers never forward messages to servers already on the hop list. This prevents the sending of duplicate messages to servers which have already seen it and would just discard the duplicate anyway. 6. SECURITY CONSIDERATIONS 6.1 IP spoofing A fairly well-known method of network attack, called spoofing, involves sending data from one host and making it appear to be from another, usually more trusted, host. In order to decrease the likelihood of success of a spoofing attack on IRC, which could be used (for example) to gain increased channel access from automated clients or to attack the reputation of another user, servers SHOULD send a ping message (see section 3.7.1) immediately upon registration of a connection, including in the message one parameter containing a randomly generated series of octets. A server implementing this procedure MUST discard all messages from the remote end of the connection without processing them until either the remote end replies with a pong message containing the same string or the ping timeout period expires. A server MAY reduce the timeout period for this ping message. An example client/server dialog using this procedure: (commands are given by their names in angle brackets) Client: "secretpass" Client: "Alcan" "achurch" "Andrew Church" Server: 0x419FC82D834960017D2A9AB540FF1683E7 Client: 0x419FC82D834960017D2A9AB540FF1683E7 (regular commands and replies follow) Since this procedure is only effective if the client cannot predict the series of octets sent by the server, servers implementing this procedure MUST ensure that the generated series of octets is truly random, or at least as unpredictable as possible without consuming undue processing time (to avoid resource consumption attacks caused by a client repeatedly connecting to the server). 6.2 DNS spoofing Another way in which malicious users may try to exploit trust systems is DNS spoofing, i.e. altering DNS records to make one host appear to have the name of another host. While spoofers may be able to just as easily modify both the forward and reverse lookup records, thus hiding any trace of their activity, the following procedure will catch at least those who can only alter one of the records; all servers SHOULD follow this procedure when determining the hostname of a remote connection. Upon receiving a connection, the server looks up the name assigned to the remote address. Assuming that lookup succeeds, the server then looks up the address associated with the name it found. If the second lookup fails or its result does not contain the actual address of the remote host, the server MUST use the remote host's raw address (dotted-quad format for IPv4, e.g. 123.45.67.89) for the remote hostname. Servers SHOULD NOT close the connection on a lookup failure or mismatch, because there are some legitimate hosts which have a mismatched IP address and DNS name (possibly due to errors on the part of the administrators for those IP addresses or domains). However, servers SHOULD generate some sort of warning for such an occurrance (for example, via a server message (section 3.2.4)). 6.3 Network sniffing Since this protocol does not include any capability for encrypting data in transit, all data sent and received by servers and clients-- including connection passwords--is vulnerable to network sniffing. For this reason, networks may wish to investigate external encryption methods, such as encrypted IP tunnels. 6.4 Timekeeping and timestamp overflows Section 5.3 discusses the necessity of maintaining synchronized clocks among all servers on a network; a server with an incorrect clock may, among other things, allow users to deliberately disconnect other users or improperly take over control of channels. Furthermore, it is important that implementors be aware of the possibility of timestamp overflows; no matter what time system is used, there are only a finite number of instants of time representable by a timestamp, and if that range is exceeded, unpredictable results similar to the case of a server with an incorrect clock will result. Therefore, implementors SHOULD take appropriate steps to reduce the likelihood of an overflow and/or handle the case of an overflow specially. As a concrete example, implementors using the C language and the "time_t" type defined on Unix (and other) systems should be aware that in many cases the "time_t" type is a 32-bit signed integer, and will overflow in January 2038; such implementors SHOULD explicitly use a 64-bit integer type (or, when such a type is not available, two 32-bit integers) rather than the predefined "time_t" type for handling timestamps. 6.5 Special characters in names The wide range of allowable characters in names (nicknames, server names, and so on) creates the potential for attacks against clients. While servers would be unlikely to encounter problems with any particular character occurring in a name, since no processing of names is performed, interactive clients in particular may suffer from certain types of attacks. For example, an attacker may choose a nickname containing unprintable characters or other characters which a user was unable to input; although this protocol provides a method for clients to filter messages from other clients (see section 3.4.3), the user would be unable to take advantage of this feature and would be at the attacker's mercy. Some clients also have features which rely on text representations of user information (for example, the "@" between a user's username and hostname), and it may be possible for attackers to choose names which cause these features to malfunction; even without such features, attackers can cause confusion to users who view the resulting text. For this reason, servers SHOULD disallow any characters which may cause problems with servers, clients, or users on the network. At present, the following characters are considered potentially dangerous; however, this is not intended to be a complete list, and implementors and administrators should feel free to add or remove characters as necessary. Null character (ASCII 0x00) May cause names to be incorrectly displayed by clients or misinterpreted by servers (0x00 is used as a string terminator in some programming languages). ASCII control characters (ASCII 0x01..0x1F) May cause unintended display side effects. However, servers MAY permit certain characters when those characters are in common use; for example, many IRC clients use control characters for bold, underline, or other display effects. " " (ASCII 0x20) May be misinterpreted by clients as a parameter separator. "!" (ASCII 0x21) In nicknames, may cause old-protocol clients to consider the "!" as a nickname-username separator. "#" (ASCII 0x23), "&" (ASCII 0x26) At the beginning of nicknames and server names, may cause clients to misinterpret the name as a channel name. "*" (ASCII 0x2A), "?" (ASCII 0x3F) May be interpreted as wildcards when entered by a user. "@" (ASCII 0x40) In nicknames and server names, may cause unintended meaning when a user attempts to send a message to the name (for example, the client may attempt to send to a remote network). Forbidden in usernames and hostnames (see section 3.1.2). 0xA0 On some systems, this is displayed as a space (ASCII 0x20) and may cause confusion. 7. AUTHOR'S ADDRESS Andrew Church Primabera Isejuku #315 10-1 Isejuku, Ichikawa-shi Chiba 272-0106 Japan E-mail: achurch@achurch.org 8. REFERENCES AND NOTES [1] Oikarinen, J. and Reed, D., "Internet Relay Chat Protocol", RFC 1459, May, 1993. [2] Arnold, S., "IRCII 1/2 proposal", http://www.the-project.org/proposals/stevenpaper.html [3] See, for example, the timestamp protocol implemented in many current servers, such as that used on the DALnet (http://www.dal.net/) and UnderNet (http://www.undernet.org/) networks, but not present in the reference implementation or in the protocol definition--note that the exact timestamp protocol also varies (incompatibly) between servers. [4] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", RFC 2119, March, 1997. [5] Postel, J., "Transmission Control Protocol", RFC 793, September, 1981. [6] Crocker, D., "Standard for the Format of ARPA Internet Text Messages", RFC 822, August, 1982. [7] St. Johns, M., "Identification Protocol", RFC 1413, February, 1993. [8] http://www.undernet.org/documents/ctcpinfo.txt [9] http://www.ircservices.za.net/ [10] Mills, David L., "Network Time Protocol (Version 3)", RFC 1305, March, 1992. 9. Copyright notice This document is copyright (c) 2001 Andrew Church. This document may be freely distributed as-is, and may be excerpted as-is provided that the excerpt includes an attribution to the author. This document may be modified, but modified versions may not be distributed unless this notice remains intact and an additional notice is included stating that the document has been modified and where the original document may be obtained. Appendix A. Dijkstra's algorithm Dijkstra's algorithm is an algorithm for finding the shortest path from one node in a graph to one or all others. It involves keeping a table of parents (the "parent" of a node is defined to be the previous node on the shortest path to the node from the starting node), path lengths (the length of a path is simply the sum of the weights of all edges on the path), and "finished" flags, indicating whether the shortest path to the node has been definitively determined. Initially, the path length to all nodes is set to positive infinity (or as close as the chosen numeric format will allow), except for the starting node, which has a path length of 0. The "finished" flag for all nodes, including the starting node, is set to false. While there is at least one node whose "finished" flag is false, choose the unfinished node N with the smallest cost (if there are multiple such nodes, choose any one of them). Set N's "finished" flag to true; then, for all unfinished nodes Q adjacent to N, set Q's path length to the path length of N plus the weight of the edge (N,Q) iff that length is shorter than the current path length for Q. If the goal is to find the shortest path to a single node, the algorithm stops when that node's "finished" flag becomes true. Appendix B. Alphabetical list of message and reply elements ack = flag serverid serverid seqnum ; first serverid is source, ; second is destination ack-request = flag serverid serverid addr-octet = addr-string = length * "@" * addr-unichar = addr-unistring = length * "@" * bits-16 = shortint bits-32 = longint byte = octet cli-serv-msg = code [network] * ;message from client to server client-message = flag length32 (cli-serv-msg / serv-cli-msg) clientid = shortint code = shortint dest = id-set / remote-name flag = shortint hop-count = shortint ;number of servers in hop-list hop-list = hop-count *32767 id-set = serverid clientid length = length16 / length32 ;chosen as appropriate length16 = <16-bit count of octets in the remainder of the object which the rule describes> length32 = longint = <32-bit integer> network = string ;destination network octet = parameter = string remote-name = network sendername senderaddr reply = flag length code sendername [string] sendername = string ;sender's nick / servername senderaddr = addr-string | addr-unistring ;sender's user@host address serv-cli-msg = code [network] sendername [senderaddr] * ;message from server to client seqnum = longint server-message = flag length32 seqnum hop-list code source dest [time] * serverid = shortint shortint = <16-bit integer> source = id-set / remote-name string = string16 / string32 string16 = length16 *32767 string32 = length32 *2147483647 timestamp = <64-bit integer> user-string = length * Appendix C. Conversion table for the RFC 1459 protocol This table lists the commands defined in RFC 1459 and their equivalent message codes in the protocol defined by this document, and is intended as a guide to implementors who wish to include support for RFC 1459 clients. Commands are listed in alphabetical order. Note that there is not a one-to-one correspondence between commands; some commands from RFC 1459 have different message codes depending on the circumstances of use, and others have no equivalent. Also note that even for commands which have a direct equivalent, the semantics of the command in the new protocol may be different from the semantics defined for the command in RFC 1459, and that many IRC servers have defined their own semantics for some of these commands. See the notes at the bottom of the table and the message definitions in this document for details on how to translate messages. | RFC 1459 | | | | Command | New Msg. Code | Notes | +----------+----------------+-------+ | ADMIN | 0x0508 | | | AWAY | 0x0301 | | | CONNECT | 0x0400 | | | DIE | 0x0404 | | | ERROR | (none) | G | | INFO | 0x0509 | | | INVITE | 0x0208 | | | ISON | 0x0505 | | | JOIN | 0x0200,0x0280 | A | | KICK | 0x0206 | | | KILL | 0x0305 | | | LINKS | 0x050C,0x058C | | | LIST | 0x0502 | | | LUSERS | 0x0506 | | | MODE | 0x0303,0x0202, | B | | | 0x0204,0x0284, | | | | 0x0205,0x0285, | | | | 0x0207,0x0247, | | | | 0x0287 | | | MOTD | 0x0507 | | | NAMES | 0x0501 | | | NICK | 0x0300 | C | | NOTICE | 0x0102,0x0103, | D | | | 0x0104,0x0106 | | | OPER | 0x0304 | | | PART | 0x0201 | | | PASS | 0x0000 | | | PING | 0x7FFE | | | PONG | 0x7FFF | | | PRIVMSG | 0x0100,0x0101, | D | | | 0x0104,0x0106 | | | QUIT | 0x0004 | | | REHASH | 0x0402 | | | RESTART | 0x0403 | | | SERVER | 0x0002 | | | SQUIT | 0x0005,0x0401 | | | STATS | 0x050B | | | SUMMON | (none) | E | | TIME | 0x050E | | | TOPIC | 0x0203 | | | TRACE | 0x050D | | | USER | 0x0001 | F | | USERS | (none) | E | | VERSION | 0x050A | | | WALLOPS | 0x0105 | | | WHO | 0x0500 | | | WHOIS | 0x0503 | | | WHOWAS | 0x0504 | | *A: JOIN 0 (leave all channels) is not supported. *B: MODE command summary: 0x0303 = MODE for a client 0x0202 = MODE for a channel (except o/v/b) 0x0204,0x0284 = MODE +o/-o for a channel 0x0205,0x0285 = MODE +v/-v for a channel 0x0207,0x0247,0x0287 = MODE +b/-b for a channel (0x0247=list) *C: For the NICK command used to change a client's nickname. When used at registration time, there is no equivalent; see the USER command. *D: Keep in mind that the new protocol distinguishes between messages/notices to a channel (public) and messages/notices to a single client (private). Also, multiple recipients may not be specified for a single message. *E: The SUMMON and USERS commands were deliberately left out of this protocol definition, as their functionality is considered unrelated to the IRC protocol and better left to other protocols (e.g. E-mail or finger). The author has never seen an IRC server with these commands enabled. *F: When registering, the nickname (formerly from the NICK command) is included in the user registration message. *G: Connection errors are signalled through standard replies, as with errors from other commands.