--- irc3-20020208.txt 2003-11-16 17:35:27 +0900 +++ irc3-20031116.txt 2003-11-16 18:39:09 +0900 @@ -1,5 +1,5 @@ Network Working Group A. Church -Request For Comments: nnnn February, 2002 +Request For Comments: nnnn November, 2003 Obsoletes: 1459 Category: Experimental @@ -58,6 +58,7 @@ 2.2.2 Server messages 2.2.3 Replies 2.2.4 Acknowledgements and acknowledgement requests + 2.2.5 Inter-network messages 2.3 Summary of message flag bits 2.4 Timestamps 2.5 Text transmission @@ -160,11 +161,12 @@ 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. + The author wishes to acknowledge the assistance of Tyrel Haveman, 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 @@ -186,8 +188,8 @@ 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]. + used in this sense, they are capitalized, and 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 @@ -277,8 +279,8 @@ 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. + server which receives a server registration message with this value + MUST reject it. 1.2 Clients @@ -342,13 +344,13 @@ 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. + optimal condition. The users that do this 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 @@ -369,8 +371,8 @@ 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. + the old and current protocols, and MUST communicate with a client + using the same protocol the client registered with. 1.4 Channels @@ -577,15 +579,19 @@ 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. + algorithm described in section 1.5.1. Examples include: - - Client-to-server: All mesages from clients. While some messages + - Client-to-server: All messages 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. + - Server-to-client: Connection maintenance messages; messages from + other clients received by the server. + + - Server-to-server: Messages destined for clients on other servers; + ping messages to determine whether an inactive link is still + connected. 1.6.3.1 Inter-network messages @@ -615,7 +621,7 @@ 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. + unique 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 @@ -624,15 +630,15 @@ 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. + For example, If server B3 in Figure 4 were 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 @@ -753,13 +759,9 @@ 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. + first, as a 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. Note that since strings may contain any binary information, they can be used for any variable-length information which is sent over the @@ -767,13 +769,9 @@ 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 + length = <32-bit count of octets in the remainder of the object which + the rule describes> + string = length *4294967295 2.2 Messages @@ -888,7 +886,6 @@ 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] * @@ -970,17 +967,17 @@ 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. + 00 - indicates that a message is destined for all servers, rather + than any particular client or set of clients. + 01 - 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).) + 10 - indicates that a message is destined for only the server to + which it was sent. + 11 - 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 @@ -1001,7 +998,9 @@ remote-name = network sendername senderaddr serverid = shortint clientid = shortint - dest = id-set / remote-name + dest = id-set / remote-dest + remote-dest = network destname + destname = string timestamp = <64-bit integer> 2.2.3 Replies @@ -1066,13 +1065,24 @@ message from the destination server which the source server (the server generating the message) has received. +2.2.5. Inter-network messages + + When a border server on one network sends a message on behalf of its + network to a border server on another network, server and client IDs + are obviously meaningless. Thus, a special format is used: + + network-message = flag length code sendername senderaddr remote-dest + [timestamp] * + + In these messages, flag bits 15-9 and 5-0 MUST be set to zero. + 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. + 13: Reserved for multi-byte character sets, set to 0. + 12: Reserved for multi-byte character sets, 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 @@ -1091,7 +1101,7 @@ 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 + a particular instant in 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 @@ -1266,9 +1276,10 @@ 3.1.2 User message - Code: 0x0001 - Client-server parameters: version-id (shortint), nickname (string), - username (user-string), real-name (string) + Code: 0x0001 (client-server), 0x0081 (server-client) + Client-server parameters: version-id (shortint), features (longint), + 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 @@ -1299,6 +1310,26 @@ features of this protocol MUST choose a new version-id value in that range for their revised protocol. + The features parameter is primarily intended for experimental use, to + allow a way for clients to indicate what experimental features they + support. Clients compliant with this protocol MUST set this + parameter to zero; servers MUST ignore the parameter's value. + + If the registration succeeds, the server MUST send a RPL_WELCOME + reply, and MAY send one or more RPL_WELCOME2 replies. The server MAY + send a RPL_FEATURES reply to inform the client of its own feature + set; the string included with a RPL_FEATURES reply includes the + feature value as the first four octets of the reply string, and any + subsequent data should be interpreted by the client as appropriate + for the protocol version and features specified. Servers compliant + with this protocol MUST NOT send a RPL_FEATURES reply with a non-zero + features value. + + 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. + 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. @@ -1341,7 +1372,7 @@ Examples: - CS: 0x0001 "Alcan" "achurch" "Andrew Church" + CS: 0x0001 0x0100 0x00000000 "Alcan" "achurch" "Andrew Church" The author's client registers its connection using the nickname "Alcan". @@ -1350,18 +1381,19 @@ 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. + consists of the four octets 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_BAD_PASSWORD RPL_FEATURES ERR_CLIENT_DENIED ERR_NICKNAME_IN_USE ERR_NAME_TOO_LONG ERR_INVALID_NAME + ERR_WRONG_VERSION 3.1.2.1 A note on the Ident Protocol @@ -1415,9 +1447,9 @@ 3.1.3 Server message Code: 0x0002 - Parameters: version-id (shortint), server-id (shortint), - server-name (string), server-desc (string), - initial-seqnum (longint) + Parameters: version-id (shortint), features (longint), + 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 @@ -1426,8 +1458,8 @@ 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). + version-id and features parameters are 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 @@ -1475,7 +1507,7 @@ Replies: ERR_NEED_MORE_PARAMS RPL_SERVER_WELCOME - ERR_ALREADY_REGISTERED + ERR_ALREADY_REGISTERED RPL_FEATURES ERR_BAD_PASSWORD ERR_SERVER_DENIED ERR_NAME_TOO_LONG @@ -1485,8 +1517,9 @@ 3.1.4 Remote server message Code: 0x0042 - Parameters: network-name (string), server-id (shortint), - server-name (string), server-desc (string) + Parameters: version-id (shortint), features (longint), + network-name (string), 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 @@ -1513,15 +1546,16 @@ Examples: - SS: 0x0042 "EsperNet" 0 "dragonfire.esper.net" + SS: 0x0042 "EsperNet" "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. + Server "dragonfire.esper.net" 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_ALREADY_REGISTERED RPL_FEATURES ERR_BAD_PASSWORD ERR_SERVER_DENIED ERR_NETWORK_DENIED @@ -1538,9 +1572,9 @@ Examples: - SS: 0x0043 0x00010000 0x00020000 "EFNet" + SS: 0x0043 0x00010000 0x00020000 "EsperNet" Server 1 sends a message to server 2 indicating that it is now - a border router for the network "EFNet". + a border router for the network "EsperNet". Replies: @@ -1794,7 +1828,7 @@ 3.3.1 Join message Code: 0x0200, 0x0280 - Parameters: (0x0200) channel-name (string) [...] + Parameters: (0x0200) channel-name (string) ... (0x0280) channel-name (string), key (string) Adds the sender to the list of clients in the given channel(s), @@ -2151,14 +2185,14 @@ Examples: - CS: 0x0207 "#dragonweyr" "*@*.lame.org" + 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" + SC: 0x0247 "#dragonweyr" "*" "*" "*.lame.org" A response to the request for the list of bans. Replies: @@ -2588,10 +2622,12 @@ 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. + server-to-connect parameter is typically 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; a server may have multiple strings which + correspond to the same server, each specifying a different way of + connecting (such as a different port number when using TCP [5]). The error ERR_ALREADY_CONNECTED is returned only when a direct connection exists between the server executing the command and the @@ -2702,7 +2738,7 @@ 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 + 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 @@ -2824,12 +2860,14 @@ 3.6.3 List message Code: 0x0502 - Parameters: channel (string), [target-server (string)] + Parameters: channel (string), min-clients (longint), + [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 + string, which may contain wildcards, and having at least the number + of clients specified in min-clients. 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 @@ -2840,7 +2878,8 @@ 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. + indicating the end of the list. If no channels match the given + parameters, a RPL_LIST_END reply is sent alone. Examples: @@ -3552,6 +3591,13 @@ Sent to acknowledge a successful remote (border) server registration request. + 0x00FE RPL_FEATURES + This reply may be sent to indicate to a newly-registered client or + server to indicate what features the server supports. A string + MUST be included, and the first four octets MUST be a longint + containing the features value. If the string is not present or + shorter than four octets, the reply MUST be ignored. + 0x0100 RPL_NOW_OPERATOR Sent to acknowledge a successful client request to be given IRC operator status. @@ -3889,8 +3935,8 @@ 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 + message, the server would then attempt to read 4,294,967,295 octets + 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. @@ -4189,24 +4235,22 @@ byte = octet cli-serv-msg = code [network] * ;message from client to server - client-message = flag length32 (cli-serv-msg / serv-cli-msg) + client-message = flag length (cli-serv-msg / serv-cli-msg) clientid = shortint code = shortint - dest = id-set / remote-name + dest = id-set / remote-dest + destname = string 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 + length = <32-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-dest = network destname remote-name = network sendername senderaddr reply = flag length code sendername [string] sendername = string ;sender's nick / servername @@ -4215,14 +4259,12 @@ 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] * + server-message = flag length 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 + string = length *4294967295 timestamp = <64-bit integer> user-string = length *