summaryrefslogtreecommitdiff
path: root/doc/rfcs
diff options
context:
space:
mode:
authorEuAndreh <eu@euandre.org>2024-11-04 09:14:24 -0300
committerEuAndreh <eu@euandre.org>2024-11-04 15:50:30 -0300
commit18052f84e1da1a4a3915264638f2b3a4b9def726 (patch)
treef40e8d0f510e33961ef82731f60c3550e52b4fa5 /doc/rfcs
parenttests/papod.go: Adapt old tests to use TestStart() and Testing() (diff)
downloadpapod-18052f84e1da1a4a3915264638f2b3a4b9def726.tar.gz
papod-18052f84e1da1a4a3915264638f2b3a4b9def726.tar.xz
mv doc/rfc/ doc/rfcs; Add newer related rfcs
Diffstat (limited to 'doc/rfcs')
-rw-r--r--doc/rfcs/rfc1459.txt3643
-rw-r--r--doc/rfcs/rfc2222.txt899
-rw-r--r--doc/rfcs/rfc2444.txt395
-rw-r--r--doc/rfcs/rfc2595.txt843
-rw-r--r--doc/rfcs/rfc2810.txt563
-rw-r--r--doc/rfcs/rfc2811.txt1067
-rw-r--r--doc/rfcs/rfc2812.txt3531
-rw-r--r--doc/rfcs/rfc2813.txt1459
-rw-r--r--doc/rfcs/rfc4422.txt1851
-rw-r--r--doc/rfcs/rfc4616.txt619
-rw-r--r--doc/rfcs/rfc5802.txt1571
-rw-r--r--doc/rfcs/rfc7628.txt1179
-rw-r--r--doc/rfcs/rfc7677.txt451
13 files changed, 18071 insertions, 0 deletions
diff --git a/doc/rfcs/rfc1459.txt b/doc/rfcs/rfc1459.txt
new file mode 100644
index 0000000..09fbf34
--- /dev/null
+++ b/doc/rfcs/rfc1459.txt
@@ -0,0 +1,3643 @@
+
+
+
+
+
+
+Network Working Group J. Oikarinen
+Request for Comments: 1459 D. Reed
+ May 1993
+
+
+ Internet Relay Chat Protocol
+
+Status of This Memo
+
+ This memo defines an Experimental Protocol for the Internet
+ community. Discussion and suggestions for improvement are requested.
+ Please refer to the current edition of the "IAB Official Protocol
+ Standards" for the standardization state and status of this protocol.
+ Distribution of this memo is unlimited.
+
+Abstract
+
+ The IRC protocol was developed over the last 4 years since it was
+ first implemented as a means for users on a BBS to chat amongst
+ themselves. Now it supports a world-wide network of servers and
+ clients, and is stringing to cope with growth. Over the past 2 years,
+ the average number of users connected to the main IRC network has
+ grown by a factor of 10.
+
+ The IRC protocol is a text-based protocol, with the simplest client
+ being any socket program capable of connecting to the server.
+
+Table of Contents
+
+ 1. INTRODUCTION ............................................... 4
+ 1.1 Servers ................................................ 4
+ 1.2 Clients ................................................ 5
+ 1.2.1 Operators .......................................... 5
+ 1.3 Channels ................................................ 5
+ 1.3.1 Channel Operators .................................... 6
+ 2. THE IRC SPECIFICATION ....................................... 7
+ 2.1 Overview ................................................ 7
+ 2.2 Character codes ......................................... 7
+ 2.3 Messages ................................................ 7
+ 2.3.1 Message format in 'pseudo' BNF .................... 8
+ 2.4 Numeric replies ......................................... 10
+ 3. IRC Concepts ................................................ 10
+ 3.1 One-to-one communication ................................ 10
+ 3.2 One-to-many ............................................. 11
+ 3.2.1 To a list .......................................... 11
+ 3.2.2 To a group (channel) ............................... 11
+ 3.2.3 To a host/server mask .............................. 12
+ 3.3 One to all .............................................. 12
+
+
+
+Oikarinen & Reed [Page 1]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+ 3.3.1 Client to Client ................................... 12
+ 3.3.2 Clients to Server .................................. 12
+ 3.3.3 Server to Server ................................... 12
+ 4. MESSAGE DETAILS ............................................. 13
+ 4.1 Connection Registration ................................. 13
+ 4.1.1 Password message ................................... 14
+ 4.1.2 Nickname message ................................... 14
+ 4.1.3 User message ....................................... 15
+ 4.1.4 Server message ..................................... 16
+ 4.1.5 Operator message ................................... 17
+ 4.1.6 Quit message ....................................... 17
+ 4.1.7 Server Quit message ................................ 18
+ 4.2 Channel operations ...................................... 19
+ 4.2.1 Join message ....................................... 19
+ 4.2.2 Part message ....................................... 20
+ 4.2.3 Mode message ....................................... 21
+ 4.2.3.1 Channel modes ................................. 21
+ 4.2.3.2 User modes .................................... 22
+ 4.2.4 Topic message ...................................... 23
+ 4.2.5 Names message ...................................... 24
+ 4.2.6 List message ....................................... 24
+ 4.2.7 Invite message ..................................... 25
+ 4.2.8 Kick message ....................................... 25
+ 4.3 Server queries and commands ............................. 26
+ 4.3.1 Version message .................................... 26
+ 4.3.2 Stats message ...................................... 27
+ 4.3.3 Links message ...................................... 28
+ 4.3.4 Time message ....................................... 29
+ 4.3.5 Connect message .................................... 29
+ 4.3.6 Trace message ...................................... 30
+ 4.3.7 Admin message ...................................... 31
+ 4.3.8 Info message ....................................... 31
+ 4.4 Sending messages ........................................ 32
+ 4.4.1 Private messages ................................... 32
+ 4.4.2 Notice messages .................................... 33
+ 4.5 User-based queries ...................................... 33
+ 4.5.1 Who query .......................................... 33
+ 4.5.2 Whois query ........................................ 34
+ 4.5.3 Whowas message ..................................... 35
+ 4.6 Miscellaneous messages .................................. 35
+ 4.6.1 Kill message ....................................... 36
+ 4.6.2 Ping message ....................................... 37
+ 4.6.3 Pong message ....................................... 37
+ 4.6.4 Error message ...................................... 38
+ 5. OPTIONAL MESSAGES ........................................... 38
+ 5.1 Away message ............................................ 38
+ 5.2 Rehash command .......................................... 39
+ 5.3 Restart command ......................................... 39
+
+
+
+Oikarinen & Reed [Page 2]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+ 5.4 Summon message .......................................... 40
+ 5.5 Users message ........................................... 40
+ 5.6 Operwall command ........................................ 41
+ 5.7 Userhost message ........................................ 42
+ 5.8 Ison message ............................................ 42
+ 6. REPLIES ..................................................... 43
+ 6.1 Error Replies ........................................... 43
+ 6.2 Command responses ....................................... 48
+ 6.3 Reserved numerics ....................................... 56
+ 7. Client and server authentication ............................ 56
+ 8. Current Implementations Details ............................. 56
+ 8.1 Network protocol: TCP ................................... 57
+ 8.1.1 Support of Unix sockets ............................ 57
+ 8.2 Command Parsing ......................................... 57
+ 8.3 Message delivery ........................................ 57
+ 8.4 Connection 'Liveness' ................................... 58
+ 8.5 Establishing a server-client connection ................. 58
+ 8.6 Establishing a server-server connection ................. 58
+ 8.6.1 State information exchange when connecting ......... 59
+ 8.7 Terminating server-client connections ................... 59
+ 8.8 Terminating server-server connections ................... 59
+ 8.9 Tracking nickname changes ............................... 60
+ 8.10 Flood control of clients ............................... 60
+ 8.11 Non-blocking lookups ................................... 61
+ 8.11.1 Hostname (DNS) lookups ............................ 61
+ 8.11.2 Username (Ident) lookups .......................... 61
+ 8.12 Configuration file ..................................... 61
+ 8.12.1 Allowing clients to connect ....................... 62
+ 8.12.2 Operators ......................................... 62
+ 8.12.3 Allowing servers to connect ....................... 62
+ 8.12.4 Administrivia ..................................... 63
+ 8.13 Channel membership ..................................... 63
+ 9. Current problems ............................................ 63
+ 9.1 Scalability ............................................. 63
+ 9.2 Labels .................................................. 63
+ 9.2.1 Nicknames .......................................... 63
+ 9.2.2 Channels ........................................... 64
+ 9.2.3 Servers ............................................ 64
+ 9.3 Algorithms .............................................. 64
+ 10. Support and availability ................................... 64
+ 11. Security Considerations .................................... 65
+ 12. Authors' Addresses ......................................... 65
+
+
+
+
+
+
+
+
+
+Oikarinen & Reed [Page 3]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+1. INTRODUCTION
+
+ The IRC (Internet Relay Chat) protocol has been designed over a
+ number of years for use with text based conferencing. This document
+ describes the current IRC protocol.
+
+ The IRC protocol has been developed on systems using the TCP/IP
+ network protocol, although there is no requirement that this remain
+ the only sphere in which it operates.
+
+ IRC itself is a teleconferencing system, which (through the use of
+ the client-server model) is well-suited to running on many machines
+ in a distributed fashion. A typical setup involves a single process
+ (the server) forming a central point for clients (or other servers)
+ to connect to, performing the required message delivery/multiplexing
+ and other functions.
+
+1.1 Servers
+
+ The server forms the backbone of IRC, providing a point to which
+ clients may connect to to talk to each other, and a point for other
+ servers to connect to, forming an IRC network. The only network
+ configuration allowed for IRC servers is that of a spanning tree [see
+ Fig. 1] where each server acts as a central node for the rest of the
+ net it sees.
+
+
+ [ Server 15 ] [ Server 13 ] [ Server 14]
+ / \ /
+ / \ /
+ [ Server 11 ] ------ [ Server 1 ] [ Server 12]
+ / \ /
+ / \ /
+ [ Server 2 ] [ Server 3 ]
+ / \ \
+ / \ \
+ [ Server 4 ] [ Server 5 ] [ Server 6 ]
+ / | \ /
+ / | \ /
+ / | \____ /
+ / | \ /
+ [ Server 7 ] [ Server 8 ] [ Server 9 ] [ Server 10 ]
+
+ :
+ [ etc. ]
+ :
+
+ [ Fig. 1. Format of IRC server network ]
+
+
+
+Oikarinen & Reed [Page 4]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+1.2 Clients
+
+ A client is anything connecting to a server that is not another
+ server. Each client is distinguished from other clients by a unique
+ nickname having a maximum length of nine (9) characters. See the
+ protocol grammar rules for what may and may not be used in a
+ nickname. In addition to the nickname, all servers must have the
+ following information about all clients: the real name of the host
+ that the client is running on, the username of the client on that
+ host, and the server to which the client is connected.
+
+1.2.1 Operators
+
+ To allow a reasonable amount of order to be kept within the IRC
+ network, a special class of clients (operators) is allowed to perform
+ general maintenance functions on the network. Although the powers
+ granted to an operator can be considered as 'dangerous', they are
+ nonetheless required. Operators should be able to perform basic
+ network tasks such as disconnecting and reconnecting servers as
+ needed to prevent long-term use of bad network routing. In
+ recognition of this need, the protocol discussed herein provides for
+ operators only to be able to perform such functions. See sections
+ 4.1.7 (SQUIT) and 4.3.5 (CONNECT).
+
+ A more controversial power of operators is the ability to remove a
+ user from the connected network by 'force', i.e. operators are able
+ to close the connection between any client and server. The
+ justification for this is delicate since its abuse is both
+ destructive and annoying. For further details on this type of
+ action, see section 4.6.1 (KILL).
+
+1.3 Channels
+
+ A channel is a named group of one or more clients which will all
+ receive messages addressed to that channel. The channel is created
+ implicitly when the first client joins it, and the channel ceases to
+ exist when the last client leaves it. While channel exists, any
+ client can reference the channel using the name of the channel.
+
+ Channels names are strings (beginning with a '&' or '#' character) of
+ length up to 200 characters. Apart from the the requirement that the
+ first character being either '&' or '#'; the only restriction on a
+ channel name is that it may not contain any spaces (' '), a control G
+ (^G or ASCII 7), or a comma (',' which is used as a list item
+ separator by the protocol).
+
+ There are two types of channels allowed by this protocol. One is a
+ distributed channel which is known to all the servers that are
+
+
+
+Oikarinen & Reed [Page 5]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+ connected to the network. These channels are marked by the first
+ character being a only clients on the server where it exists may join
+ it. These are distinguished by a leading '&' character. On top of
+ these two types, there are the various channel modes available to
+ alter the characteristics of individual channels. See section 4.2.3
+ (MODE command) for more details on this.
+
+ To create a new channel or become part of an existing channel, a user
+ is required to JOIN the channel. If the channel doesn't exist prior
+ to joining, the channel is created and the creating user becomes a
+ channel operator. If the channel already exists, whether or not your
+ request to JOIN that channel is honoured depends on the current modes
+ of the channel. For example, if the channel is invite-only, (+i),
+ then you may only join if invited. As part of the protocol, a user
+ may be a part of several channels at once, but a limit of ten (10)
+ channels is recommended as being ample for both experienced and
+ novice users. See section 8.13 for more information on this.
+
+ If the IRC network becomes disjoint because of a split between two
+ servers, the channel on each side is only composed of those clients
+ which are connected to servers on the respective sides of the split,
+ possibly ceasing to exist on one side of the split. When the split
+ is healed, the connecting servers announce to each other who they
+ think is in each channel and the mode of that channel. If the
+ channel exists on both sides, the JOINs and MODEs are interpreted in
+ an inclusive manner so that both sides of the new connection will
+ agree about which clients are in the channel and what modes the
+ channel has.
+
+1.3.1 Channel Operators
+
+ The channel operator (also referred to as a "chop" or "chanop") on a
+ given channel is considered to 'own' that channel. In recognition of
+ this status, channel operators are endowed with certain powers which
+ enable them to keep control and some sort of sanity in their channel.
+ As an owner of a channel, a channel operator is not required to have
+ reasons for their actions, although if their actions are generally
+ antisocial or otherwise abusive, it might be reasonable to ask an IRC
+ operator to intervene, or for the usersjust leave and go elsewhere
+ and form their own channel.
+
+ The commands which may only be used by channel operators are:
+
+ KICK - Eject a client from the channel
+ MODE - Change the channel's mode
+ INVITE - Invite a client to an invite-only channel (mode +i)
+ TOPIC - Change the channel topic in a mode +t channel
+
+
+
+
+Oikarinen & Reed [Page 6]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+ A channel operator is identified by the '@' symbol next to their
+ nickname whenever it is associated with a channel (ie replies to the
+ NAMES, WHO and WHOIS commands).
+
+2. The IRC Specification
+
+2.1 Overview
+
+ The protocol as described herein is for use both with server to
+ server and client to server connections. There are, however, more
+ restrictions on client connections (which are considered to be
+ untrustworthy) than on server connections.
+
+2.2 Character codes
+
+ No specific character set is specified. The protocol is based on a a
+ set of codes which are composed of eight (8) bits, making up an
+ octet. Each message may be composed of any number of these octets;
+ however, some octet values are used for control codes which act as
+ message delimiters.
+
+ Regardless of being an 8-bit protocol, the delimiters and keywords
+ are such that protocol is mostly usable from USASCII terminal and a
+ telnet connection.
+
+ Because of IRC's scandanavian origin, the characters {}| are
+ considered to be the lower case equivalents of the characters []\,
+ respectively. This is a critical issue when determining the
+ equivalence of two nicknames.
+
+2.3 Messages
+
+ Servers and clients send eachother messages which may or may not
+ generate a reply. If the message contains a valid command, as
+ described in later sections, the client should expect a reply as
+ specified but it is not advised to wait forever for the reply; client
+ to server and server to server communication is essentially
+ asynchronous in nature.
+
+ Each IRC message may consist of up to three main parts: the prefix
+ (optional), the command, and the command parameters (of which there
+ may be up to 15). The prefix, command, and all parameters are
+ separated by one (or more) ASCII space character(s) (0x20).
+
+ The presence of a prefix is indicated with a single leading ASCII
+ colon character (':', 0x3b), which must be the first character of the
+ message itself. There must be no gap (whitespace) between the colon
+ and the prefix. The prefix is used by servers to indicate the true
+
+
+
+Oikarinen & Reed [Page 7]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+ origin of the message. If the prefix is missing from the message, it
+ is assumed to have originated from the connection from which it was
+ received. Clients should not use prefix when sending a message from
+ themselves; if they use a prefix, the only valid prefix is the
+ registered nickname associated with the client. If the source
+ identified by the prefix cannot be found from the server's internal
+ database, or if the source is registered from a different link than
+ from which the message arrived, the server must ignore the message
+ silently.
+
+ The command must either be a valid IRC command or a three (3) digit
+ number represented in ASCII text.
+
+ IRC messages are always lines of characters terminated with a CR-LF
+ (Carriage Return - Line Feed) pair, and these messages shall not
+ exceed 512 characters in length, counting all characters including
+ the trailing CR-LF. Thus, there are 510 characters maximum allowed
+ for the command and its parameters. There is no provision for
+ continuation message lines. See section 7 for more details about
+ current implementations.
+
+2.3.1 Message format in 'pseudo' BNF
+
+ The protocol messages must be extracted from the contiguous stream of
+ octets. The current solution is to designate two characters, CR and
+ LF, as message separators. Empty messages are silently ignored,
+ which permits use of the sequence CR-LF between messages
+ without extra problems.
+
+ The extracted message is parsed into the components <prefix>,
+ <command> and list of parameters matched either by <middle> or
+ <trailing> components.
+
+ The BNF representation for this is:
+
+
+<message> ::= [':' <prefix> <SPACE> ] <command> <params> <crlf>
+<prefix> ::= <servername> | <nick> [ '!' <user> ] [ '@' <host> ]
+<command> ::= <letter> { <letter> } | <number> <number> <number>
+<SPACE> ::= ' ' { ' ' }
+<params> ::= <SPACE> [ ':' <trailing> | <middle> <params> ]
+
+<middle> ::= <Any *non-empty* sequence of octets not including SPACE
+ or NUL or CR or LF, the first of which may not be ':'>
+<trailing> ::= <Any, possibly *empty*, sequence of octets not including
+ NUL or CR or LF>
+
+<crlf> ::= CR LF
+
+
+
+Oikarinen & Reed [Page 8]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+NOTES:
+
+ 1) <SPACE> is consists only of SPACE character(s) (0x20).
+ Specially notice that TABULATION, and all other control
+ characters are considered NON-WHITE-SPACE.
+
+ 2) After extracting the parameter list, all parameters are equal,
+ whether matched by <middle> or <trailing>. <Trailing> is just
+ a syntactic trick to allow SPACE within parameter.
+
+ 3) The fact that CR and LF cannot appear in parameter strings is
+ just artifact of the message framing. This might change later.
+
+ 4) The NUL character is not special in message framing, and
+ basically could end up inside a parameter, but as it would
+ cause extra complexities in normal C string handling. Therefore
+ NUL is not allowed within messages.
+
+ 5) The last parameter may be an empty string.
+
+ 6) Use of the extended prefix (['!' <user> ] ['@' <host> ]) must
+ not be used in server to server communications and is only
+ intended for server to client messages in order to provide
+ clients with more useful information about who a message is
+ from without the need for additional queries.
+
+ Most protocol messages specify additional semantics and syntax for
+ the extracted parameter strings dictated by their position in the
+ list. For example, many server commands will assume that the first
+ parameter after the command is the list of targets, which can be
+ described with:
+
+ <target> ::= <to> [ "," <target> ]
+ <to> ::= <channel> | <user> '@' <servername> | <nick> | <mask>
+ <channel> ::= ('#' | '&') <chstring>
+ <servername> ::= <host>
+ <host> ::= see RFC 952 [DNS:4] for details on allowed hostnames
+ <nick> ::= <letter> { <letter> | <number> | <special> }
+ <mask> ::= ('#' | '$') <chstring>
+ <chstring> ::= <any 8bit code except SPACE, BELL, NUL, CR, LF and
+ comma (',')>
+
+ Other parameter syntaxes are:
+
+ <user> ::= <nonwhite> { <nonwhite> }
+ <letter> ::= 'a' ... 'z' | 'A' ... 'Z'
+ <number> ::= '0' ... '9'
+ <special> ::= '-' | '[' | ']' | '\' | '`' | '^' | '{' | '}'
+
+
+
+Oikarinen & Reed [Page 9]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+ <nonwhite> ::= <any 8bit code except SPACE (0x20), NUL (0x0), CR
+ (0xd), and LF (0xa)>
+
+2.4 Numeric replies
+
+ Most of the messages sent to the server generate a reply of some
+ sort. The most common reply is the numeric reply, used for both
+ errors and normal replies. The numeric reply must be sent as one
+ message consisting of the sender prefix, the three digit numeric, and
+ the target of the reply. A numeric reply is not allowed to originate
+ from a client; any such messages received by a server are silently
+ dropped. In all other respects, a numeric reply is just like a normal
+ message, except that the keyword is made up of 3 numeric digits
+ rather than a string of letters. A list of different replies is
+ supplied in section 6.
+
+3. IRC Concepts.
+
+ This section is devoted to describing the actual concepts behind the
+ organization of the IRC protocol and how the current
+ implementations deliver different classes of messages.
+
+
+
+ 1--\
+ A D---4
+ 2--/ \ /
+ B----C
+ / \
+ 3 E
+
+ Servers: A, B, C, D, E Clients: 1, 2, 3, 4
+
+ [ Fig. 2. Sample small IRC network ]
+
+3.1 One-to-one communication
+
+ Communication on a one-to-one basis is usually only performed by
+ clients, since most server-server traffic is not a result of servers
+ talking only to each other. To provide a secure means for clients to
+ talk to each other, it is required that all servers be able to send a
+ message in exactly one direction along the spanning tree in order to
+ reach any client. The path of a message being delivered is the
+ shortest path between any two points on the spanning tree.
+
+ The following examples all refer to Figure 2 above.
+
+
+
+
+
+Oikarinen & Reed [Page 10]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+Example 1:
+ A message between clients 1 and 2 is only seen by server A, which
+ sends it straight to client 2.
+
+Example 2:
+ A message between clients 1 and 3 is seen by servers A & B, and
+ client 3. No other clients or servers are allowed see the message.
+
+Example 3:
+ A message between clients 2 and 4 is seen by servers A, B, C & D
+ and client 4 only.
+
+3.2 One-to-many
+
+ The main goal of IRC is to provide a forum which allows easy and
+ efficient conferencing (one to many conversations). IRC offers
+ several means to achieve this, each serving its own purpose.
+
+3.2.1 To a list
+
+ The least efficient style of one-to-many conversation is through
+ clients talking to a 'list' of users. How this is done is almost
+ self explanatory: the client gives a list of destinations to which
+ the message is to be delivered and the server breaks it up and
+ dispatches a separate copy of the message to each given destination.
+ This isn't as efficient as using a group since the destination list
+ is broken up and the dispatch sent without checking to make sure
+ duplicates aren't sent down each path.
+
+3.2.2 To a group (channel)
+
+ In IRC the channel has a role equivalent to that of the multicast
+ group; their existence is dynamic (coming and going as people join
+ and leave channels) and the actual conversation carried out on a
+ channel is only sent to servers which are supporting users on a given
+ channel. If there are multiple users on a server in the same
+ channel, the message text is sent only once to that server and then
+ sent to each client on the channel. This action is then repeated for
+ each client-server combination until the original message has fanned
+ out and reached each member of the channel.
+
+ The following examples all refer to Figure 2.
+
+Example 4:
+ Any channel with 1 client in it. Messages to the channel go to the
+ server and then nowhere else.
+
+
+
+
+
+Oikarinen & Reed [Page 11]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+Example 5:
+ 2 clients in a channel. All messages traverse a path as if they
+ were private messages between the two clients outside a channel.
+
+Example 6:
+ Clients 1, 2 and 3 in a channel. All messages to the channel are
+ sent to all clients and only those servers which must be traversed
+ by the message if it were a private message to a single client. If
+ client 1 sends a message, it goes back to client 2 and then via
+ server B to client 3.
+
+3.2.3 To a host/server mask
+
+ To provide IRC operators with some mechanism to send messages to a
+ large body of related users, host and server mask messages are
+ provided. These messages are sent to users whose host or server
+ information match that of the mask. The messages are only sent to
+ locations where users are, in a fashion similar to that of channels.
+
+3.3 One-to-all
+
+ The one-to-all type of message is better described as a broadcast
+ message, sent to all clients or servers or both. On a large network
+ of users and servers, a single message can result in a lot of traffic
+ being sent over the network in an effort to reach all of the desired
+ destinations.
+
+ For some messages, there is no option but to broadcast it to all
+ servers so that the state information held by each server is
+ reasonably consistent between servers.
+
+3.3.1 Client-to-Client
+
+ There is no class of message which, from a single message, results in
+ a message being sent to every other client.
+
+3.3.2 Client-to-Server
+
+ Most of the commands which result in a change of state information
+ (such as channel membership, channel mode, user status, etc) must be
+ sent to all servers by default, and this distribution may not be
+ changed by the client.
+
+3.3.3 Server-to-Server.
+
+ While most messages between servers are distributed to all 'other'
+ servers, this is only required for any message that affects either a
+ user, channel or server. Since these are the basic items found in
+
+
+
+Oikarinen & Reed [Page 12]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+ IRC, nearly all messages originating from a server are broadcast to
+ all other connected servers.
+
+4. Message details
+
+ On the following pages are descriptions of each message recognized by
+ the IRC server and client. All commands described in this section
+ must be implemented by any server for this protocol.
+
+ Where the reply ERR_NOSUCHSERVER is listed, it means that the
+ <server> parameter could not be found. The server must not send any
+ other replies after this for that command.
+
+ The server to which a client is connected is required to parse the
+ complete message, returning any appropriate errors. If the server
+ encounters a fatal error while parsing a message, an error must be
+ sent back to the client and the parsing terminated. A fatal error
+ may be considered to be incorrect command, a destination which is
+ otherwise unknown to the server (server, nick or channel names fit
+ this category), not enough parameters or incorrect privileges.
+
+ If a full set of parameters is presented, then each must be checked
+ for validity and appropriate responses sent back to the client. In
+ the case of messages which use parameter lists using the comma as an
+ item separator, a reply must be sent for each item.
+
+ In the examples below, some messages appear using the full format:
+
+ :Name COMMAND parameter list
+
+ Such examples represent a message from "Name" in transit between
+ servers, where it is essential to include the name of the original
+ sender of the message so remote servers may send back a reply along
+ the correct path.
+
+4.1 Connection Registration
+
+ The commands described here are used to register a connection with an
+ IRC server as either a user or a server as well as correctly
+ disconnect.
+
+ A "PASS" command is not required for either client or server
+ connection to be registered, but it must precede the server message
+ or the latter of the NICK/USER combination. It is strongly
+ recommended that all server connections have a password in order to
+ give some level of security to the actual connections. The
+ recommended order for a client to register is as follows:
+
+
+
+
+Oikarinen & Reed [Page 13]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+ 1. Pass message
+ 2. Nick message
+ 3. User message
+
+4.1.1 Password message
+
+
+ Command: PASS
+ Parameters: <password>
+
+ The PASS command is used to set a 'connection password'. The
+ password can and must be set before any attempt to register the
+ connection is made. Currently this requires that clients send a PASS
+ command before sending the NICK/USER combination and servers *must*
+ send a PASS command before any SERVER command. The password supplied
+ must match the one contained in the C/N lines (for servers) or I
+ lines (for clients). It is possible to send multiple PASS commands
+ before registering but only the last one sent is used for
+ verification and it may not be changed once registered. Numeric
+ Replies:
+
+ ERR_NEEDMOREPARAMS ERR_ALREADYREGISTRED
+
+ Example:
+
+ PASS secretpasswordhere
+
+4.1.2 Nick message
+
+ Command: NICK
+ Parameters: <nickname> [ <hopcount> ]
+
+ NICK message is used to give user a nickname or change the previous
+ one. The <hopcount> parameter is only used by servers to indicate
+ how far away a nick is from its home server. A local connection has
+ a hopcount of 0. If supplied by a client, it must be ignored.
+
+ If a NICK message arrives at a server which already knows about an
+ identical nickname for another client, a nickname collision occurs.
+ As a result of a nickname collision, all instances of the nickname
+ are removed from the server's database, and a KILL command is issued
+ to remove the nickname from all other server's database. If the NICK
+ message causing the collision was a nickname change, then the
+ original (old) nick must be removed as well.
+
+ If the server recieves an identical NICK from a client which is
+ directly connected, it may issue an ERR_NICKCOLLISION to the local
+ client, drop the NICK command, and not generate any kills.
+
+
+
+Oikarinen & Reed [Page 14]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+ Numeric Replies:
+
+ ERR_NONICKNAMEGIVEN ERR_ERRONEUSNICKNAME
+ ERR_NICKNAMEINUSE ERR_NICKCOLLISION
+
+ Example:
+
+ NICK Wiz ; Introducing new nick "Wiz".
+
+ :WiZ NICK Kilroy ; WiZ changed his nickname to Kilroy.
+
+4.1.3 User message
+
+ Command: USER
+ Parameters: <username> <hostname> <servername> <realname>
+
+ The USER message is used at the beginning of connection to specify
+ the username, hostname, servername and realname of s new user. It is
+ also used in communication between servers to indicate new user
+ arriving on IRC, since only after both USER and NICK have been
+ received from a client does a user become registered.
+
+ Between servers USER must to be prefixed with client's NICKname.
+ Note that hostname and servername are normally ignored by the IRC
+ server when the USER command comes from a directly connected client
+ (for security reasons), but they are used in server to server
+ communication. This means that a NICK must always be sent to a
+ remote server when a new user is being introduced to the rest of the
+ network before the accompanying USER is sent.
+
+ It must be noted that realname parameter must be the last parameter,
+ because it may contain space characters and must be prefixed with a
+ colon (':') to make sure this is recognised as such.
+
+ Since it is easy for a client to lie about its username by relying
+ solely on the USER message, the use of an "Identity Server" is
+ recommended. If the host which a user connects from has such a
+ server enabled the username is set to that as in the reply from the
+ "Identity Server".
+
+ Numeric Replies:
+
+ ERR_NEEDMOREPARAMS ERR_ALREADYREGISTRED
+
+ Examples:
+
+
+ USER guest tolmoon tolsun :Ronnie Reagan
+
+
+
+Oikarinen & Reed [Page 15]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+ ; User registering themselves with a
+ username of "guest" and real name
+ "Ronnie Reagan".
+
+
+ :testnick USER guest tolmoon tolsun :Ronnie Reagan
+ ; message between servers with the
+ nickname for which the USER command
+ belongs to
+
+4.1.4 Server message
+
+ Command: SERVER
+ Parameters: <servername> <hopcount> <info>
+
+ The server message is used to tell a server that the other end of a
+ new connection is a server. This message is also used to pass server
+ data over whole net. When a new server is connected to net,
+ information about it be broadcast to the whole network. <hopcount>
+ is used to give all servers some internal information on how far away
+ all servers are. With a full server list, it would be possible to
+ construct a map of the entire server tree, but hostmasks prevent this
+ from being done.
+
+ The SERVER message must only be accepted from either (a) a connection
+ which is yet to be registered and is attempting to register as a
+ server, or (b) an existing connection to another server, in which
+ case the SERVER message is introducing a new server behind that
+ server.
+
+ Most errors that occur with the receipt of a SERVER command result in
+ the connection being terminated by the destination host (target
+ SERVER). Error replies are usually sent using the "ERROR" command
+ rather than the numeric since the ERROR command has several useful
+ properties which make it useful here.
+
+ If a SERVER message is parsed and attempts to introduce a server
+ which is already known to the receiving server, the connection from
+ which that message must be closed (following the correct procedures),
+ since a duplicate route to a server has formed and the acyclic nature
+ of the IRC tree broken.
+
+ Numeric Replies:
+
+ ERR_ALREADYREGISTRED
+
+ Example:
+
+
+
+
+Oikarinen & Reed [Page 16]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+SERVER test.oulu.fi 1 :[tolsun.oulu.fi] Experimental server
+ ; New server test.oulu.fi introducing
+ itself and attempting to register. The
+ name in []'s is the hostname for the
+ host running test.oulu.fi.
+
+
+:tolsun.oulu.fi SERVER csd.bu.edu 5 :BU Central Server
+ ; Server tolsun.oulu.fi is our uplink
+ for csd.bu.edu which is 5 hops away.
+
+4.1.5 Oper
+
+ Command: OPER
+ Parameters: <user> <password>
+
+ OPER message is used by a normal user to obtain operator privileges.
+ The combination of <user> and <password> are required to gain
+ Operator privileges.
+
+ If the client sending the OPER command supplies the correct password
+ for the given user, the server then informs the rest of the network
+ of the new operator by issuing a "MODE +o" for the clients nickname.
+
+ The OPER message is client-server only.
+
+ Numeric Replies:
+
+ ERR_NEEDMOREPARAMS RPL_YOUREOPER
+ ERR_NOOPERHOST ERR_PASSWDMISMATCH
+
+ Example:
+
+ OPER foo bar ; Attempt to register as an operator
+ using a username of "foo" and "bar" as
+ the password.
+
+4.1.6 Quit
+
+ Command: QUIT
+ Parameters: [<Quit message>]
+
+ A client session is ended with a quit message. The server must close
+ the connection to a client which sends a QUIT message. If a "Quit
+ Message" is given, this will be sent instead of the default message,
+ the nickname.
+
+ When netsplits (disconnecting of two servers) occur, the quit message
+
+
+
+Oikarinen & Reed [Page 17]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+ is composed of the names of two servers involved, separated by a
+ space. The first name is that of the server which is still connected
+ and the second name is that of the server that has become
+ disconnected.
+
+ If, for some other reason, a client connection is closed without the
+ client issuing a QUIT command (e.g. client dies and EOF occurs
+ on socket), the server is required to fill in the quit message with
+ some sort of message reflecting the nature of the event which
+ caused it to happen.
+
+ Numeric Replies:
+
+ None.
+
+ Examples:
+
+ QUIT :Gone to have lunch ; Preferred message format.
+
+4.1.7 Server quit message
+
+ Command: SQUIT
+ Parameters: <server> <comment>
+
+ The SQUIT message is needed to tell about quitting or dead servers.
+ If a server wishes to break the connection to another server it must
+ send a SQUIT message to the other server, using the the name of the
+ other server as the server parameter, which then closes its
+ connection to the quitting server.
+
+ This command is also available operators to help keep a network of
+ IRC servers connected in an orderly fashion. Operators may also
+ issue an SQUIT message for a remote server connection. In this case,
+ the SQUIT must be parsed by each server inbetween the operator and
+ the remote server, updating the view of the network held by each
+ server as explained below.
+
+ The <comment> should be supplied by all operators who execute a SQUIT
+ for a remote server (that is not connected to the server they are
+ currently on) so that other operators are aware for the reason of
+ this action. The <comment> is also filled in by servers which may
+ place an error or similar message here.
+
+ Both of the servers which are on either side of the connection being
+ closed are required to to send out a SQUIT message (to all its other
+ server connections) for all other servers which are considered to be
+ behind that link.
+
+
+
+
+Oikarinen & Reed [Page 18]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+ Similarly, a QUIT message must be sent to the other connected servers
+ rest of the network on behalf of all clients behind that link. In
+ addition to this, all channel members of a channel which lost a
+ member due to the split must be sent a QUIT message.
+
+ If a server connection is terminated prematurely (e.g. the server on
+ the other end of the link died), the server which detects
+ this disconnection is required to inform the rest of the network
+ that the connection has closed and fill in the comment field
+ with something appropriate.
+
+ Numeric replies:
+
+ ERR_NOPRIVILEGES ERR_NOSUCHSERVER
+
+ Example:
+
+ SQUIT tolsun.oulu.fi :Bad Link ? ; the server link tolson.oulu.fi has
+ been terminated because of "Bad Link".
+
+ :Trillian SQUIT cm22.eng.umd.edu :Server out of control
+ ; message from Trillian to disconnect
+ "cm22.eng.umd.edu" from the net
+ because "Server out of control".
+
+4.2 Channel operations
+
+ This group of messages is concerned with manipulating channels, their
+ properties (channel modes), and their contents (typically clients).
+ In implementing these, a number of race conditions are inevitable
+ when clients at opposing ends of a network send commands which will
+ ultimately clash. It is also required that servers keep a nickname
+ history to ensure that wherever a <nick> parameter is given, the
+ server check its history in case it has recently been changed.
+
+4.2.1 Join message
+
+ Command: JOIN
+ Parameters: <channel>{,<channel>} [<key>{,<key>}]
+
+ The JOIN command is used by client to start listening a specific
+ channel. Whether or not a client is allowed to join a channel is
+ checked only by the server the client is connected to; all other
+ servers automatically add the user to the channel when it is received
+ from other servers. The conditions which affect this are as follows:
+
+ 1. the user must be invited if the channel is invite-only;
+
+
+
+
+Oikarinen & Reed [Page 19]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+ 2. the user's nick/username/hostname must not match any
+ active bans;
+
+ 3. the correct key (password) must be given if it is set.
+
+ These are discussed in more detail under the MODE command (see
+ section 4.2.3 for more details).
+
+ Once a user has joined a channel, they receive notice about all
+ commands their server receives which affect the channel. This
+ includes MODE, KICK, PART, QUIT and of course PRIVMSG/NOTICE. The
+ JOIN command needs to be broadcast to all servers so that each server
+ knows where to find the users who are on the channel. This allows
+ optimal delivery of PRIVMSG/NOTICE messages to the channel.
+
+ If a JOIN is successful, the user is then sent the channel's topic
+ (using RPL_TOPIC) and the list of users who are on the channel (using
+ RPL_NAMREPLY), which must include the user joining.
+
+ Numeric Replies:
+
+ ERR_NEEDMOREPARAMS ERR_BANNEDFROMCHAN
+ ERR_INVITEONLYCHAN ERR_BADCHANNELKEY
+ ERR_CHANNELISFULL ERR_BADCHANMASK
+ ERR_NOSUCHCHANNEL ERR_TOOMANYCHANNELS
+ RPL_TOPIC
+
+ Examples:
+
+ JOIN #foobar ; join channel #foobar.
+
+ JOIN &foo fubar ; join channel &foo using key "fubar".
+
+ JOIN #foo,&bar fubar ; join channel #foo using key "fubar"
+ and &bar using no key.
+
+ JOIN #foo,#bar fubar,foobar ; join channel #foo using key "fubar".
+ and channel #bar using key "foobar".
+
+ JOIN #foo,#bar ; join channels #foo and #bar.
+
+ :WiZ JOIN #Twilight_zone ; JOIN message from WiZ
+
+4.2.2 Part message
+
+ Command: PART
+ Parameters: <channel>{,<channel>}
+
+
+
+
+Oikarinen & Reed [Page 20]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+ The PART message causes the client sending the message to be removed
+ from the list of active users for all given channels listed in the
+ parameter string.
+
+ Numeric Replies:
+
+ ERR_NEEDMOREPARAMS ERR_NOSUCHCHANNEL
+ ERR_NOTONCHANNEL
+
+ Examples:
+
+ PART #twilight_zone ; leave channel "#twilight_zone"
+
+ PART #oz-ops,&group5 ; leave both channels "&group5" and
+ "#oz-ops".
+
+4.2.3 Mode message
+
+ Command: MODE
+
+ The MODE command is a dual-purpose command in IRC. It allows both
+ usernames and channels to have their mode changed. The rationale for
+ this choice is that one day nicknames will be obsolete and the
+ equivalent property will be the channel.
+
+ When parsing MODE messages, it is recommended that the entire message
+ be parsed first and then the changes which resulted then passed on.
+
+4.2.3.1 Channel modes
+
+ Parameters: <channel> {[+|-]|o|p|s|i|t|n|b|v} [<limit>] [<user>]
+ [<ban mask>]
+
+ The MODE command is provided so that channel operators may change the
+ characteristics of `their' channel. It is also required that servers
+ be able to change channel modes so that channel operators may be
+ created.
+
+ The various modes available for channels are as follows:
+
+ o - give/take channel operator privileges;
+ p - private channel flag;
+ s - secret channel flag;
+ i - invite-only channel flag;
+ t - topic settable by channel operator only flag;
+ n - no messages to channel from clients on the outside;
+ m - moderated channel;
+ l - set the user limit to channel;
+
+
+
+Oikarinen & Reed [Page 21]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+ b - set a ban mask to keep users out;
+ v - give/take the ability to speak on a moderated channel;
+ k - set a channel key (password).
+
+ When using the 'o' and 'b' options, a restriction on a total of three
+ per mode command has been imposed. That is, any combination of 'o'
+ and
+
+4.2.3.2 User modes
+
+ Parameters: <nickname> {[+|-]|i|w|s|o}
+
+ The user MODEs are typically changes which affect either how the
+ client is seen by others or what 'extra' messages the client is sent.
+ A user MODE command may only be accepted if both the sender of the
+ message and the nickname given as a parameter are both the same.
+
+ The available modes are as follows:
+
+ i - marks a users as invisible;
+ s - marks a user for receipt of server notices;
+ w - user receives wallops;
+ o - operator flag.
+
+ Additional modes may be available later on.
+
+ If a user attempts to make themselves an operator using the "+o"
+ flag, the attempt should be ignored. There is no restriction,
+ however, on anyone `deopping' themselves (using "-o"). Numeric
+ Replies:
+
+ ERR_NEEDMOREPARAMS RPL_CHANNELMODEIS
+ ERR_CHANOPRIVSNEEDED ERR_NOSUCHNICK
+ ERR_NOTONCHANNEL ERR_KEYSET
+ RPL_BANLIST RPL_ENDOFBANLIST
+ ERR_UNKNOWNMODE ERR_NOSUCHCHANNEL
+
+ ERR_USERSDONTMATCH RPL_UMODEIS
+ ERR_UMODEUNKNOWNFLAG
+
+ Examples:
+
+ Use of Channel Modes:
+
+MODE #Finnish +im ; Makes #Finnish channel moderated and
+ 'invite-only'.
+
+MODE #Finnish +o Kilroy ; Gives 'chanop' privileges to Kilroy on
+
+
+
+Oikarinen & Reed [Page 22]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+ channel #Finnish.
+
+MODE #Finnish +v Wiz ; Allow WiZ to speak on #Finnish.
+
+MODE #Fins -s ; Removes 'secret' flag from channel
+ #Fins.
+
+MODE #42 +k oulu ; Set the channel key to "oulu".
+
+MODE #eu-opers +l 10 ; Set the limit for the number of users
+ on channel to 10.
+
+MODE &oulu +b ; list ban masks set for channel.
+
+MODE &oulu +b *!*@* ; prevent all users from joining.
+
+MODE &oulu +b *!*@*.edu ; prevent any user from a hostname
+ matching *.edu from joining.
+
+ Use of user Modes:
+
+:MODE WiZ -w ; turns reception of WALLOPS messages
+ off for WiZ.
+
+:Angel MODE Angel +i ; Message from Angel to make themselves
+ invisible.
+
+MODE WiZ -o ; WiZ 'deopping' (removing operator
+ status). The plain reverse of this
+ command ("MODE WiZ +o") must not be
+ allowed from users since would bypass
+ the OPER command.
+
+4.2.4 Topic message
+
+ Command: TOPIC
+ Parameters: <channel> [<topic>]
+
+ The TOPIC message is used to change or view the topic of a channel.
+ The topic for channel <channel> is returned if there is no <topic>
+ given. If the <topic> parameter is present, the topic for that
+ channel will be changed, if the channel modes permit this action.
+
+ Numeric Replies:
+
+ ERR_NEEDMOREPARAMS ERR_NOTONCHANNEL
+ RPL_NOTOPIC RPL_TOPIC
+ ERR_CHANOPRIVSNEEDED
+
+
+
+Oikarinen & Reed [Page 23]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+ Examples:
+
+ :Wiz TOPIC #test :New topic ;User Wiz setting the topic.
+
+ TOPIC #test :another topic ;set the topic on #test to "another
+ topic".
+
+ TOPIC #test ; check the topic for #test.
+
+4.2.5 Names message
+
+ Command: NAMES
+ Parameters: [<channel>{,<channel>}]
+
+ By using the NAMES command, a user can list all nicknames that are
+ visible to them on any channel that they can see. Channel names
+ which they can see are those which aren't private (+p) or secret (+s)
+ or those which they are actually on. The <channel> parameter
+ specifies which channel(s) to return information about if valid.
+ There is no error reply for bad channel names.
+
+ If no <channel> parameter is given, a list of all channels and their
+ occupants is returned. At the end of this list, a list of users who
+ are visible but either not on any channel or not on a visible channel
+ are listed as being on `channel' "*".
+
+ Numerics:
+
+ RPL_NAMREPLY RPL_ENDOFNAMES
+
+ Examples:
+
+ NAMES #twilight_zone,#42 ; list visible users on #twilight_zone
+ and #42 if the channels are visible to
+ you.
+
+ NAMES ; list all visible channels and users
+
+4.2.6 List message
+
+ Command: LIST
+ Parameters: [<channel>{,<channel>} [<server>]]
+
+ The list message is used to list channels and their topics. If the
+ <channel> parameter is used, only the status of that channel
+ is displayed. Private channels are listed (without their
+ topics) as channel "Prv" unless the client generating the query is
+ actually on that channel. Likewise, secret channels are not listed
+
+
+
+Oikarinen & Reed [Page 24]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+ at all unless the client is a member of the channel in question.
+
+ Numeric Replies:
+
+ ERR_NOSUCHSERVER RPL_LISTSTART
+ RPL_LIST RPL_LISTEND
+
+ Examples:
+
+ LIST ; List all channels.
+
+ LIST #twilight_zone,#42 ; List channels #twilight_zone and #42
+
+4.2.7 Invite message
+
+ Command: INVITE
+ Parameters: <nickname> <channel>
+
+ The INVITE message is used to invite users to a channel. The
+ parameter <nickname> is the nickname of the person to be invited to
+ the target channel <channel>. There is no requirement that the
+ channel the target user is being invited to must exist or be a valid
+ channel. To invite a user to a channel which is invite only (MODE
+ +i), the client sending the invite must be recognised as being a
+ channel operator on the given channel.
+
+ Numeric Replies:
+
+ ERR_NEEDMOREPARAMS ERR_NOSUCHNICK
+ ERR_NOTONCHANNEL ERR_USERONCHANNEL
+ ERR_CHANOPRIVSNEEDED
+ RPL_INVITING RPL_AWAY
+
+ Examples:
+
+ :Angel INVITE Wiz #Dust ; User Angel inviting WiZ to channel
+ #Dust
+
+ INVITE Wiz #Twilight_Zone ; Command to invite WiZ to
+ #Twilight_zone
+
+4.2.8 Kick command
+
+ Command: KICK
+ Parameters: <channel> <user> [<comment>]
+
+ The KICK command can be used to forcibly remove a user from a
+ channel. It 'kicks them out' of the channel (forced PART).
+
+
+
+Oikarinen & Reed [Page 25]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+ Only a channel operator may kick another user out of a channel.
+ Each server that receives a KICK message checks that it is valid
+ (ie the sender is actually a channel operator) before removing
+ the victim from the channel.
+
+ Numeric Replies:
+
+ ERR_NEEDMOREPARAMS ERR_NOSUCHCHANNEL
+ ERR_BADCHANMASK ERR_CHANOPRIVSNEEDED
+ ERR_NOTONCHANNEL
+
+ Examples:
+
+KICK &Melbourne Matthew ; Kick Matthew from &Melbourne
+
+KICK #Finnish John :Speaking English
+ ; Kick John from #Finnish using
+ "Speaking English" as the reason
+ (comment).
+
+:WiZ KICK #Finnish John ; KICK message from WiZ to remove John
+ from channel #Finnish
+
+NOTE:
+ It is possible to extend the KICK command parameters to the
+following:
+
+<channel>{,<channel>} <user>{,<user>} [<comment>]
+
+4.3 Server queries and commands
+
+ The server query group of commands has been designed to return
+ information about any server which is connected to the network. All
+ servers connected must respond to these queries and respond
+ correctly. Any invalid response (or lack thereof) must be considered
+ a sign of a broken server and it must be disconnected/disabled as
+ soon as possible until the situation is remedied.
+
+ In these queries, where a parameter appears as "<server>", it will
+ usually mean it can be a nickname or a server or a wildcard name of
+ some sort. For each parameter, however, only one query and set of
+ replies is to be generated.
+
+4.3.1 Version message
+
+ Command: VERSION
+ Parameters: [<server>]
+
+
+
+
+Oikarinen & Reed [Page 26]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+ The VERSION message is used to query the version of the server
+ program. An optional parameter <server> is used to query the version
+ of the server program which a client is not directly connected to.
+
+ Numeric Replies:
+
+ ERR_NOSUCHSERVER RPL_VERSION
+
+ Examples:
+
+ :Wiz VERSION *.se ; message from Wiz to check the version
+ of a server matching "*.se"
+
+ VERSION tolsun.oulu.fi ; check the version of server
+ "tolsun.oulu.fi".
+
+4.3.2 Stats message
+
+ Command: STATS
+ Parameters: [<query> [<server>]]
+
+ The stats message is used to query statistics of certain server. If
+ <server> parameter is omitted, only the end of stats reply is sent
+ back. The implementation of this command is highly dependent on the
+ server which replies, although the server must be able to supply
+ information as described by the queries below (or similar).
+
+ A query may be given by any single letter which is only checked by
+ the destination server (if given as the <server> parameter) and is
+ otherwise passed on by intermediate servers, ignored and unaltered.
+ The following queries are those found in the current IRC
+ implementation and provide a large portion of the setup information
+ for that server. Although these may not be supported in the same way
+ by other versions, all servers should be able to supply a valid reply
+ to a STATS query which is consistent with the reply formats currently
+ used and the purpose of the query.
+
+ The currently supported queries are:
+
+ c - returns a list of servers which the server may connect
+ to or allow connections from;
+ h - returns a list of servers which are either forced to be
+ treated as leaves or allowed to act as hubs;
+ i - returns a list of hosts which the server allows a client
+ to connect from;
+ k - returns a list of banned username/hostname combinations
+ for that server;
+ l - returns a list of the server's connections, showing how
+
+
+
+Oikarinen & Reed [Page 27]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+ long each connection has been established and the traffic
+ over that connection in bytes and messages for each
+ direction;
+ m - returns a list of commands supported by the server and
+ the usage count for each if the usage count is non zero;
+ o - returns a list of hosts from which normal clients may
+ become operators;
+ y - show Y (Class) lines from server's configuration file;
+ u - returns a string showing how long the server has been up.
+
+ Numeric Replies:
+
+ ERR_NOSUCHSERVER
+ RPL_STATSCLINE RPL_STATSNLINE
+ RPL_STATSILINE RPL_STATSKLINE
+ RPL_STATSQLINE RPL_STATSLLINE
+ RPL_STATSLINKINFO RPL_STATSUPTIME
+ RPL_STATSCOMMANDS RPL_STATSOLINE
+ RPL_STATSHLINE RPL_ENDOFSTATS
+
+ Examples:
+
+STATS m ; check the command usage for the server
+ you are connected to
+
+:Wiz STATS c eff.org ; request by WiZ for C/N line
+ information from server eff.org
+
+4.3.3 Links message
+
+ Command: LINKS
+ Parameters: [[<remote server>] <server mask>]
+
+ With LINKS, a user can list all servers which are known by the server
+ answering the query. The returned list of servers must match the
+ mask, or if no mask is given, the full list is returned.
+
+ If <remote server> is given in addition to <server mask>, the LINKS
+ command is forwarded to the first server found that matches that name
+ (if any), and that server is then required to answer the query.
+
+ Numeric Replies:
+
+ ERR_NOSUCHSERVER
+ RPL_LINKS RPL_ENDOFLINKS
+
+ Examples:
+
+
+
+
+Oikarinen & Reed [Page 28]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+LINKS *.au ; list all servers which have a name
+ that matches *.au;
+
+:WiZ LINKS *.bu.edu *.edu ; LINKS message from WiZ to the first
+ server matching *.edu for a list of
+ servers matching *.bu.edu.
+
+4.3.4 Time message
+
+ Command: TIME
+ Parameters: [<server>]
+
+ The time message is used to query local time from the specified
+ server. If the server parameter is not given, the server handling the
+ command must reply to the query.
+
+ Numeric Replies:
+
+ ERR_NOSUCHSERVER RPL_TIME
+
+ Examples:
+
+ TIME tolsun.oulu.fi ; check the time on the server
+ "tolson.oulu.fi"
+
+ Angel TIME *.au ; user angel checking the time on a
+ server matching "*.au"
+
+4.3.5 Connect message
+
+ Command: CONNECT
+ Parameters: <target server> [<port> [<remote server>]]
+
+ The CONNECT command can be used to force a server to try to establish
+ a new connection to another server immediately. CONNECT is a
+ privileged command and is to be available only to IRC Operators. If
+ a remote server is given then the CONNECT attempt is made by that
+ server to <target server> and <port>.
+
+ Numeric Replies:
+
+ ERR_NOSUCHSERVER ERR_NOPRIVILEGES
+ ERR_NEEDMOREPARAMS
+
+ Examples:
+
+CONNECT tolsun.oulu.fi ; Attempt to connect a server to
+ tolsun.oulu.fi
+
+
+
+Oikarinen & Reed [Page 29]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+:WiZ CONNECT eff.org 6667 csd.bu.edu
+ ; CONNECT attempt by WiZ to get servers
+ eff.org and csd.bu.edu connected on port
+ 6667.
+
+4.3.6 Trace message
+
+ Command: TRACE
+ Parameters: [<server>]
+
+ TRACE command is used to find the route to specific server. Each
+ server that processes this message must tell the sender about it by
+ sending a reply indicating it is a pass-through link, forming a chain
+ of replies similar to that gained from using "traceroute". After
+ sending this reply back, it must then send the TRACE message to the
+ next server until given server is reached. If the <server> parameter
+ is omitted, it is recommended that TRACE command send a message to
+ the sender telling which servers the current server has direct
+ connection to.
+
+ If the destination given by "<server>" is an actual server, then the
+ destination server is required to report all servers and users which
+ are connected to it, although only operators are permitted to see
+ users present. If the destination given by <server> is a nickname,
+ they only a reply for that nickname is given.
+
+ Numeric Replies:
+
+ ERR_NOSUCHSERVER
+
+ If the TRACE message is destined for another server, all intermediate
+ servers must return a RPL_TRACELINK reply to indicate that the TRACE
+ passed through it and where its going next.
+
+ RPL_TRACELINK
+ A TRACE reply may be composed of any number of the following numeric
+ replies.
+
+ RPL_TRACECONNECTING RPL_TRACEHANDSHAKE
+ RPL_TRACEUNKNOWN RPL_TRACEOPERATOR
+ RPL_TRACEUSER RPL_TRACESERVER
+ RPL_TRACESERVICE RPL_TRACENEWTYPE
+ RPL_TRACECLASS
+
+ Examples:
+
+TRACE *.oulu.fi ; TRACE to a server matching *.oulu.fi
+
+
+
+
+Oikarinen & Reed [Page 30]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+:WiZ TRACE AngelDust ; TRACE issued by WiZ to nick AngelDust
+
+4.3.7 Admin command
+
+ Command: ADMIN
+ Parameters: [<server>]
+
+ The admin message is used to find the name of the administrator of
+ the given server, or current server if <server> parameter is omitted.
+ Each server must have the ability to forward ADMIN messages to other
+ servers.
+
+ Numeric Replies:
+
+ ERR_NOSUCHSERVER
+ RPL_ADMINME RPL_ADMINLOC1
+ RPL_ADMINLOC2 RPL_ADMINEMAIL
+
+ Examples:
+
+ ADMIN tolsun.oulu.fi ; request an ADMIN reply from
+ tolsun.oulu.fi
+
+ :WiZ ADMIN *.edu ; ADMIN request from WiZ for first
+ server found to match *.edu.
+
+4.3.8 Info command
+
+ Command: INFO
+ Parameters: [<server>]
+
+ The INFO command is required to return information which describes
+ the server: its version, when it was compiled, the patchlevel, when
+ it was started, and any other miscellaneous information which may be
+ considered to be relevant.
+
+ Numeric Replies:
+
+ ERR_NOSUCHSERVER
+ RPL_INFO RPL_ENDOFINFO
+
+ Examples:
+
+ INFO csd.bu.edu ; request an INFO reply from
+ csd.bu.edu
+
+ :Avalon INFO *.fi ; INFO request from Avalon for first
+ server found to match *.fi.
+
+
+
+Oikarinen & Reed [Page 31]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+ INFO Angel ; request info from the server that
+ Angel is connected to.
+
+4.4 Sending messages
+
+ The main purpose of the IRC protocol is to provide a base for clients
+ to communicate with each other. PRIVMSG and NOTICE are the only
+ messages available which actually perform delivery of a text message
+ from one client to another - the rest just make it possible and try
+ to ensure it happens in a reliable and structured manner.
+
+4.4.1 Private messages
+
+ Command: PRIVMSG
+ Parameters: <receiver>{,<receiver>} <text to be sent>
+
+ PRIVMSG is used to send private messages between users. <receiver>
+ is the nickname of the receiver of the message. <receiver> can also
+ be a list of names or channels separated with commas.
+
+ The <receiver> parameter may also me a host mask (#mask) or server
+ mask ($mask). In both cases the server will only send the PRIVMSG
+ to those who have a server or host matching the mask. The mask must
+ have at least 1 (one) "." in it and no wildcards following the
+ last ".". This requirement exists to prevent people sending messages
+ to "#*" or "$*", which would broadcast to all users; from
+ experience, this is abused more than used responsibly and properly.
+ Wildcards are the '*' and '?' characters. This extension to
+ the PRIVMSG command is only available to Operators.
+
+ Numeric Replies:
+
+ ERR_NORECIPIENT ERR_NOTEXTTOSEND
+ ERR_CANNOTSENDTOCHAN ERR_NOTOPLEVEL
+ ERR_WILDTOPLEVEL ERR_TOOMANYTARGETS
+ ERR_NOSUCHNICK
+ RPL_AWAY
+
+ Examples:
+
+:Angel PRIVMSG Wiz :Hello are you receiving this message ?
+ ; Message from Angel to Wiz.
+
+PRIVMSG Angel :yes I'm receiving it !receiving it !'u>(768u+1n) .br ;
+ Message to Angel.
+
+PRIVMSG jto@tolsun.oulu.fi :Hello !
+ ; Message to a client on server
+
+
+
+Oikarinen & Reed [Page 32]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+ tolsun.oulu.fi with username of "jto".
+
+PRIVMSG $*.fi :Server tolsun.oulu.fi rebooting.
+ ; Message to everyone on a server which
+ has a name matching *.fi.
+
+PRIVMSG #*.edu :NSFNet is undergoing work, expect interruptions
+ ; Message to all users who come from a
+ host which has a name matching *.edu.
+
+4.4.2 Notice
+
+ Command: NOTICE
+ Parameters: <nickname> <text>
+
+ The NOTICE message is used similarly to PRIVMSG. The difference
+ between NOTICE and PRIVMSG is that automatic replies must never be
+ sent in response to a NOTICE message. This rule applies to servers
+ too - they must not send any error reply back to the client on
+ receipt of a notice. The object of this rule is to avoid loops
+ between a client automatically sending something in response to
+ something it received. This is typically used by automatons (clients
+ with either an AI or other interactive program controlling their
+ actions) which are always seen to be replying lest they end up in a
+ loop with another automaton.
+
+ See PRIVMSG for more details on replies and examples.
+
+4.5 User based queries
+
+ User queries are a group of commands which are primarily concerned
+ with finding details on a particular user or group users. When using
+ wildcards with any of these commands, if they match, they will only
+ return information on users who are 'visible' to you. The visibility
+ of a user is determined as a combination of the user's mode and the
+ common set of channels you are both on.
+
+4.5.1 Who query
+
+ Command: WHO
+ Parameters: [<name> [<o>]]
+
+ The WHO message is used by a client to generate a query which returns
+ a list of information which 'matches' the <name> parameter given by
+ the client. In the absence of the <name> parameter, all visible
+ (users who aren't invisible (user mode +i) and who don't have a
+ common channel with the requesting client) are listed. The same
+ result can be achieved by using a <name> of "0" or any wildcard which
+
+
+
+Oikarinen & Reed [Page 33]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+ will end up matching every entry possible.
+
+ The <name> passed to WHO is matched against users' host, server, real
+ name and nickname if the channel <name> cannot be found.
+
+ If the "o" parameter is passed only operators are returned according
+ to the name mask supplied.
+
+ Numeric Replies:
+
+ ERR_NOSUCHSERVER
+ RPL_WHOREPLY RPL_ENDOFWHO
+
+ Examples:
+
+ WHO *.fi ; List all users who match against
+ "*.fi".
+
+ WHO jto* o ; List all users with a match against
+ "jto*" if they are an operator.
+
+4.5.2 Whois query
+
+ Command: WHOIS
+ Parameters: [<server>] <nickmask>[,<nickmask>[,...]]
+
+ This message is used to query information about particular user. The
+ server will answer this message with several numeric messages
+ indicating different statuses of each user which matches the nickmask
+ (if you are entitled to see them). If no wildcard is present in the
+ <nickmask>, any information about that nick which you are allowed to
+ see is presented. A comma (',') separated list of nicknames may be
+ given.
+
+ The latter version sends the query to a specific server. It is
+ useful if you want to know how long the user in question has been
+ idle as only local server (ie. the server the user is directly
+ connected to) knows that information, while everything else is
+ globally known.
+
+ Numeric Replies:
+
+ ERR_NOSUCHSERVER ERR_NONICKNAMEGIVEN
+ RPL_WHOISUSER RPL_WHOISCHANNELS
+ RPL_WHOISCHANNELS RPL_WHOISSERVER
+ RPL_AWAY RPL_WHOISOPERATOR
+ RPL_WHOISIDLE ERR_NOSUCHNICK
+ RPL_ENDOFWHOIS
+
+
+
+Oikarinen & Reed [Page 34]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+ Examples:
+
+ WHOIS wiz ; return available user information
+ about nick WiZ
+
+ WHOIS eff.org trillian ; ask server eff.org for user
+ information about trillian
+
+4.5.3 Whowas
+
+ Command: WHOWAS
+ Parameters: <nickname> [<count> [<server>]]
+
+ Whowas asks for information about a nickname which no longer exists.
+ This may either be due to a nickname change or the user leaving IRC.
+ In response to this query, the server searches through its nickname
+ history, looking for any nicks which are lexically the same (no wild
+ card matching here). The history is searched backward, returning the
+ most recent entry first. If there are multiple entries, up to
+ <count> replies will be returned (or all of them if no <count>
+ parameter is given). If a non-positive number is passed as being
+ <count>, then a full search is done.
+
+ Numeric Replies:
+
+ ERR_NONICKNAMEGIVEN ERR_WASNOSUCHNICK
+ RPL_WHOWASUSER RPL_WHOISSERVER
+ RPL_ENDOFWHOWAS
+
+ Examples:
+
+ WHOWAS Wiz ; return all information in the nick
+ history about nick "WiZ";
+
+ WHOWAS Mermaid 9 ; return at most, the 9 most recent
+ entries in the nick history for
+ "Mermaid";
+
+ WHOWAS Trillian 1 *.edu ; return the most recent history for
+ "Trillian" from the first server found
+ to match "*.edu".
+
+4.6 Miscellaneous messages
+
+ Messages in this category do not fit into any of the above categories
+ but are nonetheless still a part of and required by the protocol.
+
+
+
+
+
+Oikarinen & Reed [Page 35]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+4.6.1 Kill message
+
+ Command: KILL
+ Parameters: <nickname> <comment>
+
+ The KILL message is used to cause a client-server connection to be
+ closed by the server which has the actual connection. KILL is used
+ by servers when they encounter a duplicate entry in the list of valid
+ nicknames and is used to remove both entries. It is also available
+ to operators.
+
+ Clients which have automatic reconnect algorithms effectively make
+ this command useless since the disconnection is only brief. It does
+ however break the flow of data and can be used to stop large amounts
+ of being abused, any user may elect to receive KILL messages
+ generated for others to keep an 'eye' on would be trouble spots.
+
+ In an arena where nicknames are required to be globally unique at all
+ times, KILL messages are sent whenever 'duplicates' are detected
+ (that is an attempt to register two users with the same nickname) in
+ the hope that both of them will disappear and only 1 reappear.
+
+ The comment given must reflect the actual reason for the KILL. For
+ server-generated KILLs it usually is made up of details concerning
+ the origins of the two conflicting nicknames. For users it is left
+ up to them to provide an adequate reason to satisfy others who see
+ it. To prevent/discourage fake KILLs from being generated to hide
+ the identify of the KILLer, the comment also shows a 'kill-path'
+ which is updated by each server it passes through, each prepending
+ its name to the path.
+
+ Numeric Replies:
+
+ ERR_NOPRIVILEGES ERR_NEEDMOREPARAMS
+ ERR_NOSUCHNICK ERR_CANTKILLSERVER
+
+
+ KILL David (csd.bu.edu <- tolsun.oulu.fi)
+ ; Nickname collision between csd.bu.edu
+ and tolson.oulu.fi
+
+
+ NOTE:
+ It is recommended that only Operators be allowed to kill other users
+ with KILL message. In an ideal world not even operators would need
+ to do this and it would be left to servers to deal with.
+
+
+
+
+
+Oikarinen & Reed [Page 36]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+4.6.2 Ping message
+
+ Command: PING
+ Parameters: <server1> [<server2>]
+
+ The PING message is used to test the presence of an active client at
+ the other end of the connection. A PING message is sent at regular
+ intervals if no other activity detected coming from a connection. If
+ a connection fails to respond to a PING command within a set amount
+ of time, that connection is closed.
+
+ Any client which receives a PING message must respond to <server1>
+ (server which sent the PING message out) as quickly as possible with
+ an appropriate PONG message to indicate it is still there and alive.
+ Servers should not respond to PING commands but rely on PINGs from
+ the other end of the connection to indicate the connection is alive.
+ If the <server2> parameter is specified, the PING message gets
+ forwarded there.
+
+ Numeric Replies:
+
+ ERR_NOORIGIN ERR_NOSUCHSERVER
+
+ Examples:
+
+ PING tolsun.oulu.fi ; server sending a PING message to
+ another server to indicate it is still
+ alive.
+
+ PING WiZ ; PING message being sent to nick WiZ
+
+4.6.3 Pong message
+
+ Command: PONG
+ Parameters: <daemon> [<daemon2>]
+
+ PONG message is a reply to ping message. If parameter <daemon2> is
+ given this message must be forwarded to given daemon. The <daemon>
+ parameter is the name of the daemon who has responded to PING message
+ and generated this message.
+
+ Numeric Replies:
+
+ ERR_NOORIGIN ERR_NOSUCHSERVER
+
+ Examples:
+
+ PONG csd.bu.edu tolsun.oulu.fi ; PONG message from csd.bu.edu to
+
+
+
+Oikarinen & Reed [Page 37]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+ tolsun.oulu.fi
+
+4.6.4 Error
+
+ Command: ERROR
+ Parameters: <error message>
+
+ The ERROR command is for use by servers when reporting a serious or
+ fatal error to its operators. It may also be sent from one server to
+ another but must not be accepted from any normal unknown clients.
+
+ An ERROR message is for use for reporting errors which occur with a
+ server-to-server link only. An ERROR message is sent to the server
+ at the other end (which sends it to all of its connected operators)
+ and to all operators currently connected. It is not to be passed
+ onto any other servers by a server if it is received from a server.
+
+ When a server sends a received ERROR message to its operators, the
+ message should be encapsulated inside a NOTICE message, indicating
+ that the client was not responsible for the error.
+
+ Numerics:
+
+ None.
+
+ Examples:
+
+ ERROR :Server *.fi already exists; ERROR message to the other server
+ which caused this error.
+
+ NOTICE WiZ :ERROR from csd.bu.edu -- Server *.fi already exists
+ ; Same ERROR message as above but sent
+ to user WiZ on the other server.
+
+5. OPTIONALS
+
+ This section describes OPTIONAL messages. They are not required in a
+ working server implementation of the protocol described herein. In
+ the absence of the option, an error reply message must be generated
+ or an unknown command error. If the message is destined for another
+ server to answer then it must be passed on (elementary parsing
+ required) The allocated numerics for this are listed with the
+ messages below.
+
+5.1 Away
+
+ Command: AWAY
+ Parameters: [message]
+
+
+
+Oikarinen & Reed [Page 38]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+ With the AWAY message, clients can set an automatic reply string for
+ any PRIVMSG commands directed at them (not to a channel they are on).
+ The automatic reply is sent by the server to client sending the
+ PRIVMSG command. The only replying server is the one to which the
+ sending client is connected to.
+
+ The AWAY message is used either with one parameter (to set an AWAY
+ message) or with no parameters (to remove the AWAY message).
+
+ Numeric Replies:
+
+ RPL_UNAWAY RPL_NOWAWAY
+
+ Examples:
+
+ AWAY :Gone to lunch. Back in 5 ; set away message to "Gone to lunch.
+ Back in 5".
+
+ :WiZ AWAY ; unmark WiZ as being away.
+
+
+5.2 Rehash message
+
+ Command: REHASH
+ Parameters: None
+
+ The rehash message can be used by the operator to force the server to
+ re-read and process its configuration file.
+
+ Numeric Replies:
+
+ RPL_REHASHING ERR_NOPRIVILEGES
+
+Examples:
+
+REHASH ; message from client with operator
+ status to server asking it to reread its
+ configuration file.
+
+5.3 Restart message
+
+ Command: RESTART
+ Parameters: None
+
+ The restart message can only be used by an operator to force a server
+ restart itself. This message is optional since it may be viewed as a
+ risk to allow arbitrary people to connect to a server as an operator
+ and execute this command, causing (at least) a disruption to service.
+
+
+
+Oikarinen & Reed [Page 39]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+ The RESTART command must always be fully processed by the server to
+ which the sending client is connected and not be passed onto other
+ connected servers.
+
+ Numeric Replies:
+
+ ERR_NOPRIVILEGES
+
+ Examples:
+
+ RESTART ; no parameters required.
+
+5.4 Summon message
+
+ Command: SUMMON
+ Parameters: <user> [<server>]
+
+ The SUMMON command can be used to give users who are on a host
+ running an IRC server a message asking them to please join IRC. This
+ message is only sent if the target server (a) has SUMMON enabled, (b)
+ the user is logged in and (c) the server process can write to the
+ user's tty (or similar).
+
+ If no <server> parameter is given it tries to summon <user> from the
+ server the client is connected to is assumed as the target.
+
+ If summon is not enabled in a server, it must return the
+ ERR_SUMMONDISABLED numeric and pass the summon message onwards.
+
+ Numeric Replies:
+
+ ERR_NORECIPIENT ERR_FILEERROR
+ ERR_NOLOGIN ERR_NOSUCHSERVER
+ RPL_SUMMONING
+
+ Examples:
+
+ SUMMON jto ; summon user jto on the server's host
+
+ SUMMON jto tolsun.oulu.fi ; summon user jto on the host which a
+ server named "tolsun.oulu.fi" is
+ running.
+
+
+5.5 Users
+
+ Command: USERS
+ Parameters: [<server>]
+
+
+
+Oikarinen & Reed [Page 40]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+ The USERS command returns a list of users logged into the server in a
+ similar format to who(1), rusers(1) and finger(1). Some people
+ may disable this command on their server for security related
+ reasons. If disabled, the correct numeric must be returned to
+ indicate this.
+
+ Numeric Replies:
+
+ ERR_NOSUCHSERVER ERR_FILEERROR
+ RPL_USERSSTART RPL_USERS
+ RPL_NOUSERS RPL_ENDOFUSERS
+ ERR_USERSDISABLED
+
+ Disabled Reply:
+
+ ERR_USERSDISABLED
+
+ Examples:
+
+USERS eff.org ; request a list of users logged in on
+ server eff.org
+
+:John USERS tolsun.oulu.fi ; request from John for a list of users
+ logged in on server tolsun.oulu.fi
+
+5.6 Operwall message
+
+ Command: WALLOPS
+ Parameters: Text to be sent to all operators currently online
+
+ Sends a message to all operators currently online. After
+ implementing WALLOPS as a user command it was found that it was
+ often and commonly abused as a means of sending a message to a lot
+ of people (much similar to WALL). Due to this it is recommended
+ that the current implementation of WALLOPS be used as an
+ example by allowing and recognising only servers as the senders of
+ WALLOPS.
+
+ Numeric Replies:
+
+ ERR_NEEDMOREPARAMS
+
+ Examples:
+
+ :csd.bu.edu WALLOPS :Connect '*.uiuc.edu 6667' from Joshua; WALLOPS
+ message from csd.bu.edu announcing a
+ CONNECT message it received and acted
+ upon from Joshua.
+
+
+
+Oikarinen & Reed [Page 41]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+5.7 Userhost message
+
+ Command: USERHOST
+ Parameters: <nickname>{<space><nickname>}
+
+ The USERHOST command takes a list of up to 5 nicknames, each
+ separated by a space character and returns a list of information
+ about each nickname that it found. The returned list has each reply
+ separated by a space.
+
+ Numeric Replies:
+
+ RPL_USERHOST ERR_NEEDMOREPARAMS
+
+ Examples:
+
+ USERHOST Wiz Michael Marty p ;USERHOST request for information on
+ nicks "Wiz", "Michael", "Marty" and "p"
+
+5.8 Ison message
+
+ Command: ISON
+ Parameters: <nickname>{<space><nickname>}
+
+ The ISON command was implemented to provide a quick and efficient
+ means to get a response about whether a given nickname was currently
+ on IRC. ISON only takes one (1) parameter: a space-separated list of
+ nicks. For each nickname in the list that is present, the server
+ adds that to its reply string. Thus the reply string may return
+ empty (none of the given nicks are present), an exact copy of the
+ parameter string (all of them present) or as any other subset of the
+ set of nicks given in the parameter. The only limit on the number
+ of nicks that may be checked is that the combined length must not be
+ too large as to cause the server to chop it off so it fits in 512
+ characters.
+
+ ISON is only be processed by the server local to the client sending
+ the command and thus not passed onto other servers for further
+ processing.
+
+ Numeric Replies:
+
+ RPL_ISON ERR_NEEDMOREPARAMS
+
+ Examples:
+
+ ISON phone trillian WiZ jarlek Avalon Angel Monstah
+ ; Sample ISON request for 7 nicks.
+
+
+
+Oikarinen & Reed [Page 42]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+6. REPLIES
+
+ The following is a list of numeric replies which are generated in
+ response to the commands given above. Each numeric is given with its
+ number, name and reply string.
+
+6.1 Error Replies.
+
+ 401 ERR_NOSUCHNICK
+ "<nickname> :No such nick/channel"
+
+ - Used to indicate the nickname parameter supplied to a
+ command is currently unused.
+
+ 402 ERR_NOSUCHSERVER
+ "<server name> :No such server"
+
+ - Used to indicate the server name given currently
+ doesn't exist.
+
+ 403 ERR_NOSUCHCHANNEL
+ "<channel name> :No such channel"
+
+ - Used to indicate the given channel name is invalid.
+
+ 404 ERR_CANNOTSENDTOCHAN
+ "<channel name> :Cannot send to channel"
+
+ - Sent to a user who is either (a) not on a channel
+ which is mode +n or (b) not a chanop (or mode +v) on
+ a channel which has mode +m set and is trying to send
+ a PRIVMSG message to that channel.
+
+ 405 ERR_TOOMANYCHANNELS
+ "<channel name> :You have joined too many \
+ channels"
+ - Sent to a user when they have joined the maximum
+ number of allowed channels and they try to join
+ another channel.
+
+ 406 ERR_WASNOSUCHNICK
+ "<nickname> :There was no such nickname"
+
+ - Returned by WHOWAS to indicate there is no history
+ information for that nickname.
+
+ 407 ERR_TOOMANYTARGETS
+ "<target> :Duplicate recipients. No message \
+
+
+
+Oikarinen & Reed [Page 43]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+ delivered"
+
+ - Returned to a client which is attempting to send a
+ PRIVMSG/NOTICE using the user@host destination format
+ and for a user@host which has several occurrences.
+
+ 409 ERR_NOORIGIN
+ ":No origin specified"
+
+ - PING or PONG message missing the originator parameter
+ which is required since these commands must work
+ without valid prefixes.
+
+ 411 ERR_NORECIPIENT
+ ":No recipient given (<command>)"
+ 412 ERR_NOTEXTTOSEND
+ ":No text to send"
+ 413 ERR_NOTOPLEVEL
+ "<mask> :No toplevel domain specified"
+ 414 ERR_WILDTOPLEVEL
+ "<mask> :Wildcard in toplevel domain"
+
+ - 412 - 414 are returned by PRIVMSG to indicate that
+ the message wasn't delivered for some reason.
+ ERR_NOTOPLEVEL and ERR_WILDTOPLEVEL are errors that
+ are returned when an invalid use of
+ "PRIVMSG $<server>" or "PRIVMSG #<host>" is attempted.
+
+ 421 ERR_UNKNOWNCOMMAND
+ "<command> :Unknown command"
+
+ - Returned to a registered client to indicate that the
+ command sent is unknown by the server.
+
+ 422 ERR_NOMOTD
+ ":MOTD File is missing"
+
+ - Server's MOTD file could not be opened by the server.
+
+ 423 ERR_NOADMININFO
+ "<server> :No administrative info available"
+
+ - Returned by a server in response to an ADMIN message
+ when there is an error in finding the appropriate
+ information.
+
+ 424 ERR_FILEERROR
+ ":File error doing <file op> on <file>"
+
+
+
+Oikarinen & Reed [Page 44]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+ - Generic error message used to report a failed file
+ operation during the processing of a message.
+
+ 431 ERR_NONICKNAMEGIVEN
+ ":No nickname given"
+
+ - Returned when a nickname parameter expected for a
+ command and isn't found.
+
+ 432 ERR_ERRONEUSNICKNAME
+ "<nick> :Erroneus nickname"
+
+ - Returned after receiving a NICK message which contains
+ characters which do not fall in the defined set. See
+ section x.x.x for details on valid nicknames.
+
+ 433 ERR_NICKNAMEINUSE
+ "<nick> :Nickname is already in use"
+
+ - Returned when a NICK message is processed that results
+ in an attempt to change to a currently existing
+ nickname.
+
+ 436 ERR_NICKCOLLISION
+ "<nick> :Nickname collision KILL"
+
+ - Returned by a server to a client when it detects a
+ nickname collision (registered of a NICK that
+ already exists by another server).
+
+ 441 ERR_USERNOTINCHANNEL
+ "<nick> <channel> :They aren't on that channel"
+
+ - Returned by the server to indicate that the target
+ user of the command is not on the given channel.
+
+ 442 ERR_NOTONCHANNEL
+ "<channel> :You're not on that channel"
+
+ - Returned by the server whenever a client tries to
+ perform a channel effecting command for which the
+ client isn't a member.
+
+ 443 ERR_USERONCHANNEL
+ "<user> <channel> :is already on channel"
+
+ - Returned when a client tries to invite a user to a
+ channel they are already on.
+
+
+
+Oikarinen & Reed [Page 45]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+ 444 ERR_NOLOGIN
+ "<user> :User not logged in"
+
+ - Returned by the summon after a SUMMON command for a
+ user was unable to be performed since they were not
+ logged in.
+
+ 445 ERR_SUMMONDISABLED
+ ":SUMMON has been disabled"
+
+ - Returned as a response to the SUMMON command. Must be
+ returned by any server which does not implement it.
+
+ 446 ERR_USERSDISABLED
+ ":USERS has been disabled"
+
+ - Returned as a response to the USERS command. Must be
+ returned by any server which does not implement it.
+
+ 451 ERR_NOTREGISTERED
+ ":You have not registered"
+
+ - Returned by the server to indicate that the client
+ must be registered before the server will allow it
+ to be parsed in detail.
+
+ 461 ERR_NEEDMOREPARAMS
+ "<command> :Not enough parameters"
+
+ - Returned by the server by numerous commands to
+ indicate to the client that it didn't supply enough
+ parameters.
+
+ 462 ERR_ALREADYREGISTRED
+ ":You may not reregister"
+
+ - Returned by the server to any link which tries to
+ change part of the registered details (such as
+ password or user details from second USER message).
+
+
+ 463 ERR_NOPERMFORHOST
+ ":Your host isn't among the privileged"
+
+ - Returned to a client which attempts to register with
+ a server which does not been setup to allow
+ connections from the host the attempted connection
+ is tried.
+
+
+
+Oikarinen & Reed [Page 46]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+ 464 ERR_PASSWDMISMATCH
+ ":Password incorrect"
+
+ - Returned to indicate a failed attempt at registering
+ a connection for which a password was required and
+ was either not given or incorrect.
+
+ 465 ERR_YOUREBANNEDCREEP
+ ":You are banned from this server"
+
+ - Returned after an attempt to connect and register
+ yourself with a server which has been setup to
+ explicitly deny connections to you.
+
+ 467 ERR_KEYSET
+ "<channel> :Channel key already set"
+ 471 ERR_CHANNELISFULL
+ "<channel> :Cannot join channel (+l)"
+ 472 ERR_UNKNOWNMODE
+ "<char> :is unknown mode char to me"
+ 473 ERR_INVITEONLYCHAN
+ "<channel> :Cannot join channel (+i)"
+ 474 ERR_BANNEDFROMCHAN
+ "<channel> :Cannot join channel (+b)"
+ 475 ERR_BADCHANNELKEY
+ "<channel> :Cannot join channel (+k)"
+ 481 ERR_NOPRIVILEGES
+ ":Permission Denied- You're not an IRC operator"
+
+ - Any command requiring operator privileges to operate
+ must return this error to indicate the attempt was
+ unsuccessful.
+
+ 482 ERR_CHANOPRIVSNEEDED
+ "<channel> :You're not channel operator"
+
+ - Any command requiring 'chanop' privileges (such as
+ MODE messages) must return this error if the client
+ making the attempt is not a chanop on the specified
+ channel.
+
+ 483 ERR_CANTKILLSERVER
+ ":You cant kill a server!"
+
+ - Any attempts to use the KILL command on a server
+ are to be refused and this error returned directly
+ to the client.
+
+
+
+
+Oikarinen & Reed [Page 47]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+ 491 ERR_NOOPERHOST
+ ":No O-lines for your host"
+
+ - If a client sends an OPER message and the server has
+ not been configured to allow connections from the
+ client's host as an operator, this error must be
+ returned.
+
+ 501 ERR_UMODEUNKNOWNFLAG
+ ":Unknown MODE flag"
+
+ - Returned by the server to indicate that a MODE
+ message was sent with a nickname parameter and that
+ the a mode flag sent was not recognized.
+
+ 502 ERR_USERSDONTMATCH
+ ":Cant change mode for other users"
+
+ - Error sent to any user trying to view or change the
+ user mode for a user other than themselves.
+
+6.2 Command responses.
+
+ 300 RPL_NONE
+ Dummy reply number. Not used.
+
+ 302 RPL_USERHOST
+ ":[<reply>{<space><reply>}]"
+
+ - Reply format used by USERHOST to list replies to
+ the query list. The reply string is composed as
+ follows:
+
+ <reply> ::= <nick>['*'] '=' <'+'|'-'><hostname>
+
+ The '*' indicates whether the client has registered
+ as an Operator. The '-' or '+' characters represent
+ whether the client has set an AWAY message or not
+ respectively.
+
+ 303 RPL_ISON
+ ":[<nick> {<space><nick>}]"
+
+ - Reply format used by ISON to list replies to the
+ query list.
+
+ 301 RPL_AWAY
+ "<nick> :<away message>"
+
+
+
+Oikarinen & Reed [Page 48]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+ 305 RPL_UNAWAY
+ ":You are no longer marked as being away"
+ 306 RPL_NOWAWAY
+ ":You have been marked as being away"
+
+ - These replies are used with the AWAY command (if
+ allowed). RPL_AWAY is sent to any client sending a
+ PRIVMSG to a client which is away. RPL_AWAY is only
+ sent by the server to which the client is connected.
+ Replies RPL_UNAWAY and RPL_NOWAWAY are sent when the
+ client removes and sets an AWAY message.
+
+ 311 RPL_WHOISUSER
+ "<nick> <user> <host> * :<real name>"
+ 312 RPL_WHOISSERVER
+ "<nick> <server> :<server info>"
+ 313 RPL_WHOISOPERATOR
+ "<nick> :is an IRC operator"
+ 317 RPL_WHOISIDLE
+ "<nick> <integer> :seconds idle"
+ 318 RPL_ENDOFWHOIS
+ "<nick> :End of /WHOIS list"
+ 319 RPL_WHOISCHANNELS
+ "<nick> :{[@|+]<channel><space>}"
+
+ - Replies 311 - 313, 317 - 319 are all replies
+ generated in response to a WHOIS message. Given that
+ there are enough parameters present, the answering
+ server must either formulate a reply out of the above
+ numerics (if the query nick is found) or return an
+ error reply. The '*' in RPL_WHOISUSER is there as
+ the literal character and not as a wild card. For
+ each reply set, only RPL_WHOISCHANNELS may appear
+ more than once (for long lists of channel names).
+ The '@' and '+' characters next to the channel name
+ indicate whether a client is a channel operator or
+ has been granted permission to speak on a moderated
+ channel. The RPL_ENDOFWHOIS reply is used to mark
+ the end of processing a WHOIS message.
+
+ 314 RPL_WHOWASUSER
+ "<nick> <user> <host> * :<real name>"
+ 369 RPL_ENDOFWHOWAS
+ "<nick> :End of WHOWAS"
+
+ - When replying to a WHOWAS message, a server must use
+ the replies RPL_WHOWASUSER, RPL_WHOISSERVER or
+ ERR_WASNOSUCHNICK for each nickname in the presented
+
+
+
+Oikarinen & Reed [Page 49]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+ list. At the end of all reply batches, there must
+ be RPL_ENDOFWHOWAS (even if there was only one reply
+ and it was an error).
+
+ 321 RPL_LISTSTART
+ "Channel :Users Name"
+ 322 RPL_LIST
+ "<channel> <# visible> :<topic>"
+ 323 RPL_LISTEND
+ ":End of /LIST"
+
+ - Replies RPL_LISTSTART, RPL_LIST, RPL_LISTEND mark
+ the start, actual replies with data and end of the
+ server's response to a LIST command. If there are
+ no channels available to return, only the start
+ and end reply must be sent.
+
+ 324 RPL_CHANNELMODEIS
+ "<channel> <mode> <mode params>"
+
+ 331 RPL_NOTOPIC
+ "<channel> :No topic is set"
+ 332 RPL_TOPIC
+ "<channel> :<topic>"
+
+ - When sending a TOPIC message to determine the
+ channel topic, one of two replies is sent. If
+ the topic is set, RPL_TOPIC is sent back else
+ RPL_NOTOPIC.
+
+ 341 RPL_INVITING
+ "<channel> <nick>"
+
+ - Returned by the server to indicate that the
+ attempted INVITE message was successful and is
+ being passed onto the end client.
+
+ 342 RPL_SUMMONING
+ "<user> :Summoning user to IRC"
+
+ - Returned by a server answering a SUMMON message to
+ indicate that it is summoning that user.
+
+ 351 RPL_VERSION
+ "<version>.<debuglevel> <server> :<comments>"
+
+ - Reply by the server showing its version details.
+ The <version> is the version of the software being
+
+
+
+Oikarinen & Reed [Page 50]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+ used (including any patchlevel revisions) and the
+ <debuglevel> is used to indicate if the server is
+ running in "debug mode".
+
+ The "comments" field may contain any comments about
+ the version or further version details.
+
+ 352 RPL_WHOREPLY
+ "<channel> <user> <host> <server> <nick> \
+ <H|G>[*][@|+] :<hopcount> <real name>"
+ 315 RPL_ENDOFWHO
+ "<name> :End of /WHO list"
+
+ - The RPL_WHOREPLY and RPL_ENDOFWHO pair are used
+ to answer a WHO message. The RPL_WHOREPLY is only
+ sent if there is an appropriate match to the WHO
+ query. If there is a list of parameters supplied
+ with a WHO message, a RPL_ENDOFWHO must be sent
+ after processing each list item with <name> being
+ the item.
+
+ 353 RPL_NAMREPLY
+ "<channel> :[[@|+]<nick> [[@|+]<nick> [...]]]"
+ 366 RPL_ENDOFNAMES
+ "<channel> :End of /NAMES list"
+
+ - To reply to a NAMES message, a reply pair consisting
+ of RPL_NAMREPLY and RPL_ENDOFNAMES is sent by the
+ server back to the client. If there is no channel
+ found as in the query, then only RPL_ENDOFNAMES is
+ returned. The exception to this is when a NAMES
+ message is sent with no parameters and all visible
+ channels and contents are sent back in a series of
+ RPL_NAMEREPLY messages with a RPL_ENDOFNAMES to mark
+ the end.
+
+ 364 RPL_LINKS
+ "<mask> <server> :<hopcount> <server info>"
+ 365 RPL_ENDOFLINKS
+ "<mask> :End of /LINKS list"
+
+ - In replying to the LINKS message, a server must send
+ replies back using the RPL_LINKS numeric and mark the
+ end of the list using an RPL_ENDOFLINKS reply.
+
+ 367 RPL_BANLIST
+ "<channel> <banid>"
+ 368 RPL_ENDOFBANLIST
+
+
+
+Oikarinen & Reed [Page 51]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+ "<channel> :End of channel ban list"
+
+ - When listing the active 'bans' for a given channel,
+ a server is required to send the list back using the
+ RPL_BANLIST and RPL_ENDOFBANLIST messages. A separate
+ RPL_BANLIST is sent for each active banid. After the
+ banids have been listed (or if none present) a
+ RPL_ENDOFBANLIST must be sent.
+
+ 371 RPL_INFO
+ ":<string>"
+ 374 RPL_ENDOFINFO
+ ":End of /INFO list"
+
+ - A server responding to an INFO message is required to
+ send all its 'info' in a series of RPL_INFO messages
+ with a RPL_ENDOFINFO reply to indicate the end of the
+ replies.
+
+ 375 RPL_MOTDSTART
+ ":- <server> Message of the day - "
+ 372 RPL_MOTD
+ ":- <text>"
+ 376 RPL_ENDOFMOTD
+ ":End of /MOTD command"
+
+ - When responding to the MOTD message and the MOTD file
+ is found, the file is displayed line by line, with
+ each line no longer than 80 characters, using
+ RPL_MOTD format replies. These should be surrounded
+ by a RPL_MOTDSTART (before the RPL_MOTDs) and an
+ RPL_ENDOFMOTD (after).
+
+ 381 RPL_YOUREOPER
+ ":You are now an IRC operator"
+
+ - RPL_YOUREOPER is sent back to a client which has
+ just successfully issued an OPER message and gained
+ operator status.
+
+ 382 RPL_REHASHING
+ "<config file> :Rehashing"
+
+ - If the REHASH option is used and an operator sends
+ a REHASH message, an RPL_REHASHING is sent back to
+ the operator.
+
+ 391 RPL_TIME
+
+
+
+Oikarinen & Reed [Page 52]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+ "<server> :<string showing server's local time>"
+
+ - When replying to the TIME message, a server must send
+ the reply using the RPL_TIME format above. The string
+ showing the time need only contain the correct day and
+ time there. There is no further requirement for the
+ time string.
+
+ 392 RPL_USERSSTART
+ ":UserID Terminal Host"
+ 393 RPL_USERS
+ ":%-8s %-9s %-8s"
+ 394 RPL_ENDOFUSERS
+ ":End of users"
+ 395 RPL_NOUSERS
+ ":Nobody logged in"
+
+ - If the USERS message is handled by a server, the
+ replies RPL_USERSTART, RPL_USERS, RPL_ENDOFUSERS and
+ RPL_NOUSERS are used. RPL_USERSSTART must be sent
+ first, following by either a sequence of RPL_USERS
+ or a single RPL_NOUSER. Following this is
+ RPL_ENDOFUSERS.
+
+ 200 RPL_TRACELINK
+ "Link <version & debug level> <destination> \
+ <next server>"
+ 201 RPL_TRACECONNECTING
+ "Try. <class> <server>"
+ 202 RPL_TRACEHANDSHAKE
+ "H.S. <class> <server>"
+ 203 RPL_TRACEUNKNOWN
+ "???? <class> [<client IP address in dot form>]"
+ 204 RPL_TRACEOPERATOR
+ "Oper <class> <nick>"
+ 205 RPL_TRACEUSER
+ "User <class> <nick>"
+ 206 RPL_TRACESERVER
+ "Serv <class> <int>S <int>C <server> \
+ <nick!user|*!*>@<host|server>"
+ 208 RPL_TRACENEWTYPE
+ "<newtype> 0 <client name>"
+ 261 RPL_TRACELOG
+ "File <logfile> <debug level>"
+
+ - The RPL_TRACE* are all returned by the server in
+ response to the TRACE message. How many are
+ returned is dependent on the the TRACE message and
+
+
+
+Oikarinen & Reed [Page 53]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+ whether it was sent by an operator or not. There
+ is no predefined order for which occurs first.
+ Replies RPL_TRACEUNKNOWN, RPL_TRACECONNECTING and
+ RPL_TRACEHANDSHAKE are all used for connections
+ which have not been fully established and are either
+ unknown, still attempting to connect or in the
+ process of completing the 'server handshake'.
+ RPL_TRACELINK is sent by any server which handles
+ a TRACE message and has to pass it on to another
+ server. The list of RPL_TRACELINKs sent in
+ response to a TRACE command traversing the IRC
+ network should reflect the actual connectivity of
+ the servers themselves along that path.
+ RPL_TRACENEWTYPE is to be used for any connection
+ which does not fit in the other categories but is
+ being displayed anyway.
+
+ 211 RPL_STATSLINKINFO
+ "<linkname> <sendq> <sent messages> \
+ <sent bytes> <received messages> \
+ <received bytes> <time open>"
+ 212 RPL_STATSCOMMANDS
+ "<command> <count>"
+ 213 RPL_STATSCLINE
+ "C <host> * <name> <port> <class>"
+ 214 RPL_STATSNLINE
+ "N <host> * <name> <port> <class>"
+ 215 RPL_STATSILINE
+ "I <host> * <host> <port> <class>"
+ 216 RPL_STATSKLINE
+ "K <host> * <username> <port> <class>"
+ 218 RPL_STATSYLINE
+ "Y <class> <ping frequency> <connect \
+ frequency> <max sendq>"
+ 219 RPL_ENDOFSTATS
+ "<stats letter> :End of /STATS report"
+ 241 RPL_STATSLLINE
+ "L <hostmask> * <servername> <maxdepth>"
+ 242 RPL_STATSUPTIME
+ ":Server Up %d days %d:%02d:%02d"
+ 243 RPL_STATSOLINE
+ "O <hostmask> * <name>"
+ 244 RPL_STATSHLINE
+ "H <hostmask> * <servername>"
+
+ 221 RPL_UMODEIS
+ "<user mode string>"
+
+
+
+
+Oikarinen & Reed [Page 54]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+ - To answer a query about a client's own mode,
+ RPL_UMODEIS is sent back.
+
+ 251 RPL_LUSERCLIENT
+ ":There are <integer> users and <integer> \
+ invisible on <integer> servers"
+ 252 RPL_LUSEROP
+ "<integer> :operator(s) online"
+ 253 RPL_LUSERUNKNOWN
+ "<integer> :unknown connection(s)"
+ 254 RPL_LUSERCHANNELS
+ "<integer> :channels formed"
+ 255 RPL_LUSERME
+ ":I have <integer> clients and <integer> \
+ servers"
+
+ - In processing an LUSERS message, the server
+ sends a set of replies from RPL_LUSERCLIENT,
+ RPL_LUSEROP, RPL_USERUNKNOWN,
+ RPL_LUSERCHANNELS and RPL_LUSERME. When
+ replying, a server must send back
+ RPL_LUSERCLIENT and RPL_LUSERME. The other
+ replies are only sent back if a non-zero count
+ is found for them.
+
+ 256 RPL_ADMINME
+ "<server> :Administrative info"
+ 257 RPL_ADMINLOC1
+ ":<admin info>"
+ 258 RPL_ADMINLOC2
+ ":<admin info>"
+ 259 RPL_ADMINEMAIL
+ ":<admin info>"
+
+ - When replying to an ADMIN message, a server
+ is expected to use replies RLP_ADMINME
+ through to RPL_ADMINEMAIL and provide a text
+ message with each. For RPL_ADMINLOC1 a
+ description of what city, state and country
+ the server is in is expected, followed by
+ details of the university and department
+ (RPL_ADMINLOC2) and finally the administrative
+ contact for the server (an email address here
+ is required) in RPL_ADMINEMAIL.
+
+
+
+
+
+
+
+Oikarinen & Reed [Page 55]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+6.3 Reserved numerics.
+
+ These numerics are not described above since they fall into one of
+ the following categories:
+
+ 1. no longer in use;
+
+ 2. reserved for future planned use;
+
+ 3. in current use but are part of a non-generic 'feature' of
+ the current IRC server.
+
+ 209 RPL_TRACECLASS 217 RPL_STATSQLINE
+ 231 RPL_SERVICEINFO 232 RPL_ENDOFSERVICES
+ 233 RPL_SERVICE 234 RPL_SERVLIST
+ 235 RPL_SERVLISTEND
+ 316 RPL_WHOISCHANOP 361 RPL_KILLDONE
+ 362 RPL_CLOSING 363 RPL_CLOSEEND
+ 373 RPL_INFOSTART 384 RPL_MYPORTIS
+ 466 ERR_YOUWILLBEBANNED 476 ERR_BADCHANMASK
+ 492 ERR_NOSERVICEHOST
+
+7. Client and server authentication
+
+ Clients and servers are both subject to the same level of
+ authentication. For both, an IP number to hostname lookup (and
+ reverse check on this) is performed for all connections made to the
+ server. Both connections are then subject to a password check (if
+ there is a password set for that connection). These checks are
+ possible on all connections although the password check is only
+ commonly used with servers.
+
+ An additional check that is becoming of more and more common is that
+ of the username responsible for making the connection. Finding the
+ username of the other end of the connection typically involves
+ connecting to an authentication server such as IDENT as described in
+ RFC 1413.
+
+ Given that without passwords it is not easy to reliably determine who
+ is on the other end of a network connection, use of passwords is
+ strongly recommended on inter-server connections in addition to any
+ other measures such as using an ident server.
+
+8. Current implementations
+
+ The only current implementation of this protocol is the IRC server,
+ version 2.8. Earlier versions may implement some or all of the
+ commands described by this document with NOTICE messages replacing
+
+
+
+Oikarinen & Reed [Page 56]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+ many of the numeric replies. Unfortunately, due to backward
+ compatibility requirements, the implementation of some parts of this
+ document varies with what is laid out. On notable difference is:
+
+ * recognition that any LF or CR anywhere in a message marks the
+ end of that message (instead of requiring CR-LF);
+
+ The rest of this section deals with issues that are mostly of
+ importance to those who wish to implement a server but some parts
+ also apply directly to clients as well.
+
+8.1 Network protocol: TCP - why it is best used here.
+
+ IRC has been implemented on top of TCP since TCP supplies a reliable
+ network protocol which is well suited to this scale of conferencing.
+ The use of multicast IP is an alternative, but it is not widely
+ available or supported at the present time.
+
+8.1.1 Support of Unix sockets
+
+ Given that Unix domain sockets allow listen/connect operations, the
+ current implementation can be configured to listen and accept both
+ client and server connections on a Unix domain socket. These are
+ recognized as sockets where the hostname starts with a '/'.
+
+ When providing any information about the connections on a Unix domain
+ socket, the server is required to supplant the actual hostname in
+ place of the pathname unless the actual socket name is being asked
+ for.
+
+8.2 Command Parsing
+
+ To provide useful 'non-buffered' network IO for clients and servers,
+ each connection is given its own private 'input buffer' in which the
+ results of the most recent read and parsing are kept. A buffer size
+ of 512 bytes is used so as to hold 1 full message, although, this
+ will usually hold several commands. The private buffer is parsed
+ after every read operation for valid messages. When dealing with
+ multiple messages from one client in the buffer, care should be taken
+ in case one happens to cause the client to be 'removed'.
+
+8.3 Message delivery
+
+ It is common to find network links saturated or hosts to which you
+ are sending data unable to send data. Although Unix typically
+ handles this through the TCP window and internal buffers, the server
+ often has large amounts of data to send (especially when a new
+ server-server link forms) and the small buffers provided in the
+
+
+
+Oikarinen & Reed [Page 57]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+ kernel are not enough for the outgoing queue. To alleviate this
+ problem, a "send queue" is used as a FIFO queue for data to be sent.
+ A typical "send queue" may grow to 200 Kbytes on a large IRC network
+ with a slow network connection when a new server connects.
+
+ When polling its connections, a server will first read and parse all
+ incoming data, queuing any data to be sent out. When all available
+ input is processed, the queued data is sent. This reduces the number
+ of write() system calls and helps TCP make bigger packets.
+
+8.4 Connection 'Liveness'
+
+ To detect when a connection has died or become unresponsive, the
+ server must ping each of its connections that it doesn't get a
+ response from in a given amount of time.
+
+ If a connection doesn't respond in time, its connection is closed
+ using the appropriate procedures. A connection is also dropped if
+ its sendq grows beyond the maximum allowed, because it is better to
+ close a slow connection than have a server process block.
+
+8.5 Establishing a server to client connection
+
+ Upon connecting to an IRC server, a client is sent the MOTD (if
+ present) as well as the current user/server count (as per the LUSER
+ command). The server is also required to give an unambiguous message
+ to the client which states its name and version as well as any other
+ introductory messages which may be deemed appropriate.
+
+ After dealing with this, the server must then send out the new user's
+ nickname and other information as supplied by itself (USER command)
+ and as the server could discover (from DNS/authentication servers).
+ The server must send this information out with NICK first followed by
+ USER.
+
+8.6 Establishing a server-server connection.
+
+ The process of establishing of a server-to-server connection is
+ fraught with danger since there are many possible areas where
+ problems can occur - the least of which are race conditions.
+
+ After a server has received a connection following by a PASS/SERVER
+ pair which were recognised as being valid, the server should then
+ reply with its own PASS/SERVER information for that connection as
+ well as all of the other state information it knows about as
+ described below.
+
+ When the initiating server receives a PASS/SERVER pair, it too then
+
+
+
+Oikarinen & Reed [Page 58]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+ checks that the server responding is authenticated properly before
+ accepting the connection to be that server.
+
+8.6.1 Server exchange of state information when connecting
+
+ The order of state information being exchanged between servers is
+ essential. The required order is as follows:
+
+ * all known other servers;
+
+ * all known user information;
+
+ * all known channel information.
+
+ Information regarding servers is sent via extra SERVER messages, user
+ information with NICK/USER/MODE/JOIN messages and channels with MODE
+ messages.
+
+ NOTE: channel topics are *NOT* exchanged here because the TOPIC
+ command overwrites any old topic information, so at best, the two
+ sides of the connection would exchange topics.
+
+ By passing the state information about servers first, any collisions
+ with servers that already exist occur before nickname collisions due
+ to a second server introducing a particular nickname. Due to the IRC
+ network only being able to exist as an acyclic graph, it may be
+ possible that the network has already reconnected in another
+ location, the place where the collision occurs indicating where the
+ net needs to split.
+
+8.7 Terminating server-client connections
+
+ When a client connection closes, a QUIT message is generated on
+ behalf of the client by the server to which the client connected. No
+ other message is to be generated or used.
+
+8.8 Terminating server-server connections
+
+ If a server-server connection is closed, either via a remotely
+ generated SQUIT or 'natural' causes, the rest of the connected IRC
+ network must have its information updated with by the server which
+ detected the closure. The server then sends a list of SQUITs (one
+ for each server behind that connection) and a list of QUITs (again,
+ one for each client behind that connection).
+
+
+
+
+
+
+
+Oikarinen & Reed [Page 59]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+8.9 Tracking nickname changes
+
+ All IRC servers are required to keep a history of recent nickname
+ changes. This is required to allow the server to have a chance of
+ keeping in touch of things when nick-change race conditions occur
+ with commands which manipulate them. Commands which must trace nick
+ changes are:
+
+ * KILL (the nick being killed)
+
+ * MODE (+/- o,v)
+
+ * KICK (the nick being kicked)
+
+ No other commands are to have nick changes checked for.
+
+ In the above cases, the server is required to first check for the
+ existence of the nickname, then check its history to see who that
+ nick currently belongs to (if anyone!). This reduces the chances of
+ race conditions but they can still occur with the server ending up
+ affecting the wrong client. When performing a change trace for an
+ above command it is recommended that a time range be given and
+ entries which are too old ignored.
+
+ For a reasonable history, a server should be able to keep previous
+ nickname for every client it knows about if they all decided to
+ change. This size is limited by other factors (such as memory, etc).
+
+8.10 Flood control of clients
+
+ With a large network of interconnected IRC servers, it is quite easy
+ for any single client attached to the network to supply a continuous
+ stream of messages that result in not only flooding the network, but
+ also degrading the level of service provided to others. Rather than
+ require every 'victim' to be provide their own protection, flood
+ protection was written into the server and is applied to all clients
+ except services. The current algorithm is as follows:
+
+ * check to see if client's `message timer' is less than
+ current time (set to be equal if it is);
+
+ * read any data present from the client;
+
+ * while the timer is less than ten seconds ahead of the current
+ time, parse any present messages and penalize the client by
+ 2 seconds for each message;
+
+ which in essence means that the client may send 1 message every 2
+
+
+
+Oikarinen & Reed [Page 60]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+ seconds without being adversely affected.
+
+8.11 Non-blocking lookups
+
+ In a real-time environment, it is essential that a server process do
+ as little waiting as possible so that all the clients are serviced
+ fairly. Obviously this requires non-blocking IO on all network
+ read/write operations. For normal server connections, this was not
+ difficult, but there are other support operations that may cause the
+ server to block (such as disk reads). Where possible, such activity
+ should be performed with a short timeout.
+
+8.11.1 Hostname (DNS) lookups
+
+ Using the standard resolver libraries from Berkeley and others has
+ meant large delays in some cases where replies have timed out. To
+ avoid this, a separate set of DNS routines were written which were
+ setup for non-blocking IO operations and then polled from within the
+ main server IO loop.
+
+8.11.2 Username (Ident) lookups
+
+ Although there are numerous ident libraries for use and inclusion
+ into other programs, these caused problems since they operated in a
+ synchronous manner and resulted in frequent delays. Again the
+ solution was to write a set of routines which would cooperate with
+ the rest of the server and work using non-blocking IO.
+
+8.12 Configuration File
+
+ To provide a flexible way of setting up and running the server, it is
+ recommended that a configuration file be used which contains
+ instructions to the server on the following:
+
+ * which hosts to accept client connections from;
+
+ * which hosts to allow to connect as servers;
+
+ * which hosts to connect to (both actively and
+ passively);
+
+ * information about where the server is (university,
+ city/state, company are examples of this);
+
+ * who is responsible for the server and an email address
+ at which they can be contacted;
+
+ * hostnames and passwords for clients which wish to be given
+
+
+
+Oikarinen & Reed [Page 61]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+ access to restricted operator commands.
+
+ In specifying hostnames, both domain names and use of the 'dot'
+ notation (127.0.0.1) should both be accepted. It must be possible to
+ specify the password to be used/accepted for all outgoing and
+ incoming connections (although the only outgoing connections are
+ those to other servers).
+
+ The above list is the minimum requirement for any server which wishes
+ to make a connection with another server. Other items which may be
+ of use are:
+
+ * specifying which servers other server may introduce;
+
+ * how deep a server branch is allowed to become;
+
+ * hours during which clients may connect.
+
+8.12.1 Allowing clients to connect
+
+ A server should use some sort of 'access control list' (either in the
+ configuration file or elsewhere) that is read at startup and used to
+ decide what hosts clients may use to connect to it.
+
+ Both 'deny' and 'allow' should be implemented to provide the required
+ flexibility for host access control.
+
+8.12.2 Operators
+
+ The granting of operator privileges to a disruptive person can have
+ dire consequences for the well-being of the IRC net in general due to
+ the powers given to them. Thus, the acquisition of such powers
+ should not be very easy. The current setup requires two 'passwords'
+ to be used although one of them is usually easy guessed. Storage of
+ oper passwords in configuration files is preferable to hard coding
+ them in and should be stored in a crypted format (ie using crypt(3)
+ from Unix) to prevent easy theft.
+
+8.12.3 Allowing servers to connect
+
+ The interconnection of server is not a trivial matter: a bad
+ connection can have a large impact on the usefulness of IRC. Thus,
+ each server should have a list of servers to which it may connect and
+ which servers may connect to it. Under no circumstances should a
+ server allow an arbitrary host to connect as a server. In addition
+ to which servers may and may not connect, the configuration file
+ should also store the password and other characteristics of that
+ link.
+
+
+
+Oikarinen & Reed [Page 62]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+8.12.4 Administrivia
+
+ To provide accurate and valid replies to the ADMIN command (see
+ section 4.3.7), the server should find the relevant details in the
+ configuration.
+
+8.13 Channel membership
+
+ The current server allows any registered local user to join upto 10
+ different channels. There is no limit imposed on non-local users so
+ that the server remains (reasonably) consistant with all others on a
+ channel membership basis
+
+9. Current problems
+
+ There are a number of recognized problems with this protocol, all of
+ which hope to be solved sometime in the near future during its
+ rewrite. Currently, work is underway to find working solutions to
+ these problems.
+
+9.1 Scalability
+
+ It is widely recognized that this protocol does not scale
+ sufficiently well when used in a large arena. The main problem comes
+ from the requirement that all servers know about all other servers
+ and users and that information regarding them be updated as soon as
+ it changes. It is also desirable to keep the number of servers low
+ so that the path length between any two points is kept minimal and
+ the spanning tree as strongly branched as possible.
+
+9.2 Labels
+
+ The current IRC protocol has 3 types of labels: the nickname, the
+ channel name and the server name. Each of the three types has its
+ own domain and no duplicates are allowed inside that domain.
+ Currently, it is possible for users to pick the label for any of the
+ three, resulting in collisions. It is widely recognized that this
+ needs reworking, with a plan for unique names for channels and nicks
+ that don't collide being desirable as well as a solution allowing a
+ cyclic tree.
+
+9.2.1 Nicknames
+
+ The idea of the nickname on IRC is very convenient for users to use
+ when talking to each other outside of a channel, but there is only a
+ finite nickname space and being what they are, its not uncommon for
+ several people to want to use the same nick. If a nickname is chosen
+ by two people using this protocol, either one will not succeed or
+
+
+
+Oikarinen & Reed [Page 63]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+ both will removed by use of KILL (4.6.1).
+
+9.2.2 Channels
+
+ The current channel layout requires that all servers know about all
+ channels, their inhabitants and properties. Besides not scaling
+ well, the issue of privacy is also a concern. A collision of
+ channels is treated as an inclusive event (both people who create the
+ new channel are considered to be members of it) rather than an
+ exclusive one such as used to solve nickname collisions.
+
+9.2.3 Servers
+
+ Although the number of servers is usually small relative to the
+ number of users and channels, they two currently required to be known
+ globally, either each one separately or hidden behind a mask.
+
+9.3 Algorithms
+
+ In some places within the server code, it has not been possible to
+ avoid N^2 algorithms such as checking the channel list of a set
+ of clients.
+
+ In current server versions, there are no database consistency checks,
+ each server assumes that a neighbouring server is correct. This
+ opens the door to large problems if a connecting server is buggy or
+ otherwise tries to introduce contradictions to the existing net.
+
+ Currently, because of the lack of unique internal and global labels,
+ there are a multitude of race conditions that exist. These race
+ conditions generally arise from the problem of it taking time for
+ messages to traverse and effect the IRC network. Even by changing to
+ unique labels, there are problems with channel-related commands being
+ disrupted.
+
+10. Current support and availability
+
+ Mailing lists for IRC related discussion:
+ Future protocol: ircd-three-request@eff.org
+ General discussion: operlist-request@eff.org
+
+ Software implemenations
+ cs.bu.edu:/irc
+ nic.funet.fi:/pub/irc
+ coombs.anu.edu.au:/pub/irc
+
+ Newsgroup: alt.irc
+
+
+
+
+Oikarinen & Reed [Page 64]
+
+RFC 1459 Internet Relay Chat Protocol May 1993
+
+
+Security Considerations
+
+ Security issues are discussed in sections 4.1, 4.1.1, 4.1.3, 5.5, and
+ 7.
+
+12. Authors' Addresses
+
+ Jarkko Oikarinen
+ Tuirantie 17 as 9
+ 90500 OULU
+ FINLAND
+
+ Email: jto@tolsun.oulu.fi
+
+
+ Darren Reed
+ 4 Pateman Street
+ Watsonia, Victoria 3087
+ Australia
+
+ Email: avalon@coombs.anu.edu.au
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Oikarinen & Reed [Page 65]
+ \ No newline at end of file
diff --git a/doc/rfcs/rfc2222.txt b/doc/rfcs/rfc2222.txt
new file mode 100644
index 0000000..2b0a2ab
--- /dev/null
+++ b/doc/rfcs/rfc2222.txt
@@ -0,0 +1,899 @@
+
+
+
+
+
+
+Network Working Group J. Myers
+Request for Comments: 2222 Netscape Communications
+Category: Standards Track October 1997
+
+
+ Simple Authentication and Security Layer (SASL)
+
+Status of this Memo
+
+ This document specifies an Internet standards track protocol for the
+ Internet community, and requests discussion and suggestions for
+ improvements. Please refer to the current edition of the "Internet
+ Official Protocol Standards" (STD 1) for the standardization state
+ and status of this protocol. Distribution of this memo is unlimited.
+
+Copyright Notice
+
+ Copyright (C) The Internet Society (1997). All Rights Reserved.
+
+Table of Contents
+
+ 1. Abstract .............................................. 2
+ 2. Organization of this Document ......................... 2
+ 2.1. How to Read This Document ............................. 2
+ 2.2. Conventions Used in this Document ..................... 2
+ 2.3. Examples .............................................. 3
+ 3. Introduction and Overview ............................. 3
+ 4. Profiling requirements ................................ 4
+ 5. Specific issues ....................................... 5
+ 5.1. Client sends data first ............................... 5
+ 5.2. Server returns success with additional data ........... 5
+ 5.3. Multiple authentications .............................. 5
+ 6. Registration procedures ............................... 6
+ 6.1. Comments on SASL mechanism registrations .............. 6
+ 6.2. Location of Registered SASL Mechanism List ............ 6
+ 6.3. Change Control ........................................ 7
+ 6.4. Registration Template ................................. 7
+ 7. Mechanism definitions ................................. 8
+ 7.1. Kerberos version 4 mechanism .......................... 8
+ 7.2. GSSAPI mechanism ...................................... 9
+ 7.2.1 Client side of authentication protocol exchange ....... 9
+ 7.2.2 Server side of authentication protocol exchange ....... 10
+ 7.2.3 Security layer ........................................ 11
+ 7.3. S/Key mechanism ....................................... 11
+ 7.4. External mechanism .................................... 12
+ 8. References ............................................ 13
+ 9. Security Considerations ............................... 13
+ 10. Author's Address ...................................... 14
+
+
+
+Myers Standards Track [Page 1]
+
+RFC 2222 SASL October 1997
+
+
+ Appendix A. Relation of SASL to Transport Security .......... 15
+ Full Copyright Statement .................................... 16
+
+1. Abstract
+
+ This document describes a method for adding authentication support to
+ connection-based protocols. To use this specification, a protocol
+ includes a command for identifying and authenticating a user to a
+ server and for optionally negotiating protection of subsequent
+ protocol interactions. If its use is negotiated, a security layer is
+ inserted between the protocol and the connection. This document
+ describes how a protocol specifies such a command, defines several
+ mechanisms for use by the command, and defines the protocol used for
+ carrying a negotiated security layer over the connection.
+
+2. Organization of this Document
+
+2.1. How to Read This Document
+
+ This document is written to serve two different audiences, protocol
+ designers using this specification to support authentication in their
+ protocol, and implementors of clients or servers for those protocols
+ using this specification.
+
+ The sections "Introduction and Overview", "Profiling requirements",
+ and "Security Considerations" cover issues that protocol designers
+ need to understand and address in profiling this specification for
+ use in a specific protocol.
+
+ Implementors of a protocol using this specification need the
+ protocol-specific profiling information in addition to the
+ information in this document.
+
+2.2. Conventions Used in this Document
+
+ In examples, "C:" and "S:" indicate lines sent by the client and
+ server respectively.
+
+ The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY"
+ in this document are to be interpreted as defined in "Key words for
+ use in RFCs to Indicate Requirement Levels" [RFC 2119].
+
+
+
+
+
+
+
+
+
+
+Myers Standards Track [Page 2]
+
+RFC 2222 SASL October 1997
+
+
+2.3. Examples
+
+ Examples in this document are for the IMAP profile [RFC 2060] of this
+ specification. The base64 encoding of challenges and responses, as
+ well as the "+ " preceding the responses are part of the IMAP4
+ profile, not part of the SASL specification itself.
+
+3. Introduction and Overview
+
+ The Simple Authentication and Security Layer (SASL) is a method for
+ adding authentication support to connection-based protocols. To use
+ this specification, a protocol includes a command for identifying and
+ authenticating a user to a server and for optionally negotiating a
+ security layer for subsequent protocol interactions.
+
+ The command has a required argument identifying a SASL mechanism.
+ SASL mechanisms are named by strings, from 1 to 20 characters in
+ length, consisting of upper-case letters, digits, hyphens, and/or
+ underscores. SASL mechanism names must be registered with the IANA.
+ Procedures for registering new SASL mechanisms are given in the
+ section "Registration procedures"
+
+ If a server supports the requested mechanism, it initiates an
+ authentication protocol exchange. This consists of a series of
+ server challenges and client responses that are specific to the
+ requested mechanism. The challenges and responses are defined by the
+ mechanisms as binary tokens of arbitrary length. The protocol's
+ profile then specifies how these binary tokens are then encoded for
+ transfer over the connection.
+
+ After receiving the authentication command or any client response, a
+ server may issue a challenge, indicate failure, or indicate
+ completion. The protocol's profile specifies how the server
+ indicates which of the above it is doing.
+
+ After receiving a challenge, a client may issue a response or abort
+ the exchange. The protocol's profile specifies how the client
+ indicates which of the above it is doing.
+
+ During the authentication protocol exchange, the mechanism performs
+ authentication, transmits an authorization identity (frequently known
+ as a userid) from the client to server, and negotiates the use of a
+ mechanism-specific security layer. If the use of a security layer is
+ agreed upon, then the mechanism must also define or negotiate the
+ maximum cipher-text buffer size that each side is able to receive.
+
+
+
+
+
+
+Myers Standards Track [Page 3]
+
+RFC 2222 SASL October 1997
+
+
+ The transmitted authorization identity may be different than the
+ identity in the client's authentication credentials. This permits
+ agents such as proxy servers to authenticate using their own
+ credentials, yet request the access privileges of the identity for
+ which they are proxying. With any mechanism, transmitting an
+ authorization identity of the empty string directs the server to
+ derive an authorization identity from the client's authentication
+ credentials.
+
+ If use of a security layer is negotiated, it is applied to all
+ subsequent data sent over the connection. The security layer takes
+ effect immediately following the last response of the authentication
+ exchange for data sent by the client and the completion indication
+ for data sent by the server. Once the security layer is in effect,
+ the protocol stream is processed by the security layer into buffers
+ of cipher-text. Each buffer is transferred over the connection as a
+ stream of octets prepended with a four octet field in network byte
+ order that represents the length of the following buffer. The length
+ of the cipher-text buffer must be no larger than the maximum size
+ that was defined or negotiated by the other side.
+
+4. Profiling requirements
+
+ In order to use this specification, a protocol definition must supply
+ the following information:
+
+ 1. A service name, to be selected from the IANA registry of "service"
+ elements for the GSSAPI host-based service name form [RFC 2078].
+
+ 2. A definition of the command to initiate the authentication
+ protocol exchange. This command must have as a parameter the
+ mechanism name being selected by the client.
+
+ The command SHOULD have an optional parameter giving an initial
+ response. This optional parameter allows the client to avoid a
+ round trip when using a mechanism which is defined to have the
+ client send data first. When this initial response is sent by the
+ client and the selected mechanism is defined to have the server
+ start with an initial challenge, the command fails. See section
+ 5.1 of this document for further information.
+
+ 3. A definition of the method by which the authentication protocol
+ exchange is carried out, including how the challenges and
+ responses are encoded, how the server indicates completion or
+ failure of the exchange, how the client aborts an exchange, and
+ how the exchange method interacts with any line length limits in
+ the protocol.
+
+
+
+
+Myers Standards Track [Page 4]
+
+RFC 2222 SASL October 1997
+
+
+ 4. Identification of the octet where any negotiated security layer
+ starts to take effect, in both directions.
+
+ 5. A specification of how the authorization identity passed from the
+ client to the server is to be interpreted.
+
+5. Specific issues
+
+5.1. Client sends data first
+
+ Some mechanisms specify that the first data sent in the
+ authentication protocol exchange is from the client to the server.
+
+ If a protocol's profile permits the command which initiates an
+ authentication protocol exchange to contain an initial client
+ response, this parameter SHOULD be used with such mechanisms.
+
+ If the initial client response parameter is not given, or if a
+ protocol's profile does not permit the command which initiates an
+ authentication protocol exchange to contain an initial client
+ response, then the server issues a challenge with no data. The
+ client's response to this challenge is then used as the initial
+ client response. (The server then proceeds to send the next
+ challenge, indicates completion, or indicates failure.)
+
+5.2. Server returns success with additional data
+
+ Some mechanisms may specify that server challenge data be sent to the
+ client along with an indication of successful completion of the
+ exchange. This data would, for example, authenticate the server to
+ the client.
+
+ If a protocol's profile does not permit this server challenge to be
+ returned with a success indication, then the server issues the server
+ challenge without an indication of successful completion. The client
+ then responds with no data. After receiving this empty response, the
+ server then indicates successful completion.
+
+5.3. Multiple authentications
+
+ Unless otherwise stated by the protocol's profile, only one
+ successful SASL negotiation may occur in a protocol session. In this
+ case, once an authentication protocol exchange has successfully
+ completed, further attempts to initiate an authentication protocol
+ exchange fail.
+
+
+
+
+
+
+Myers Standards Track [Page 5]
+
+RFC 2222 SASL October 1997
+
+
+ In the case that a profile explicitly permits multiple successful
+ SASL negotiations to occur, then in no case may multiple security
+ layers be simultaneously in effect. If a security layer is in effect
+ and a subsequent SASL negotiation selects no security layer, the
+ original security layer remains in effect. If a security layer is in
+ effect and a subsequent SASL negotiation selects a second security
+ layer, then the second security layer replaces the first.
+
+6. Registration procedures
+
+ Registration of a SASL mechanism is done by filling in the template
+ in section 6.4 and sending it in to iana@isi.edu. IANA has the right
+ to reject obviously bogus registrations, but will perform no review
+ of clams made in the registration form.
+
+ There is no naming convention for SASL mechanisms; any name that
+ conforms to the syntax of a SASL mechanism name can be registered.
+
+ While the registration procedures do not require it, authors of SASL
+ mechanisms are encouraged to seek community review and comment
+ whenever that is feasible. Authors may seek community review by
+ posting a specification of their proposed mechanism as an internet-
+ draft. SASL mechanisms intended for widespread use should be
+ standardized through the normal IETF process, when appropriate.
+
+6.1. Comments on SASL mechanism registrations
+
+ Comments on registered SASL mechanisms should first be sent to the
+ "owner" of the mechanism. Submitters of comments may, after a
+ reasonable attempt to contact the owner, request IANA to attach their
+ comment to the SASL mechanism registration itself. If IANA approves
+ of this the comment will be made accessible in conjunction with the
+ SASL mechanism registration itself.
+
+6.2. Location of Registered SASL Mechanism List
+
+ SASL mechanism registrations will be posted in the anonymous FTP
+ directory "ftp://ftp.isi.edu/in-notes/iana/assignments/sasl-
+ mechanisms/" and all registered SASL mechanisms will be listed in the
+ periodically issued "Assigned Numbers" RFC [currently STD 2, RFC
+ 1700]. The SASL mechanism description and other supporting material
+ may also be published as an Informational RFC by sending it to "rfc-
+ editor@isi.edu" (please follow the instructions to RFC authors [RFC
+ 2223]).
+
+
+
+
+
+
+
+Myers Standards Track [Page 6]
+
+RFC 2222 SASL October 1997
+
+
+6.3. Change Control
+
+ Once a SASL mechanism registration has been published by IANA, the
+ author may request a change to its definition. The change request
+ follows the same procedure as the registration request.
+
+ The owner of a SASL mechanism may pass responsibility for the SASL
+ mechanism to another person or agency by informing IANA; this can be
+ done without discussion or review.
+
+ The IESG may reassign responsibility for a SASL mechanism. The most
+ common case of this will be to enable changes to be made to
+ mechanisms where the author of the registration has died, moved out
+ of contact or is otherwise unable to make changes that are important
+ to the community.
+
+ SASL mechanism registrations may not be deleted; mechanisms which are
+ no longer believed appropriate for use can be declared OBSOLETE by a
+ change to their "intended use" field; such SASL mechanisms will be
+ clearly marked in the lists published by IANA.
+
+ The IESG is considered to be the owner of all SASL mechanisms which
+ are on the IETF standards track.
+
+6.4. Registration Template
+
+ To: iana@iana.org
+ Subject: Registration of SASL mechanism X
+
+ SASL mechanism name:
+
+ Security considerations:
+
+ Published specification (optional, recommended):
+
+ Person & email address to contact for further information:
+
+ Intended usage:
+
+ (One of COMMON, LIMITED USE or OBSOLETE)
+
+ Author/Change controller:
+
+ (Any other information that the author deems interesting may be
+ added below this line.)
+
+
+
+
+
+
+Myers Standards Track [Page 7]
+
+RFC 2222 SASL October 1997
+
+
+7. Mechanism definitions
+
+ The following mechanisms are hereby defined.
+
+7.1. Kerberos version 4 mechanism
+
+ The mechanism name associated with Kerberos version 4 is
+ "KERBEROS_V4".
+
+ The first challenge consists of a random 32-bit number in network
+ byte order. The client responds with a Kerberos ticket and an
+ authenticator for the principal "service.hostname@realm", where
+ "service" is the service name specified in the protocol's profile,
+ "hostname" is the first component of the host name of the server with
+ all letters in lower case, and where "realm" is the Kerberos realm of
+ the server. The encrypted checksum field included within the
+ Kerberos authenticator contains the server provided challenge in
+ network byte order.
+
+ Upon decrypting and verifying the ticket and authenticator, the
+ server verifies that the contained checksum field equals the original
+ server provided random 32-bit number. Should the verification be
+ successful, the server must add one to the checksum and construct 8
+ octets of data, with the first four octets containing the incremented
+ checksum in network byte order, the fifth octet containing a bit-mask
+ specifying the security layers supported by the server, and the sixth
+ through eighth octets containing, in network byte order, the maximum
+ cipher-text buffer size the server is able to receive. The server
+ must encrypt using DES ECB mode the 8 octets of data in the session
+ key and issue that encrypted data in a second challenge. The client
+ considers the server authenticated if the first four octets of the
+ un-encrypted data is equal to one plus the checksum it previously
+ sent.
+
+ The client must construct data with the first four octets containing
+ the original server-issued checksum in network byte order, the fifth
+ octet containing the bit-mask specifying the selected security layer,
+ the sixth through eighth octets containing in network byte order the
+ maximum cipher-text buffer size the client is able to receive, and
+ the following octets containing the authorization identity. The
+ client must then append from one to eight zero-valued octets so that
+ the length of the data is a multiple of eight octets. The client must
+ then encrypt using DES PCBC mode the data with the session key and
+ respond with the encrypted data. The server decrypts the data and
+ verifies the contained checksum. The server must verify that the
+ principal identified in the Kerberos ticket is authorized to connect
+ as that authorization identity. After this verification, the
+ authentication process is complete.
+
+
+
+Myers Standards Track [Page 8]
+
+RFC 2222 SASL October 1997
+
+
+ The security layers and their corresponding bit-masks are as follows:
+
+ 1 No security layer
+ 2 Integrity (krb_mk_safe) protection
+ 4 Privacy (krb_mk_priv) protection
+
+ Other bit-masks may be defined in the future; bits which are not
+ understood must be negotiated off.
+
+ EXAMPLE: The following are two Kerberos version 4 login scenarios to
+ the IMAP4 protocol (note that the line breaks in the sample
+ authenticators are for editorial clarity and are not in real
+ authenticators)
+
+ S: * OK IMAP4 Server
+ C: A001 AUTHENTICATE KERBEROS_V4
+ S: + AmFYig==
+ C: BAcAQU5EUkVXLkNNVS5FRFUAOCAsho84kLN3/IJmrMG+25a4DT
+ +nZImJjnTNHJUtxAA+o0KPKfHEcAFs9a3CL5Oebe/ydHJUwYFd
+ WwuQ1MWiy6IesKvjL5rL9WjXUb9MwT9bpObYLGOKi1Qh
+ S: + or//EoAADZI=
+ C: DiAF5A4gA+oOIALuBkAAmw==
+ S: A001 OK Kerberos V4 authentication successful
+
+
+ S: * OK IMAP4 Server
+ C: A001 AUTHENTICATE KERBEROS_V4
+ S: + gcfgCA==
+ C: BAcAQU5EUkVXLkNNVS5FRFUAOCAsho84kLN3/IJmrMG+25a4DT
+ +nZImJjnTNHJUtxAA+o0KPKfHEcAFs9a3CL5Oebe/ydHJUwYFd
+ WwuQ1MWiy6IesKvjL5rL9WjXUb9MwT9bpObYLGOKi1Qh
+ S: A001 NO Kerberos V4 authentication failed
+
+7.2. GSSAPI mechanism
+
+ The mechanism name associated with all mechanisms employing the
+ GSSAPI [RFC 2078] is "GSSAPI".
+
+7.2.1 Client side of authentication protocol exchange
+
+ The client calls GSS_Init_sec_context, passing in 0 for
+ input_context_handle (initially) and a targ_name equal to output_name
+ from GSS_Import_Name called with input_name_type of
+ GSS_C_NT_HOSTBASED_SERVICE and input_name_string of
+ "service@hostname" where "service" is the service name specified in
+ the protocol's profile, and "hostname" is the fully qualified host
+ name of the server. The client then responds with the resulting
+ output_token. If GSS_Init_sec_context returns GSS_S_CONTINUE_NEEDED,
+
+
+
+Myers Standards Track [Page 9]
+
+RFC 2222 SASL October 1997
+
+
+ then the client should expect the server to issue a token in a
+ subsequent challenge. The client must pass the token to another call
+ to GSS_Init_sec_context, repeating the actions in this paragraph.
+
+ When GSS_Init_sec_context returns GSS_S_COMPLETE, the client takes
+ the following actions: If the last call to GSS_Init_sec_context
+ returned an output_token, then the client responds with the
+ output_token, otherwise the client responds with no data. The client
+ should then expect the server to issue a token in a subsequent
+ challenge. The client passes this token to GSS_Unwrap and interprets
+ the first octet of resulting cleartext as a bit-mask specifying the
+ security layers supported by the server and the second through fourth
+ octets as the maximum size output_message to send to the server. The
+ client then constructs data, with the first octet containing the
+ bit-mask specifying the selected security layer, the second through
+ fourth octets containing in network byte order the maximum size
+ output_message the client is able to receive, and the remaining
+ octets containing the authorization identity. The client passes the
+ data to GSS_Wrap with conf_flag set to FALSE, and responds with the
+ generated output_message. The client can then consider the server
+ authenticated.
+
+7.2.2 Server side of authentication protocol exchange
+
+ The server passes the initial client response to
+ GSS_Accept_sec_context as input_token, setting input_context_handle
+ to 0 (initially). If GSS_Accept_sec_context returns
+ GSS_S_CONTINUE_NEEDED, the server returns the generated output_token
+ to the client in challenge and passes the resulting response to
+ another call to GSS_Accept_sec_context, repeating the actions in this
+ paragraph.
+
+ When GSS_Accept_sec_context returns GSS_S_COMPLETE, the client takes
+ the following actions: If the last call to GSS_Accept_sec_context
+ returned an output_token, the server returns it to the client in a
+ challenge and expects a reply from the client with no data. Whether
+ or not an output_token was returned (and after receipt of any
+ response from the client to such an output_token), the server then
+ constructs 4 octets of data, with the first octet containing a bit-
+ mask specifying the security layers supported by the server and the
+ second through fourth octets containing in network byte order the
+ maximum size output_token the server is able to receive. The server
+ must then pass the plaintext to GSS_Wrap with conf_flag set to FALSE
+ and issue the generated output_message to the client in a challenge.
+ The server must then pass the resulting response to GSS_Unwrap and
+ interpret the first octet of resulting cleartext as the bit-mask for
+ the selected security layer, the second through fourth octets as the
+ maximum size output_message to send to the client, and the remaining
+
+
+
+Myers Standards Track [Page 10]
+
+RFC 2222 SASL October 1997
+
+
+ octets as the authorization identity. The server must verify that
+ the src_name is authorized to authenticate as the authorization
+ identity. After these verifications, the authentication process is
+ complete.
+
+7.2.3 Security layer
+
+ The security layers and their corresponding bit-masks are as follows:
+
+ 1 No security layer
+ 2 Integrity protection.
+ Sender calls GSS_Wrap with conf_flag set to FALSE
+ 4 Privacy protection.
+ Sender calls GSS_Wrap with conf_flag set to TRUE
+
+ Other bit-masks may be defined in the future; bits which are not
+ understood must be negotiated off.
+
+7.3. S/Key mechanism
+
+ The mechanism name associated with S/Key [RFC 1760] using the MD4
+ digest algorithm is "SKEY".
+
+ The client sends an initial response with the authorization identity.
+
+ The server then issues a challenge which contains the decimal
+ sequence number followed by a single space and the seed string for
+ the indicated authorization identity. The client responds with the
+ one-time-password, as either a 64-bit value in network byte order or
+ encoded in the "six English words" format.
+
+ The server must verify the one-time-password. After this
+ verification, the authentication process is complete.
+
+ S/Key authentication does not provide for any security layers.
+
+ EXAMPLE: The following are two S/Key login scenarios in the IMAP4
+ protocol.
+
+ S: * OK IMAP4 Server
+ C: A001 AUTHENTICATE SKEY
+ S: +
+ C: bW9yZ2Fu
+ S: + OTUgUWE1ODMwOA==
+ C: Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA==
+ S: A001 OK S/Key authentication successful
+
+
+
+
+
+Myers Standards Track [Page 11]
+
+RFC 2222 SASL October 1997
+
+
+ S: * OK IMAP4 Server
+ C: A001 AUTHENTICATE SKEY
+ S: +
+ C: c21pdGg=
+ S: + OTUgUWE1ODMwOA==
+ C: BsAY3g4gBNo=
+ S: A001 NO S/Key authentication failed
+
+ The following is an S/Key login scenario in an IMAP4-like protocol
+ which has an optional "initial response" argument to the AUTHENTICATE
+ command.
+
+ S: * OK IMAP4-Like Server
+ C: A001 AUTHENTICATE SKEY bW9yZ2Fu
+ S: + OTUgUWE1ODMwOA==
+ C: Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA==
+ S: A001 OK S/Key authentication successful
+
+7.4. External mechanism
+
+ The mechanism name associated with external authentication is
+ "EXTERNAL".
+
+ The client sends an initial response with the authorization identity.
+
+ The server uses information, external to SASL, to determine whether
+ the client is authorized to authenticate as the authorization
+ identity. If the client is so authorized, the server indicates
+ successful completion of the authentication exchange; otherwise the
+ server indicates failure.
+
+ The system providing this external information may be, for example,
+ IPsec or TLS.
+
+ If the client sends the empty string as the authorization identity
+ (thus requesting the authorization identity be derived from the
+ client's authentication credentials), the authorization identity is
+ to be derived from authentication credentials which exist in the
+ system which is providing the external authentication.
+
+
+
+
+
+
+
+
+
+
+
+
+Myers Standards Track [Page 12]
+
+RFC 2222 SASL October 1997
+
+
+8. References
+
+ [RFC 2060] Crispin, M., "Internet Message Access Protocol - Version
+ 4rev1", RFC 2060, December 1996.
+
+ [RFC 2078] Linn, J., "Generic Security Service Application Program
+ Interface, Version 2", RFC 2078, January 1997.
+
+ [RFC 2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", RFC 2119, March 1997.
+
+ [RFC 2223] Postel, J., and J. Reynolds, "Instructions to RFC
+ Authors", RFC 2223, October 1997.
+
+ [RFC 1760] Haller, N., "The S/Key One-Time Password System", RFC
+ 1760, February 1995.
+
+ [RFC 1700] Reynolds, J., and J. Postel, "Assigned Numbers", STD 2,
+ RFC 1700, October 1994.
+
+9. Security Considerations
+
+ Security issues are discussed throughout this memo.
+
+ The mechanisms that support integrity protection are designed such
+ that the negotiation of the security layer and authorization identity
+ is integrity protected. When the client selects a security layer
+ with at least integrity protection, this protects against an active
+ attacker hijacking the connection and modifying the authentication
+ exchange to negotiate a plaintext connection.
+
+ When a server or client supports multiple authentication mechanisms,
+ each of which has a different security strength, it is possible for
+ an active attacker to cause a party to use the least secure mechanism
+ supported. To protect against this sort of attack, a client or
+ server which supports mechanisms of different strengths should have a
+ configurable minimum strength that it will use. It is not sufficient
+ for this minimum strength check to only be on the server, since an
+ active attacker can change which mechanisms the client sees as being
+ supported, causing the client to send authentication credentials for
+ its weakest supported mechanism.
+
+
+
+
+
+
+
+
+
+
+Myers Standards Track [Page 13]
+
+RFC 2222 SASL October 1997
+
+
+ The client's selection of a SASL mechanism is done in the clear and
+ may be modified by an active attacker. It is important for any new
+ SASL mechanisms to be designed such that an active attacker cannot
+ obtain an authentication with weaker security properties by modifying
+ the SASL mechanism name and/or the challenges and responses.
+
+ Any protocol interactions prior to authentication are performed in
+ the clear and may be modified by an active attacker. In the case
+ where a client selects integrity protection, it is important that any
+ security-sensitive protocol negotiations be performed after
+ authentication is complete. Protocols should be designed such that
+ negotiations performed prior to authentication should be either
+ ignored or revalidated once authentication is complete.
+
+10. Author's Address
+
+ John G. Myers
+ Netscape Communications
+ 501 E. Middlefield Road
+ Mail Stop MV-029
+ Mountain View, CA 94043-4042
+
+ EMail: jgmyers@netscape.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Myers Standards Track [Page 14]
+
+RFC 2222 SASL October 1997
+
+
+Appendix A. Relation of SASL to Transport Security
+
+ Questions have been raised about the relationship between SASL and
+ various services (such as IPsec and TLS) which provide a secured
+ connection.
+
+ Two of the key features of SASL are:
+
+ 1. The separation of the authorization identity from the identity in
+ the client's credentials. This permits agents such as proxy
+ servers to authenticate using their own credentials, yet request
+ the access privileges of the identity for which they are proxying.
+
+ 2. Upon successful completion of an authentication exchange, the
+ server knows the authorization identity the client wishes to use.
+ This allows servers to move to a "user is authenticated" state in
+ the protocol.
+
+ These features are extremely important to some application protocols,
+ yet Transport Security services do not always provide them. To
+ define SASL mechanisms based on these services would be a very messy
+ task, as the framing of these services would be redundant with the
+ framing of SASL and some method of providing these important SASL
+ features would have to be devised.
+
+ Sometimes it is desired to enable within an existing connection the
+ use of a security service which does not fit the SASL model. (TLS is
+ an example of such a service.) This can be done by adding a command,
+ for example "STARTTLS", to the protocol. Such a command is outside
+ the scope of SASL, and should be different from the command which
+ starts a SASL authentication protocol exchange.
+
+ In certain situations, it is reasonable to use SASL underneath one of
+ these Transport Security services. The transport service would
+ secure the connection, either service would authenticate the client,
+ and SASL would negotiate the authorization identity. The SASL
+ negotiation would be what moves the protocol from "unauthenticated"
+ to "authenticated" state. The "EXTERNAL" SASL mechanism is
+ explicitly intended to handle the case where the transport service
+ secures the connection and authenticates the client and SASL
+ negotiates the authorization identity.
+
+ When using SASL underneath a sufficiently strong Transport Security
+ service, a SASL security layer would most likely be redundant. The
+ client and server would thus probably want to negotiate off the use
+ of a SASL security layer.
+
+
+
+
+
+Myers Standards Track [Page 15]
+
+RFC 2222 SASL October 1997
+
+
+Full Copyright Statement
+
+ Copyright (C) The Internet Society (1997). All Rights Reserved.
+
+ This document and translations of it may be copied and furnished to
+ others, and derivative works that comment on or otherwise explain it
+ or assist in its implmentation may be prepared, copied, published
+ andand distributed, in whole or in part, without restriction of any
+ kind, provided that the above copyright notice and this paragraph are
+ included on all such copies and derivative works. However, this
+ document itself may not be modified in any way, such as by removing
+ the copyright notice or references to the Internet Society or other
+ Internet organizations, except as needed for the purpose of
+ developing Internet standards in which case the procedures for
+ copyrights defined in the Internet Standards process must be
+ followed, or as required to translate it into languages other than
+ English.
+
+ The limited permissions granted above are perpetual and will not be
+ revoked by the Internet Society or its successors or assigns.
+
+ This document and the information contained herein is provided on an
+ "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
+ TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
+ BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
+ HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
+ MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Myers Standards Track [Page 16]
+
diff --git a/doc/rfcs/rfc2444.txt b/doc/rfcs/rfc2444.txt
new file mode 100644
index 0000000..80a65a2
--- /dev/null
+++ b/doc/rfcs/rfc2444.txt
@@ -0,0 +1,395 @@
+
+
+
+
+
+
+Network Working Group C. Newman
+Request for Comments: 2444 Innosoft
+Updates: 2222 October 1998
+Category: Standards Track
+
+
+ The One-Time-Password SASL Mechanism
+
+Status of this Memo
+
+ This document specifies an Internet standards track protocol for the
+ Internet community, and requests discussion and suggestions for
+ improvements. Please refer to the current edition of the "Internet
+ Official Protocol Standards" (STD 1) for the standardization state
+ and status of this protocol. Distribution of this memo is unlimited.
+
+Copyright Notice
+
+ Copyright (C) The Internet Society (1998). All Rights Reserved.
+
+Abstract
+
+ OTP [OTP] provides a useful authentication mechanism for situations
+ where there is limited client or server trust. Currently, OTP is
+ added to protocols in an ad-hoc fashion with heuristic parsing. This
+ specification defines an OTP SASL [SASL] mechanism so it can be
+ easily and formally integrated into many application protocols.
+
+1. How to Read This Document
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT",
+ "RECOMMENDED" and "MAY" in this document are to be interpreted as
+ defined in "Key words for use in RFCs to Indicate Requirement Levels"
+ [KEYWORDS].
+
+ This memo assumes the reader is familiar with OTP [OTP], OTP extended
+ responses [OTP-EXT] and SASL [SASL].
+
+2. Intended Use
+
+ The OTP SASL mechanism replaces the SKEY SASL mechanism [SASL]. OTP
+ is a good choice for usage scenarios where the client is untrusted
+ (e.g., a kiosk client), as a one-time password will only give the
+ client a single opportunity to act on behalf of the user. OTP is
+ also a good choice for situations where interactive logins are
+ permitted to the server, as a compromised OTP authentication database
+ is only subject to dictionary attacks, unlike authentication
+ databases for other simple mechanisms such as CRAM-MD5 [CRAM-MD5].
+
+
+
+Newman Standards Track [Page 1]
+
+RFC 2444 OTP SASL Mechanism October 1998
+
+
+ It is important to note that each use of the OTP mechanism causes the
+ authentication database entry for a user to be updated.
+
+ This SASL mechanism provides a formal way to integrate OTP into
+ SASL-enabled protocols including IMAP [IMAP4], ACAP [ACAP], POP3
+ [POP-AUTH] and LDAPv3 [LDAPv3].
+
+3. Profiling OTP for SASL
+
+ OTP [OTP] and OTP extended responses [OTP-EXT] offer a number of
+ options. However, for authentication to succeed, the client and
+ server need compatible option sets. This specification defines a
+ single SASL mechanism: OTP. The following rules apply to this
+ mechanism:
+
+ o The extended response syntax MUST be used.
+
+ o Servers MUST support the following four OTP extended responses:
+ "hex", "word", "init-hex" and "init-word". Servers MUST support
+ the "word" and "init-word" responses for the standard dictionary
+ and SHOULD support alternate dictionaries. Servers MUST NOT
+ require use of any additional OTP extensions or options.
+
+ o Clients SHOULD support display of the OTP challenge to the user
+ and entry of an OTP in multi-word format. Clients MAY also
+ support direct entry of the pass phrase and compute the "hex" or
+ "word" response.
+
+ o Clients MUST indicate when authentication fails due to the
+ sequence number getting too low and SHOULD offer the user the
+ option to reset the sequence using the "init-hex" or "init-word"
+ response.
+
+ Support for the MD5 algorithm is REQUIRED, and support for the SHA1
+ algorithm is RECOMMENDED.
+
+4. OTP Authentication Mechanism
+
+ The mechanism does not provide any security layer.
+
+ The client begins by sending a message to the server containing the
+ following two pieces of information.
+
+ (1) An authorization identity. When the empty string is used, this
+ defaults to the authentication identity. This is used by system
+ administrators or proxy servers to login with a different user
+ identity. This field may be up to 255 octets and is terminated by a
+ NUL (0) octet. US-ASCII printable characters are preferred, although
+
+
+
+Newman Standards Track [Page 2]
+
+RFC 2444 OTP SASL Mechanism October 1998
+
+
+ UTF-8 [UTF-8] printable characters are permitted to support
+ international names. Use of character sets other than US-ASCII and
+ UTF-8 is forbidden.
+
+ (2) An authentication identity. The identity whose pass phrase will
+ be used. This field may be up to 255 octets. US-ASCII printable
+ characters are preferred, although UTF-8 [UTF-8] printable characters
+ are permitted to support international names. Use of character sets
+ other than US-ASCII and UTF-8 is forbidden.
+
+ The server responds by sending a message containing the OTP challenge
+ as described in OTP [OTP] and OTP extended responses [OTP-EXT].
+
+ If a client sees an unknown hash algorithm name it will not be able
+ to process a pass phrase input by the user. In this situation the
+ client MAY prompt for the six-word format, issue the cancel sequence
+ as specified by the SASL profile for the protocol in use and try a
+ different SASL mechanism, or close the connection and refuse to
+ authenticate. As a result of this behavior, a server is restricted
+ to one OTP hash algorithm per user.
+
+ On success, the client generates an extended response in the "hex",
+ "word", "init-hex" or "init-word" format. The client is not required
+ to terminate the response with a space or a newline and SHOULD NOT
+ include unnecessary whitespace.
+
+ Servers MUST tolerate input of arbitrary length, but MAY fail the
+ authentication if the length of client input exceeds reasonable size.
+
+5. Examples
+
+ In these example, "C:" represents lines sent from the client to the
+ server and "S:" represents lines sent from the server to the client.
+ The user name is "tim" and no authorization identity is provided.
+ The "<NUL>" below represents an ASCII NUL octet.
+
+ The following is an example of the OTP mechanism using the ACAP
+ [ACAP] profile of SASL. The pass phrase used in this example is:
+ This is a test.
+
+ C: a001 AUTHENTICATE "OTP" {4}
+ C: <NUL>tim
+ S: + "otp-md5 499 ke1234 ext"
+ C: "hex:5bf075d9959d036f"
+ S: a001 OK "AUTHENTICATE completed"
+
+
+
+
+
+
+Newman Standards Track [Page 3]
+
+RFC 2444 OTP SASL Mechanism October 1998
+
+
+ Here is the same example using the six-words response:
+
+ C: a001 AUTHENTICATE "OTP" {4}
+ C: <NUL>tim
+ S: + "otp-md5 499 ke1234 ext"
+ C: "word:BOND FOGY DRAB NE RISE MART"
+ S: a001 OK "AUTHENTICATE completed"
+
+ Here is the same example using the OTP-SHA1 mechanism:
+
+ C: a001 AUTHENTICATE "OTP" {4}
+ C: <NUL>tim
+ S: + "otp-sha1 499 ke1234 ext"
+ C: "hex:c90fc02cc488df5e"
+ S: a001 OK "AUTHENTICATE completed"
+
+ Here is the same example with the init-hex extended response
+
+ C: a001 AUTHENTICATE "OTP" {4}
+ C: <NUL>tim
+ S: + "otp-md5 499 ke1234 ext"
+ C: "init-hex:5bf075d9959d036f:md5 499 ke1235:3712dcb4aa5316c1"
+ S: a001 OK "OTP sequence reset, authentication complete"
+
+ The following is an example of the OTP mechanism using the IMAP
+ [IMAP4] profile of SASL. The pass phrase used in this example is:
+ this is a test
+
+ C: a001 AUTHENTICATE OTP
+ S: +
+ C: AHRpbQ==
+ S: + b3RwLW1kNSAxMjMga2UxMjM0IGV4dA==
+ C: aGV4OjExZDRjMTQ3ZTIyN2MxZjE=
+ S: a001 OK AUTHENTICATE completed
+
+ Note that the lack of an initial client response and the base64
+ encoding are characteristics of the IMAP profile of SASL. The server
+ challenge is "otp-md5 123 ke1234 ext" and the client response is
+ "hex:11d4c147e227c1f1".
+
+6. Security Considerations
+
+ This specification introduces no security considerations beyond those
+ those described in SASL [SASL], OTP [OTP] and OTP extended responses
+ [OTP-EXT]. A brief summary of these considerations follows:
+
+ This mechanism does not provide session privacy, server
+ authentication or protection from active attacks.
+
+
+
+Newman Standards Track [Page 4]
+
+RFC 2444 OTP SASL Mechanism October 1998
+
+
+ This mechanism is subject to passive dictionary attacks. The
+ severity of this attack can be reduced by choosing pass phrases well.
+
+ The server authentication database necessary for use with OTP need
+ not be plaintext-equivalent.
+
+ Server implementations MUST protect against the race attack [OTP].
+
+7. Multinational Considerations
+
+ As remote access is a crucial service, users are encouraged to
+ restrict user names and pass phrases to the US-ASCII character set.
+ However, if characters outside the US-ASCII chracter set are used in
+ user names and pass phrases, then they are interpreted according to
+ UTF-8 [UTF-8].
+
+ Server support for alternate dictionaries is strongly RECOMMENDED to
+ permit use of the six-word format with non-English words.
+
+8. IANA Considerations
+
+ Here is the registration template for the OTP SASL mechanism:
+
+ SASL mechanism name: OTP
+ Security Considerations: See section 6 of this memo
+ Published specification: this memo
+ Person & email address to contact for futher information:
+ see author's address section below
+ Intended usage: COMMON
+ Author/Change controller: see author's address section below
+
+ This memo also amends the SKEY SASL mechanism registration [SASL] by
+ changing its intended usage to OBSOLETE.
+
+9. References
+
+ [ACAP] Newman, C. and J. Myers, "ACAP -- Application
+ Configuration Access Protocol", RFC 2244, November 1997.
+
+ [CRAM-MD5] Klensin, J., Catoe, R. and P. Krumviede, "IMAP/POP
+ AUTHorize Extension for Simple Challenge/Response", RFC
+ 2195, September 1997.
+
+ [IMAP4] Crispin, M., "Internet Message Access Protocol - Version
+ 4rev1", RFC 2060, December 1996.
+
+ [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+
+
+Newman Standards Track [Page 5]
+
+RFC 2444 OTP SASL Mechanism October 1998
+
+
+ [LDAPv3] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory
+ Access Protocol (v3)", RFC 2251, December 1997.
+
+ [MD5] Rivest, R., "The MD5 Message Digest Algorithm", RFC 1321,
+ April 1992.
+
+ [OTP] Haller, N., Metz, C., Nesser, P. and M. Straw, "A One-Time
+ Password System", RFC 2289, February 1998.
+
+ [OTP-EXT] Metz, C., "OTP Extended Responses", RFC 2243, November
+ 1997.
+
+ [POP-AUTH] Myers, J., "POP3 AUTHentication command", RFC 1734,
+ December 1994.
+
+ [SASL] Myers, J., "Simple Authentication and Security Layer
+ (SASL)", RFC 2222, October 1997.
+
+ [UTF-8] Yergeau, F., "UTF-8, a transformation format of ISO
+ 10646", RFC 2279, January 1998.
+
+10. Author's Address
+
+ Chris Newman
+ Innosoft International, Inc.
+ 1050 Lakes Drive
+ West Covina, CA 91790 USA
+
+ EMail: chris.newman@innosoft.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Newman Standards Track [Page 6]
+
+RFC 2444 OTP SASL Mechanism October 1998
+
+
+11. Full Copyright Statement
+
+ Copyright (C) The Internet Society (1998). All Rights Reserved.
+
+ This document and translations of it may be copied and furnished to
+ others, and derivative works that comment on or otherwise explain it
+ or assist in its implementation may be prepared, copied, published
+ and distributed, in whole or in part, without restriction of any
+ kind, provided that the above copyright notice and this paragraph are
+ included on all such copies and derivative works. However, this
+ document itself may not be modified in any way, such as by removing
+ the copyright notice or references to the Internet Society or other
+ Internet organizations, except as needed for the purpose of
+ developing Internet standards in which case the procedures for
+ copyrights defined in the Internet Standards process must be
+ followed, or as required to translate it into languages other than
+ English.
+
+ The limited permissions granted above are perpetual and will not be
+ revoked by the Internet Society or its successors or assigns.
+
+ This document and the information contained herein is provided on an
+ "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
+ TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
+ BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
+ HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
+ MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Newman Standards Track [Page 7]
+
diff --git a/doc/rfcs/rfc2595.txt b/doc/rfcs/rfc2595.txt
new file mode 100644
index 0000000..66897cd
--- /dev/null
+++ b/doc/rfcs/rfc2595.txt
@@ -0,0 +1,843 @@
+
+
+
+
+
+
+Network Working Group C. Newman
+Request for Comments: 2595 Innosoft
+Category: Standards Track June 1999
+
+
+ Using TLS with IMAP, POP3 and ACAP
+
+
+Status of this Memo
+
+ This document specifies an Internet standards track protocol for the
+ Internet community, and requests discussion and suggestions for
+ improvements. Please refer to the current edition of the "Internet
+ Official Protocol Standards" (STD 1) for the standardization state
+ and status of this protocol. Distribution of this memo is unlimited.
+
+Copyright Notice
+
+ Copyright (C) The Internet Society (1999). All Rights Reserved.
+
+1. Motivation
+
+ The TLS protocol (formerly known as SSL) provides a way to secure an
+ application protocol from tampering and eavesdropping. The option of
+ using such security is desirable for IMAP, POP and ACAP due to common
+ connection eavesdropping and hijacking attacks [AUTH]. Although
+ advanced SASL authentication mechanisms can provide a lightweight
+ version of this service, TLS is complimentary to simple
+ authentication-only SASL mechanisms or deployed clear-text password
+ login commands.
+
+ Many sites have a high investment in authentication infrastructure
+ (e.g., a large database of a one-way-function applied to user
+ passwords), so a privacy layer which is not tightly bound to user
+ authentication can protect against network eavesdropping attacks
+ without requiring a new authentication infrastructure and/or forcing
+ all users to change their password. Recognizing that such sites will
+ desire simple password authentication in combination with TLS
+ encryption, this specification defines the PLAIN SASL mechanism for
+ use with protocols which lack a simple password authentication
+ command such as ACAP and SMTP. (Note there is a separate RFC for the
+ STARTTLS command in SMTP [SMTPTLS].)
+
+ There is a strong desire in the IETF to eliminate the transmission of
+ clear-text passwords over unencrypted channels. While SASL can be
+ used for this purpose, TLS provides an additional tool with different
+ deployability characteristics. A server supporting both TLS with
+
+
+
+
+Newman Standards Track [Page 1]
+
+RFC 2595 Using TLS with IMAP, POP3 and ACAP June 1999
+
+
+ simple passwords and a challenge/response SASL mechanism is likely to
+ interoperate with a wide variety of clients without resorting to
+ unencrypted clear-text passwords.
+
+ The STARTTLS command rectifies a number of the problems with using a
+ separate port for a "secure" protocol variant. Some of these are
+ mentioned in section 7.
+
+1.1. Conventions Used in this Document
+
+ The key words "REQUIRED", "MUST", "MUST NOT", "SHOULD", "SHOULD NOT",
+ "MAY", and "OPTIONAL" in this document are to be interpreted as
+ described in "Key words for use in RFCs to Indicate Requirement
+ Levels" [KEYWORDS].
+
+ Terms related to authentication are defined in "On Internet
+ Authentication" [AUTH].
+
+ Formal syntax is defined using ABNF [ABNF].
+
+ In examples, "C:" and "S:" indicate lines sent by the client and
+ server respectively.
+
+2. Basic Interoperability and Security Requirements
+
+ The following requirements apply to all implementations of the
+ STARTTLS extension for IMAP, POP3 and ACAP.
+
+2.1. Cipher Suite Requirements
+
+ Implementation of the TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA [TLS] cipher
+ suite is REQUIRED. This is important as it assures that any two
+ compliant implementations can be configured to interoperate.
+
+ All other cipher suites are OPTIONAL.
+
+2.2. Privacy Operational Mode Security Requirements
+
+ Both clients and servers SHOULD have a privacy operational mode which
+ refuses authentication unless successful activation of an encryption
+ layer (such as that provided by TLS) occurs prior to or at the time
+ of authentication and which will terminate the connection if that
+ encryption layer is deactivated. Implementations are encouraged to
+ have flexability with respect to the minimal encryption strength or
+ cipher suites permitted. A minimalist approach to this
+ recommendation would be an operational mode where the
+ TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA cipher suite is mandatory prior to
+ permitting authentication.
+
+
+
+Newman Standards Track [Page 2]
+
+RFC 2595 Using TLS with IMAP, POP3 and ACAP June 1999
+
+
+ Clients MAY have an operational mode which uses encryption only when
+ it is advertised by the server, but authentication continues
+ regardless. For backwards compatibility, servers SHOULD have an
+ operational mode where only the authentication mechanisms required by
+ the relevant base protocol specification are needed to successfully
+ authenticate.
+
+2.3. Clear-Text Password Requirements
+
+ Clients and servers which implement STARTTLS MUST be configurable to
+ refuse all clear-text login commands or mechanisms (including both
+ standards-track and nonstandard mechanisms) unless an encryption
+ layer of adequate strength is active. Servers which allow
+ unencrypted clear-text logins SHOULD be configurable to refuse
+ clear-text logins both for the entire server, and on a per-user
+ basis.
+
+2.4. Server Identity Check
+
+ During the TLS negotiation, the client MUST check its understanding
+ of the server hostname against the server's identity as presented in
+ the server Certificate message, in order to prevent man-in-the-middle
+ attacks. Matching is performed according to these rules:
+
+ - The client MUST use the server hostname it used to open the
+ connection as the value to compare against the server name as
+ expressed in the server certificate. The client MUST NOT use any
+ form of the server hostname derived from an insecure remote source
+ (e.g., insecure DNS lookup). CNAME canonicalization is not done.
+
+ - If a subjectAltName extension of type dNSName is present in the
+ certificate, it SHOULD be used as the source of the server's
+ identity.
+
+ - Matching is case-insensitive.
+
+ - A "*" wildcard character MAY be used as the left-most name
+ component in the certificate. For example, *.example.com would
+ match a.example.com, foo.example.com, etc. but would not match
+ example.com.
+
+ - If the certificate contains multiple names (e.g. more than one
+ dNSName field), then a match with any one of the fields is
+ considered acceptable.
+
+ If the match fails, the client SHOULD either ask for explicit user
+ confirmation, or terminate the connection and indicate the server's
+ identity is suspect.
+
+
+
+Newman Standards Track [Page 3]
+
+RFC 2595 Using TLS with IMAP, POP3 and ACAP June 1999
+
+
+2.5. TLS Security Policy Check
+
+ Both the client and server MUST check the result of the STARTTLS
+ command and subsequent TLS negotiation to see whether acceptable
+ authentication or privacy was achieved. Ignoring this step
+ completely invalidates using TLS for security. The decision about
+ whether acceptable authentication or privacy was achieved is made
+ locally, is implementation-dependent, and is beyond the scope of this
+ document.
+
+3. IMAP STARTTLS extension
+
+ When the TLS extension is present in IMAP, "STARTTLS" is listed as a
+ capability in response to the CAPABILITY command. This extension
+ adds a single command, "STARTTLS" to the IMAP protocol which is used
+ to begin a TLS negotiation.
+
+3.1. STARTTLS Command
+
+ Arguments: none
+
+ Responses: no specific responses for this command
+
+ Result: OK - begin TLS negotiation
+ BAD - command unknown or arguments invalid
+
+ A TLS negotiation begins immediately after the CRLF at the end of
+ the tagged OK response from the server. Once a client issues a
+ STARTTLS command, it MUST NOT issue further commands until a
+ server response is seen and the TLS negotiation is complete.
+
+ The STARTTLS command is only valid in non-authenticated state.
+ The server remains in non-authenticated state, even if client
+ credentials are supplied during the TLS negotiation. The SASL
+ [SASL] EXTERNAL mechanism MAY be used to authenticate once TLS
+ client credentials are successfully exchanged, but servers
+ supporting the STARTTLS command are not required to support the
+ EXTERNAL mechanism.
+
+ Once TLS has been started, the client MUST discard cached
+ information about server capabilities and SHOULD re-issue the
+ CAPABILITY command. This is necessary to protect against
+ man-in-the-middle attacks which alter the capabilities list prior
+ to STARTTLS. The server MAY advertise different capabilities
+ after STARTTLS.
+
+ The formal syntax for IMAP is amended as follows:
+
+
+
+
+Newman Standards Track [Page 4]
+
+RFC 2595 Using TLS with IMAP, POP3 and ACAP June 1999
+
+
+ command_any =/ "STARTTLS"
+
+ Example: C: a001 CAPABILITY
+ S: * CAPABILITY IMAP4rev1 STARTTLS LOGINDISABLED
+ S: a001 OK CAPABILITY completed
+ C: a002 STARTTLS
+ S: a002 OK Begin TLS negotiation now
+ <TLS negotiation, further commands are under TLS layer>
+ C: a003 CAPABILITY
+ S: * CAPABILITY IMAP4rev1 AUTH=EXTERNAL
+ S: a003 OK CAPABILITY completed
+ C: a004 LOGIN joe password
+ S: a004 OK LOGIN completed
+
+3.2. IMAP LOGINDISABLED capability
+
+ The current IMAP protocol specification (RFC 2060) requires the
+ implementation of the LOGIN command which uses clear-text passwords.
+ Many sites may choose to disable this command unless encryption is
+ active for security reasons. An IMAP server MAY advertise that the
+ LOGIN command is disabled by including the LOGINDISABLED capability
+ in the capability response. Such a server will respond with a tagged
+ "NO" response to any attempt to use the LOGIN command.
+
+ An IMAP server which implements STARTTLS MUST implement support for
+ the LOGINDISABLED capability on unencrypted connections.
+
+ An IMAP client which complies with this specification MUST NOT issue
+ the LOGIN command if this capability is present.
+
+ This capability is useful to prevent clients compliant with this
+ specification from sending an unencrypted password in an environment
+ subject to passive attacks. It has no impact on an environment
+ subject to active attacks as a man-in-the-middle attacker can remove
+ this capability. Therefore this does not relieve clients of the need
+ to follow the privacy mode recommendation in section 2.2.
+
+ Servers advertising this capability will fail to interoperate with
+ many existing compliant IMAP clients and will be unable to prevent
+ those clients from disclosing the user's password.
+
+4. POP3 STARTTLS extension
+
+ The POP3 STARTTLS extension adds the STLS command to POP3 servers.
+ If this is implemented, the POP3 extension mechanism [POP3EXT] MUST
+ also be implemented to avoid the need for client probing of multiple
+ commands. The capability name "STLS" indicates this command is
+ present and permitted in the current state.
+
+
+
+Newman Standards Track [Page 5]
+
+RFC 2595 Using TLS with IMAP, POP3 and ACAP June 1999
+
+
+ STLS
+
+ Arguments: none
+
+ Restrictions:
+ Only permitted in AUTHORIZATION state.
+
+ Discussion:
+ A TLS negotiation begins immediately after the CRLF at the
+ end of the +OK response from the server. A -ERR response
+ MAY result if a security layer is already active. Once a
+ client issues a STLS command, it MUST NOT issue further
+ commands until a server response is seen and the TLS
+ negotiation is complete.
+
+ The STLS command is only permitted in AUTHORIZATION state
+ and the server remains in AUTHORIZATION state, even if
+ client credentials are supplied during the TLS negotiation.
+ The AUTH command [POP-AUTH] with the EXTERNAL mechanism
+ [SASL] MAY be used to authenticate once TLS client
+ credentials are successfully exchanged, but servers
+ supporting the STLS command are not required to support the
+ EXTERNAL mechanism.
+
+ Once TLS has been started, the client MUST discard cached
+ information about server capabilities and SHOULD re-issue
+ the CAPA command. This is necessary to protect against
+ man-in-the-middle attacks which alter the capabilities list
+ prior to STLS. The server MAY advertise different
+ capabilities after STLS.
+
+ Possible Responses:
+ +OK -ERR
+
+ Examples:
+ C: STLS
+ S: +OK Begin TLS negotiation
+ <TLS negotiation, further commands are under TLS layer>
+ ...
+ C: STLS
+ S: -ERR Command not permitted when TLS active
+
+
+
+
+
+
+
+
+
+
+Newman Standards Track [Page 6]
+
+RFC 2595 Using TLS with IMAP, POP3 and ACAP June 1999
+
+
+5. ACAP STARTTLS extension
+
+ When the TLS extension is present in ACAP, "STARTTLS" is listed as a
+ capability in the ACAP greeting. No arguments to this capability are
+ defined at this time. This extension adds a single command,
+ "STARTTLS" to the ACAP protocol which is used to begin a TLS
+ negotiation.
+
+5.1. STARTTLS Command
+
+ Arguments: none
+
+ Responses: no specific responses for this command
+
+ Result: OK - begin TLS negotiation
+ BAD - command unknown or arguments invalid
+
+ A TLS negotiation begins immediately after the CRLF at the end of
+ the tagged OK response from the server. Once a client issues a
+ STARTTLS command, it MUST NOT issue further commands until a
+ server response is seen and the TLS negotiation is complete.
+
+ The STARTTLS command is only valid in non-authenticated state.
+ The server remains in non-authenticated state, even if client
+ credentials are supplied during the TLS negotiation. The SASL
+ [SASL] EXTERNAL mechanism MAY be used to authenticate once TLS
+ client credentials are successfully exchanged, but servers
+ supporting the STARTTLS command are not required to support the
+ EXTERNAL mechanism.
+
+ After the TLS layer is established, the server MUST re-issue an
+ untagged ACAP greeting. This is necessary to protect against
+ man-in-the-middle attacks which alter the capabilities list prior
+ to STARTTLS. The client MUST discard cached capability
+ information and replace it with the information from the new ACAP
+ greeting. The server MAY advertise different capabilities after
+ STARTTLS.
+
+ The formal syntax for ACAP is amended as follows:
+
+ command_any =/ "STARTTLS"
+
+ Example: S: * ACAP (SASL "CRAM-MD5") (STARTTLS)
+ C: a002 STARTTLS
+ S: a002 OK "Begin TLS negotiation now"
+ <TLS negotiation, further commands are under TLS layer>
+ S: * ACAP (SASL "CRAM-MD5" "PLAIN" "EXTERNAL")
+
+
+
+
+Newman Standards Track [Page 7]
+
+RFC 2595 Using TLS with IMAP, POP3 and ACAP June 1999
+
+
+6. PLAIN SASL mechanism
+
+ Clear-text passwords are simple, interoperate with almost all
+ existing operating system authentication databases, and are useful
+ for a smooth transition to a more secure password-based
+ authentication mechanism. The drawback is that they are unacceptable
+ for use over an unencrypted network connection.
+
+ This defines the "PLAIN" SASL mechanism for use with ACAP and other
+ protocols with no clear-text login command. The PLAIN SASL mechanism
+ MUST NOT be advertised or used unless a strong encryption layer (such
+ as the provided by TLS) is active or backwards compatibility dictates
+ otherwise.
+
+ The mechanism consists of a single message from the client to the
+ server. The client sends the authorization identity (identity to
+ login as), followed by a US-ASCII NUL character, followed by the
+ authentication identity (identity whose password will be used),
+ followed by a US-ASCII NUL character, followed by the clear-text
+ password. The client may leave the authorization identity empty to
+ indicate that it is the same as the authentication identity.
+
+ The server will verify the authentication identity and password with
+ the system authentication database and verify that the authentication
+ credentials permit the client to login as the authorization identity.
+ If both steps succeed, the user is logged in.
+
+ The server MAY also use the password to initialize any new
+ authentication database, such as one suitable for CRAM-MD5
+ [CRAM-MD5].
+
+ Non-US-ASCII characters are permitted as long as they are represented
+ in UTF-8 [UTF-8]. Use of non-visible characters or characters which
+ a user may be unable to enter on some keyboards is discouraged.
+
+ The formal grammar for the client message using Augmented BNF [ABNF]
+ follows.
+
+ message = [authorize-id] NUL authenticate-id NUL password
+ authenticate-id = 1*UTF8-SAFE ; MUST accept up to 255 octets
+ authorize-id = 1*UTF8-SAFE ; MUST accept up to 255 octets
+ password = 1*UTF8-SAFE ; MUST accept up to 255 octets
+ NUL = %x00
+ UTF8-SAFE = %x01-09 / %x0B-0C / %x0E-7F / UTF8-2 /
+ UTF8-3 / UTF8-4 / UTF8-5 / UTF8-6
+ UTF8-1 = %x80-BF
+ UTF8-2 = %xC0-DF UTF8-1
+ UTF8-3 = %xE0-EF 2UTF8-1
+
+
+
+Newman Standards Track [Page 8]
+
+RFC 2595 Using TLS with IMAP, POP3 and ACAP June 1999
+
+
+ UTF8-4 = %xF0-F7 3UTF8-1
+ UTF8-5 = %xF8-FB 4UTF8-1
+ UTF8-6 = %xFC-FD 5UTF8-1
+
+ Here is an example of how this might be used to initialize a CRAM-MD5
+ authentication database for ACAP:
+
+ Example: S: * ACAP (SASL "CRAM-MD5") (STARTTLS)
+ C: a001 AUTHENTICATE "CRAM-MD5"
+ S: + "<1896.697170952@postoffice.reston.mci.net>"
+ C: "tim b913a602c7eda7a495b4e6e7334d3890"
+ S: a001 NO (TRANSITION-NEEDED)
+ "Please change your password, or use TLS to login"
+ C: a002 STARTTLS
+ S: a002 OK "Begin TLS negotiation now"
+ <TLS negotiation, further commands are under TLS layer>
+ S: * ACAP (SASL "CRAM-MD5" "PLAIN" "EXTERNAL")
+ C: a003 AUTHENTICATE "PLAIN" {21+}
+ C: <NUL>tim<NUL>tanstaaftanstaaf
+ S: a003 OK CRAM-MD5 password initialized
+
+ Note: In this example, <NUL> represents a single ASCII NUL octet.
+
+7. imaps and pop3s ports
+
+ Separate "imaps" and "pop3s" ports were registered for use with SSL.
+ Use of these ports is discouraged in favor of the STARTTLS or STLS
+ commands.
+
+ A number of problems have been observed with separate ports for
+ "secure" variants of protocols. This is an attempt to enumerate some
+ of those problems.
+
+ - Separate ports lead to a separate URL scheme which intrudes into
+ the user interface in inappropriate ways. For example, many web
+ pages use language like "click here if your browser supports SSL."
+ This is a decision the browser is often more capable of making than
+ the user.
+
+ - Separate ports imply a model of either "secure" or "not secure."
+ This can be misleading in a number of ways. First, the "secure"
+ port may not in fact be acceptably secure as an export-crippled
+ cipher suite might be in use. This can mislead users into a false
+ sense of security. Second, the normal port might in fact be
+ secured by using a SASL mechanism which includes a security layer.
+ Thus the separate port distinction makes the complex topic of
+ security policy even more confusing. One common result of this
+ confusion is that firewall administrators are often misled into
+
+
+
+Newman Standards Track [Page 9]
+
+RFC 2595 Using TLS with IMAP, POP3 and ACAP June 1999
+
+
+ permitting the "secure" port and blocking the standard port. This
+ could be a poor choice given the common use of SSL with a 40-bit
+ key encryption layer and plain-text password authentication is less
+ secure than strong SASL mechanisms such as GSSAPI with Kerberos 5.
+
+ - Use of separate ports for SSL has caused clients to implement only
+ two security policies: use SSL or don't use SSL. The desirable
+ security policy "use TLS when available" would be cumbersome with
+ the separate port model, but is simple with STARTTLS.
+
+ - Port numbers are a limited resource. While they are not yet in
+ short supply, it is unwise to set a precedent that could double (or
+ worse) the speed of their consumption.
+
+
+8. IANA Considerations
+
+ This constitutes registration of the "STARTTLS" and "LOGINDISABLED"
+ IMAP capabilities as required by section 7.2.1 of RFC 2060 [IMAP].
+
+ The registration for the POP3 "STLS" capability follows:
+
+ CAPA tag: STLS
+ Arguments: none
+ Added commands: STLS
+ Standard commands affected: May enable USER/PASS as a side-effect.
+ CAPA command SHOULD be re-issued after successful completion.
+ Announced states/Valid states: AUTHORIZATION state only.
+ Specification reference: this memo
+
+ The registration for the ACAP "STARTTLS" capability follows:
+
+ Capability name: STARTTLS
+ Capability keyword: STARTTLS
+ Capability arguments: none
+ Published Specification(s): this memo
+ Person and email address for further information:
+ see author's address section below
+
+ The registration for the PLAIN SASL mechanism follows:
+
+ SASL mechanism name: PLAIN
+ Security Considerations: See section 9 of this memo
+ Published specification: this memo
+ Person & email address to contact for further information:
+ see author's address section below
+ Intended usage: COMMON
+ Author/Change controller: see author's address section below
+
+
+
+Newman Standards Track [Page 10]
+
+RFC 2595 Using TLS with IMAP, POP3 and ACAP June 1999
+
+
+9. Security Considerations
+
+ TLS only provides protection for data sent over a network connection.
+ Messages transferred over IMAP or POP3 are still available to server
+ administrators and usually subject to eavesdropping, tampering and
+ forgery when transmitted through SMTP or NNTP. TLS is no substitute
+ for an end-to-end message security mechanism using MIME security
+ multiparts [MIME-SEC].
+
+ A man-in-the-middle attacker can remove STARTTLS from the capability
+ list or generate a failure response to the STARTTLS command. In
+ order to detect such an attack, clients SHOULD warn the user when
+ session privacy is not active and/or be configurable to refuse to
+ proceed without an acceptable level of security.
+
+ A man-in-the-middle attacker can always cause a down-negotiation to
+ the weakest authentication mechanism or cipher suite available. For
+ this reason, implementations SHOULD be configurable to refuse weak
+ mechanisms or cipher suites.
+
+ Any protocol interactions prior to the TLS handshake are performed in
+ the clear and can be modified by a man-in-the-middle attacker. For
+ this reason, clients MUST discard cached information about server
+ capabilities advertised prior to the start of the TLS handshake.
+
+ Clients are encouraged to clearly indicate when the level of
+ encryption active is known to be vulnerable to attack using modern
+ hardware (such as encryption keys with 56 bits of entropy or less).
+
+ The LOGINDISABLED IMAP capability (discussed in section 3.2) only
+ reduces the potential for passive attacks, it provides no protection
+ against active attacks. The responsibility remains with the client
+ to avoid sending a password over a vulnerable channel.
+
+ The PLAIN mechanism relies on the TLS encryption layer for security.
+ When used without TLS, it is vulnerable to a common network
+ eavesdropping attack. Therefore PLAIN MUST NOT be advertised or used
+ unless a suitable TLS encryption layer is active or backwards
+ compatibility dictates otherwise.
+
+ When the PLAIN mechanism is used, the server gains the ability to
+ impersonate the user to all services with the same password
+ regardless of any encryption provided by TLS or other network privacy
+ mechanisms. While many other authentication mechanisms have similar
+ weaknesses, stronger SASL mechanisms such as Kerberos address this
+ issue. Clients are encouraged to have an operational mode where all
+ mechanisms which are likely to reveal the user's password to the
+ server are disabled.
+
+
+
+Newman Standards Track [Page 11]
+
+RFC 2595 Using TLS with IMAP, POP3 and ACAP June 1999
+
+
+ The security considerations for TLS apply to STARTTLS and the
+ security considerations for SASL apply to the PLAIN mechanism.
+ Additional security requirements are discussed in section 2.
+
+10. References
+
+ [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax
+ Specifications: ABNF", RFC 2234, November 1997.
+
+ [ACAP] Newman, C. and J. Myers, "ACAP -- Application
+ Configuration Access Protocol", RFC 2244, November 1997.
+
+ [AUTH] Haller, N. and R. Atkinson, "On Internet Authentication",
+ RFC 1704, October 1994.
+
+ [CRAM-MD5] Klensin, J., Catoe, R. and P. Krumviede, "IMAP/POP
+ AUTHorize Extension for Simple Challenge/Response", RFC
+ 2195, September 1997.
+
+ [IMAP] Crispin, M., "Internet Message Access Protocol - Version
+ 4rev1", RFC 2060, December 1996.
+
+ [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+ [MIME-SEC] Galvin, J., Murphy, S., Crocker, S. and N. Freed,
+ "Security Multiparts for MIME: Multipart/Signed and
+ Multipart/Encrypted", RFC 1847, October 1995.
+
+ [POP3] Myers, J. and M. Rose, "Post Office Protocol - Version 3",
+ STD 53, RFC 1939, May 1996.
+
+ [POP3EXT] Gellens, R., Newman, C. and L. Lundblade, "POP3 Extension
+ Mechanism", RFC 2449, November 1998.
+
+ [POP-AUTH] Myers, J., "POP3 AUTHentication command", RFC 1734,
+ December 1994.
+
+ [SASL] Myers, J., "Simple Authentication and Security Layer
+ (SASL)", RFC 2222, October 1997.
+
+ [SMTPTLS] Hoffman, P., "SMTP Service Extension for Secure SMTP over
+ TLS", RFC 2487, January 1999.
+
+ [TLS] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0",
+ RFC 2246, January 1999.
+
+
+
+
+
+Newman Standards Track [Page 12]
+
+RFC 2595 Using TLS with IMAP, POP3 and ACAP June 1999
+
+
+ [UTF-8] Yergeau, F., "UTF-8, a transformation format of ISO
+ 10646", RFC 2279, January 1998.
+
+
+11. Author's Address
+
+ Chris Newman
+ Innosoft International, Inc.
+ 1050 Lakes Drive
+ West Covina, CA 91790 USA
+
+ EMail: chris.newman@innosoft.com
+
+
+A. Appendix -- Compliance Checklist
+
+ An implementation is not compliant if it fails to satisfy one or more
+ of the MUST requirements for the protocols it implements. An
+ implementation that satisfies all the MUST and all the SHOULD
+ requirements for its protocols is said to be "unconditionally
+ compliant"; one that satisfies all the MUST requirements but not all
+ the SHOULD requirements for its protocols is said to be
+ "conditionally compliant".
+
+ Rules Section
+ ----- -------
+ Mandatory-to-implement Cipher Suite 2.1
+ SHOULD have mode where encryption required 2.2
+ server SHOULD have mode where TLS not required 2.2
+ MUST be configurable to refuse all clear-text login
+ commands or mechanisms 2.3
+ server SHOULD be configurable to refuse clear-text
+ login commands on entire server and on per-user basis 2.3
+ client MUST check server identity 2.4
+ client MUST use hostname used to open connection 2.4
+ client MUST NOT use hostname from insecure remote lookup 2.4
+ client SHOULD support subjectAltName of dNSName type 2.4
+ client SHOULD ask for confirmation or terminate on fail 2.4
+ MUST check result of STARTTLS for acceptable privacy 2.5
+ client MUST NOT issue commands after STARTTLS
+ until server response and negotiation done 3.1,4,5.1
+ client MUST discard cached information 3.1,4,5.1,9
+ client SHOULD re-issue CAPABILITY/CAPA command 3.1,4
+ IMAP server with STARTTLS MUST implement LOGINDISABLED 3.2
+ IMAP client MUST NOT issue LOGIN if LOGINDISABLED 3.2
+ POP server MUST implement POP3 extensions 4
+ ACAP server MUST re-issue ACAP greeting 5.1
+
+
+
+
+Newman Standards Track [Page 13]
+
+RFC 2595 Using TLS with IMAP, POP3 and ACAP June 1999
+
+
+ client SHOULD warn when session privacy not active and/or
+ refuse to proceed without acceptable security level 9
+ SHOULD be configurable to refuse weak mechanisms or
+ cipher suites 9
+
+ The PLAIN mechanism is an optional part of this specification.
+ However if it is implemented the following rules apply:
+
+ Rules Section
+ ----- -------
+ MUST NOT use PLAIN unless strong encryption active
+ or backwards compatibility dictates otherwise 6,9
+ MUST use UTF-8 encoding for characters in PLAIN 6
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Newman Standards Track [Page 14]
+
+RFC 2595 Using TLS with IMAP, POP3 and ACAP June 1999
+
+
+Full Copyright Statement
+
+ Copyright (C) The Internet Society (1999). All Rights Reserved.
+
+ This document and translations of it may be copied and furnished to
+ others, and derivative works that comment on or otherwise explain it
+ or assist in its implementation may be prepared, copied, published
+ and distributed, in whole or in part, without restriction of any
+ kind, provided that the above copyright notice and this paragraph are
+ included on all such copies and derivative works. However, this
+ document itself may not be modified in any way, such as by removing
+ the copyright notice or references to the Internet Society or other
+ Internet organizations, except as needed for the purpose of
+ developing Internet standards in which case the procedures for
+ copyrights defined in the Internet Standards process must be
+ followed, or as required to translate it into languages other than
+ English.
+
+ The limited permissions granted above are perpetual and will not be
+ revoked by the Internet Society or its successors or assigns.
+
+ This document and the information contained herein is provided on an
+ "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
+ TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
+ BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
+ HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
+ MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+Acknowledgement
+
+ Funding for the RFC Editor function is currently provided by the
+ Internet Society.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Newman Standards Track [Page 15]
+
diff --git a/doc/rfcs/rfc2810.txt b/doc/rfcs/rfc2810.txt
new file mode 100644
index 0000000..e628a83
--- /dev/null
+++ b/doc/rfcs/rfc2810.txt
@@ -0,0 +1,563 @@
+
+
+
+
+
+
+Network Working Group C. Kalt
+Request for Comments: 2810 April 2000
+Updates: 1459
+Category: Informational
+
+
+ Internet Relay Chat: Architecture
+
+Status of this Memo
+
+ This memo provides information for the Internet community. It does
+ not specify an Internet standard of any kind. Distribution of this
+ memo is unlimited.
+
+Copyright Notice
+
+ Copyright (C) The Internet Society (2000). All Rights Reserved.
+
+Abstract
+
+ The IRC (Internet Relay Chat) protocol is for use with text based
+ conferencing. It has been developed since 1989 when it was originally
+ implemented as a mean for users on a BBS to chat amongst themselves.
+
+ First formally documented in May 1993 by RFC 1459 [IRC], the protocol
+ has kept evolving. This document is an update describing the
+ architecture of the current IRC protocol and the role of its
+ different components. Other documents describe in detail the
+ protocol used between the various components defined here.
+
+Table of Contents
+
+ 1. Introduction ............................................... 2
+ 2. Components ................................................. 2
+ 2.1 Servers ................................................ 2
+ 2.2 Clients ................................................ 3
+ 2.2.1 User Clients ...................................... 3
+ 2.2.2 Service Clients ................................... 3
+ 3. Architecture ............................................... 3
+ 4. IRC Protocol Services ...................................... 4
+ 4.1 Client Locator ......................................... 4
+ 4.2 Message Relaying ....................................... 4
+ 4.3 Channel Hosting And Management ......................... 4
+ 5. IRC Concepts ............................................... 4
+ 5.1 One-To-One Communication ............................... 5
+ 5.2 One-To-Many ............................................ 5
+ 5.2.1 To A Channel ...................................... 5
+ 5.2.2 To A Host/Server Mask ............................. 6
+
+
+
+Kalt Informational [Page 1]
+
+RFC 2810 Internet Relay Chat: Architecture April 2000
+
+
+ 5.2.3 To A List ......................................... 6
+ 5.3 One-To-All ............................................. 6
+ 5.3.1 Client-to-Client .................................. 6
+ 5.3.2 Client-to-Server .................................. 7
+ 5.3.3 Server-to-Server .................................. 7
+ 6. Current Problems ........................................... 7
+ 6.1 Scalability ............................................ 7
+ 6.2 Reliability ............................................ 7
+ 6.3 Network Congestion ..................................... 7
+ 6.4 Privacy ................................................ 8
+ 7. Security Considerations .................................... 8
+ 8. Current Support And Availability ........................... 8
+ 9. Acknowledgements ........................................... 8
+ 10. References ................................................ 8
+ 11. Author's Address .......................................... 9
+ 12. Full Copyright Statement .................................. 10
+
+1. Introduction
+
+ The IRC (Internet Relay Chat) protocol has been designed over a
+ number of years for use with text based conferencing. This document
+ describes its current architecture.
+
+ The IRC Protocol is based on the client-server model, and is well
+ suited to running on many machines in a distributed fashion. A
+ typical setup involves a single process (the server) forming a
+ central point for clients (or other servers) to connect to,
+ performing the required message delivery/multiplexing and other
+ functions.
+
+ This distributed model, which requires each server to have a copy
+ of the global state information, is still the most flagrant problem
+ of the protocol as it is a serious handicap, which limits the maximum
+ size a network can reach. If the existing networks have been able to
+ keep growing at an incredible pace, we must thank hardware
+ manufacturers for giving us ever more powerful systems.
+
+2. Components
+
+ The following paragraphs define the basic components of the IRC
+ protocol.
+
+2.1 Servers
+
+ The server forms the backbone of IRC as it is the only component
+ of the protocol which is able to link all the other components
+ together: it provides a point to which clients may connect to talk to
+
+
+
+
+Kalt Informational [Page 2]
+
+RFC 2810 Internet Relay Chat: Architecture April 2000
+
+
+ each other [IRC-CLIENT], and a point for other servers to connect to
+ [IRC-SERVER]. The server is also responsible for providing the basic
+ services defined by the IRC protocol.
+
+2.2 Clients
+
+ A client is anything connecting to a server that is not another
+ server. There are two types of clients which both serve a different
+ purpose.
+
+2.2.1 User Clients
+
+ User clients are generally programs providing a text based
+ interface that is used to communicate interactively via IRC. This
+ particular type of clients is often referred as "users".
+
+2.2.2 Service Clients
+
+ Unlike users, service clients are not intended to be used manually
+ nor for talking. They have a more limited access to the chat
+ functions of the protocol, while optionally having access to more
+ private data from the servers.
+
+ Services are typically automatons used to provide some kind of
+ service (not necessarily related to IRC itself) to users. An example
+ is a service collecting statistics about the origin of users
+ connected on the IRC network.
+
+3. Architecture
+
+ An IRC network is defined by a group of servers connected to each
+ other. A single server forms the simplest IRC network.
+
+ The only network configuration allowed for IRC servers is that of
+ a spanning tree where each server acts as a central node for the rest
+ of the network it sees.
+
+ 1--\
+ A D---4
+ 2--/ \ /
+ B----C
+ / \
+ 3 E
+
+ Servers: A, B, C, D, E Clients: 1, 2, 3, 4
+
+ [ Fig. 1. Sample small IRC network ]
+
+
+
+
+Kalt Informational [Page 3]
+
+RFC 2810 Internet Relay Chat: Architecture April 2000
+
+
+ The IRC protocol provides no mean for two clients to directly
+ communicate. All communication between clients is relayed by the
+ server(s).
+
+4. IRC Protocol Services
+
+ This section describes the services offered by the IRC protocol. The
+ combination of these services allow real-time conferencing.
+
+4.1 Client Locator
+
+ To be able to exchange messages, two clients must be able to locate
+ each other.
+
+ Upon connecting to a server, a client registers using a label which
+ is then used by other servers and clients to know where the client is
+ located. Servers are responsible for keeping track of all the labels
+ being used.
+
+4.2 Message Relaying
+
+ The IRC protocol provides no mean for two clients to directly
+ communicate. All communication between clients is relayed by the
+ server(s).
+
+4.3 Channel Hosting And Management
+
+ A channel is a named group of one or more users which will all
+ receive messages addressed to that channel. A channel is
+ characterized by its name and current members, it also has a set of
+ properties which can be manipulated by (some of) its members.
+
+ Channels provide a mean for a message to be sent to several clients.
+ Servers host channels, providing the necessary message multiplexing.
+ Servers are also responsible for managing channels by keeping track
+ of the channel members. The exact role of servers is defined in
+ "Internet Relay Chat: Channel Management" [IRC-CHAN].
+
+5. IRC Concepts
+
+ This section is devoted to describing the actual concepts behind the
+ organization of the IRC protocol and how different classes of
+ messages are delivered.
+
+
+
+
+
+
+
+
+Kalt Informational [Page 4]
+
+RFC 2810 Internet Relay Chat: Architecture April 2000
+
+
+5.1 One-To-One Communication
+
+ Communication on a one-to-one basis is usually performed by clients,
+ since most server-server traffic is not a result of servers talking
+ only to each other. To provide a means for clients to talk to each
+ other, it is REQUIRED that all servers be able to send a message in
+ exactly one direction along the spanning tree in order to reach any
+ client. Thus the path of a message being delivered is the shortest
+ path between any two points on the spanning tree.
+
+ The following examples all refer to Figure 1 above.
+
+ Example 1: A message between clients 1 and 2 is only seen by server
+ A, which sends it straight to client 2.
+
+ Example 2: A message between clients 1 and 3 is seen by servers A &
+ B, and client 3. No other clients or servers are allowed see the
+ message.
+
+ Example 3: A message between clients 2 and 4 is seen by servers A, B,
+ C & D and client 4 only.
+
+5.2 One-To-Many
+
+ The main goal of IRC is to provide a forum which allows easy and
+ efficient conferencing (one to many conversations). IRC offers
+ several means to achieve this, each serving its own purpose.
+
+5.2.1 To A Channel
+
+ In IRC the channel has a role equivalent to that of the multicast
+ group; their existence is dynamic and the actual conversation carried
+ out on a channel MUST only be sent to servers which are supporting
+ users on a given channel. Moreover, the message SHALL only be sent
+ once to every local link as each server is responsible to fan the
+ original message to ensure that it will reach all the recipients.
+
+ The following examples all refer to Figure 2.
+
+ Example 4: Any channel with 1 client in it. Messages to the channel
+ go to the server and then nowhere else.
+
+ Example 5: 2 clients in a channel. All messages traverse a path as if
+ they were private messages between the two clients outside a
+ channel.
+
+
+
+
+
+
+Kalt Informational [Page 5]
+
+RFC 2810 Internet Relay Chat: Architecture April 2000
+
+
+ Example 6: Clients 1, 2 and 3 in a channel. All messages to the
+ channel are sent to all clients and only those servers which must
+ be traversed by the message if it were a private message to a
+ single client. If client 1 sends a message, it goes back to
+ client 2 and then via server B to client 3.
+
+5.2.2 To A Host/Server Mask
+
+ To provide with some mechanism to send messages to a large body of
+ related users, host and server mask messages are available. These
+ messages are sent to users whose host or server information match
+ that of the mask. The messages are only sent to locations where
+ users are, in a fashion similar to that of channels.
+
+5.2.3 To A List
+
+ The least efficient style of one-to-many conversation is through
+ clients talking to a 'list' of targets (client, channel, mask). How
+ this is done is almost self explanatory: the client gives a list of
+ destinations to which the message is to be delivered and the server
+ breaks it up and dispatches a separate copy of the message to each
+ given destination.
+
+ This is not as efficient as using a channel since the destination
+ list MAY be broken up and the dispatch sent without checking to make
+ sure duplicates aren't sent down each path.
+
+5.3 One-To-All
+
+ The one-to-all type of message is better described as a broadcast
+ message, sent to all clients or servers or both. On a large network
+ of users and servers, a single message can result in a lot of traffic
+ being sent over the network in an effort to reach all of the desired
+ destinations.
+
+ For some class of messages, there is no option but to broadcast it to
+ all servers so that the state information held by each server is
+ consistent between servers.
+
+5.3.1 Client-to-Client
+
+ There is no class of message which, from a single message, results in
+ a message being sent to every other client.
+
+
+
+
+
+
+
+
+Kalt Informational [Page 6]
+
+RFC 2810 Internet Relay Chat: Architecture April 2000
+
+
+5.3.2 Client-to-Server
+
+ Most of the commands which result in a change of state information
+ (such as channel membership, channel mode, user status, etc.) MUST be
+ sent to all servers by default, and this distribution SHALL NOT be
+ changed by the client.
+
+5.3.3 Server-to-Server
+
+ While most messages between servers are distributed to all 'other'
+ servers, this is only required for any message that affects a user,
+ channel or server. Since these are the basic items found in IRC,
+ nearly all messages originating from a server are broadcast to all
+ other connected servers.
+
+6. Current Problems
+
+ There are a number of recognized problems with this protocol, this
+ section only addresses the problems related to the architecture of
+ the protocol.
+
+6.1 Scalability
+
+ It is widely recognized that this protocol does not scale
+ sufficiently well when used in a large arena. The main problem comes
+ from the requirement that all servers know about all other servers,
+ clients and channels and that information regarding them be updated
+ as soon as it changes.
+
+6.2 Reliability
+
+ As the only network configuration allowed for IRC servers is that of
+ a spanning tree, each link between two servers is an obvious and
+ quite serious point of failure. This particular issue is addressed
+ more in detail in "Internet Relay Chat: Server Protocol" [IRC-
+ SERVER].
+
+6.3 Network Congestion
+
+ Another problem related to the scalability and reliability issues, as
+ well as the spanning tree architecture, is that the protocol and
+ architecture for IRC are extremely vulnerable to network congestions.
+ This problem is endemic, and should be solved for the next
+ generation: if congestion and high traffic volume cause a link
+ between two servers to fail, not only this failure generates more
+ network traffic, but the reconnection (eventually elsewhere) of two
+ servers also generates more traffic.
+
+
+
+
+Kalt Informational [Page 7]
+
+RFC 2810 Internet Relay Chat: Architecture April 2000
+
+
+ In an attempt to minimize the impact of these problems, it is
+ strongly RECOMMENDED that servers do not automatically try to
+ reconnect too fast, in order to avoid aggravating the situation.
+
+6.4 Privacy
+
+ Besides not scaling well, the fact that servers need to know all
+ information about other entities, the issue of privacy is also a
+ concern. This is in particular true for channels, as the related
+ information is quite a lot more revealing than whether a user is
+ online or not.
+
+7. Security Considerations
+
+ Asides from the privacy concerns mentioned in section 6.4 (Privacy),
+ security is believed to be irrelevant to this document.
+
+8. Current Support And Availability
+
+ Mailing lists for IRC related discussion:
+ General discussion: ircd-users@irc.org
+ Protocol development: ircd-dev@irc.org
+
+ Software implementations:
+ ftp://ftp.irc.org/irc/server
+ ftp://ftp.funet.fi/pub/unix/irc
+ ftp://coombs.anu.edu.au/pub/irc
+
+ Newsgroup: alt.irc
+
+9. Acknowledgements
+
+ Parts of this document were copied from the RFC 1459 [IRC] which
+ first formally documented the IRC Protocol. It has also benefited
+ from many rounds of review and comments. In particular, the
+ following people have made significant contributions to this
+ document:
+
+ Matthew Green, Michael Neumayer, Volker Paulsen, Kurt Roeckx, Vesa
+ Ruokonen, Magnus Tjernstrom, Stefan Zehl.
+
+
+
+
+
+
+
+
+
+
+
+Kalt Informational [Page 8]
+
+RFC 2810 Internet Relay Chat: Architecture April 2000
+
+
+10. References
+
+ [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+ [IRC] Oikarinen, J. and D. Reed, "Internet Relay Chat
+ Protocol", RFC 1459, May 1993.
+
+ [IRC-CLIENT] Kalt, C., "Internet Relay Chat: Client Protocol", RFC
+ 2812, April 2000.
+
+ [IRC-SERVER] Kalt, C., "Internet Relay Chat: Server Protocol", RFC
+ 2813, April 2000.
+
+ [IRC-CHAN] Kalt, C., "Internet Relay Chat: Channel Management", RFC
+ 2811, April 2000.
+
+11. Author's Address
+
+ Christophe Kalt
+ 99 Teaneck Rd, Apt #117
+ Ridgefield Park, NJ 07660
+ USA
+
+ EMail: kalt@stealth.net
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Kalt Informational [Page 9]
+
+RFC 2810 Internet Relay Chat: Architecture April 2000
+
+
+12. Full Copyright Statement
+
+ Copyright (C) The Internet Society (2000). All Rights Reserved.
+
+ This document and translations of it may be copied and furnished to
+ others, and derivative works that comment on or otherwise explain it
+ or assist in its implementation may be prepared, copied, published
+ and distributed, in whole or in part, without restriction of any
+ kind, provided that the above copyright notice and this paragraph are
+ included on all such copies and derivative works. However, this
+ document itself may not be modified in any way, such as by removing
+ the copyright notice or references to the Internet Society or other
+ Internet organizations, except as needed for the purpose of
+ developing Internet standards in which case the procedures for
+ copyrights defined in the Internet Standards process must be
+ followed, or as required to translate it into languages other than
+ English.
+
+ The limited permissions granted above are perpetual and will not be
+ revoked by the Internet Society or its successors or assigns.
+
+ This document and the information contained herein is provided on an
+ "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
+ TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
+ BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
+ HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
+ MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+Acknowledgement
+
+ Funding for the RFC Editor function is currently provided by the
+ Internet Society.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Kalt Informational [Page 10]
+
diff --git a/doc/rfcs/rfc2811.txt b/doc/rfcs/rfc2811.txt
new file mode 100644
index 0000000..7c2c4ea
--- /dev/null
+++ b/doc/rfcs/rfc2811.txt
@@ -0,0 +1,1067 @@
+
+
+
+
+
+
+Network Working Group C. Kalt
+Request for Comments: 2811 April 2000
+Updates: 1459
+Category: Informational
+
+
+ Internet Relay Chat: Channel Management
+
+Status of this Memo
+
+ This memo provides information for the Internet community. It does
+ not specify an Internet standard of any kind. Distribution of this
+ memo is unlimited.
+
+Copyright Notice
+
+ Copyright (C) The Internet Society (2000). All Rights Reserved.
+
+Abstract
+
+ One of the most notable characteristics of the IRC (Internet Relay
+ Chat) protocol is to allow for users to be grouped in forums, called
+ channels, providing a mean for multiple users to communicate
+ together.
+
+ There was originally a unique type of channels, but with the years,
+ new types appeared either as a response to a need, or for
+ experimental purposes.
+
+ This document specifies how channels, their characteristics and
+ properties are managed by IRC servers.
+
+Table of Contents
+
+ 1. Introduction ............................................... 2
+ 2. Channel Characteristics .................................... 3
+ 2.1 Namespace .............................................. 3
+ 2.2 Channel Scope .......................................... 3
+ 2.3 Channel Properties ..................................... 4
+ 2.4 Privileged Channel Members ............................. 4
+ 2.4.1 Channel Operators ................................. 5
+ 2.4.2 Channel Creator ................................... 5
+ 3. Channel lifetime ........................................... 5
+ 3.1 Standard channels ...................................... 5
+ 3.2 Safe Channels .......................................... 6
+ 4. Channel Modes .............................................. 7
+ 4.1 Member Status .......................................... 7
+ 4.1.1 "Channel Creator" Status .......................... 7
+
+
+
+Kalt Informational [Page 1]
+
+RFC 2811 Internet Relay Chat: Channel Management April 2000
+
+
+ 4.1.2 Channel Operator Status ........................... 8
+ 4.1.3 Voice Privilege ................................... 8
+ 4.2 Channel Flags .......................................... 8
+ 4.2.1 Anonymous Flag .................................... 8
+ 4.2.2 Invite Only Flag .................................. 8
+ 4.2.3 Moderated Channel Flag ............................ 9
+ 4.2.4 No Messages To Channel From Clients On The Outside 9
+ 4.2.5 Quiet Channel ..................................... 9
+ 4.2.6 Private and Secret Channels ....................... 9
+ 4.2.7 Server Reop Flag .................................. 10
+ 4.2.8 Topic ............................................. 10
+ 4.2.9 User Limit ........................................ 10
+ 4.2.10 Channel Key ...................................... 10
+ 4.3 Channel Access Control ................................. 10
+ 4.3.1 Channel Ban and Exception ......................... 11
+ 4.3.2 Channel Invitation ................................ 11
+ 5. Current Implementations .................................... 11
+ 5.1 Tracking Recently Used Channels ........................ 11
+ 5.2 Safe Channels .......................................... 12
+ 5.2.1 Channel Identifier ................................ 12
+ 5.2.2 Channel Delay ..................................... 12
+ 5.2.3 Abuse Window ...................................... 13
+ 5.2.4 Preserving Sanity In The Name Space ............... 13
+ 5.2.5 Server Reop Mechanism ............................. 13
+ 6. Current problems ........................................... 14
+ 6.1 Labels ................................................. 14
+ 6.1.1 Channel Delay ..................................... 14
+ 6.1.2 Safe Channels ..................................... 15
+ 6.2 Mode Propagation Delays ................................ 15
+ 6.3 Collisions And Channel Modes ........................... 15
+ 6.4 Resource Exhaustion .................................... 16
+ 7. Security Considerations .................................... 16
+ 7.1 Access Control ......................................... 16
+ 7.2 Channel Privacy ........................................ 16
+ 7.3 Anonymity ............................................... 17
+ 8. Current support and availability ........................... 17
+ 9. Acknowledgements ........................................... 17
+ 10. References ................................................ 18
+ 11. Author's Address .......................................... 18
+ 12. Full Copyright Statement ................................... 19
+
+1. Introduction
+
+ This document defines in detail on how channels are managed by the
+ IRC servers and will be mostly useful to people working on
+ implementing an IRC server.
+
+
+
+
+
+Kalt Informational [Page 2]
+
+RFC 2811 Internet Relay Chat: Channel Management April 2000
+
+
+ While the concepts defined here are an important part of IRC, they
+ remain non essential for implementing clients. While the trend seems
+ to be towards more and more complex and "intelligent" clients which
+ are able to take advantage of knowing the internal workings of
+ channels to provide the users with a more friendly interface, simple
+ clients can be implemented without reading this document.
+
+ Many of the concepts defined here were designed with the IRC
+ architecture [IRC-ARCH] in mind and mostly make sense in this
+ context. However, many others could be applied to other
+ architectures in order to provide forums for a conferencing system.
+
+ Finally, it is to be noted that IRC users may find some of the
+ following sections of interest, in particular sections 2 (Channel
+ Characteristics) and 4 (Channel Modes).
+
+2. Channel Characteristics
+
+ A channel is a named group of one or more users which will all
+ receive messages addressed to that channel. A channel is
+ characterized by its name, properties and current members.
+
+2.1 Namespace
+
+ Channels names are strings (beginning with a '&', '#', '+' or '!'
+ character) of length up to fifty (50) characters. Channel names are
+ case insensitive.
+
+ Apart from the the requirement that the first character being either
+ '&', '#', '+' or '!' (hereafter called "channel prefix"). The only
+ restriction on a channel name is that it SHALL NOT contain any spaces
+ (' '), a control G (^G or ASCII 7), a comma (',' which is used as a
+ list item separator by the protocol). Also, a colon (':') is used as
+ a delimiter for the channel mask. The exact syntax of a channel name
+ is defined in "IRC Server Protocol" [IRC-SERVER].
+
+ The use of different prefixes effectively creates four (4) distinct
+ namespaces for channel names. This is important because of the
+ protocol limitations regarding namespaces (in general). See section
+ 6.1 (Labels) for more details on these limitations.
+
+2.2 Channel Scope
+
+ A channel entity is known by one or more servers on the IRC network.
+ A user can only become member of a channel known by the server to
+ which the user is directly connected. The list of servers which know
+
+
+
+
+
+Kalt Informational [Page 3]
+
+RFC 2811 Internet Relay Chat: Channel Management April 2000
+
+
+ of the existence of a particular channel MUST be a contiguous part of
+ the IRC network, in order for the messages addressed to the channel
+ to be sent to all the channel members.
+
+ Channels with '&' as prefix are local to the server where they are
+ created.
+
+ Other channels are known to one (1) or more servers that are
+ connected to the network, depending on the channel mask:
+
+ If there is no channel mask, then the channel is known to all
+ the servers.
+
+ If there is a channel mask, then the channel MUST only be known
+ to servers which has a local user on the channel, and to its
+ neighbours if the mask matches both the local and neighbouring
+ server names. Since other servers have absolutely no knowledge of
+ the existence of such a channel, the area formed by the servers
+ having a name matching the mask has to be contiguous for the
+ channel to be known by all these servers. Channel masks are best
+ used in conjunction with server hostmasking [IRC-SERVER].
+
+2.3 Channel Properties
+
+ Each channel has its own properties, which are defined by channel
+ modes. Channel modes can be manipulated by the channel members. The
+ modes affect the way servers manage the channels.
+
+ Channels with '+' as prefix do not support channel modes. This means
+ that all the modes are unset, with the exception of the 't' channel
+ flag which is set.
+
+2.4 Privileged Channel Members
+
+ In order for the channel members to keep some control over a channel,
+ and some kind of sanity, some channel members are privileged. Only
+ these members are allowed to perform the following actions on the
+ channel:
+
+ INVITE - Invite a client to an invite-only channel (mode +i)
+ KICK - Eject a client from the channel
+ MODE - Change the channel's mode, as well as
+ members' privileges
+ PRIVMSG - Sending messages to the channel (mode +n, +m, +v)
+ TOPIC - Change the channel topic in a mode +t channel
+
+
+
+
+
+
+Kalt Informational [Page 4]
+
+RFC 2811 Internet Relay Chat: Channel Management April 2000
+
+
+2.4.1 Channel Operators
+
+ The channel operators (also referred to as a "chop" or "chanop") on a
+ given channel are considered to 'own' that channel. Ownership of a
+ channel is shared among channel operators.
+
+ Channel operators are identified by the '@' symbol next to their
+ nickname whenever it is associated with a channel (i.e., replies to
+ the NAMES, WHO and WHOIS commands).
+
+ Since channels starting with the character '+' as prefix do not
+ support channel modes, no member can therefore have the status of
+ channel operator.
+
+2.4.2 Channel Creator
+
+ A user who creates a channel with the character '!' as prefix is
+ identified as the "channel creator". Upon creation of the channel,
+ this user is also given channel operator status.
+
+ In recognition of this status, the channel creators are endowed with
+ the ability to toggle certain modes of the channel which channel
+ operators may not manipulate.
+
+ A "channel creator" can be distinguished from a channel operator by
+ issuing the proper MODE command. See the "IRC Client Protocol"
+ [IRC-CLIENT] for more information on this topic.
+
+3. Channel lifetime
+
+ In regard to the lifetime of a channel, there are typically two
+ groups of channels: standard channels which prefix is either '&', '#'
+ or '+', and "safe channels" which prefix is '!'.
+
+3.1 Standard channels
+
+ These channels are created implicitly when the first user joins it,
+ and cease to exist when the last user leaves it. While the channel
+ exists, any client can reference the channel using the name of the
+ channel.
+
+ The user creating a channel automatically becomes channel operator
+ with the notable exception of channels which name is prefixed by the
+ character '+', see section 4 (Channel modes). See section 2.4.1
+ (Channel Operators) for more details on this title.
+
+
+
+
+
+
+Kalt Informational [Page 5]
+
+RFC 2811 Internet Relay Chat: Channel Management April 2000
+
+
+ In order to avoid the creation of duplicate channels (typically when
+ the IRC network becomes disjoint because of a split between two
+ servers), channel names SHOULD NOT be allowed to be reused by a user
+ if a channel operator (See Section 2.4.1 (Channel Operators)) has
+ recently left the channel because of a network split. If this
+ happens, the channel name is temporarily unavailable. The duration
+ while a channel remains unavailable should be tuned on a per IRC
+ network basis. It is important to note that this prevents local
+ users from creating a channel using the same name, but does not
+ prevent the channel to be recreated by a remote user. The latter
+ typically happens when the IRC network rejoins. Obviously, this
+ mechanism only makes sense for channels which name begins with the
+ character '#', but MAY be used for channels which name begins with
+ the character '+'. This mechanism is commonly known as "Channel
+ Delay".
+
+3.2 Safe Channels
+
+ Unlike other channels, "safe channels" are not implicitly created. A
+ user wishing to create such a channel MUST request the creation by
+ sending a special JOIN command to the server in which the channel
+ identifier (then unknown) is replaced by the character '!'. The
+ creation process for this type of channel is strictly controlled.
+ The user only chooses part of the channel name (known as the channel
+ "short name"), the server automatically prepends the user provided
+ name with a channel identifier consisting of five (5) characters.
+ The channel name resulting from the combination of these two elements
+ is unique, making the channel safe from abuses based on network
+ splits.
+
+ The user who creates such a channel automatically becomes "channel
+ creator". See section 2.4.2 (Channel Creator) for more details on
+ this title.
+
+ A server MUST NOT allow the creation of a new channel if another
+ channel with the same short name exists; or if another channel with
+ the same short name existed recently AND any of its member(s) left
+ because of a network split. Such channel ceases to exist after last
+ user leaves AND no other member recently left the channel because of
+ a network split.
+
+ Unlike the mechanism described in section 5.2.2 (Channel Delay), in
+ this case, channel names do not become unavailable: these channels
+ may continue to exist after the last user left. Only the user
+ creating the channel becomes "channel creator", users joining an
+ existing empty channel do not automatically become "channel creator"
+ nor "channel operator".
+
+
+
+
+Kalt Informational [Page 6]
+
+RFC 2811 Internet Relay Chat: Channel Management April 2000
+
+
+ To ensure the uniqueness of the channel names, the channel identifier
+ created by the server MUST follow specific rules. For more details
+ on this, see section 5.2.1 (Channel Identifier).
+
+4. Channel Modes
+
+ The various modes available for channels are as follows:
+
+ O - give "channel creator" status;
+ o - give/take channel operator privilege;
+ v - give/take the voice privilege;
+
+ a - toggle the anonymous channel flag;
+ i - toggle the invite-only channel flag;
+ m - toggle the moderated channel;
+ n - toggle the no messages to channel from clients on the
+ outside;
+ q - toggle the quiet channel flag;
+ p - toggle the private channel flag;
+ s - toggle the secret channel flag;
+ r - toggle the server reop channel flag;
+ t - toggle the topic settable by channel operator only flag;
+
+ k - set/remove the channel key (password);
+ l - set/remove the user limit to channel;
+
+ b - set/remove ban mask to keep users out;
+ e - set/remove an exception mask to override a ban mask;
+ I - set/remove an invitation mask to automatically override
+ the invite-only flag;
+
+ Unless mentioned otherwise below, all these modes can be manipulated
+ by "channel operators" by using the MODE command defined in "IRC
+ Client Protocol" [IRC-CLIENT].
+
+4.1 Member Status
+
+ The modes in this category take a channel member nickname as argument
+ and affect the privileges given to this user.
+
+4.1.1 "Channel Creator" Status
+
+ The mode 'O' is only used in conjunction with "safe channels" and
+ SHALL NOT be manipulated by users. Servers use it to give the user
+ creating the channel the status of "channel creator".
+
+
+
+
+
+
+Kalt Informational [Page 7]
+
+RFC 2811 Internet Relay Chat: Channel Management April 2000
+
+
+4.1.2 Channel Operator Status
+
+ The mode 'o' is used to toggle the operator status of a channel
+ member.
+
+4.1.3 Voice Privilege
+
+ The mode 'v' is used to give and take voice privilege to/from a
+ channel member. Users with this privilege can talk on moderated
+ channels. (See section 4.2.3 (Moderated Channel Flag).
+
+4.2 Channel Flags
+
+ The modes in this category are used to define properties which
+ affects how channels operate.
+
+4.2.1 Anonymous Flag
+
+ The channel flag 'a' defines an anonymous channel. This means that
+ when a message sent to the channel is sent by the server to users,
+ and the origin is a user, then it MUST be masked. To mask the
+ message, the origin is changed to "anonymous!anonymous@anonymous."
+ (e.g., a user with the nickname "anonymous", the username "anonymous"
+ and from a host called "anonymous."). Because of this, servers MUST
+ forbid users from using the nickname "anonymous". Servers MUST also
+ NOT send QUIT messages for users leaving such channels to the other
+ channel members but generate a PART message instead.
+
+ On channels with the character '&' as prefix, this flag MAY be
+ toggled by channel operators, but on channels with the character '!'
+ as prefix, this flag can be set (but SHALL NOT be unset) by the
+ "channel creator" only. This flag MUST NOT be made available on
+ other types of channels.
+
+ Replies to the WHOIS, WHO and NAMES commands MUST NOT reveal the
+ presence of other users on channels for which the anonymous flag is
+ set.
+
+4.2.2 Invite Only Flag
+
+ When the channel flag 'i' is set, new members are only accepted if
+ their mask matches Invite-list (See section 4.3.2) or they have been
+ invited by a channel operator. This flag also restricts the usage of
+ the INVITE command (See "IRC Client Protocol" [IRC-CLIENT]) to
+ channel operators.
+
+
+
+
+
+
+Kalt Informational [Page 8]
+
+RFC 2811 Internet Relay Chat: Channel Management April 2000
+
+
+4.2.3 Moderated Channel Flag
+
+ The channel flag 'm' is used to control who may speak on a channel.
+ When it is set, only channel operators, and members who have been
+ given the voice privilege may send messages to the channel.
+
+ This flag only affects users.
+
+4.2.4 No Messages To Channel From Clients On The Outside
+
+ When the channel flag 'n' is set, only channel members MAY send
+ messages to the channel.
+
+ This flag only affects users.
+
+4.2.5 Quiet Channel
+
+ The channel flag 'q' is for use by servers only. When set, it
+ restricts the type of data sent to users about the channel
+ operations: other user joins, parts and nick changes are not sent.
+ From a user's point of view, the channel contains only one user.
+
+ This is typically used to create special local channels on which the
+ server sends notices related to its operations. This was used as a
+ more efficient and flexible way to replace the user mode 's' defined
+ in RFC 1459 [IRC].
+
+4.2.6 Private and Secret Channels
+
+ The channel flag 'p' is used to mark a channel "private" and the
+ channel flag 's' to mark a channel "secret". Both properties are
+ similar and conceal the existence of the channel from other users.
+
+ This means that there is no way of getting this channel's name from
+ the server without being a member. In other words, these channels
+ MUST be omitted from replies to queries like the WHOIS command.
+
+ When a channel is "secret", in addition to the restriction above, the
+ server will act as if the channel does not exist for queries like the
+ TOPIC, LIST, NAMES commands. Note that there is one exception to
+ this rule: servers will correctly reply to the MODE command.
+ Finally, secret channels are not accounted for in the reply to the
+ LUSERS command (See "Internet Relay Chat: Client Protocol" [IRC-
+ CLIENT]) when the <mask> parameter is specified.
+
+
+
+
+
+
+
+Kalt Informational [Page 9]
+
+RFC 2811 Internet Relay Chat: Channel Management April 2000
+
+
+ The channel flags 'p' and 's' MUST NOT both be set at the same time.
+ If a MODE message originating from a server sets the flag 'p' and the
+ flag 's' is already set for the channel, the change is silently
+ ignored. This should only happen during a split healing phase
+ (mentioned in the "IRC Server Protocol" document [IRC-SERVER]).
+
+4.2.7 Server Reop Flag
+
+ The channel flag 'r' is only available on channels which name begins
+ with the character '!' and MAY only be toggled by the "channel
+ creator".
+
+ This flag is used to prevent a channel from having no channel
+ operator for an extended period of time. When this flag is set, any
+ channel that has lost all its channel operators for longer than the
+ "reop delay" period triggers a mechanism in servers to reop some or
+ all of the channel inhabitants. This mechanism is described more in
+ detail in section 5.2.4 (Channel Reop Mechanism).
+
+4.2.8 Topic
+
+ The channel flag 't' is used to restrict the usage of the TOPIC
+ command to channel operators.
+
+4.2.9 User Limit
+
+ A user limit may be set on channels by using the channel flag 'l'.
+ When the limit is reached, servers MUST forbid their local users to
+ join the channel.
+
+ The value of the limit MUST only be made available to the channel
+ members in the reply sent by the server to a MODE query.
+
+4.2.10 Channel Key
+
+ When a channel key is set (by using the mode 'k'), servers MUST
+ reject their local users request to join the channel unless this key
+ is given.
+
+ The channel key MUST only be made visible to the channel members in
+ the reply sent by the server to a MODE query.
+
+4.3 Channel Access Control
+
+ The last category of modes is used to control access to the channel,
+ they take a mask as argument.
+
+
+
+
+
+Kalt Informational [Page 10]
+
+RFC 2811 Internet Relay Chat: Channel Management April 2000
+
+
+ In order to reduce the size of the global database for control access
+ modes set for channels, servers MAY put a maximum limit on the number
+ of such modes set for a particular channel. If such restriction is
+ imposed, it MUST only affect user requests. The limit SHOULD be
+ homogeneous on a per IRC network basis.
+
+4.3.1 Channel Ban and Exception
+
+ When a user requests to join a channel, his local server checks if
+ the user's address matches any of the ban masks set for the channel.
+ If a match is found, the user request is denied unless the address
+ also matches an exception mask set for the channel.
+
+ Servers MUST NOT allow a channel member who is banned from the
+ channel to speak on the channel, unless this member is a channel
+ operator or has voice privilege. (See Section 4.1.3 (Voice
+ Privilege)).
+
+ A user who is banned from a channel and who carries an invitation
+ sent by a channel operator is allowed to join the channel.
+
+4.3.2 Channel Invitation
+
+ For channels which have the invite-only flag set (See Section 4.2.2
+ (Invite Only Flag)), users whose address matches an invitation mask
+ set for the channel are allowed to join the channel without any
+ invitation.
+
+5. Current Implementations
+
+ The only current implementation of these rules as part of the IRC
+ protocol is the IRC server, version 2.10.
+
+ The rest of this section deals with issues that are mostly of
+ importance to those who wish to implement a server but some parts may
+ also be of interest for client writers.
+
+5.1 Tracking Recently Used Channels
+
+ This mechanism is commonly known as "Channel Delay" and generally
+ only applies to channels which names is prefixed with the character
+ '#' (See Section 3.1 "Standard channels").
+
+ When a network split occurs, servers SHOULD keep track of which
+ channels lost a "channel operator" as the result of the break. These
+ channels are then in a special state which lasts for a certain period
+ of time. In this particular state, the channels cannot cease to
+
+
+
+
+Kalt Informational [Page 11]
+
+RFC 2811 Internet Relay Chat: Channel Management April 2000
+
+
+ exist. If all the channel members leave the channel, the channel
+ becomes unavailable: the server local clients cannot join the channel
+ as long as it is empty.
+
+ Once a channel is unavailable, it will become available again either
+ because a remote user has joined the channel (most likely because the
+ network is healing), or because the delay period has expired (in
+ which case the channel ceases to exist and may be re-created).
+
+ The duration for which a channel death is delayed SHOULD be set
+ considering many factors among which are the size (user wise) of the
+ IRC network, and the usual duration of network splits. It SHOULD be
+ uniform on all servers for a given IRC network.
+
+5.2 Safe Channels
+
+ This document introduces the notion of "safe channels". These
+ channels have a name prefixed with the character '!' and great effort
+ is made to avoid collisions in this name space. Collisions are not
+ impossible, however they are very unlikely.
+
+5.2.1 Channel Identifier
+
+ The channel identifier is a function of the time. The current time
+ (as defined under UNIX by the number of seconds elapsed since
+ 00:00:00 GMT, January 1, 1970) is converted in a string of five (5)
+ characters using the following base:
+ "ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890" (each character has a decimal
+ value starting from 0 for 'A' to 35 for '0').
+
+ The channel identifier therefore has a periodicity of 36^5 seconds
+ (about 700 days).
+
+5.2.2 Channel Delay
+
+ These channels MUST be subject to the "channel delay" mechanism
+ described in section 5.1 (Channel Delay). However, the mechanism is
+ slightly adapted to fit better.
+
+ Servers MUST keep track of all such channels which lose members as
+ the result of a network split, no matter whether the user is a
+ "channel operator" or not.
+
+ However, these channels do NOT ever become unavailable, it is always
+ possible to join them even when they are empty.
+
+
+
+
+
+
+Kalt Informational [Page 12]
+
+RFC 2811 Internet Relay Chat: Channel Management April 2000
+
+
+5.2.3 Abuse Window
+
+ Because the periodicity is so long, attacks on a particular channel
+ (name) may only occur once in a very long while. However, with luck
+ and patience, it is still possible for a user to cause a channel
+ collision. In order to avoid this, servers MUST "look in the future"
+ and keep a list of channel names which identifier is about to be used
+ (in the coming few days for example). Such list should remain small,
+ not be a burden for servers to maintain and be used to avoid channel
+ collisions by preventing the re-creation of such channel for a longer
+ period of time than channel delay does.
+
+ Eventually a server MAY choose to extend this procedure to forbid
+ creation of channels with the same shortname only (then ignoring the
+ channel identifier).
+
+5.2.4 Preserving Sanity In The Name Space
+
+ The combination of the mechanisms described in sections 5.2.2 and
+ 5.2.3 makes it quite difficult for a user to create a channel
+ collision. However, another type of abuse consists of creating many
+ channels having the same shortname, but different identifiers. To
+ prevent this from happening, servers MUST forbid the creation of a
+ new channel which has the same shortname of a channel currently
+ existing.
+
+5.2.5 Server Reop Mechanism
+
+ When a channel has been opless for longer than the "reop delay"
+ period and has the channel flag 'r' set (See Section 4.2.7 (Server
+ Reop Flag)), IRC servers are responsible for giving the channel
+ operator status randomly to some of the members.
+
+ The exact logic used for this mechanism by the current implementation
+ is described below. Servers MAY use a different logic, but that it
+ is strongly RECOMMENDED that all servers use the same logic on a
+ particular IRC network to maintain coherence as well as fairness.
+ For the same reason, the "reop delay" SHOULD be uniform on all
+ servers for a given IRC network. As for the "channel delay", the
+ value of the "reop delay" SHOULD be set considering many factors
+ among which are the size (user wise) of the IRC network, and the
+ usual duration of network splits.
+
+ a) the reop mechanism is triggered after a random time following the
+ expiration of the "reop delay". This should limit the eventuality
+ of the mechanism being triggered at the same time (for the same
+ channel) on two separate servers.
+
+
+
+
+Kalt Informational [Page 13]
+
+RFC 2811 Internet Relay Chat: Channel Management April 2000
+
+
+ b) If the channel is small (five (5) users or less), and the "channel
+ delay" for this channel has expired,
+ Then reop all channel members if at least one member is local to
+ the server.
+
+ c) If the channel is small (five (5) users or less), and the "channel
+ delay" for this channel has expired, and the "reop delay" has
+ expired for longer than its value,
+ Then reop all channel members.
+
+ d) For other cases, reop at most one member on the channel, based on
+ some method build into the server. If you don't reop a member, the
+ method should be such that another server will probably op
+ someone. The method SHOULD be the same over the whole network. A
+ good heuristic could be just random reop.
+ (The current implementation actually tries to choose a member
+ local to the server who has not been idle for too long, eventually
+ postponing action, therefore letting other servers have a chance
+ to find a "not too idle" member. This is over complicated due to
+ the fact that servers only know the "idle" time of their local
+ users)
+
+6. Current problems
+
+ There are a number of recognized problems with the way IRC channels
+ are managed. Some of these can be directly attributed to the rules
+ defined in this document, while others are the result of the
+ underlying "IRC Server Protocol" [IRC-SERVER]. Although derived from
+ RFC 1459 [IRC], this document introduces several novelties in an
+ attempt to solve some of the known problems.
+
+6.1 Labels
+
+ This document defines one of the many labels used by the IRC
+ protocol. Although there are several distinct namespaces (based on
+ the channel name prefix), duplicates inside each of these are not
+ allowed. Currently, it is possible for users on different servers to
+ pick the label which may result in collisions (with the exception of
+ channels known to only one server where they can be averted).
+
+6.1.1 Channel Delay
+
+ The channel delay mechanism described in section 5.1 (Tracking
+ Recently Used Channels) and used for channels prefixed with the
+ character '#' is a simple attempt at preventing collisions from
+ happening. Experience has shown that, under normal circumstances, it
+
+
+
+
+
+Kalt Informational [Page 14]
+
+RFC 2811 Internet Relay Chat: Channel Management April 2000
+
+
+ is very efficient; however, it obviously has severe limitations
+ keeping it from being an adequate solution to the problem discussed
+ here.
+
+6.1.2 Safe Channels
+
+ "Safe channels" described in section 3.2 (Safe Channels) are a better
+ way to prevent collisions from happening as it prevents users from
+ having total control over the label they choose. The obvious
+ drawback for such labels is that they are not user friendly.
+ However, it is fairly trivial for a client program to improve on
+ this.
+
+6.2 Mode Propagation Delays
+
+ Because of network delays induced by the network, and because each
+ server on the path is REQUIRED to check the validity of mode changes
+ (e.g., user exists and has the right privileges), it is not unusual
+ for a MODE message to only affect part of the network, often creating
+ a discrepancy between servers on the current state of a channel.
+
+ While this may seem easy to fix (by having only the original server
+ check the validity of mode changes), it was decided not to do so for
+ various reasons. One concern is that servers cannot trust each
+ other, and that a misbehaving servers can easily be detected. This
+ way of doing so also stops wave effects on channels which are out of
+ synch when mode changes are issued from different directions.
+
+6.3 Collisions And Channel Modes
+
+ The "Internet Relay Chat: Server Protocol" document [IRC-SERVER]
+ describes how channel data is exchanged when two servers connect to
+ each other. Channel collisions (either legitimate or not) are
+ treated as inclusive events, meaning that the resulting channel has
+ for members all the users who are members of the channel on either
+ server prior to the connection.
+
+ Similarly, each server sends the channel modes to the other one.
+ Therefore, each server also receives these channel modes. There are
+ three types of modes for a given channel: flags, masks, and data.
+ The first two types are easy to deal with as they are either set or
+ unset. If such a mode is set on one server, it MUST be set on the
+ other server as a result of the connection.
+
+
+
+
+
+
+
+
+Kalt Informational [Page 15]
+
+RFC 2811 Internet Relay Chat: Channel Management April 2000
+
+
+ As topics are not sent as part of this exchange, they are not a
+ problem. However, channel modes 'l' and 'k' are exchanged, and if
+ they are set on both servers prior to the connection, there is no
+ mechanism to decide which of the two values takes precedence. It is
+ left up to the users to fix the resulting discrepancy.
+
+6.4 Resource Exhaustion
+
+ The mode based on masks defined in section 4.3 make the IRC servers
+ (and network) vulnerable to a simple abuse of the system: a single
+ channel operator can set as many different masks as possible on a
+ particular channel. This can easily cause the server to waste
+ memory, as well as network bandwidth (since the info is propagated to
+ other servers). For this reason it is RECOMMENDED that a limit be
+ put on the number of such masks per channels as mentioned in section
+ 4.3.
+
+ Moreover, more complex mechanisms MAY be used to avoid having
+ redundant masks set for the same channel.
+
+7. Security Considerations
+
+7.1 Access Control
+
+ One of the main ways to control access to a channel is to use masks
+ which are based on the username and hostname of the user connections.
+ This mechanism can only be efficient and safe if the IRC servers have
+ an accurate way of authenticating user connections, and if users
+ cannot easily get around it. While it is in theory possible to
+ implement such a strict authentication mechanism, most IRC networks
+ (especially public networks) do not have anything like this in place
+ and provide little guaranty about the accuracy of the username and
+ hostname for a particular client connection.
+
+ Another way to control access is to use a channel key, but since this
+ key is sent in plaintext, it is vulnerable to traditional man in the
+ middle attacks.
+
+7.2 Channel Privacy
+
+ Because channel collisions are treated as inclusive events (See
+ Section 6.3), it is possible for users to join a channel overriding
+ its access control settings. This method has long been used by
+ individuals to "take over" channels by "illegitimately" gaining
+ channel operator status on the channel. The same method can be used
+ to find out the exact list of members of a channel, as well as to
+ eventually receive some of the messages sent to the channel.
+
+
+
+
+Kalt Informational [Page 16]
+
+RFC 2811 Internet Relay Chat: Channel Management April 2000
+
+
+7.3 Anonymity
+
+ The anonymous channel flag (See Section 4.2.1) can be used to render
+ all users on such channel "anonymous" by presenting all messages to
+ the channel as originating from a pseudo user which nickname is
+ "anonymous". This is done at the client-server level, and no
+ anonymity is provided at the server-server level.
+
+ It should be obvious to readers, that the level of anonymity offered
+ is quite poor and insecure, and that clients SHOULD display strong
+ warnings for users joining such channels.
+
+8. Current support and availability
+
+ Mailing lists for IRC related discussion:
+ General discussion: ircd-users@irc.org
+ Protocol development: ircd-dev@irc.org
+
+ Software implementations:
+ ftp://ftp.irc.org/irc/server
+ ftp://ftp.funet.fi/pub/unix/irc
+ ftp://coombs.anu.edu.au/pub/irc
+
+ Newsgroup: alt.irc
+
+9. Acknowledgements
+
+ Parts of this document were copied from the RFC 1459 [IRC] which
+ first formally documented the IRC Protocol. It has also benefited
+ from many rounds of review and comments. In particular, the
+ following people have made significant contributions to this
+ document:
+
+ Matthew Green, Michael Neumayer, Volker Paulsen, Kurt Roeckx, Vesa
+ Ruokonen, Magnus Tjernstrom, Stefan Zehl.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Kalt Informational [Page 17]
+
+RFC 2811 Internet Relay Chat: Channel Management April 2000
+
+
+10. References
+
+ [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+ [IRC] Oikarinen, J. and D. Reed, "Internet Relay Chat
+ Protocol", RFC 1459, May 1993.
+
+ [IRC-ARCH] Kalt, C., "Internet Relay Chat: Architecture", RFC 2810,
+ April 2000.
+
+ [IRC-CLIENT] Kalt, C., "Internet Relay Chat: Client Protocol", RFC
+ 2812, April 2000.
+
+ [IRC-SERVER] Kalt, C., "Internet Relay Chat: Server Protocol", RFC
+ 2813, April 2000.
+
+11. Author's Address
+
+ Christophe Kalt
+ 99 Teaneck Rd, Apt #117
+ Ridgefield Park, NJ 07660
+ USA
+
+ EMail: kalt@stealth.net
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Kalt Informational [Page 18]
+
+RFC 2811 Internet Relay Chat: Channel Management April 2000
+
+
+12. Full Copyright Statement
+
+ Copyright (C) The Internet Society (2000). All Rights Reserved.
+
+ This document and translations of it may be copied and furnished to
+ others, and derivative works that comment on or otherwise explain it
+ or assist in its implementation may be prepared, copied, published
+ and distributed, in whole or in part, without restriction of any
+ kind, provided that the above copyright notice and this paragraph are
+ included on all such copies and derivative works. However, this
+ document itself may not be modified in any way, such as by removing
+ the copyright notice or references to the Internet Society or other
+ Internet organizations, except as needed for the purpose of
+ developing Internet standards in which case the procedures for
+ copyrights defined in the Internet Standards process must be
+ followed, or as required to translate it into languages other than
+ English.
+
+ The limited permissions granted above are perpetual and will not be
+ revoked by the Internet Society or its successors or assigns.
+
+ This document and the information contained herein is provided on an
+ "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
+ TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
+ BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
+ HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
+ MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+Acknowledgement
+
+ Funding for the RFC Editor function is currently provided by the
+ Internet Society.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Kalt Informational [Page 19]
+
diff --git a/doc/rfcs/rfc2812.txt b/doc/rfcs/rfc2812.txt
new file mode 100644
index 0000000..7f1b162
--- /dev/null
+++ b/doc/rfcs/rfc2812.txt
@@ -0,0 +1,3531 @@
+
+
+
+
+
+
+Network Working Group C. Kalt
+Request for Comments: 2812 April 2000
+Updates: 1459
+Category: Informational
+
+
+ Internet Relay Chat: Client Protocol
+
+Status of this Memo
+
+ This memo provides information for the Internet community. It does
+ not specify an Internet standard of any kind. Distribution of this
+ memo is unlimited.
+
+Copyright Notice
+
+ Copyright (C) The Internet Society (2000). All Rights Reserved.
+
+IESG NOTE:
+
+ The IRC protocol itself enables several possibilities of transferring
+ data between clients, and just like with other transfer mechanisms
+ like email, the receiver of the data has to be careful about how the
+ data is handled. For more information on security issues with the IRC
+ protocol, see for example http://www.irchelp.org/irchelp/security/.
+
+Abstract
+
+ The IRC (Internet Relay Chat) protocol is for use with text based
+ conferencing; the simplest client being any socket program capable of
+ connecting to the server.
+
+ This document defines the Client Protocol, and assumes that the
+ reader is familiar with the IRC Architecture [IRC-ARCH].
+
+Table of Contents
+
+ 1. Labels ..................................................... 3
+ 1.1 Servers ................................................ 3
+ 1.2 Clients ................................................ 3
+ 1.2.1 Users ............................................. 4
+ 1.2.1.1 Operators .................................... 4
+ 1.2.2 Services .......................................... 4
+ 1.3 Channels ............................................... 4
+ 2. The IRC Client Specification ............................... 5
+ 2.1 Overview ............................................... 5
+ 2.2 Character codes ........................................ 5
+ 2.3 Messages ............................................... 5
+
+
+
+Kalt Informational [Page 1]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ 2.3.1 Message format in Augmented BNF ................... 6
+ 2.4 Numeric replies ........................................ 8
+ 2.5 Wildcard expressions ................................... 9
+ 3. Message Details ............................................ 9
+ 3.1 Connection Registration ................................ 10
+ 3.1.1 Password message .................................. 10
+ 3.1.2 Nick message ...................................... 10
+ 3.1.3 User message ...................................... 11
+ 3.1.4 Oper message ...................................... 12
+ 3.1.5 User mode message ................................. 12
+ 3.1.6 Service message ................................... 13
+ 3.1.7 Quit .............................................. 14
+ 3.1.8 Squit ............................................. 15
+ 3.2 Channel operations ..................................... 15
+ 3.2.1 Join message ...................................... 16
+ 3.2.2 Part message ...................................... 17
+ 3.2.3 Channel mode message .............................. 18
+ 3.2.4 Topic message ..................................... 19
+ 3.2.5 Names message ..................................... 20
+ 3.2.6 List message ...................................... 21
+ 3.2.7 Invite message .................................... 21
+ 3.2.8 Kick command ...................................... 22
+ 3.3 Sending messages ....................................... 23
+ 3.3.1 Private messages .................................. 23
+ 3.3.2 Notice ............................................ 24
+ 3.4 Server queries and commands ............................ 25
+ 3.4.1 Motd message ...................................... 25
+ 3.4.2 Lusers message .................................... 25
+ 3.4.3 Version message ................................... 26
+ 3.4.4 Stats message ..................................... 26
+ 3.4.5 Links message ..................................... 27
+ 3.4.6 Time message ...................................... 28
+ 3.4.7 Connect message ................................... 28
+ 3.4.8 Trace message ..................................... 29
+ 3.4.9 Admin command ..................................... 30
+ 3.4.10 Info command ...................................... 31
+ 3.5 Service Query and Commands ............................. 31
+ 3.5.1 Servlist message .................................. 31
+ 3.5.2 Squery ............................................ 32
+ 3.6 User based queries ..................................... 32
+ 3.6.1 Who query ......................................... 32
+ 3.6.2 Whois query ....................................... 33
+ 3.6.3 Whowas ............................................ 34
+ 3.7 Miscellaneous messages ................................. 34
+ 3.7.1 Kill message ...................................... 35
+ 3.7.2 Ping message ...................................... 36
+ 3.7.3 Pong message ...................................... 37
+ 3.7.4 Error ............................................. 37
+
+
+
+Kalt Informational [Page 2]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ 4. Optional features .......................................... 38
+ 4.1 Away ................................................... 38
+ 4.2 Rehash message ......................................... 39
+ 4.3 Die message ............................................ 39
+ 4.4 Restart message ........................................ 40
+ 4.5 Summon message ......................................... 40
+ 4.6 Users .................................................. 41
+ 4.7 Operwall message ....................................... 41
+ 4.8 Userhost message ....................................... 42
+ 4.9 Ison message ........................................... 42
+ 5. Replies .................................................... 43
+ 5.1 Command responses ...................................... 43
+ 5.2 Error Replies .......................................... 53
+ 5.3 Reserved numerics ...................................... 59
+ 6. Current implementations .................................... 60
+ 7. Current problems ........................................... 60
+ 7.1 Nicknames .............................................. 60
+ 7.2 Limitation of wildcards ................................ 61
+ 7.3 Security considerations ................................ 61
+ 8. Current support and availability ........................... 61
+ 9. Acknowledgements ........................................... 61
+ 10. References ................................................ 62
+ 11. Author's Address .......................................... 62
+ 12. Full Copyright Statement .................................. 63
+
+1. Labels
+
+ This section defines the identifiers used for the various components
+ of the IRC protocol.
+
+1.1 Servers
+
+ Servers are uniquely identified by their name, which has a maximum
+ length of sixty three (63) characters. See the protocol grammar
+ rules (section 2.3.1) for what may and may not be used in a server
+ name.
+
+1.2 Clients
+
+ For each client all servers MUST have the following information: a
+ netwide unique identifier (whose format depends on the type of
+ client) and the server which introduced the client.
+
+
+
+
+
+
+
+
+
+Kalt Informational [Page 3]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+1.2.1 Users
+
+ Each user is distinguished from other users by a unique nickname
+ having a maximum length of nine (9) characters. See the protocol
+ grammar rules (section 2.3.1) for what may and may not be used in a
+ nickname.
+
+ While the maximum length is limited to nine characters, clients
+ SHOULD accept longer strings as they may become used in future
+ evolutions of the protocol.
+
+1.2.1.1 Operators
+
+ To allow a reasonable amount of order to be kept within the IRC
+ network, a special class of users (operators) is allowed to perform
+ general maintenance functions on the network. Although the powers
+ granted to an operator can be considered as 'dangerous', they are
+ nonetheless often necessary. Operators SHOULD be able to perform
+ basic network tasks such as disconnecting and reconnecting servers as
+ needed. In recognition of this need, the protocol discussed herein
+ provides for operators only to be able to perform such functions.
+ See sections 3.1.8 (SQUIT) and 3.4.7 (CONNECT).
+
+ A more controversial power of operators is the ability to remove a
+ user from the connected network by 'force', i.e., operators are able
+ to close the connection between any client and server. The
+ justification for this is very delicate since its abuse is both
+ destructive and annoying, and its benefits close to inexistent. For
+ further details on this type of action, see section 3.7.1 (KILL).
+
+1.2.2 Services
+
+ Each service is distinguished from other services by a service name
+ composed of a nickname and a server name. As for users, the nickname
+ has a maximum length of nine (9) characters. See the protocol
+ grammar rules (section 2.3.1) for what may and may not be used in a
+ nickname.
+
+1.3 Channels
+
+ Channels names are strings (beginning with a '&', '#', '+' or '!'
+ character) of length up to fifty (50) characters. Apart from the
+ requirement that the first character is either '&', '#', '+' or '!',
+ the only restriction on a channel name is that it SHALL NOT contain
+ any spaces (' '), a control G (^G or ASCII 7), a comma (','). Space
+ is used as parameter separator and command is used as a list item
+ separator by the protocol). A colon (':') can also be used as a
+ delimiter for the channel mask. Channel names are case insensitive.
+
+
+
+Kalt Informational [Page 4]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ See the protocol grammar rules (section 2.3.1) for the exact syntax
+ of a channel name.
+
+ Each prefix characterizes a different channel type. The definition
+ of the channel types is not relevant to the client-server protocol
+ and thus it is beyond the scope of this document. More details can
+ be found in "Internet Relay Chat: Channel Management" [IRC-CHAN].
+
+2. The IRC Client Specification
+
+2.1 Overview
+
+ The protocol as described herein is for use only with client to
+ server connections when the client registers as a user.
+
+2.2 Character codes
+
+ No specific character set is specified. The protocol is based on a
+ set of codes which are composed of eight (8) bits, making up an
+ octet. Each message may be composed of any number of these octets;
+ however, some octet values are used for control codes, which act as
+ message delimiters.
+
+ Regardless of being an 8-bit protocol, the delimiters and keywords
+ are such that protocol is mostly usable from US-ASCII terminal and a
+ telnet connection.
+
+ Because of IRC's Scandinavian origin, the characters {}|^ are
+ considered to be the lower case equivalents of the characters []\~,
+ respectively. This is a critical issue when determining the
+ equivalence of two nicknames or channel names.
+
+2.3 Messages
+
+ Servers and clients send each other messages, which may or may not
+ generate a reply. If the message contains a valid command, as
+ described in later sections, the client should expect a reply as
+ specified but it is not advised to wait forever for the reply; client
+ to server and server to server communication is essentially
+ asynchronous by nature.
+
+ Each IRC message may consist of up to three main parts: the prefix
+ (OPTIONAL), the command, and the command parameters (maximum of
+ fifteen (15)). The prefix, command, and all parameters are separated
+ by one ASCII space character (0x20) each.
+
+
+
+
+
+
+Kalt Informational [Page 5]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ The presence of a prefix is indicated with a single leading ASCII
+ colon character (':', 0x3b), which MUST be the first character of the
+ message itself. There MUST be NO gap (whitespace) between the colon
+ and the prefix. The prefix is used by servers to indicate the true
+ origin of the message. If the prefix is missing from the message, it
+ is assumed to have originated from the connection from which it was
+ received from. Clients SHOULD NOT use a prefix when sending a
+ message; if they use one, the only valid prefix is the registered
+ nickname associated with the client.
+
+ The command MUST either be a valid IRC command or a three (3) digit
+ number represented in ASCII text.
+
+ IRC messages are always lines of characters terminated with a CR-LF
+ (Carriage Return - Line Feed) pair, and these messages SHALL NOT
+ exceed 512 characters in length, counting all characters including
+ the trailing CR-LF. Thus, there are 510 characters maximum allowed
+ for the command and its parameters. There is no provision for
+ continuation of message lines. See section 6 for more details about
+ current implementations.
+
+2.3.1 Message format in Augmented BNF
+
+ The protocol messages must be extracted from the contiguous stream of
+ octets. The current solution is to designate two characters, CR and
+ LF, as message separators. Empty messages are silently ignored,
+ which permits use of the sequence CR-LF between messages without
+ extra problems.
+
+ The extracted message is parsed into the components <prefix>,
+ <command> and list of parameters (<params>).
+
+ The Augmented BNF representation for this is:
+
+ message = [ ":" prefix SPACE ] command [ params ] crlf
+ prefix = servername / ( nickname [ [ "!" user ] "@" host ] )
+ command = 1*letter / 3digit
+ params = *14( SPACE middle ) [ SPACE ":" trailing ]
+ =/ 14( SPACE middle ) [ SPACE [ ":" ] trailing ]
+
+ nospcrlfcl = %x01-09 / %x0B-0C / %x0E-1F / %x21-39 / %x3B-FF
+ ; any octet except NUL, CR, LF, " " and ":"
+ middle = nospcrlfcl *( ":" / nospcrlfcl )
+ trailing = *( ":" / " " / nospcrlfcl )
+
+ SPACE = %x20 ; space character
+ crlf = %x0D %x0A ; "carriage return" "linefeed"
+
+
+
+
+Kalt Informational [Page 6]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ NOTES:
+ 1) After extracting the parameter list, all parameters are equal
+ whether matched by <middle> or <trailing>. <trailing> is just a
+ syntactic trick to allow SPACE within the parameter.
+
+ 2) The NUL (%x00) character is not special in message framing, and
+ basically could end up inside a parameter, but it would cause
+ extra complexities in normal C string handling. Therefore, NUL
+ is not allowed within messages.
+
+ Most protocol messages specify additional semantics and syntax for
+ the extracted parameter strings dictated by their position in the
+ list. For example, many server commands will assume that the first
+ parameter after the command is the list of targets, which can be
+ described with:
+
+ target = nickname / server
+ msgtarget = msgto *( "," msgto )
+ msgto = channel / ( user [ "%" host ] "@" servername )
+ msgto =/ ( user "%" host ) / targetmask
+ msgto =/ nickname / ( nickname "!" user "@" host )
+ channel = ( "#" / "+" / ( "!" channelid ) / "&" ) chanstring
+ [ ":" chanstring ]
+ servername = hostname
+ host = hostname / hostaddr
+ hostname = shortname *( "." shortname )
+ shortname = ( letter / digit ) *( letter / digit / "-" )
+ *( letter / digit )
+ ; as specified in RFC 1123 [HNAME]
+ hostaddr = ip4addr / ip6addr
+ ip4addr = 1*3digit "." 1*3digit "." 1*3digit "." 1*3digit
+ ip6addr = 1*hexdigit 7( ":" 1*hexdigit )
+ ip6addr =/ "0:0:0:0:0:" ( "0" / "FFFF" ) ":" ip4addr
+ nickname = ( letter / special ) *8( letter / digit / special / "-" )
+ targetmask = ( "$" / "#" ) mask
+ ; see details on allowed masks in section 3.3.1
+ chanstring = %x01-07 / %x08-09 / %x0B-0C / %x0E-1F / %x21-2B
+ chanstring =/ %x2D-39 / %x3B-FF
+ ; any octet except NUL, BELL, CR, LF, " ", "," and ":"
+ channelid = 5( %x41-5A / digit ) ; 5( A-Z / 0-9 )
+
+
+
+
+
+
+
+
+
+
+
+Kalt Informational [Page 7]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ Other parameter syntaxes are:
+
+ user = 1*( %x01-09 / %x0B-0C / %x0E-1F / %x21-3F / %x41-FF )
+ ; any octet except NUL, CR, LF, " " and "@"
+ key = 1*23( %x01-05 / %x07-08 / %x0C / %x0E-1F / %x21-7F )
+ ; any 7-bit US_ASCII character,
+ ; except NUL, CR, LF, FF, h/v TABs, and " "
+ letter = %x41-5A / %x61-7A ; A-Z / a-z
+ digit = %x30-39 ; 0-9
+ hexdigit = digit / "A" / "B" / "C" / "D" / "E" / "F"
+ special = %x5B-60 / %x7B-7D
+ ; "[", "]", "\", "`", "_", "^", "{", "|", "}"
+
+ NOTES:
+ 1) The <hostaddr> syntax is given here for the sole purpose of
+ indicating the format to follow for IP addresses. This
+ reflects the fact that the only available implementations of
+ this protocol uses TCP/IP as underlying network protocol but is
+ not meant to prevent other protocols to be used.
+
+ 2) <hostname> has a maximum length of 63 characters. This is a
+ limitation of the protocol as internet hostnames (in
+ particular) can be longer. Such restriction is necessary
+ because IRC messages are limited to 512 characters in length.
+ Clients connecting from a host which name is longer than 63
+ characters are registered using the host (numeric) address
+ instead of the host name.
+
+ 3) Some parameters used in the following sections of this
+ documents are not defined here as there is nothing specific
+ about them besides the name that is used for convenience.
+ These parameters follow the general syntax defined for
+ <params>.
+
+2.4 Numeric replies
+
+ Most of the messages sent to the server generate a reply of some
+ sort. The most common reply is the numeric reply, used for both
+ errors and normal replies. The numeric reply MUST be sent as one
+ message consisting of the sender prefix, the three-digit numeric, and
+ the target of the reply. A numeric reply is not allowed to originate
+ from a client. In all other respects, a numeric reply is just like a
+ normal message, except that the keyword is made up of 3 numeric
+ digits rather than a string of letters. A list of different replies
+ is supplied in section 5 (Replies).
+
+
+
+
+
+
+Kalt Informational [Page 8]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+2.5 Wildcard expressions
+
+ When wildcards are allowed in a string, it is referred as a "mask".
+
+ For string matching purposes, the protocol allows the use of two
+ special characters: '?' (%x3F) to match one and only one character,
+ and '*' (%x2A) to match any number of any characters. These two
+ characters can be escaped using the character '\' (%x5C).
+
+ The Augmented BNF syntax for this is:
+
+ mask = *( nowild / noesc wildone / noesc wildmany )
+ wildone = %x3F
+ wildmany = %x2A
+ nowild = %x01-29 / %x2B-3E / %x40-FF
+ ; any octet except NUL, "*", "?"
+ noesc = %x01-5B / %x5D-FF
+ ; any octet except NUL and "\"
+ matchone = %x01-FF
+ ; matches wildone
+ matchmany = *matchone
+ ; matches wildmany
+
+ Examples:
+
+ a?c ; Matches any string of 3 characters in length starting
+ with "a" and ending with "c"
+
+ a*c ; Matches any string of at least 2 characters in length
+ starting with "a" and ending with "c"
+
+3. Message Details
+
+ On the following pages there are descriptions of each message
+ recognized by the IRC server and client. All commands described in
+ this section MUST be implemented by any server for this protocol.
+
+ Where the reply ERR_NOSUCHSERVER is returned, it means that the
+ target of the message could not be found. The server MUST NOT send
+ any other replies after this error for that command.
+
+ The server to which a client is connected is required to parse the
+ complete message, and return any appropriate errors.
+
+ If multiple parameters is presented, then each MUST be checked for
+ validity and appropriate responses MUST be sent back to the client.
+ In the case of incorrect messages which use parameter lists with
+ comma as an item separator, a reply MUST be sent for each item.
+
+
+
+Kalt Informational [Page 9]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+3.1 Connection Registration
+
+ The commands described here are used to register a connection with an
+ IRC server as a user as well as to correctly disconnect.
+
+ A "PASS" command is not required for a client connection to be
+ registered, but it MUST precede the latter of the NICK/USER
+ combination (for a user connection) or the SERVICE command (for a
+ service connection). The RECOMMENDED order for a client to register
+ is as follows:
+
+ 1. Pass message
+ 2. Nick message 2. Service message
+ 3. User message
+
+ Upon success, the client will receive an RPL_WELCOME (for users) or
+ RPL_YOURESERVICE (for services) message indicating that the
+ connection is now registered and known the to the entire IRC network.
+ The reply message MUST contain the full client identifier upon which
+ it was registered.
+
+3.1.1 Password message
+
+ Command: PASS
+ Parameters: <password>
+
+ The PASS command is used to set a 'connection password'. The
+ optional password can and MUST be set before any attempt to register
+ the connection is made. Currently this requires that user send a
+ PASS command before sending the NICK/USER combination.
+
+ Numeric Replies:
+
+ ERR_NEEDMOREPARAMS ERR_ALREADYREGISTRED
+
+ Example:
+
+ PASS secretpasswordhere
+
+3.1.2 Nick message
+
+
+ Command: NICK
+ Parameters: <nickname>
+
+ NICK command is used to give user a nickname or change the existing
+ one.
+
+
+
+
+Kalt Informational [Page 10]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ Numeric Replies:
+
+ ERR_NONICKNAMEGIVEN ERR_ERRONEUSNICKNAME
+ ERR_NICKNAMEINUSE ERR_NICKCOLLISION
+ ERR_UNAVAILRESOURCE ERR_RESTRICTED
+
+ Examples:
+
+ NICK Wiz ; Introducing new nick "Wiz" if session is
+ still unregistered, or user changing his
+ nickname to "Wiz"
+
+ :WiZ!jto@tolsun.oulu.fi NICK Kilroy
+ ; Server telling that WiZ changed his
+ nickname to Kilroy.
+
+3.1.3 User message
+
+ Command: USER
+ Parameters: <user> <mode> <unused> <realname>
+
+ The USER command is used at the beginning of connection to specify
+ the username, hostname and realname of a new user.
+
+ The <mode> parameter should be a numeric, and can be used to
+ automatically set user modes when registering with the server. This
+ parameter is a bitmask, with only 2 bits having any signification: if
+ the bit 2 is set, the user mode 'w' will be set and if the bit 3 is
+ set, the user mode 'i' will be set. (See Section 3.1.5 "User
+ Modes").
+
+ The <realname> may contain space characters.
+
+ Numeric Replies:
+
+ ERR_NEEDMOREPARAMS ERR_ALREADYREGISTRED
+
+ Example:
+
+ USER guest 0 * :Ronnie Reagan ; User registering themselves with a
+ username of "guest" and real name
+ "Ronnie Reagan".
+
+ USER guest 8 * :Ronnie Reagan ; User registering themselves with a
+ username of "guest" and real name
+ "Ronnie Reagan", and asking to be set
+ invisible.
+
+
+
+
+Kalt Informational [Page 11]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+3.1.4 Oper message
+
+ Command: OPER
+ Parameters: <name> <password>
+
+ A normal user uses the OPER command to obtain operator privileges.
+ The combination of <name> and <password> are REQUIRED to gain
+ Operator privileges. Upon success, the user will receive a MODE
+ message (see section 3.1.5) indicating the new user modes.
+
+ Numeric Replies:
+
+ ERR_NEEDMOREPARAMS RPL_YOUREOPER
+ ERR_NOOPERHOST ERR_PASSWDMISMATCH
+
+ Example:
+
+ OPER foo bar ; Attempt to register as an operator
+ using a username of "foo" and "bar"
+ as the password.
+
+3.1.5 User mode message
+
+ Command: MODE
+ Parameters: <nickname>
+ *( ( "+" / "-" ) *( "i" / "w" / "o" / "O" / "r" ) )
+
+ The user MODE's are typically changes which affect either how the
+ client is seen by others or what 'extra' messages the client is sent.
+
+ A user MODE command MUST only be accepted if both the sender of the
+ message and the nickname given as a parameter are both the same. If
+ no other parameter is given, then the server will return the current
+ settings for the nick.
+
+ The available modes are as follows:
+
+ a - user is flagged as away;
+ i - marks a users as invisible;
+ w - user receives wallops;
+ r - restricted user connection;
+ o - operator flag;
+ O - local operator flag;
+ s - marks a user for receipt of server notices.
+
+ Additional modes may be available later on.
+
+
+
+
+
+Kalt Informational [Page 12]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ The flag 'a' SHALL NOT be toggled by the user using the MODE command,
+ instead use of the AWAY command is REQUIRED.
+
+ If a user attempts to make themselves an operator using the "+o" or
+ "+O" flag, the attempt SHOULD be ignored as users could bypass the
+ authentication mechanisms of the OPER command. There is no
+ restriction, however, on anyone `deopping' themselves (using "-o" or
+ "-O").
+
+ On the other hand, if a user attempts to make themselves unrestricted
+ using the "-r" flag, the attempt SHOULD be ignored. There is no
+ restriction, however, on anyone `deopping' themselves (using "+r").
+ This flag is typically set by the server upon connection for
+ administrative reasons. While the restrictions imposed are left up
+ to the implementation, it is typical that a restricted user not be
+ allowed to change nicknames, nor make use of the channel operator
+ status on channels.
+
+ The flag 's' is obsolete but MAY still be used.
+
+ Numeric Replies:
+
+ ERR_NEEDMOREPARAMS ERR_USERSDONTMATCH
+ ERR_UMODEUNKNOWNFLAG RPL_UMODEIS
+
+ Examples:
+
+ MODE WiZ -w ; Command by WiZ to turn off
+ reception of WALLOPS messages.
+
+ MODE Angel +i ; Command from Angel to make herself
+ invisible.
+
+ MODE WiZ -o ; WiZ 'deopping' (removing operator
+ status).
+
+3.1.6 Service message
+
+ Command: SERVICE
+ Parameters: <nickname> <reserved> <distribution> <type>
+ <reserved> <info>
+
+ The SERVICE command to register a new service. Command parameters
+ specify the service nickname, distribution, type and info of a new
+ service.
+
+
+
+
+
+
+Kalt Informational [Page 13]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ The <distribution> parameter is used to specify the visibility of a
+ service. The service may only be known to servers which have a name
+ matching the distribution. For a matching server to have knowledge
+ of the service, the network path between that server and the server
+ on which the service is connected MUST be composed of servers which
+ names all match the mask.
+
+ The <type> parameter is currently reserved for future usage.
+
+ Numeric Replies:
+
+ ERR_ALREADYREGISTRED ERR_NEEDMOREPARAMS
+ ERR_ERRONEUSNICKNAME
+ RPL_YOURESERVICE RPL_YOURHOST
+ RPL_MYINFO
+
+ Example:
+
+ SERVICE dict * *.fr 0 0 :French Dictionary ; Service registering
+ itself with a name of "dict". This
+ service will only be available on
+ servers which name matches "*.fr".
+
+3.1.7 Quit
+
+ Command: QUIT
+ Parameters: [ <Quit Message> ]
+
+ A client session is terminated with a quit message. The server
+ acknowledges this by sending an ERROR message to the client.
+
+ Numeric Replies:
+
+ None.
+
+ Example:
+
+ QUIT :Gone to have lunch ; Preferred message format.
+
+ :syrk!kalt@millennium.stealth.net QUIT :Gone to have lunch ; User
+ syrk has quit IRC to have lunch.
+
+
+
+
+
+
+
+
+
+
+Kalt Informational [Page 14]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+3.1.8 Squit
+
+ Command: SQUIT
+ Parameters: <server> <comment>
+
+ The SQUIT command is available only to operators. It is used to
+ disconnect server links. Also servers can generate SQUIT messages on
+ error conditions. A SQUIT message may also target a remote server
+ connection. In this case, the SQUIT message will simply be sent to
+ the remote server without affecting the servers in between the
+ operator and the remote server.
+
+ The <comment> SHOULD be supplied by all operators who execute a SQUIT
+ for a remote server. The server ordered to disconnect its peer
+ generates a WALLOPS message with <comment> included, so that other
+ users may be aware of the reason of this action.
+
+ Numeric replies:
+
+ ERR_NOPRIVILEGES ERR_NOSUCHSERVER
+ ERR_NEEDMOREPARAMS
+
+ Examples:
+
+ SQUIT tolsun.oulu.fi :Bad Link ? ; Command to uplink of the server
+ tolson.oulu.fi to terminate its
+ connection with comment "Bad Link".
+
+ :Trillian SQUIT cm22.eng.umd.edu :Server out of control ; Command
+ from Trillian from to disconnect
+ "cm22.eng.umd.edu" from the net with
+ comment "Server out of control".
+
+3.2 Channel operations
+
+ This group of messages is concerned with manipulating channels, their
+ properties (channel modes), and their contents (typically users).
+ For this reason, these messages SHALL NOT be made available to
+ services.
+
+ All of these messages are requests which will or will not be granted
+ by the server. The server MUST send a reply informing the user
+ whether the request was granted, denied or generated an error. When
+ the server grants the request, the message is typically sent back
+ (eventually reformatted) to the user with the prefix set to the user
+ itself.
+
+
+
+
+
+Kalt Informational [Page 15]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ The rules governing how channels are managed are enforced by the
+ servers. These rules are beyond the scope of this document. More
+ details are found in "Internet Relay Chat: Channel Management" [IRC-
+ CHAN].
+
+3.2.1 Join message
+
+ Command: JOIN
+ Parameters: ( <channel> *( "," <channel> ) [ <key> *( "," <key> ) ] )
+ / "0"
+
+ The JOIN command is used by a user to request to start listening to
+ the specific channel. Servers MUST be able to parse arguments in the
+ form of a list of target, but SHOULD NOT use lists when sending JOIN
+ messages to clients.
+
+ Once a user has joined a channel, he receives information about
+ all commands his server receives affecting the channel. This
+ includes JOIN, MODE, KICK, PART, QUIT and of course PRIVMSG/NOTICE.
+ This allows channel members to keep track of the other channel
+ members, as well as channel modes.
+
+ If a JOIN is successful, the user receives a JOIN message as
+ confirmation and is then sent the channel's topic (using RPL_TOPIC) and
+ the list of users who are on the channel (using RPL_NAMREPLY), which
+ MUST include the user joining.
+
+ Note that this message accepts a special argument ("0"), which is
+ a special request to leave all channels the user is currently a member
+ of. The server will process this message as if the user had sent
+ a PART command (See Section 3.2.2) for each channel he is a member
+ of.
+
+ Numeric Replies:
+
+ ERR_NEEDMOREPARAMS ERR_BANNEDFROMCHAN
+ ERR_INVITEONLYCHAN ERR_BADCHANNELKEY
+ ERR_CHANNELISFULL ERR_BADCHANMASK
+ ERR_NOSUCHCHANNEL ERR_TOOMANYCHANNELS
+ ERR_TOOMANYTARGETS ERR_UNAVAILRESOURCE
+ RPL_TOPIC
+
+ Examples:
+
+ JOIN #foobar ; Command to join channel #foobar.
+
+ JOIN &foo fubar ; Command to join channel &foo using
+ key "fubar".
+
+
+
+Kalt Informational [Page 16]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ JOIN #foo,&bar fubar ; Command to join channel #foo using
+ key "fubar" and &bar using no key.
+
+ JOIN #foo,#bar fubar,foobar ; Command to join channel #foo using
+ key "fubar", and channel #bar using
+ key "foobar".
+
+ JOIN #foo,#bar ; Command to join channels #foo and
+ #bar.
+
+ JOIN 0 ; Leave all currently joined
+ channels.
+
+ :WiZ!jto@tolsun.oulu.fi JOIN #Twilight_zone ; JOIN message from WiZ
+ on channel #Twilight_zone
+
+3.2.2 Part message
+
+ Command: PART
+ Parameters: <channel> *( "," <channel> ) [ <Part Message> ]
+
+ The PART command causes the user sending the message to be removed
+ from the list of active members for all given channels listed in the
+ parameter string. If a "Part Message" is given, this will be sent
+ instead of the default message, the nickname. This request is always
+ granted by the server.
+
+ Servers MUST be able to parse arguments in the form of a list of
+ target, but SHOULD NOT use lists when sending PART messages to
+ clients.
+
+ Numeric Replies:
+
+ ERR_NEEDMOREPARAMS ERR_NOSUCHCHANNEL
+ ERR_NOTONCHANNEL
+
+ Examples:
+
+ PART #twilight_zone ; Command to leave channel
+ "#twilight_zone"
+
+ PART #oz-ops,&group5 ; Command to leave both channels
+ "&group5" and "#oz-ops".
+
+ :WiZ!jto@tolsun.oulu.fi PART #playzone :I lost
+ ; User WiZ leaving channel
+ "#playzone" with the message "I
+ lost".
+
+
+
+Kalt Informational [Page 17]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+3.2.3 Channel mode message
+
+ Command: MODE
+ Parameters: <channel> *( ( "-" / "+" ) *<modes> *<modeparams> )
+
+ The MODE command is provided so that users may query and change the
+ characteristics of a channel. For more details on available modes
+ and their uses, see "Internet Relay Chat: Channel Management" [IRC-
+ CHAN]. Note that there is a maximum limit of three (3) changes per
+ command for modes that take a parameter.
+
+ Numeric Replies:
+
+ ERR_NEEDMOREPARAMS ERR_KEYSET
+ ERR_NOCHANMODES ERR_CHANOPRIVSNEEDED
+ ERR_USERNOTINCHANNEL ERR_UNKNOWNMODE
+ RPL_CHANNELMODEIS
+ RPL_BANLIST RPL_ENDOFBANLIST
+ RPL_EXCEPTLIST RPL_ENDOFEXCEPTLIST
+ RPL_INVITELIST RPL_ENDOFINVITELIST
+ RPL_UNIQOPIS
+
+ The following examples are given to help understanding the syntax of
+ the MODE command, but refer to modes defined in "Internet Relay Chat:
+ Channel Management" [IRC-CHAN].
+
+ Examples:
+
+ MODE #Finnish +imI *!*@*.fi ; Command to make #Finnish channel
+ moderated and 'invite-only' with user
+ with a hostname matching *.fi
+ automatically invited.
+
+ MODE #Finnish +o Kilroy ; Command to give 'chanop' privileges
+ to Kilroy on channel #Finnish.
+
+ MODE #Finnish +v Wiz ; Command to allow WiZ to speak on
+ #Finnish.
+
+ MODE #Fins -s ; Command to remove 'secret' flag
+ from channel #Fins.
+
+ MODE #42 +k oulu ; Command to set the channel key to
+ "oulu".
+
+ MODE #42 -k oulu ; Command to remove the "oulu"
+ channel key on channel "#42".
+
+
+
+
+Kalt Informational [Page 18]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ MODE #eu-opers +l 10 ; Command to set the limit for the
+ number of users on channel
+ "#eu-opers" to 10.
+
+ :WiZ!jto@tolsun.oulu.fi MODE #eu-opers -l
+ ; User "WiZ" removing the limit for
+ the number of users on channel "#eu-
+ opers".
+
+ MODE &oulu +b ; Command to list ban masks set for
+ the channel "&oulu".
+
+ MODE &oulu +b *!*@* ; Command to prevent all users from
+ joining.
+
+ MODE &oulu +b *!*@*.edu +e *!*@*.bu.edu
+ ; Command to prevent any user from a
+ hostname matching *.edu from joining,
+ except if matching *.bu.edu
+
+ MODE #bu +be *!*@*.edu *!*@*.bu.edu
+ ; Comment to prevent any user from a
+ hostname matching *.edu from joining,
+ except if matching *.bu.edu
+
+ MODE #meditation e ; Command to list exception masks set
+ for the channel "#meditation".
+
+ MODE #meditation I ; Command to list invitations masks
+ set for the channel "#meditation".
+
+ MODE !12345ircd O ; Command to ask who the channel
+ creator for "!12345ircd" is
+
+3.2.4 Topic message
+
+ Command: TOPIC
+ Parameters: <channel> [ <topic> ]
+
+ The TOPIC command is used to change or view the topic of a channel.
+ The topic for channel <channel> is returned if there is no <topic>
+ given. If the <topic> parameter is present, the topic for that
+ channel will be changed, if this action is allowed for the user
+ requesting it. If the <topic> parameter is an empty string, the
+ topic for that channel will be removed.
+
+
+
+
+
+
+Kalt Informational [Page 19]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ Numeric Replies:
+
+ ERR_NEEDMOREPARAMS ERR_NOTONCHANNEL
+ RPL_NOTOPIC RPL_TOPIC
+ ERR_CHANOPRIVSNEEDED ERR_NOCHANMODES
+
+ Examples:
+
+ :WiZ!jto@tolsun.oulu.fi TOPIC #test :New topic ; User Wiz setting the
+ topic.
+
+ TOPIC #test :another topic ; Command to set the topic on #test
+ to "another topic".
+
+ TOPIC #test : ; Command to clear the topic on
+ #test.
+
+ TOPIC #test ; Command to check the topic for
+ #test.
+
+3.2.5 Names message
+
+ Command: NAMES
+ Parameters: [ <channel> *( "," <channel> ) [ <target> ] ]
+
+ By using the NAMES command, a user can list all nicknames that are
+ visible to him. For more details on what is visible and what is not,
+ see "Internet Relay Chat: Channel Management" [IRC-CHAN]. The
+ <channel> parameter specifies which channel(s) to return information
+ about. There is no error reply for bad channel names.
+
+ If no <channel> parameter is given, a list of all channels and their
+ occupants is returned. At the end of this list, a list of users who
+ are visible but either not on any channel or not on a visible channel
+ are listed as being on `channel' "*".
+
+ If the <target> parameter is specified, the request is forwarded to
+ that server which will generate the reply.
+
+ Wildcards are allowed in the <target> parameter.
+
+ Numerics:
+
+ ERR_TOOMANYMATCHES ERR_NOSUCHSERVER
+ RPL_NAMREPLY RPL_ENDOFNAMES
+
+
+
+
+
+
+Kalt Informational [Page 20]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ Examples:
+
+ NAMES #twilight_zone,#42 ; Command to list visible users on
+ #twilight_zone and #42
+
+ NAMES ; Command to list all visible
+ channels and users
+
+3.2.6 List message
+
+ Command: LIST
+ Parameters: [ <channel> *( "," <channel> ) [ <target> ] ]
+
+ The list command is used to list channels and their topics. If the
+ <channel> parameter is used, only the status of that channel is
+ displayed.
+
+ If the <target> parameter is specified, the request is forwarded to
+ that server which will generate the reply.
+
+ Wildcards are allowed in the <target> parameter.
+
+ Numeric Replies:
+
+ ERR_TOOMANYMATCHES ERR_NOSUCHSERVER
+ RPL_LIST RPL_LISTEND
+
+ Examples:
+
+ LIST ; Command to list all channels.
+
+ LIST #twilight_zone,#42 ; Command to list channels
+ #twilight_zone and #42
+
+3.2.7 Invite message
+
+ Command: INVITE
+ Parameters: <nickname> <channel>
+
+ The INVITE command is used to invite a user to a channel. The
+ parameter <nickname> is the nickname of the person to be invited to
+ the target channel <channel>. There is no requirement that the
+ channel the target user is being invited to must exist or be a valid
+ channel. However, if the channel exists, only members of the channel
+ are allowed to invite other users. When the channel has invite-only
+ flag set, only channel operators may issue INVITE command.
+
+
+
+
+
+Kalt Informational [Page 21]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ Only the user inviting and the user being invited will receive
+ notification of the invitation. Other channel members are not
+ notified. (This is unlike the MODE changes, and is occasionally the
+ source of trouble for users.)
+
+ Numeric Replies:
+
+ ERR_NEEDMOREPARAMS ERR_NOSUCHNICK
+ ERR_NOTONCHANNEL ERR_USERONCHANNEL
+ ERR_CHANOPRIVSNEEDED
+ RPL_INVITING RPL_AWAY
+
+ Examples:
+
+ :Angel!wings@irc.org INVITE Wiz #Dust
+
+ ; Message to WiZ when he has been
+ invited by user Angel to channel
+ #Dust
+
+ INVITE Wiz #Twilight_Zone ; Command to invite WiZ to
+ #Twilight_zone
+
+3.2.8 Kick command
+
+ Command: KICK
+ Parameters: <channel> *( "," <channel> ) <user> *( "," <user> )
+ [<comment>]
+
+ The KICK command can be used to request the forced removal of a user
+ from a channel. It causes the <user> to PART from the <channel> by
+ force. For the message to be syntactically correct, there MUST be
+ either one channel parameter and multiple user parameter, or as many
+ channel parameters as there are user parameters. If a "comment" is
+ given, this will be sent instead of the default message, the nickname
+ of the user issuing the KICK.
+
+ The server MUST NOT send KICK messages with multiple channels or
+ users to clients. This is necessarily to maintain backward
+ compatibility with old client software.
+
+ Numeric Replies:
+
+ ERR_NEEDMOREPARAMS ERR_NOSUCHCHANNEL
+ ERR_BADCHANMASK ERR_CHANOPRIVSNEEDED
+ ERR_USERNOTINCHANNEL ERR_NOTONCHANNEL
+
+
+
+
+
+Kalt Informational [Page 22]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ Examples:
+
+ KICK &Melbourne Matthew ; Command to kick Matthew from
+ &Melbourne
+
+ KICK #Finnish John :Speaking English
+ ; Command to kick John from #Finnish
+ using "Speaking English" as the
+ reason (comment).
+
+ :WiZ!jto@tolsun.oulu.fi KICK #Finnish John
+ ; KICK message on channel #Finnish
+ from WiZ to remove John from channel
+
+3.3 Sending messages
+
+ The main purpose of the IRC protocol is to provide a base for clients
+ to communicate with each other. PRIVMSG, NOTICE and SQUERY
+ (described in Section 3.5 on Service Query and Commands) are the only
+ messages available which actually perform delivery of a text message
+ from one client to another - the rest just make it possible and try
+ to ensure it happens in a reliable and structured manner.
+
+3.3.1 Private messages
+
+ Command: PRIVMSG
+ Parameters: <msgtarget> <text to be sent>
+
+ PRIVMSG is used to send private messages between users, as well as to
+ send messages to channels. <msgtarget> is usually the nickname of
+ the recipient of the message, or a channel name.
+
+ The <msgtarget> parameter may also be a host mask (#<mask>) or server
+ mask ($<mask>). In both cases the server will only send the PRIVMSG
+ to those who have a server or host matching the mask. The mask MUST
+ have at least 1 (one) "." in it and no wildcards following the last
+ ".". This requirement exists to prevent people sending messages to
+ "#*" or "$*", which would broadcast to all users. Wildcards are the
+ '*' and '?' characters. This extension to the PRIVMSG command is
+ only available to operators.
+
+ Numeric Replies:
+
+ ERR_NORECIPIENT ERR_NOTEXTTOSEND
+ ERR_CANNOTSENDTOCHAN ERR_NOTOPLEVEL
+ ERR_WILDTOPLEVEL ERR_TOOMANYTARGETS
+ ERR_NOSUCHNICK
+ RPL_AWAY
+
+
+
+Kalt Informational [Page 23]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ Examples:
+
+ :Angel!wings@irc.org PRIVMSG Wiz :Are you receiving this message ?
+ ; Message from Angel to Wiz.
+
+ PRIVMSG Angel :yes I'm receiving it !
+ ; Command to send a message to Angel.
+
+ PRIVMSG jto@tolsun.oulu.fi :Hello !
+ ; Command to send a message to a user
+ on server tolsun.oulu.fi with
+ username of "jto".
+
+ PRIVMSG kalt%millennium.stealth.net@irc.stealth.net :Are you a frog?
+ ; Message to a user on server
+ irc.stealth.net with username of
+ "kalt", and connected from the host
+ millennium.stealth.net.
+
+ PRIVMSG kalt%millennium.stealth.net :Do you like cheese?
+ ; Message to a user on the local
+ server with username of "kalt", and
+ connected from the host
+ millennium.stealth.net.
+
+ PRIVMSG Wiz!jto@tolsun.oulu.fi :Hello !
+ ; Message to the user with nickname
+ Wiz who is connected from the host
+ tolsun.oulu.fi and has the username
+ "jto".
+
+ PRIVMSG $*.fi :Server tolsun.oulu.fi rebooting.
+ ; Message to everyone on a server
+ which has a name matching *.fi.
+
+ PRIVMSG #*.edu :NSFNet is undergoing work, expect interruptions
+ ; Message to all users who come from
+ a host which has a name matching
+ *.edu.
+
+3.3.2 Notice
+
+ Command: NOTICE
+ Parameters: <msgtarget> <text>
+
+ The NOTICE command is used similarly to PRIVMSG. The difference
+ between NOTICE and PRIVMSG is that automatic replies MUST NEVER be
+ sent in response to a NOTICE message. This rule applies to servers
+
+
+
+Kalt Informational [Page 24]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ too - they MUST NOT send any error reply back to the client on
+ receipt of a notice. The object of this rule is to avoid loops
+ between clients automatically sending something in response to
+ something it received.
+
+ This command is available to services as well as users.
+
+ This is typically used by services, and automatons (clients with
+ either an AI or other interactive program controlling their actions).
+
+ See PRIVMSG for more details on replies and examples.
+
+3.4 Server queries and commands
+
+ The server query group of commands has been designed to return
+ information about any server which is connected to the network.
+
+ In these queries, where a parameter appears as <target>, wildcard
+ masks are usually valid. For each parameter, however, only one query
+ and set of replies is to be generated. In most cases, if a nickname
+ is given, it will mean the server to which the user is connected.
+
+ These messages typically have little value for services, it is
+ therefore RECOMMENDED to forbid services from using them.
+
+3.4.1 Motd message
+
+ Command: MOTD
+ Parameters: [ <target> ]
+
+ The MOTD command is used to get the "Message Of The Day" of the given
+ server, or current server if <target> is omitted.
+
+ Wildcards are allowed in the <target> parameter.
+
+ Numeric Replies:
+ RPL_MOTDSTART RPL_MOTD
+ RPL_ENDOFMOTD ERR_NOMOTD
+
+3.4.2 Lusers message
+
+ Command: LUSERS
+ Parameters: [ <mask> [ <target> ] ]
+
+ The LUSERS command is used to get statistics about the size of the
+ IRC network. If no parameter is given, the reply will be about the
+ whole net. If a <mask> is specified, then the reply will only
+
+
+
+
+Kalt Informational [Page 25]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ concern the part of the network formed by the servers matching the
+ mask. Finally, if the <target> parameter is specified, the request
+ is forwarded to that server which will generate the reply.
+
+ Wildcards are allowed in the <target> parameter.
+
+ Numeric Replies:
+
+ RPL_LUSERCLIENT RPL_LUSEROP
+ RPL_LUSERUNKOWN RPL_LUSERCHANNELS
+ RPL_LUSERME ERR_NOSUCHSERVER
+
+3.4.3 Version message
+
+ Command: VERSION
+ Parameters: [ <target> ]
+
+ The VERSION command is used to query the version of the server
+ program. An optional parameter <target> is used to query the version
+ of the server program which a client is not directly connected to.
+
+ Wildcards are allowed in the <target> parameter.
+
+ Numeric Replies:
+
+ ERR_NOSUCHSERVER RPL_VERSION
+
+ Examples:
+
+ VERSION tolsun.oulu.fi ; Command to check the version of
+ server "tolsun.oulu.fi".
+
+3.4.4 Stats message
+
+ Command: STATS
+ Parameters: [ <query> [ <target> ] ]
+
+ The stats command is used to query statistics of certain server. If
+ <query> parameter is omitted, only the end of stats reply is sent
+ back.
+
+ A query may be given for any single letter which is only checked by
+ the destination server and is otherwise passed on by intermediate
+ servers, ignored and unaltered.
+
+ Wildcards are allowed in the <target> parameter.
+
+
+
+
+
+Kalt Informational [Page 26]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ Except for the ones below, the list of valid queries is
+ implementation dependent. The standard queries below SHOULD be
+ supported by the server:
+
+ l - returns a list of the server's connections, showing how
+ long each connection has been established and the
+ traffic over that connection in Kbytes and messages for
+ each direction;
+ m - returns the usage count for each of commands supported
+ by the server; commands for which the usage count is
+ zero MAY be omitted;
+ o - returns a list of configured privileged users,
+ operators;
+ u - returns a string showing how long the server has been
+ up.
+
+ It is also RECOMMENDED that client and server access configuration be
+ published this way.
+
+ Numeric Replies:
+
+ ERR_NOSUCHSERVER
+ RPL_STATSLINKINFO RPL_STATSUPTIME
+ RPL_STATSCOMMANDS RPL_STATSOLINE
+ RPL_ENDOFSTATS
+
+ Examples:
+
+ STATS m ; Command to check the command usage
+ for the server you are connected to
+
+3.4.5 Links message
+
+ Command: LINKS
+ Parameters: [ [ <remote server> ] <server mask> ]
+
+ With LINKS, a user can list all servernames, which are known by the
+ server answering the query. The returned list of servers MUST match
+ the mask, or if no mask is given, the full list is returned.
+
+ If <remote server> is given in addition to <server mask>, the LINKS
+ command is forwarded to the first server found that matches that name
+ (if any), and that server is then required to answer the query.
+
+ Numeric Replies:
+
+ ERR_NOSUCHSERVER
+ RPL_LINKS RPL_ENDOFLINKS
+
+
+
+Kalt Informational [Page 27]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ Examples:
+
+ LINKS *.au ; Command to list all servers which
+ have a name that matches *.au;
+
+ LINKS *.edu *.bu.edu ; Command to list servers matching
+ *.bu.edu as seen by the first server
+ matching *.edu.
+
+3.4.6 Time message
+
+ Command: TIME
+ Parameters: [ <target> ]
+
+ The time command is used to query local time from the specified
+ server. If the <target> parameter is not given, the server receiving
+ the command must reply to the query.
+
+ Wildcards are allowed in the <target> parameter.
+
+ Numeric Replies:
+
+ ERR_NOSUCHSERVER RPL_TIME
+
+ Examples:
+ TIME tolsun.oulu.fi ; check the time on the server
+ "tolson.oulu.fi"
+
+3.4.7 Connect message
+
+ Command: CONNECT
+ Parameters: <target server> <port> [ <remote server> ]
+
+ The CONNECT command can be used to request a server to try to
+ establish a new connection to another server immediately. CONNECT is
+ a privileged command and SHOULD be available only to IRC Operators.
+ If a <remote server> is given and its mask doesn't match name of the
+ parsing server, the CONNECT attempt is sent to the first match of
+ remote server. Otherwise the CONNECT attempt is made by the server
+ processing the request.
+
+ The server receiving a remote CONNECT command SHOULD generate a
+ WALLOPS message describing the source and target of the request.
+
+ Numeric Replies:
+
+ ERR_NOSUCHSERVER ERR_NOPRIVILEGES
+ ERR_NEEDMOREPARAMS
+
+
+
+Kalt Informational [Page 28]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ Examples:
+
+ CONNECT tolsun.oulu.fi 6667 ; Command to attempt to connect local
+ server to tolsun.oulu.fi on port 6667
+
+3.4.8 Trace message
+
+ Command: TRACE
+ Parameters: [ <target> ]
+
+ TRACE command is used to find the route to specific server and
+ information about its peers. Each server that processes this command
+ MUST report to the sender about it. The replies from pass-through
+ links form a chain, which shows route to destination. After sending
+ this reply back, the query MUST be sent to the next server until
+ given <target> server is reached.
+
+ TRACE command is used to find the route to specific server. Each
+ server that processes this message MUST tell the sender about it by
+ sending a reply indicating it is a pass-through link, forming a chain
+ of replies. After sending this reply back, it MUST then send the
+ TRACE message to the next server until given server is reached. If
+ the <target> parameter is omitted, it is RECOMMENDED that TRACE
+ command sends a message to the sender telling which servers the local
+ server has direct connection to.
+
+ If the destination given by <target> is an actual server, the
+ destination server is REQUIRED to report all servers, services and
+ operators which are connected to it; if the command was issued by an
+ operator, the server MAY also report all users which are connected to
+ it. If the destination given by <target> is a nickname, then only a
+ reply for that nickname is given. If the <target> parameter is
+ omitted, it is RECOMMENDED that the TRACE command is parsed as
+ targeted to the processing server.
+
+ Wildcards are allowed in the <target> parameter.
+
+ Numeric Replies:
+
+ ERR_NOSUCHSERVER
+
+ If the TRACE message is destined for another server, all
+ intermediate servers must return a RPL_TRACELINK reply to indicate
+ that the TRACE passed through it and where it is going next.
+
+ RPL_TRACELINK
+
+
+
+
+
+Kalt Informational [Page 29]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ A TRACE reply may be composed of any number of the following
+ numeric replies.
+
+ RPL_TRACECONNECTING RPL_TRACEHANDSHAKE
+ RPL_TRACEUNKNOWN RPL_TRACEOPERATOR
+ RPL_TRACEUSER RPL_TRACESERVER
+ RPL_TRACESERVICE RPL_TRACENEWTYPE
+ RPL_TRACECLASS RPL_TRACELOG
+ RPL_TRACEEND
+
+ Examples:
+
+ TRACE *.oulu.fi ; TRACE to a server matching
+ *.oulu.fi
+
+3.4.9 Admin command
+
+ Command: ADMIN
+ Parameters: [ <target> ]
+
+ The admin command is used to find information about the administrator
+ of the given server, or current server if <target> parameter is
+ omitted. Each server MUST have the ability to forward ADMIN messages
+ to other servers.
+
+ Wildcards are allowed in the <target> parameter.
+
+ Numeric Replies:
+
+ ERR_NOSUCHSERVER
+ RPL_ADMINME RPL_ADMINLOC1
+ RPL_ADMINLOC2 RPL_ADMINEMAIL
+
+ Examples:
+
+ ADMIN tolsun.oulu.fi ; request an ADMIN reply from
+ tolsun.oulu.fi
+
+ ADMIN syrk ; ADMIN request for the server to
+ which the user syrk is connected
+
+
+
+
+
+
+
+
+
+
+
+Kalt Informational [Page 30]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+3.4.10 Info command
+
+ Command: INFO
+ Parameters: [ <target> ]
+
+ The INFO command is REQUIRED to return information describing the
+ server: its version, when it was compiled, the patchlevel, when it
+ was started, and any other miscellaneous information which may be
+ considered to be relevant.
+
+ Wildcards are allowed in the <target> parameter.
+
+ Numeric Replies:
+
+ ERR_NOSUCHSERVER
+ RPL_INFO RPL_ENDOFINFO
+
+ Examples:
+
+ INFO csd.bu.edu ; request an INFO reply from
+ csd.bu.edu
+
+ INFO Angel ; request info from the server that
+ Angel is connected to.
+
+3.5 Service Query and Commands
+
+ The service query group of commands has been designed to return
+ information about any service which is connected to the network.
+
+3.5.1 Servlist message
+
+ Command: SERVLIST
+ Parameters: [ <mask> [ <type> ] ]
+
+ The SERVLIST command is used to list services currently connected to
+ the network and visible to the user issuing the command. The
+ optional parameters may be used to restrict the result of the query
+ (to matching services names, and services type).
+
+ Numeric Replies:
+
+ RPL_SERVLIST RPL_SERVLISTEND
+
+
+
+
+
+
+
+
+Kalt Informational [Page 31]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+3.5.2 Squery
+
+ Command: SQUERY
+ Parameters: <servicename> <text>
+
+ The SQUERY command is used similarly to PRIVMSG. The only difference
+ is that the recipient MUST be a service. This is the only way for a
+ text message to be delivered to a service.
+
+ See PRIVMSG for more details on replies and example.
+
+ Examples:
+
+ SQUERY irchelp :HELP privmsg
+ ; Message to the service with
+ nickname irchelp.
+
+ SQUERY dict@irc.fr :fr2en blaireau
+ ; Message to the service with name
+ dict@irc.fr.
+
+3.6 User based queries
+
+ User queries are a group of commands which are primarily concerned
+ with finding details on a particular user or group users. When using
+ wildcards with any of these commands, if they match, they will only
+ return information on users who are 'visible' to you. The visibility
+ of a user is determined as a combination of the user's mode and the
+ common set of channels you are both on.
+
+ Although services SHOULD NOT be using this class of message, they are
+ allowed to.
+
+3.6.1 Who query
+
+ Command: WHO
+ Parameters: [ <mask> [ "o" ] ]
+
+ The WHO command is used by a client to generate a query which returns
+ a list of information which 'matches' the <mask> parameter given by
+ the client. In the absence of the <mask> parameter, all visible
+ (users who aren't invisible (user mode +i) and who don't have a
+ common channel with the requesting client) are listed. The same
+ result can be achieved by using a <mask> of "0" or any wildcard which
+ will end up matching every visible user.
+
+ The <mask> passed to WHO is matched against users' host, server, real
+ name and nickname if the channel <mask> cannot be found.
+
+
+
+Kalt Informational [Page 32]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ If the "o" parameter is passed only operators are returned according
+ to the <mask> supplied.
+
+ Numeric Replies:
+
+ ERR_NOSUCHSERVER
+ RPL_WHOREPLY RPL_ENDOFWHO
+
+ Examples:
+
+ WHO *.fi ; Command to list all users who match
+ against "*.fi".
+
+ WHO jto* o ; Command to list all users with a
+ match against "jto*" if they are an
+ operator.
+
+3.6.2 Whois query
+
+ Command: WHOIS
+ Parameters: [ <target> ] <mask> *( "," <mask> )
+
+ This command is used to query information about particular user.
+ The server will answer this command with several numeric messages
+ indicating different statuses of each user which matches the mask (if
+ you are entitled to see them). If no wildcard is present in the
+ <mask>, any information about that nick which you are allowed to see
+ is presented.
+
+ If the <target> parameter is specified, it sends the query to a
+ specific server. It is useful if you want to know how long the user
+ in question has been idle as only local server (i.e., the server the
+ user is directly connected to) knows that information, while
+ everything else is globally known.
+
+ Wildcards are allowed in the <target> parameter.
+
+ Numeric Replies:
+
+ ERR_NOSUCHSERVER ERR_NONICKNAMEGIVEN
+ RPL_WHOISUSER RPL_WHOISCHANNELS
+ RPL_WHOISCHANNELS RPL_WHOISSERVER
+ RPL_AWAY RPL_WHOISOPERATOR
+ RPL_WHOISIDLE ERR_NOSUCHNICK
+ RPL_ENDOFWHOIS
+
+
+
+
+
+
+Kalt Informational [Page 33]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ Examples:
+
+ WHOIS wiz ; return available user information
+ about nick WiZ
+
+ WHOIS eff.org trillian ; ask server eff.org for user
+ information about trillian
+
+3.6.3 Whowas
+
+ Command: WHOWAS
+ Parameters: <nickname> *( "," <nickname> ) [ <count> [ <target> ] ]
+
+ Whowas asks for information about a nickname which no longer exists.
+ This may either be due to a nickname change or the user leaving IRC.
+ In response to this query, the server searches through its nickname
+ history, looking for any nicks which are lexically the same (no wild
+ card matching here). The history is searched backward, returning the
+ most recent entry first. If there are multiple entries, up to
+ <count> replies will be returned (or all of them if no <count>
+ parameter is given). If a non-positive number is passed as being
+ <count>, then a full search is done.
+
+ Wildcards are allowed in the <target> parameter.
+
+ Numeric Replies:
+
+ ERR_NONICKNAMEGIVEN ERR_WASNOSUCHNICK
+ RPL_WHOWASUSER RPL_WHOISSERVER
+ RPL_ENDOFWHOWAS
+
+ Examples:
+
+ WHOWAS Wiz ; return all information in the nick
+ history about nick "WiZ";
+
+ WHOWAS Mermaid 9 ; return at most, the 9 most recent
+ entries in the nick history for
+ "Mermaid";
+
+ WHOWAS Trillian 1 *.edu ; return the most recent history for
+ "Trillian" from the first server
+ found to match "*.edu".
+
+3.7 Miscellaneous messages
+
+ Messages in this category do not fit into any of the above categories
+ but are nonetheless still a part of and REQUIRED by the protocol.
+
+
+
+Kalt Informational [Page 34]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+3.7.1 Kill message
+
+ Command: KILL
+ Parameters: <nickname> <comment>
+
+ The KILL command is used to cause a client-server connection to be
+ closed by the server which has the actual connection. Servers
+ generate KILL messages on nickname collisions. It MAY also be
+ available available to users who have the operator status.
+
+ Clients which have automatic reconnect algorithms effectively make
+ this command useless since the disconnection is only brief. It does
+ however break the flow of data and can be used to stop large amounts
+ of 'flooding' from abusive users or accidents. Abusive users usually
+ don't care as they will reconnect promptly and resume their abusive
+ behaviour. To prevent this command from being abused, any user may
+ elect to receive KILL messages generated for others to keep an 'eye'
+ on would be trouble spots.
+
+ In an arena where nicknames are REQUIRED to be globally unique at all
+ times, KILL messages are sent whenever 'duplicates' are detected
+ (that is an attempt to register two users with the same nickname) in
+ the hope that both of them will disappear and only 1 reappear.
+
+ When a client is removed as the result of a KILL message, the server
+ SHOULD add the nickname to the list of unavailable nicknames in an
+ attempt to avoid clients to reuse this name immediately which is
+ usually the pattern of abusive behaviour often leading to useless
+ "KILL loops". See the "IRC Server Protocol" document [IRC-SERVER]
+ for more information on this procedure.
+
+ The comment given MUST reflect the actual reason for the KILL. For
+ server-generated KILLs it usually is made up of details concerning
+ the origins of the two conflicting nicknames. For users it is left
+ up to them to provide an adequate reason to satisfy others who see
+ it. To prevent/discourage fake KILLs from being generated to hide
+ the identify of the KILLer, the comment also shows a 'kill-path'
+ which is updated by each server it passes through, each prepending
+ its name to the path.
+
+ Numeric Replies:
+
+ ERR_NOPRIVILEGES ERR_NEEDMOREPARAMS
+ ERR_NOSUCHNICK ERR_CANTKILLSERVER
+
+
+
+
+
+
+
+Kalt Informational [Page 35]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ NOTE:
+ It is RECOMMENDED that only Operators be allowed to kill other users
+ with KILL command. This command has been the subject of many
+ controversies over the years, and along with the above
+ recommendation, it is also widely recognized that not even operators
+ should be allowed to kill users on remote servers.
+
+3.7.2 Ping message
+
+ Command: PING
+ Parameters: <server1> [ <server2> ]
+
+ The PING command is used to test the presence of an active client or
+ server at the other end of the connection. Servers send a PING
+ message at regular intervals if no other activity detected coming
+ from a connection. If a connection fails to respond to a PING
+ message within a set amount of time, that connection is closed. A
+ PING message MAY be sent even if the connection is active.
+
+ When a PING message is received, the appropriate PONG message MUST be
+ sent as reply to <server1> (server which sent the PING message out)
+ as soon as possible. If the <server2> parameter is specified, it
+ represents the target of the ping, and the message gets forwarded
+ there.
+
+ Numeric Replies:
+
+ ERR_NOORIGIN ERR_NOSUCHSERVER
+
+ Examples:
+
+ PING tolsun.oulu.fi ; Command to send a PING message to
+ server
+
+ PING WiZ tolsun.oulu.fi ; Command from WiZ to send a PING
+ message to server "tolsun.oulu.fi"
+
+ PING :irc.funet.fi ; Ping message sent by server
+ "irc.funet.fi"
+
+
+
+
+
+
+
+
+
+
+
+
+Kalt Informational [Page 36]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+3.7.3 Pong message
+
+ Command: PONG
+ Parameters: <server> [ <server2> ]
+
+ PONG message is a reply to ping message. If parameter <server2> is
+ given, this message MUST be forwarded to given target. The <server>
+ parameter is the name of the entity who has responded to PING message
+ and generated this message.
+
+ Numeric Replies:
+
+ ERR_NOORIGIN ERR_NOSUCHSERVER
+
+ Example:
+
+ PONG csd.bu.edu tolsun.oulu.fi ; PONG message from csd.bu.edu to
+ tolsun.oulu.fi
+
+3.7.4 Error
+
+ Command: ERROR
+ Parameters: <error message>
+
+ The ERROR command is for use by servers when reporting a serious or
+ fatal error to its peers. It may also be sent from one server to
+ another but MUST NOT be accepted from any normal unknown clients.
+
+ Only an ERROR message SHOULD be used for reporting errors which occur
+ with a server-to-server link. An ERROR message is sent to the server
+ at the other end (which reports it to appropriate local users and
+ logs) and to appropriate local users and logs. It is not to be
+ passed onto any other servers by a server if it is received from a
+ server.
+
+ The ERROR message is also used before terminating a client
+ connection.
+
+ When a server sends a received ERROR message to its operators, the
+ message SHOULD be encapsulated inside a NOTICE message, indicating
+ that the client was not responsible for the error.
+
+ Numerics:
+
+ None.
+
+
+
+
+
+
+Kalt Informational [Page 37]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ Examples:
+
+ ERROR :Server *.fi already exists ; ERROR message to the other server
+ which caused this error.
+
+ NOTICE WiZ :ERROR from csd.bu.edu -- Server *.fi already exists
+ ; Same ERROR message as above but
+ sent to user WiZ on the other server.
+
+4. Optional features
+
+ This section describes OPTIONAL messages. They are not required in a
+ working server implementation of the protocol described herein. In
+ the absence of the feature, an error reply message MUST be generated
+ or an unknown command error. If the message is destined for another
+ server to answer then it MUST be passed on (elementary parsing
+ REQUIRED) The allocated numerics for this are listed with the
+ messages below.
+
+ From this section, only the USERHOST and ISON messages are available
+ to services.
+
+4.1 Away
+
+ Command: AWAY
+ Parameters: [ <text> ]
+
+ With the AWAY command, clients can set an automatic reply string for
+ any PRIVMSG commands directed at them (not to a channel they are on).
+ The server sends an automatic reply to the client sending the PRIVMSG
+ command. The only replying server is the one to which the sending
+ client is connected to.
+
+ The AWAY command is used either with one parameter, to set an AWAY
+ message, or with no parameters, to remove the AWAY message.
+
+ Because of its high cost (memory and bandwidth wise), the AWAY
+ message SHOULD only be used for client-server communication. A
+ server MAY choose to silently ignore AWAY messages received from
+ other servers. To update the away status of a client across servers,
+ the user mode 'a' SHOULD be used instead. (See Section 3.1.5)
+
+ Numeric Replies:
+
+ RPL_UNAWAY RPL_NOWAWAY
+
+
+
+
+
+
+Kalt Informational [Page 38]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ Example:
+
+ AWAY :Gone to lunch. Back in 5 ; Command to set away message to
+ "Gone to lunch. Back in 5".
+
+4.2 Rehash message
+
+ Command: REHASH
+ Parameters: None
+
+ The rehash command is an administrative command which can be used by
+ an operator to force the server to re-read and process its
+ configuration file.
+
+ Numeric Replies:
+
+ RPL_REHASHING ERR_NOPRIVILEGES
+
+
+ Example:
+
+ REHASH ; message from user with operator
+ status to server asking it to reread
+ its configuration file.
+
+4.3 Die message
+
+ Command: DIE
+ Parameters: None
+
+ An operator can use the DIE command to shutdown the server. This
+ message is optional since it may be viewed as a risk to allow
+ arbitrary people to connect to a server as an operator and execute
+ this command.
+
+ The DIE command MUST always be fully processed by the server to which
+ the sending client is connected and MUST NOT be passed onto other
+ connected servers.
+
+ Numeric Replies:
+
+ ERR_NOPRIVILEGES
+
+ Example:
+
+ DIE ; no parameters required.
+
+
+
+
+
+Kalt Informational [Page 39]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+4.4 Restart message
+
+ Command: RESTART
+ Parameters: None
+
+ An operator can use the restart command to force the server to
+ restart itself. This message is optional since it may be viewed as a
+ risk to allow arbitrary people to connect to a server as an operator
+ and execute this command, causing (at least) a disruption to service.
+
+ The RESTART command MUST always be fully processed by the server to
+ which the sending client is connected and MUST NOT be passed onto
+ other connected servers.
+
+ Numeric Replies:
+
+ ERR_NOPRIVILEGES
+
+ Example:
+
+ RESTART ; no parameters required.
+
+4.5 Summon message
+
+ Command: SUMMON
+ Parameters: <user> [ <target> [ <channel> ] ]
+
+ The SUMMON command can be used to give users who are on a host
+ running an IRC server a message asking them to please join IRC. This
+ message is only sent if the target server (a) has SUMMON enabled, (b)
+ the user is logged in and (c) the server process can write to the
+ user's tty (or similar).
+
+ If no <server> parameter is given it tries to summon <user> from the
+ server the client is connected to is assumed as the target.
+
+ If summon is not enabled in a server, it MUST return the
+ ERR_SUMMONDISABLED numeric.
+
+ Numeric Replies:
+
+ ERR_NORECIPIENT ERR_FILEERROR
+ ERR_NOLOGIN ERR_NOSUCHSERVER
+ ERR_SUMMONDISABLED RPL_SUMMONING
+
+
+
+
+
+
+
+Kalt Informational [Page 40]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ Examples:
+
+ SUMMON jto ; summon user jto on the server's
+ host
+
+ SUMMON jto tolsun.oulu.fi ; summon user jto on the host which a
+ server named "tolsun.oulu.fi" is
+ running.
+
+4.6 Users
+
+ Command: USERS
+ Parameters: [ <target> ]
+
+ The USERS command returns a list of users logged into the server in a
+ format similar to the UNIX commands who(1), rusers(1) and finger(1).
+ If disabled, the correct numeric MUST be returned to indicate this.
+
+ Because of the security implications of such a command, it SHOULD be
+ disabled by default in server implementations. Enabling it SHOULD
+ require recompiling the server or some equivalent change rather than
+ simply toggling an option and restarting the server. The procedure
+ to enable this command SHOULD also include suitable large comments.
+
+ Numeric Replies:
+
+ ERR_NOSUCHSERVER ERR_FILEERROR
+ RPL_USERSSTART RPL_USERS
+ RPL_NOUSERS RPL_ENDOFUSERS
+ ERR_USERSDISABLED
+
+ Disabled Reply:
+
+ ERR_USERSDISABLED
+
+ Example:
+
+ USERS eff.org ; request a list of users logged in
+ on server eff.org
+
+4.7 Operwall message
+
+ Command: WALLOPS
+ Parameters: <Text to be sent>
+
+ The WALLOPS command is used to send a message to all currently
+ connected users who have set the 'w' user mode for themselves. (See
+ Section 3.1.5 "User modes").
+
+
+
+Kalt Informational [Page 41]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ After implementing WALLOPS as a user command it was found that it was
+ often and commonly abused as a means of sending a message to a lot of
+ people. Due to this, it is RECOMMENDED that the implementation of
+ WALLOPS allows and recognizes only servers as the originators of
+ WALLOPS.
+
+ Numeric Replies:
+
+ ERR_NEEDMOREPARAMS
+
+ Example:
+
+ :csd.bu.edu WALLOPS :Connect '*.uiuc.edu 6667' from Joshua ; WALLOPS
+ message from csd.bu.edu announcing a
+ CONNECT message it received from
+ Joshua and acted upon.
+
+4.8 Userhost message
+
+ Command: USERHOST
+ Parameters: <nickname> *( SPACE <nickname> )
+
+ The USERHOST command takes a list of up to 5 nicknames, each
+ separated by a space character and returns a list of information
+ about each nickname that it found. The returned list has each reply
+ separated by a space.
+
+ Numeric Replies:
+
+ RPL_USERHOST ERR_NEEDMOREPARAMS
+
+ Example:
+
+ USERHOST Wiz Michael syrk ; USERHOST request for information on
+ nicks "Wiz", "Michael", and "syrk"
+
+ :ircd.stealth.net 302 yournick :syrk=+syrk@millennium.stealth.net
+ ; Reply for user syrk
+
+4.9 Ison message
+
+ Command: ISON
+ Parameters: <nickname> *( SPACE <nickname> )
+
+ The ISON command was implemented to provide a quick and efficient
+ means to get a response about whether a given nickname was currently
+ on IRC. ISON only takes one (1) type of parameter: a space-separated
+ list of nicks. For each nickname in the list that is present, the
+
+
+
+Kalt Informational [Page 42]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ server adds that to its reply string. Thus the reply string may
+ return empty (none of the given nicks are present), an exact copy of
+ the parameter string (all of them present) or any other subset of the
+ set of nicks given in the parameter. The only limit on the number of
+ nicks that may be checked is that the combined length MUST NOT be too
+ large as to cause the server to chop it off so it fits in 512
+ characters.
+
+ ISON is only processed by the server local to the client sending the
+ command and thus not passed onto other servers for further
+ processing.
+
+ Numeric Replies:
+
+ RPL_ISON ERR_NEEDMOREPARAMS
+
+ Example:
+
+ ISON phone trillian WiZ jarlek Avalon Angel Monstah syrk
+ ; Sample ISON request for 7 nicks.
+
+5. Replies
+
+ The following is a list of numeric replies which are generated in
+ response to the commands given above. Each numeric is given with its
+ number, name and reply string.
+
+5.1 Command responses
+
+ Numerics in the range from 001 to 099 are used for client-server
+ connections only and should never travel between servers. Replies
+ generated in the response to commands are found in the range from 200
+ to 399.
+
+ 001 RPL_WELCOME
+ "Welcome to the Internet Relay Network
+ <nick>!<user>@<host>"
+ 002 RPL_YOURHOST
+ "Your host is <servername>, running version <ver>"
+ 003 RPL_CREATED
+ "This server was created <date>"
+ 004 RPL_MYINFO
+ "<servername> <version> <available user modes>
+ <available channel modes>"
+
+ - The server sends Replies 001 to 004 to a user upon
+ successful registration.
+
+
+
+
+Kalt Informational [Page 43]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ 005 RPL_BOUNCE
+ "Try server <server name>, port <port number>"
+
+ - Sent by the server to a user to suggest an alternative
+ server. This is often used when the connection is
+ refused because the server is already full.
+
+ 302 RPL_USERHOST
+ ":*1<reply> *( " " <reply> )"
+
+ - Reply format used by USERHOST to list replies to
+ the query list. The reply string is composed as
+ follows:
+
+ reply = nickname [ "*" ] "=" ( "+" / "-" ) hostname
+
+ The '*' indicates whether the client has registered
+ as an Operator. The '-' or '+' characters represent
+ whether the client has set an AWAY message or not
+ respectively.
+
+ 303 RPL_ISON
+ ":*1<nick> *( " " <nick> )"
+
+ - Reply format used by ISON to list replies to the
+ query list.
+
+ 301 RPL_AWAY
+ "<nick> :<away message>"
+ 305 RPL_UNAWAY
+ ":You are no longer marked as being away"
+ 306 RPL_NOWAWAY
+ ":You have been marked as being away"
+
+ - These replies are used with the AWAY command (if
+ allowed). RPL_AWAY is sent to any client sending a
+ PRIVMSG to a client which is away. RPL_AWAY is only
+ sent by the server to which the client is connected.
+ Replies RPL_UNAWAY and RPL_NOWAWAY are sent when the
+ client removes and sets an AWAY message.
+
+ 311 RPL_WHOISUSER
+ "<nick> <user> <host> * :<real name>"
+ 312 RPL_WHOISSERVER
+ "<nick> <server> :<server info>"
+ 313 RPL_WHOISOPERATOR
+ "<nick> :is an IRC operator"
+
+
+
+
+Kalt Informational [Page 44]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ 317 RPL_WHOISIDLE
+ "<nick> <integer> :seconds idle"
+ 318 RPL_ENDOFWHOIS
+ "<nick> :End of WHOIS list"
+ 319 RPL_WHOISCHANNELS
+ "<nick> :*( ( "@" / "+" ) <channel> " " )"
+
+ - Replies 311 - 313, 317 - 319 are all replies
+ generated in response to a WHOIS message. Given that
+ there are enough parameters present, the answering
+ server MUST either formulate a reply out of the above
+ numerics (if the query nick is found) or return an
+ error reply. The '*' in RPL_WHOISUSER is there as
+ the literal character and not as a wild card. For
+ each reply set, only RPL_WHOISCHANNELS may appear
+ more than once (for long lists of channel names).
+ The '@' and '+' characters next to the channel name
+ indicate whether a client is a channel operator or
+ has been granted permission to speak on a moderated
+ channel. The RPL_ENDOFWHOIS reply is used to mark
+ the end of processing a WHOIS message.
+
+ 314 RPL_WHOWASUSER
+ "<nick> <user> <host> * :<real name>"
+ 369 RPL_ENDOFWHOWAS
+ "<nick> :End of WHOWAS"
+
+ - When replying to a WHOWAS message, a server MUST use
+ the replies RPL_WHOWASUSER, RPL_WHOISSERVER or
+ ERR_WASNOSUCHNICK for each nickname in the presented
+ list. At the end of all reply batches, there MUST
+ be RPL_ENDOFWHOWAS (even if there was only one reply
+ and it was an error).
+
+ 321 RPL_LISTSTART
+ Obsolete. Not used.
+
+ 322 RPL_LIST
+ "<channel> <# visible> :<topic>"
+ 323 RPL_LISTEND
+ ":End of LIST"
+
+ - Replies RPL_LIST, RPL_LISTEND mark the actual replies
+ with data and end of the server's response to a LIST
+ command. If there are no channels available to return,
+ only the end reply MUST be sent.
+
+
+
+
+
+Kalt Informational [Page 45]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ 325 RPL_UNIQOPIS
+ "<channel> <nickname>"
+
+ 324 RPL_CHANNELMODEIS
+ "<channel> <mode> <mode params>"
+
+ 331 RPL_NOTOPIC
+ "<channel> :No topic is set"
+ 332 RPL_TOPIC
+ "<channel> :<topic>"
+
+ - When sending a TOPIC message to determine the
+ channel topic, one of two replies is sent. If
+ the topic is set, RPL_TOPIC is sent back else
+ RPL_NOTOPIC.
+
+ 341 RPL_INVITING
+ "<channel> <nick>"
+
+ - Returned by the server to indicate that the
+ attempted INVITE message was successful and is
+ being passed onto the end client.
+
+ 342 RPL_SUMMONING
+ "<user> :Summoning user to IRC"
+
+ - Returned by a server answering a SUMMON message to
+ indicate that it is summoning that user.
+
+ 346 RPL_INVITELIST
+ "<channel> <invitemask>"
+ 347 RPL_ENDOFINVITELIST
+ "<channel> :End of channel invite list"
+
+ - When listing the 'invitations masks' for a given channel,
+ a server is required to send the list back using the
+ RPL_INVITELIST and RPL_ENDOFINVITELIST messages. A
+ separate RPL_INVITELIST is sent for each active mask.
+ After the masks have been listed (or if none present) a
+ RPL_ENDOFINVITELIST MUST be sent.
+
+ 348 RPL_EXCEPTLIST
+ "<channel> <exceptionmask>"
+ 349 RPL_ENDOFEXCEPTLIST
+ "<channel> :End of channel exception list"
+
+
+
+
+
+
+Kalt Informational [Page 46]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ - When listing the 'exception masks' for a given channel,
+ a server is required to send the list back using the
+ RPL_EXCEPTLIST and RPL_ENDOFEXCEPTLIST messages. A
+ separate RPL_EXCEPTLIST is sent for each active mask.
+ After the masks have been listed (or if none present)
+ a RPL_ENDOFEXCEPTLIST MUST be sent.
+
+ 351 RPL_VERSION
+ "<version>.<debuglevel> <server> :<comments>"
+
+ - Reply by the server showing its version details.
+ The <version> is the version of the software being
+ used (including any patchlevel revisions) and the
+ <debuglevel> is used to indicate if the server is
+ running in "debug mode".
+
+ The "comments" field may contain any comments about
+ the version or further version details.
+
+ 352 RPL_WHOREPLY
+ "<channel> <user> <host> <server> <nick>
+ ( "H" / "G" > ["*"] [ ( "@" / "+" ) ]
+ :<hopcount> <real name>"
+
+ 315 RPL_ENDOFWHO
+ "<name> :End of WHO list"
+
+ - The RPL_WHOREPLY and RPL_ENDOFWHO pair are used
+ to answer a WHO message. The RPL_WHOREPLY is only
+ sent if there is an appropriate match to the WHO
+ query. If there is a list of parameters supplied
+ with a WHO message, a RPL_ENDOFWHO MUST be sent
+ after processing each list item with <name> being
+ the item.
+
+ 353 RPL_NAMREPLY
+ "( "=" / "*" / "@" ) <channel>
+ :[ "@" / "+" ] <nick> *( " " [ "@" / "+" ] <nick> )
+ - "@" is used for secret channels, "*" for private
+ channels, and "=" for others (public channels).
+
+ 366 RPL_ENDOFNAMES
+ "<channel> :End of NAMES list"
+
+ - To reply to a NAMES message, a reply pair consisting
+ of RPL_NAMREPLY and RPL_ENDOFNAMES is sent by the
+ server back to the client. If there is no channel
+ found as in the query, then only RPL_ENDOFNAMES is
+
+
+
+Kalt Informational [Page 47]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ returned. The exception to this is when a NAMES
+ message is sent with no parameters and all visible
+ channels and contents are sent back in a series of
+ RPL_NAMEREPLY messages with a RPL_ENDOFNAMES to mark
+ the end.
+
+ 364 RPL_LINKS
+ "<mask> <server> :<hopcount> <server info>"
+ 365 RPL_ENDOFLINKS
+ "<mask> :End of LINKS list"
+
+ - In replying to the LINKS message, a server MUST send
+ replies back using the RPL_LINKS numeric and mark the
+ end of the list using an RPL_ENDOFLINKS reply.
+
+ 367 RPL_BANLIST
+ "<channel> <banmask>"
+ 368 RPL_ENDOFBANLIST
+ "<channel> :End of channel ban list"
+
+ - When listing the active 'bans' for a given channel,
+ a server is required to send the list back using the
+ RPL_BANLIST and RPL_ENDOFBANLIST messages. A separate
+ RPL_BANLIST is sent for each active banmask. After the
+ banmasks have been listed (or if none present) a
+ RPL_ENDOFBANLIST MUST be sent.
+
+ 371 RPL_INFO
+ ":<string>"
+ 374 RPL_ENDOFINFO
+ ":End of INFO list"
+
+ - A server responding to an INFO message is required to
+ send all its 'info' in a series of RPL_INFO messages
+ with a RPL_ENDOFINFO reply to indicate the end of the
+ replies.
+
+ 375 RPL_MOTDSTART
+ ":- <server> Message of the day - "
+ 372 RPL_MOTD
+ ":- <text>"
+ 376 RPL_ENDOFMOTD
+ ":End of MOTD command"
+
+ - When responding to the MOTD message and the MOTD file
+ is found, the file is displayed line by line, with
+ each line no longer than 80 characters, using
+
+
+
+
+Kalt Informational [Page 48]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ RPL_MOTD format replies. These MUST be surrounded
+ by a RPL_MOTDSTART (before the RPL_MOTDs) and an
+ RPL_ENDOFMOTD (after).
+
+ 381 RPL_YOUREOPER
+ ":You are now an IRC operator"
+
+ - RPL_YOUREOPER is sent back to a client which has
+ just successfully issued an OPER message and gained
+ operator status.
+
+ 382 RPL_REHASHING
+ "<config file> :Rehashing"
+
+ - If the REHASH option is used and an operator sends
+ a REHASH message, an RPL_REHASHING is sent back to
+ the operator.
+
+ 383 RPL_YOURESERVICE
+ "You are service <servicename>"
+
+ - Sent by the server to a service upon successful
+ registration.
+
+ 391 RPL_TIME
+ "<server> :<string showing server's local time>"
+
+ - When replying to the TIME message, a server MUST send
+ the reply using the RPL_TIME format above. The string
+ showing the time need only contain the correct day and
+ time there. There is no further requirement for the
+ time string.
+
+ 392 RPL_USERSSTART
+ ":UserID Terminal Host"
+ 393 RPL_USERS
+ ":<username> <ttyline> <hostname>"
+ 394 RPL_ENDOFUSERS
+ ":End of users"
+ 395 RPL_NOUSERS
+ ":Nobody logged in"
+
+ - If the USERS message is handled by a server, the
+ replies RPL_USERSTART, RPL_USERS, RPL_ENDOFUSERS and
+ RPL_NOUSERS are used. RPL_USERSSTART MUST be sent
+ first, following by either a sequence of RPL_USERS
+ or a single RPL_NOUSER. Following this is
+ RPL_ENDOFUSERS.
+
+
+
+Kalt Informational [Page 49]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ 200 RPL_TRACELINK
+ "Link <version & debug level> <destination>
+ <next server> V<protocol version>
+ <link uptime in seconds> <backstream sendq>
+ <upstream sendq>"
+ 201 RPL_TRACECONNECTING
+ "Try. <class> <server>"
+ 202 RPL_TRACEHANDSHAKE
+ "H.S. <class> <server>"
+ 203 RPL_TRACEUNKNOWN
+ "???? <class> [<client IP address in dot form>]"
+ 204 RPL_TRACEOPERATOR
+ "Oper <class> <nick>"
+ 205 RPL_TRACEUSER
+ "User <class> <nick>"
+ 206 RPL_TRACESERVER
+ "Serv <class> <int>S <int>C <server>
+ <nick!user|*!*>@<host|server> V<protocol version>"
+ 207 RPL_TRACESERVICE
+ "Service <class> <name> <type> <active type>"
+ 208 RPL_TRACENEWTYPE
+ "<newtype> 0 <client name>"
+ 209 RPL_TRACECLASS
+ "Class <class> <count>"
+ 210 RPL_TRACERECONNECT
+ Unused.
+ 261 RPL_TRACELOG
+ "File <logfile> <debug level>"
+ 262 RPL_TRACEEND
+ "<server name> <version & debug level> :End of TRACE"
+
+ - The RPL_TRACE* are all returned by the server in
+ response to the TRACE message. How many are
+ returned is dependent on the TRACE message and
+ whether it was sent by an operator or not. There
+ is no predefined order for which occurs first.
+ Replies RPL_TRACEUNKNOWN, RPL_TRACECONNECTING and
+ RPL_TRACEHANDSHAKE are all used for connections
+ which have not been fully established and are either
+ unknown, still attempting to connect or in the
+ process of completing the 'server handshake'.
+ RPL_TRACELINK is sent by any server which handles
+ a TRACE message and has to pass it on to another
+ server. The list of RPL_TRACELINKs sent in
+ response to a TRACE command traversing the IRC
+ network should reflect the actual connectivity of
+ the servers themselves along that path.
+
+
+
+
+Kalt Informational [Page 50]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ RPL_TRACENEWTYPE is to be used for any connection
+ which does not fit in the other categories but is
+ being displayed anyway.
+ RPL_TRACEEND is sent to indicate the end of the list.
+
+ 211 RPL_STATSLINKINFO
+ "<linkname> <sendq> <sent messages>
+ <sent Kbytes> <received messages>
+ <received Kbytes> <time open>"
+
+ - reports statistics on a connection. <linkname>
+ identifies the particular connection, <sendq> is
+ the amount of data that is queued and waiting to be
+ sent <sent messages> the number of messages sent,
+ and <sent Kbytes> the amount of data sent, in
+ Kbytes. <received messages> and <received Kbytes>
+ are the equivalent of <sent messages> and <sent
+ Kbytes> for received data, respectively. <time
+ open> indicates how long ago the connection was
+ opened, in seconds.
+
+ 212 RPL_STATSCOMMANDS
+ "<command> <count> <byte count> <remote count>"
+
+ - reports statistics on commands usage.
+
+ 219 RPL_ENDOFSTATS
+ "<stats letter> :End of STATS report"
+
+ 242 RPL_STATSUPTIME
+ ":Server Up %d days %d:%02d:%02d"
+
+ - reports the server uptime.
+
+ 243 RPL_STATSOLINE
+ "O <hostmask> * <name>"
+
+ - reports the allowed hosts from where user may become IRC
+ operators.
+
+ 221 RPL_UMODEIS
+ "<user mode string>"
+
+ - To answer a query about a client's own mode,
+ RPL_UMODEIS is sent back.
+
+ 234 RPL_SERVLIST
+ "<name> <server> <mask> <type> <hopcount> <info>"
+
+
+
+Kalt Informational [Page 51]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ 235 RPL_SERVLISTEND
+ "<mask> <type> :End of service listing"
+
+ - When listing services in reply to a SERVLIST message,
+ a server is required to send the list back using the
+ RPL_SERVLIST and RPL_SERVLISTEND messages. A separate
+ RPL_SERVLIST is sent for each service. After the
+ services have been listed (or if none present) a
+ RPL_SERVLISTEND MUST be sent.
+
+ 251 RPL_LUSERCLIENT
+ ":There are <integer> users and <integer>
+ services on <integer> servers"
+ 252 RPL_LUSEROP
+ "<integer> :operator(s) online"
+ 253 RPL_LUSERUNKNOWN
+ "<integer> :unknown connection(s)"
+ 254 RPL_LUSERCHANNELS
+ "<integer> :channels formed"
+ 255 RPL_LUSERME
+ ":I have <integer> clients and <integer>
+ servers"
+
+ - In processing an LUSERS message, the server
+ sends a set of replies from RPL_LUSERCLIENT,
+ RPL_LUSEROP, RPL_USERUNKNOWN,
+ RPL_LUSERCHANNELS and RPL_LUSERME. When
+ replying, a server MUST send back
+ RPL_LUSERCLIENT and RPL_LUSERME. The other
+ replies are only sent back if a non-zero count
+ is found for them.
+
+ 256 RPL_ADMINME
+ "<server> :Administrative info"
+ 257 RPL_ADMINLOC1
+ ":<admin info>"
+ 258 RPL_ADMINLOC2
+ ":<admin info>"
+ 259 RPL_ADMINEMAIL
+ ":<admin info>"
+
+ - When replying to an ADMIN message, a server
+ is expected to use replies RPL_ADMINME
+ through to RPL_ADMINEMAIL and provide a text
+ message with each. For RPL_ADMINLOC1 a
+ description of what city, state and country
+ the server is in is expected, followed by
+ details of the institution (RPL_ADMINLOC2)
+
+
+
+Kalt Informational [Page 52]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ and finally the administrative contact for the
+ server (an email address here is REQUIRED)
+ in RPL_ADMINEMAIL.
+
+ 263 RPL_TRYAGAIN
+ "<command> :Please wait a while and try again."
+
+ - When a server drops a command without processing it,
+ it MUST use the reply RPL_TRYAGAIN to inform the
+ originating client.
+
+5.2 Error Replies
+
+ Error replies are found in the range from 400 to 599.
+
+ 401 ERR_NOSUCHNICK
+ "<nickname> :No such nick/channel"
+
+ - Used to indicate the nickname parameter supplied to a
+ command is currently unused.
+
+ 402 ERR_NOSUCHSERVER
+ "<server name> :No such server"
+
+ - Used to indicate the server name given currently
+ does not exist.
+
+ 403 ERR_NOSUCHCHANNEL
+ "<channel name> :No such channel"
+
+ - Used to indicate the given channel name is invalid.
+
+ 404 ERR_CANNOTSENDTOCHAN
+ "<channel name> :Cannot send to channel"
+
+ - Sent to a user who is either (a) not on a channel
+ which is mode +n or (b) not a chanop (or mode +v) on
+ a channel which has mode +m set or where the user is
+ banned and is trying to send a PRIVMSG message to
+ that channel.
+
+ 405 ERR_TOOMANYCHANNELS
+ "<channel name> :You have joined too many channels"
+
+ - Sent to a user when they have joined the maximum
+ number of allowed channels and they try to join
+ another channel.
+
+
+
+
+Kalt Informational [Page 53]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ 406 ERR_WASNOSUCHNICK
+ "<nickname> :There was no such nickname"
+
+ - Returned by WHOWAS to indicate there is no history
+ information for that nickname.
+
+ 407 ERR_TOOMANYTARGETS
+ "<target> :<error code> recipients. <abort message>"
+
+ - Returned to a client which is attempting to send a
+ PRIVMSG/NOTICE using the user@host destination format
+ and for a user@host which has several occurrences.
+
+ - Returned to a client which trying to send a
+ PRIVMSG/NOTICE to too many recipients.
+
+ - Returned to a client which is attempting to JOIN a safe
+ channel using the shortname when there are more than one
+ such channel.
+
+ 408 ERR_NOSUCHSERVICE
+ "<service name> :No such service"
+
+ - Returned to a client which is attempting to send a SQUERY
+ to a service which does not exist.
+
+ 409 ERR_NOORIGIN
+ ":No origin specified"
+
+ - PING or PONG message missing the originator parameter.
+
+ 411 ERR_NORECIPIENT
+ ":No recipient given (<command>)"
+ 412 ERR_NOTEXTTOSEND
+ ":No text to send"
+ 413 ERR_NOTOPLEVEL
+ "<mask> :No toplevel domain specified"
+ 414 ERR_WILDTOPLEVEL
+ "<mask> :Wildcard in toplevel domain"
+ 415 ERR_BADMASK
+ "<mask> :Bad Server/host mask"
+
+ - 412 - 415 are returned by PRIVMSG to indicate that
+ the message wasn't delivered for some reason.
+ ERR_NOTOPLEVEL and ERR_WILDTOPLEVEL are errors that
+ are returned when an invalid use of
+ "PRIVMSG $<server>" or "PRIVMSG #<host>" is attempted.
+
+
+
+
+Kalt Informational [Page 54]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ 421 ERR_UNKNOWNCOMMAND
+ "<command> :Unknown command"
+
+ - Returned to a registered client to indicate that the
+ command sent is unknown by the server.
+
+ 422 ERR_NOMOTD
+ ":MOTD File is missing"
+
+ - Server's MOTD file could not be opened by the server.
+
+ 423 ERR_NOADMININFO
+ "<server> :No administrative info available"
+
+ - Returned by a server in response to an ADMIN message
+ when there is an error in finding the appropriate
+ information.
+
+ 424 ERR_FILEERROR
+ ":File error doing <file op> on <file>"
+
+ - Generic error message used to report a failed file
+ operation during the processing of a message.
+
+ 431 ERR_NONICKNAMEGIVEN
+ ":No nickname given"
+
+ - Returned when a nickname parameter expected for a
+ command and isn't found.
+
+ 432 ERR_ERRONEUSNICKNAME
+ "<nick> :Erroneous nickname"
+
+ - Returned after receiving a NICK message which contains
+ characters which do not fall in the defined set. See
+ section 2.3.1 for details on valid nicknames.
+
+ 433 ERR_NICKNAMEINUSE
+ "<nick> :Nickname is already in use"
+
+ - Returned when a NICK message is processed that results
+ in an attempt to change to a currently existing
+ nickname.
+
+
+
+
+
+
+
+
+Kalt Informational [Page 55]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ 436 ERR_NICKCOLLISION
+ "<nick> :Nickname collision KILL from <user>@<host>"
+
+ - Returned by a server to a client when it detects a
+ nickname collision (registered of a NICK that
+ already exists by another server).
+
+ 437 ERR_UNAVAILRESOURCE
+ "<nick/channel> :Nick/channel is temporarily unavailable"
+
+ - Returned by a server to a user trying to join a channel
+ currently blocked by the channel delay mechanism.
+
+ - Returned by a server to a user trying to change nickname
+ when the desired nickname is blocked by the nick delay
+ mechanism.
+
+ 441 ERR_USERNOTINCHANNEL
+ "<nick> <channel> :They aren't on that channel"
+
+ - Returned by the server to indicate that the target
+ user of the command is not on the given channel.
+
+ 442 ERR_NOTONCHANNEL
+ "<channel> :You're not on that channel"
+
+ - Returned by the server whenever a client tries to
+ perform a channel affecting command for which the
+ client isn't a member.
+
+ 443 ERR_USERONCHANNEL
+ "<user> <channel> :is already on channel"
+
+ - Returned when a client tries to invite a user to a
+ channel they are already on.
+
+ 444 ERR_NOLOGIN
+ "<user> :User not logged in"
+
+ - Returned by the summon after a SUMMON command for a
+ user was unable to be performed since they were not
+ logged in.
+
+
+
+
+
+
+
+
+
+Kalt Informational [Page 56]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ 445 ERR_SUMMONDISABLED
+ ":SUMMON has been disabled"
+
+ - Returned as a response to the SUMMON command. MUST be
+ returned by any server which doesn't implement it.
+
+ 446 ERR_USERSDISABLED
+ ":USERS has been disabled"
+
+ - Returned as a response to the USERS command. MUST be
+ returned by any server which does not implement it.
+
+ 451 ERR_NOTREGISTERED
+ ":You have not registered"
+
+ - Returned by the server to indicate that the client
+ MUST be registered before the server will allow it
+ to be parsed in detail.
+
+ 461 ERR_NEEDMOREPARAMS
+ "<command> :Not enough parameters"
+
+ - Returned by the server by numerous commands to
+ indicate to the client that it didn't supply enough
+ parameters.
+
+ 462 ERR_ALREADYREGISTRED
+ ":Unauthorized command (already registered)"
+
+ - Returned by the server to any link which tries to
+ change part of the registered details (such as
+ password or user details from second USER message).
+
+ 463 ERR_NOPERMFORHOST
+ ":Your host isn't among the privileged"
+
+ - Returned to a client which attempts to register with
+ a server which does not been setup to allow
+ connections from the host the attempted connection
+ is tried.
+
+ 464 ERR_PASSWDMISMATCH
+ ":Password incorrect"
+
+ - Returned to indicate a failed attempt at registering
+ a connection for which a password was required and
+ was either not given or incorrect.
+
+
+
+
+Kalt Informational [Page 57]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ 465 ERR_YOUREBANNEDCREEP
+ ":You are banned from this server"
+
+ - Returned after an attempt to connect and register
+ yourself with a server which has been setup to
+ explicitly deny connections to you.
+
+ 466 ERR_YOUWILLBEBANNED
+
+ - Sent by a server to a user to inform that access to the
+ server will soon be denied.
+
+ 467 ERR_KEYSET
+ "<channel> :Channel key already set"
+ 471 ERR_CHANNELISFULL
+ "<channel> :Cannot join channel (+l)"
+ 472 ERR_UNKNOWNMODE
+ "<char> :is unknown mode char to me for <channel>"
+ 473 ERR_INVITEONLYCHAN
+ "<channel> :Cannot join channel (+i)"
+ 474 ERR_BANNEDFROMCHAN
+ "<channel> :Cannot join channel (+b)"
+ 475 ERR_BADCHANNELKEY
+ "<channel> :Cannot join channel (+k)"
+ 476 ERR_BADCHANMASK
+ "<channel> :Bad Channel Mask"
+ 477 ERR_NOCHANMODES
+ "<channel> :Channel doesn't support modes"
+ 478 ERR_BANLISTFULL
+ "<channel> <char> :Channel list is full"
+
+ 481 ERR_NOPRIVILEGES
+ ":Permission Denied- You're not an IRC operator"
+
+ - Any command requiring operator privileges to operate
+ MUST return this error to indicate the attempt was
+ unsuccessful.
+
+ 482 ERR_CHANOPRIVSNEEDED
+ "<channel> :You're not channel operator"
+
+ - Any command requiring 'chanop' privileges (such as
+ MODE messages) MUST return this error if the client
+ making the attempt is not a chanop on the specified
+ channel.
+
+
+
+
+
+
+Kalt Informational [Page 58]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ 483 ERR_CANTKILLSERVER
+ ":You can't kill a server!"
+
+ - Any attempts to use the KILL command on a server
+ are to be refused and this error returned directly
+ to the client.
+
+ 484 ERR_RESTRICTED
+ ":Your connection is restricted!"
+
+ - Sent by the server to a user upon connection to indicate
+ the restricted nature of the connection (user mode "+r").
+
+ 485 ERR_UNIQOPPRIVSNEEDED
+ ":You're not the original channel operator"
+
+ - Any MODE requiring "channel creator" privileges MUST
+ return this error if the client making the attempt is not
+ a chanop on the specified channel.
+
+ 491 ERR_NOOPERHOST
+ ":No O-lines for your host"
+
+ - If a client sends an OPER message and the server has
+ not been configured to allow connections from the
+ client's host as an operator, this error MUST be
+ returned.
+
+ 501 ERR_UMODEUNKNOWNFLAG
+ ":Unknown MODE flag"
+
+ - Returned by the server to indicate that a MODE
+ message was sent with a nickname parameter and that
+ the a mode flag sent was not recognized.
+
+ 502 ERR_USERSDONTMATCH
+ ":Cannot change mode for other users"
+
+ - Error sent to any user trying to view or change the
+ user mode for a user other than themselves.
+
+5.3 Reserved numerics
+
+ These numerics are not described above since they fall into one of
+ the following categories:
+
+ 1. no longer in use;
+
+
+
+
+Kalt Informational [Page 59]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+ 2. reserved for future planned use;
+
+ 3. in current use but are part of a non-generic 'feature' of
+ the current IRC server.
+
+ 231 RPL_SERVICEINFO 232 RPL_ENDOFSERVICES
+ 233 RPL_SERVICE
+ 300 RPL_NONE 316 RPL_WHOISCHANOP
+ 361 RPL_KILLDONE 362 RPL_CLOSING
+ 363 RPL_CLOSEEND 373 RPL_INFOSTART
+ 384 RPL_MYPORTIS
+
+ 213 RPL_STATSCLINE 214 RPL_STATSNLINE
+ 215 RPL_STATSILINE 216 RPL_STATSKLINE
+ 217 RPL_STATSQLINE 218 RPL_STATSYLINE
+ 240 RPL_STATSVLINE 241 RPL_STATSLLINE
+ 244 RPL_STATSHLINE 244 RPL_STATSSLINE
+ 246 RPL_STATSPING 247 RPL_STATSBLINE
+ 250 RPL_STATSDLINE
+
+ 492 ERR_NOSERVICEHOST
+
+6. Current implementations
+
+ The IRC software, version 2.10 is the only complete implementation of
+ the IRC protocol (client and server). Because of the small amount of
+ changes in the client protocol since the publication of RFC 1459
+ [IRC], implementations that follow it are likely to be compliant with
+ this protocol or to require a small amount of changes to reach
+ compliance.
+
+7. Current problems
+
+ There are a number of recognized problems with the IRC Client
+ Protocol, and more generally with the IRC Server Protocol. In order
+ to preserve backward compatibility with old clients, this protocol
+ has almost not evolved since the publication of RFC 1459 [IRC].
+
+7.1 Nicknames
+
+ The idea of the nickname on IRC is very convenient for users to use
+ when talking to each other outside of a channel, but there is only a
+ finite nickname space and being what they are, it's not uncommon for
+ several people to want to use the same nick. If a nickname is chosen
+ by two people using this protocol, either one will not succeed or
+ both will removed by use of a server KILL (See Section 3.7.1).
+
+
+
+
+
+Kalt Informational [Page 60]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+7.2 Limitation of wildcards
+
+ There is no way to escape the escape character "\" (%x5C). While
+ this isn't usually a problem, it makes it impossible to form a mask
+ with a backslash character ("\") preceding a wildcard.
+
+7.3 Security considerations
+
+ Security issues related to this protocol are discussed in the "IRC
+ Server Protocol" [IRC-SERVER] as they are mostly an issue for the
+ server side of the connection.
+
+8. Current support and availability
+
+ Mailing lists for IRC related discussion:
+ General discussion: ircd-users@irc.org
+ Protocol development: ircd-dev@irc.org
+
+ Software implementations:
+ ftp://ftp.irc.org/irc/server
+ ftp://ftp.funet.fi/pub/unix/irc
+ ftp://ftp.irc.org/irc/clients
+
+ Newsgroup: alt.irc
+
+9. Acknowledgements
+
+ Parts of this document were copied from the RFC 1459 [IRC] which
+ first formally documented the IRC Protocol. It has also benefited
+ from many rounds of review and comments. In particular, the
+ following people have made significant contributions to this
+ document:
+
+ Matthew Green, Michael Neumayer, Volker Paulsen, Kurt Roeckx, Vesa
+ Ruokonen, Magnus Tjernstrom, Stefan Zehl.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Kalt Informational [Page 61]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+10. References
+
+ [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+ [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax
+ Specifications: ABNF", RFC 2234, November 1997.
+
+ [HNAME] Braden, R., "Requirements for Internet Hosts --
+ Application and Support", STD 3, RFC 1123, October 1989.
+
+ [IRC] Oikarinen, J. & D. Reed, "Internet Relay Chat Protocol",
+ RFC 1459, May 1993.
+
+ [IRC-ARCH] Kalt, C., "Internet Relay Chat: Architecture", RFC 2810,
+ April 2000.
+
+ [IRC-CHAN] Kalt, C., "Internet Relay Chat: Channel Management", RFC
+ 2811, April 2000.
+
+ [IRC-SERVER] Kalt, C., "Internet Relay Chat: Server Protocol", RFC
+ 2813, April 2000.
+
+11. Author's Address
+
+ Christophe Kalt
+ 99 Teaneck Rd, Apt #117
+ Ridgefield Park, NJ 07660
+ USA
+
+ EMail: kalt@stealth.net
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Kalt Informational [Page 62]
+
+RFC 2812 Internet Relay Chat: Client Protocol April 2000
+
+
+12. Full Copyright Statement
+
+ Copyright (C) The Internet Society (2000). All Rights Reserved.
+
+ This document and translations of it may be copied and furnished to
+ others, and derivative works that comment on or otherwise explain it
+ or assist in its implementation may be prepared, copied, published
+ and distributed, in whole or in part, without restriction of any
+ kind, provided that the above copyright notice and this paragraph are
+ included on all such copies and derivative works. However, this
+ document itself may not be modified in any way, such as by removing
+ the copyright notice or references to the Internet Society or other
+ Internet organizations, except as needed for the purpose of
+ developing Internet standards in which case the procedures for
+ copyrights defined in the Internet Standards process must be
+ followed, or as required to translate it into languages other than
+ English.
+
+ The limited permissions granted above are perpetual and will not be
+ revoked by the Internet Society or its successors or assigns.
+
+ This document and the information contained herein is provided on an
+ "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
+ TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
+ BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
+ HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
+ MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+Acknowledgement
+
+ Funding for the RFC Editor function is currently provided by the
+ Internet Society.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Kalt Informational [Page 63]
+
diff --git a/doc/rfcs/rfc2813.txt b/doc/rfcs/rfc2813.txt
new file mode 100644
index 0000000..2da3de0
--- /dev/null
+++ b/doc/rfcs/rfc2813.txt
@@ -0,0 +1,1459 @@
+
+
+
+
+
+
+Network Working Group C. Kalt
+Request for Comments: 2813 April 2000
+Updates: 1459
+Category: Informational
+
+
+ Internet Relay Chat: Server Protocol
+
+Status of this Memo
+
+ This memo provides information for the Internet community. It does
+ not specify an Internet standard of any kind. Distribution of this
+ memo is unlimited.
+
+Copyright Notice
+
+ Copyright (C) The Internet Society (2000). All Rights Reserved.
+
+Abstract
+
+ While based on the client-server model, the IRC (Internet Relay Chat)
+ protocol allows servers to connect to each other effectively forming
+ a network.
+
+ This document defines the protocol used by servers to talk to each
+ other. It was originally a superset of the client protocol but has
+ evolved differently.
+
+ First formally documented in May 1993 as part of RFC 1459 [IRC], most
+ of the changes brought since then can be found in this document as
+ development was focused on making the protocol scale better. Better
+ scalability has allowed existing world-wide networks to keep growing
+ and reach sizes which defy the old specification.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Kalt Informational [Page 1]
+
+RFC 2813 Internet Relay Chat: Server Protocol April 2000
+
+
+Table of Contents
+
+ 1. Introduction ............................................... 3
+ 2. Global database ............................................ 3
+ 2.1 Servers ................................................ 3
+ 2.2 Clients ................................................ 4
+ 2.2.1 Users ............................................. 4
+ 2.2.2 Services .......................................... 4
+ 2.3 Channels ............................................... 4
+ 3. The IRC Server Specification ............................... 5
+ 3.1 Overview ............................................... 5
+ 3.2 Character codes ........................................ 5
+ 3.3 Messages ............................................... 5
+ 3.3.1 Message format in Augmented BNF ................... 6
+ 3.4 Numeric replies ........................................ 7
+ 4. Message Details ............................................ 7
+ 4.1 Connection Registration ................................ 8
+ 4.1.1 Password message .................................. 8
+ 4.1.2 Server message .................................... 9
+ 4.1.3 Nick .............................................. 10
+ 4.1.4 Service message ................................... 11
+ 4.1.5 Quit .............................................. 12
+ 4.1.6 Server quit message ............................... 13
+ 4.2 Channel operations ..................................... 14
+ 4.2.1 Join message ...................................... 14
+ 4.2.2 Njoin message ..................................... 15
+ 4.2.3 Mode message ...................................... 16
+ 5. Implementation details .................................... 16
+ 5.1 Connection 'Liveness' .................................. 16
+ 5.2 Accepting a client to server connection ................ 16
+ 5.2.1 Users ............................................. 16
+ 5.2.2 Services .......................................... 17
+ 5.3 Establishing a server-server connection. ............... 17
+ 5.3.1 Link options ...................................... 17
+ 5.3.1.1 Compressed server to server links ............ 18
+ 5.3.1.2 Anti abuse protections ....................... 18
+ 5.3.2 State information exchange when connecting ........ 18
+ 5.4 Terminating server-client connections .................. 19
+ 5.5 Terminating server-server connections .................. 19
+ 5.6 Tracking nickname changes .............................. 19
+ 5.7 Tracking recently used nicknames ....................... 20
+ 5.8 Flood control of clients ............................... 20
+ 5.9 Non-blocking lookups ................................... 21
+ 5.9.1 Hostname (DNS) lookups ............................ 21
+ 5.9.2 Username (Ident) lookups .......................... 21
+ 6. Current problems ........................................... 21
+ 6.1 Scalability ............................................ 21
+ 6.2 Labels ................................................. 22
+
+
+
+Kalt Informational [Page 2]
+
+RFC 2813 Internet Relay Chat: Server Protocol April 2000
+
+
+ 6.2.1 Nicknames ......................................... 22
+ 6.2.2 Channels .......................................... 22
+ 6.2.3 Servers ........................................... 22
+ 6.3 Algorithms ............................................. 22
+ 7. Security Considerations .................................... 23
+ 7.1 Authentication ......................................... 23
+ 7.2 Integrity .............................................. 23
+ 8. Current support and availability ........................... 24
+ 9. Acknowledgements ........................................... 24
+ 10. References ................................................ 24
+ 11. Author's Address .......................................... 25
+ 12. Full Copyright Statement ................................... 26
+
+1. Introduction
+
+ This document is intended for people working on implementing an IRC
+ server but will also be useful to anyone implementing an IRC service.
+
+ Servers provide the three basic services required for realtime
+ conferencing defined by the "Internet Relay Chat: Architecture"
+ [IRC-ARCH]: client locator (via the client protocol [IRC-CLIENT]),
+ message relaying (via the server protocol defined in this document)
+ and channel hosting and management (following specific rules [IRC-
+ CHAN]).
+
+2. Global database
+
+ Although the IRC Protocol defines a fairly distributed model, each
+ server maintains a "global state database" about the whole IRC
+ network. This database is, in theory, identical on all servers.
+
+2.1 Servers
+
+ Servers are uniquely identified by their name which has a maximum
+ length of sixty three (63) characters. See the protocol grammar
+ rules (section 3.3.1) for what may and may not be used in a server
+ name.
+
+ Each server is typically known by all other servers, however it is
+ possible to define a "hostmask" to group servers together according
+ to their name. Inside the hostmasked area, all the servers have a
+ name which matches the hostmask, and any other server with a name
+ matching the hostmask SHALL NOT be connected to the IRC network
+ outside the hostmasked area. Servers which are outside the area have
+ no knowledge of the individual servers present inside the area,
+ instead they are presented with a virtual server which has the
+ hostmask for name.
+
+
+
+
+Kalt Informational [Page 3]
+
+RFC 2813 Internet Relay Chat: Server Protocol April 2000
+
+
+2.2 Clients
+
+ For each client, all servers MUST have the following information: a
+ netwide unique identifier (whose format depends on the type of
+ client) and the server to which the client is connected.
+
+2.2.1 Users
+
+ Each user is distinguished from other users by a unique nickname
+ having a maximum length of nine (9) characters. See the protocol
+ grammar rules (section 3.3.1) for what may and may not be used in a
+ nickname. In addition to the nickname, all servers MUST have the
+ following information about all users: the name of the host that the
+ user is running on, the username of the user on that host, and the
+ server to which the client is connected.
+
+2.2.2 Services
+
+ Each service is distinguished from other services by a service name
+ composed of a nickname and a server name. The nickname has a maximum
+ length of nine (9) characters. See the protocol grammar rules
+ (section 3.3.1) for what may and may not be used in a nickname. The
+ server name used to compose the service name is the name of the
+ server to which the service is connected. In addition to this
+ service name all servers MUST know the service type.
+
+ Services differ from users by the format of their identifier, but
+ more importantly services and users don't have the same type of
+ access to the server: services can request part or all of the global
+ state information that a server maintains, but have a more restricted
+ set of commands available to them (See "IRC Client Protocol" [IRC-
+ CLIENT] for details on which) and are not allowed to join channels.
+ Finally services are not usually subject to the "Flood control"
+ mechanism described in section 5.8.
+
+2.3 Channels
+
+ Alike services, channels have a scope [IRC-CHAN] and are not
+ necessarily known to all servers. When a channel existence is known
+ to a server, the server MUST keep track of the channel members, as
+ well as the channel modes.
+
+
+
+
+
+
+
+
+
+
+Kalt Informational [Page 4]
+
+RFC 2813 Internet Relay Chat: Server Protocol April 2000
+
+
+3. The IRC Server Specification
+
+3.1 Overview
+
+ The protocol as described herein is for use with server to server
+ connections. For client to server connections, see the IRC Client
+ Protocol specification.
+
+ There are, however, more restrictions on client connections (which
+ are considered to be untrustworthy) than on server connections.
+
+3.2 Character codes
+
+ No specific character set is specified. The protocol is based on a a
+ set of codes which are composed of eight (8) bits, making up an
+ octet. Each message may be composed of any number of these octets;
+ however, some octet values are used for control codes which act as
+ message delimiters.
+
+ Regardless of being an 8-bit protocol, the delimiters and keywords
+ are such that protocol is mostly usable from US-ASCII terminal and a
+ telnet connection.
+
+ Because of IRC's Scandinavian origin, the characters {}|^ are
+ considered to be the lower case equivalents of the characters []\~,
+ respectively. This is a critical issue when determining the
+ equivalence of two nicknames, or channel names.
+
+3.3 Messages
+
+ Servers and clients send each other messages which may or may not
+ generate a reply. Most communication between servers do not generate
+ any reply, as servers mostly perform routing tasks for the clients.
+
+ Each IRC message may consist of up to three main parts: the prefix
+ (OPTIONAL), the command, and the command parameters (maximum of
+ fifteen (15)). The prefix, command, and all parameters are separated
+ by one ASCII space character (0x20) each.
+
+ The presence of a prefix is indicated with a single leading ASCII
+ colon character (':', 0x3b), which MUST be the first character of the
+ message itself. There MUST be NO gap (whitespace) between the colon
+ and the prefix. The prefix is used by servers to indicate the true
+ origin of the message. If the prefix is missing from the message, it
+ is assumed to have originated from the connection from which it was
+ received. Clients SHOULD not use a prefix when sending a message
+ from themselves; if they use one, the only valid prefix is the
+ registered nickname associated with the client.
+
+
+
+Kalt Informational [Page 5]
+
+RFC 2813 Internet Relay Chat: Server Protocol April 2000
+
+
+ When a server receives a message, it MUST identify its source using
+ the (eventually assumed) prefix. If the prefix cannot be found in
+ the server's internal database, it MUST be discarded, and if the
+ prefix indicates the message comes from an (unknown) server, the link
+ from which the message was received MUST be dropped. Dropping a link
+ in such circumstances is a little excessive but necessary to maintain
+ the integrity of the network and to prevent future problems. Another
+ common error condition is that the prefix found in the server's
+ internal database identifies a different source (typically a source
+ registered from a different link than from which the message
+ arrived). If the message was received from a server link and the
+ prefix identifies a client, a KILL message MUST be issued for the
+ client and sent to all servers. In other cases, the link from which
+ the message arrived SHOULD be dropped for clients, and MUST be
+ dropped for servers. In all cases, the message MUST be discarded.
+
+ The command MUST either be a valid IRC command or a three (3) digit
+ number represented in ASCII text.
+
+ IRC messages are always lines of characters terminated with a CR-LF
+ (Carriage Return - Line Feed) pair, and these messages SHALL NOT
+ exceed 512 characters in length, counting all characters including
+ the trailing CR-LF. Thus, there are 510 characters maximum allowed
+ for the command and its parameters. There is no provision for
+ continuation message lines. See section 5 for more details about
+ current implementations.
+
+3.3.1 Message format in Augmented BNF
+
+ The protocol messages must be extracted from the contiguous stream of
+ octets. The current solution is to designate two characters, CR and
+ LF, as message separators. Empty messages are silently ignored,
+ which permits use of the sequence CR-LF between messages without
+ extra problems.
+
+ The extracted message is parsed into the components <prefix>,
+ <command> and list of parameters (<params>).
+
+ The Augmented BNF representation for this is found in "IRC Client
+ Protocol" [IRC-CLIENT].
+
+ The extended prefix (["!" user "@" host ]) MUST NOT be used in server
+ to server communications and is only intended for server to client
+ messages in order to provide clients with more useful information
+ about who a message is from without the need for additional queries.
+
+
+
+
+
+
+Kalt Informational [Page 6]
+
+RFC 2813 Internet Relay Chat: Server Protocol April 2000
+
+
+3.4 Numeric replies
+
+ Most of the messages sent to the server generate a reply of some
+ sort. The most common reply is the numeric reply, used for both
+ errors and normal replies. The numeric reply MUST be sent as one
+ message consisting of the sender prefix, the three digit numeric, and
+ the target of the reply. A numeric reply is not allowed to originate
+ from a client; any such messages received by a server are silently
+ dropped. In all other respects, a numeric reply is just like a normal
+ message, except that the keyword is made up of 3 numeric digits
+ rather than a string of letters. A list of different replies is
+ supplied in "IRC Client Protocol" [IRC-CLIENT].
+
+4. Message Details
+
+ All the messages recognized by the IRC server and client are
+ described in the IRC Client Protocol specification.
+
+ Where the reply ERR_NOSUCHSERVER is returned, it means that the
+ target of the message could not be found. The server MUST NOT send
+ any other replies after this error for that command.
+
+ The server to which a client is connected is required to parse the
+ complete message, returning any appropriate errors. If the server
+ encounters a fatal error while parsing a message, an error MUST be
+ sent back to the client and the parsing terminated. A fatal error
+ may follow from incorrect command, a destination which is otherwise
+ unknown to the server (server, client or channel names fit this
+ category), not enough parameters or incorrect privileges.
+
+ If a full set of parameters is presented, then each MUST be checked
+ for validity and appropriate responses sent back to the client. In
+ the case of messages which use parameter lists using the comma as an
+ item separator, a reply MUST be sent for each item.
+
+ In the examples below, some messages appear using the full format:
+
+ :Name COMMAND parameter list
+
+ Such examples represent a message from "Name" in transit between
+ servers, where it is essential to include the name of the original
+ sender of the message so remote servers may send back a reply along
+ the correct path.
+
+ The message details for client to server communication are described
+ in the "IRC Client Protocol" [IRC-CLIENT]. Some sections in the
+ following pages apply to some of these messages, they are additions
+ to the message specifications which are only relevant to server to
+
+
+
+Kalt Informational [Page 7]
+
+RFC 2813 Internet Relay Chat: Server Protocol April 2000
+
+
+ server communication, or to the server implementation. The messages
+ which are introduced here are only used for server to server
+ communication.
+
+4.1 Connection Registration
+
+ The commands described here are used to register a connection with
+ another IRC server.
+
+4.1.1 Password message
+
+ Command: PASS
+ Parameters: <password> <version> <flags> [<options>]
+
+ The PASS command is used to set a 'connection password'. The
+ password MUST be set before any attempt to register the connection is
+ made. Currently this means that servers MUST send a PASS command
+ before any SERVER command. Only one (1) PASS command SHALL be
+ accepted from a connection.
+
+ The last three (3) parameters MUST be ignored if received from a
+ client (e.g. a user or a service). They are only relevant when
+ received from a server.
+
+ The <version> parameter is a string of at least four (4) characters,
+ and up to fourteen (14) characters. The first four (4) characters
+ MUST be digits and indicate the protocol version known by the server
+ issuing the message. The protocol described by this document is
+ version 2.10 which is encoded as "0210". The remaining OPTIONAL
+ characters are implementation dependent and should describe the
+ software version number.
+
+ The <flags> parameter is a string of up to one hundred (100)
+ characters. It is composed of two substrings separated by the
+ character "|" (%x7C). If present, the first substring MUST be the
+ name of the implementation. The reference implementation (See
+ Section 8, "Current support and availability") uses the string "IRC".
+ If a different implementation is written, which needs an identifier,
+ then that identifier should be registered through publication of an
+ RFC. The second substring is implementation dependent. Both
+ substrings are OPTIONAL, but the character "|" is REQUIRED. The
+ character "|" MUST NOT appear in either substring.
+
+ Finally, the last parameter, <options>, is used for link options.
+ The only options defined by the protocol are link compression (using
+ the character "Z"), and an abuse protection flag (using the character
+
+
+
+
+
+Kalt Informational [Page 8]
+
+RFC 2813 Internet Relay Chat: Server Protocol April 2000
+
+
+ "P"). See sections 5.3.1.1 (Compressed server to server links) and
+ 5.3.1.2 (Anti abuse protections) respectively for more information on
+ these options.
+
+ Numeric Replies:
+
+ ERR_NEEDMOREPARAMS ERR_ALREADYREGISTRED
+
+ Example:
+
+ PASS moresecretpassword 0210010000 IRC|aBgH$ Z
+
+4.1.2 Server message
+
+ Command: SERVER
+ Parameters: <servername> <hopcount> <token> <info>
+
+ The SERVER command is used to register a new server. A new connection
+ introduces itself as a server to its peer. This message is also used
+ to pass server data over whole net. When a new server is connected
+ to net, information about it MUST be broadcasted to the whole
+ network.
+
+ The <info> parameter may contain space characters.
+
+ <hopcount> is used to give all servers some internal information on
+ how far away each server is. Local peers have a value of 0, and each
+ passed server increments the value. With a full server list, it
+ would be possible to construct a map of the entire server tree, but
+ hostmasks prevent this from being done.
+
+ The <token> parameter is an unsigned number used by servers as an
+ identifier. This identifier is subsequently used to reference a
+ server in the NICK and SERVICE messages sent between servers. Server
+ tokens only have a meaning for the point-to-point peering they are
+ used and MUST be unique for that connection. They are not global.
+
+ The SERVER message MUST only be accepted from either (a) a connection
+ which is yet to be registered and is attempting to register as a
+ server, or (b) an existing connection to another server, in which
+ case the SERVER message is introducing a new server behind that
+ server.
+
+ Most errors that occur with the receipt of a SERVER command result in
+ the connection being terminated by the destination host (target
+ SERVER). Because of the severity of such event, error replies are
+ usually sent using the "ERROR" command rather than a numeric.
+
+
+
+
+Kalt Informational [Page 9]
+
+RFC 2813 Internet Relay Chat: Server Protocol April 2000
+
+
+ If a SERVER message is parsed and it attempts to introduce a server
+ which is already known to the receiving server, the connection, from
+ which that message arrived, MUST be closed (following the correct
+ procedures), since a duplicate route to a server has been formed and
+ the acyclic nature of the IRC tree breaks. In some conditions, the
+ connection from which the already known server has registered MAY be
+ closed instead. It should be noted that this kind of error can also
+ be the result of a second running server, problem which cannot be
+ fixed within the protocol and typically requires human intervention.
+ This type of problem is particularly insidious, as it can quite
+ easily result in part of the IRC network to be isolated, with one of
+ the two servers connected to each partition therefore making it
+ impossible for the two parts to unite.
+
+ Numeric Replies:
+
+ ERR_ALREADYREGISTRED
+
+ Example:
+
+ SERVER test.oulu.fi 1 1 :Experimental server ; New server
+ test.oulu.fi introducing itself and
+ attempting to register.
+
+ :tolsun.oulu.fi SERVER csd.bu.edu 5 34 :BU Central Server ; Server
+ tolsun.oulu.fi is our uplink for
+ csd.bu.edu which is 5 hops away. The
+ token "34" will be used by
+ tolsun.oulu.fi when introducing new
+ users or services connected to
+ csd.bu.edu.
+
+4.1.3 Nick
+
+ Command: NICK
+ Parameters: <nickname> <hopcount> <username> <host> <servertoken>
+ <umode> <realname>
+
+ This form of the NICK message MUST NOT be allowed from user
+ connections. However, it MUST be used instead of the NICK/USER pair
+ to notify other servers of new users joining the IRC network.
+
+ This message is really the combination of three distinct messages:
+ NICK, USER and MODE [IRC-CLIENT].
+
+ The <hopcount> parameter is used by servers to indicate how far away
+ a user is from its home server. A local connection has a hopcount of
+ 0. The hopcount value is incremented by each passed server.
+
+
+
+Kalt Informational [Page 10]
+
+RFC 2813 Internet Relay Chat: Server Protocol April 2000
+
+
+ The <servertoken> parameter replaces the <servername> parameter of
+ the USER (See section 4.1.2 for more information on server tokens).
+
+ Examples:
+
+ NICK syrk 5 kalt millennium.stealth.net 34 +i :Christophe Kalt ; New
+ user with nickname "syrk", username
+ "kalt", connected from host
+ "millennium.stealth.net" to server
+ "34" ("csd.bu.edu" according to the
+ previous example).
+
+ :krys NICK syrk ; The other form of the NICK message,
+ as defined in "IRC Client Protocol"
+ [IRC-CLIENT] and used between
+ servers: krys changed his nickname to
+ syrk
+
+4.1.4 Service message
+
+ Command: SERVICE
+ Parameters: <servicename> <servertoken> <distribution> <type>
+ <hopcount> <info>
+
+ The SERVICE command is used to introduce a new service. This form of
+ the SERVICE message SHOULD NOT be allowed from client (unregistered,
+ or registered) connections. However, it MUST be used between servers
+ to notify other servers of new services joining the IRC network.
+
+ The <servertoken> is used to identify the server to which the service
+ is connected. (See section 4.1.2 for more information on server
+ tokens).
+
+ The <hopcount> parameter is used by servers to indicate how far away
+ a service is from its home server. A local connection has a hopcount
+ of 0. The hopcount value is incremented by each passed server.
+
+ The <distribution> parameter is used to specify the visibility of a
+ service. The service may only be known to servers which have a name
+ matching the distribution. For a matching server to have knowledge
+ of the service, the network path between that server and the server
+ to which the service is connected MUST be composed of servers whose
+ names all match the mask. Plain "*" is used when no restriction is
+ wished.
+
+ The <type> parameter is currently reserved for future usage.
+
+
+
+
+
+Kalt Informational [Page 11]
+
+RFC 2813 Internet Relay Chat: Server Protocol April 2000
+
+
+ Numeric Replies:
+
+ ERR_ALREADYREGISTRED ERR_NEEDMOREPARAMS
+ ERR_ERRONEUSNICKNAME
+ RPL_YOURESERVICE RPL_YOURHOST
+ RPL_MYINFO
+
+ Example:
+
+SERVICE dict@irc.fr 9 *.fr 0 1 :French Dictionary r" registered on
+ server "9" is being announced to
+ another server. This service will
+ only be available on servers whose
+ name matches "*.fr".
+
+4.1.5 Quit
+
+ Command: QUIT
+ Parameters: [<Quit Message>]
+
+ A client session ends with a quit message. The server MUST close the
+ connection to a client which sends a QUIT message. If a "Quit
+ Message" is given, this will be sent instead of the default message,
+ the nickname or service name.
+
+ When "netsplit" (See Section 4.1.6) occur, the "Quit Message" is
+ composed of the names of two servers involved, separated by a space.
+ The first name is that of the server which is still connected and the
+ second name is either that of the server which has become
+ disconnected or that of the server to which the leaving client was
+ connected:
+
+ <Quit Message> = ":" servername SPACE servername
+
+ Because the "Quit Message" has a special meaning for "netsplits",
+ servers SHOULD NOT allow a client to use a <Quit Message> in the
+ format described above.
+
+ If, for some other reason, a client connection is closed without the
+ client issuing a QUIT command (e.g. client dies and EOF occurs on
+ socket), the server is REQUIRED to fill in the quit message with some
+ sort of message reflecting the nature of the event which caused it to
+ happen. Typically, this is done by reporting a system specific
+ error.
+
+ Numeric Replies:
+
+ None.
+
+
+
+Kalt Informational [Page 12]
+
+RFC 2813 Internet Relay Chat: Server Protocol April 2000
+
+
+ Examples:
+
+ :WiZ QUIT :Gone to have lunch ; Preferred message format.
+
+4.1.6 Server quit message
+
+ Command: SQUIT
+ Parameters: <server> <comment>
+
+ The SQUIT message has two distinct uses.
+
+ The first one (described in "Internet Relay Chat: Client Protocol"
+ [IRC-CLIENT]) allows operators to break a local or remote server
+ link. This form of the message is also eventually used by servers to
+ break a remote server link.
+
+ The second use of this message is needed to inform other servers when
+ a "network split" (also known as "netsplit") occurs, in other words
+ to inform other servers about quitting or dead servers. If a server
+ wishes to break the connection to another server it MUST send a SQUIT
+ message to the other server, using the name of the other server as
+ the server parameter, which then closes its connection to the
+ quitting server.
+
+ The <comment> is filled in by servers which SHOULD place an error or
+ similar message here.
+
+ Both of the servers which are on either side of the connection being
+ closed are REQUIRED to send out a SQUIT message (to all its other
+ server connections) for all other servers which are considered to be
+ behind that link.
+
+ Similarly, a QUIT message MAY be sent to the other still connected
+ servers on behalf of all clients behind that quitting link. In
+ addition to this, all channel members of a channel which lost a
+ member due to the "split" MUST be sent a QUIT message. Messages to
+ channel members are generated by each client's local server.
+
+ If a server connection is terminated prematurely (e.g., the server on
+ the other end of the link died), the server which detects this
+ disconnection is REQUIRED to inform the rest of the network that the
+ connection has closed and fill in the comment field with something
+ appropriate.
+
+ When a client is removed as the result of a SQUIT message, the server
+ SHOULD add the nickname to the list of temporarily unavailable
+ nicknames in an attempt to prevent future nickname collisions. See
+
+
+
+
+Kalt Informational [Page 13]
+
+RFC 2813 Internet Relay Chat: Server Protocol April 2000
+
+
+ section 5.7 (Tracking recently used nicknames) for more information
+ on this procedure.
+
+ Numeric replies:
+
+ ERR_NOPRIVILEGES ERR_NOSUCHSERVER
+ ERR_NEEDMOREPARAMS
+
+ Example:
+
+ SQUIT tolsun.oulu.fi :Bad Link ? ; the server link tolson.oulu.fi
+ has been terminated because of "Bad
+ Link".
+
+ :Trillian SQUIT cm22.eng.umd.edu :Server out of control ; message
+ from Trillian to disconnect
+ "cm22.eng.umd.edu" from the net
+ because "Server out of control".
+
+4.2 Channel operations
+
+ This group of messages is concerned with manipulating channels, their
+ properties (channel modes), and their contents (typically users). In
+ implementing these, a number of race conditions are inevitable when
+ users at opposing ends of a network send commands which will
+ ultimately clash. It is also REQUIRED that servers keep a nickname
+ history to ensure that wherever a <nick> parameter is given, the
+ server check its history in case it has recently been changed.
+
+4.2.1 Join message
+
+ Command: JOIN
+ Parameters: <channel>[ %x7 <modes> ]
+ *( "," <channel>[ %x7 <modes> ] )
+
+ The JOIN command is used by client to start listening a specific
+ channel. Whether or not a client is allowed to join a channel is
+ checked only by the local server the client is connected to; all
+ other servers automatically add the user to the channel when the
+ command is received from other servers.
+
+ Optionally, the user status (channel modes 'O', 'o', and 'v') on the
+ channel may be appended to the channel name using a control G (^G or
+ ASCII 7) as separator. Such data MUST be ignored if the message
+ wasn't received from a server. This format MUST NOT be sent to
+ clients, it can only be used between servers and SHOULD be avoided.
+
+
+
+
+
+Kalt Informational [Page 14]
+
+RFC 2813 Internet Relay Chat: Server Protocol April 2000
+
+
+ The JOIN command MUST be broadcast to all servers so that each server
+ knows where to find the users who are on the channel. This allows
+ optimal delivery of PRIVMSG and NOTICE messages to the channel.
+
+ Numeric Replies:
+
+ ERR_NEEDMOREPARAMS ERR_BANNEDFROMCHAN
+ ERR_INVITEONLYCHAN ERR_BADCHANNELKEY
+ ERR_CHANNELISFULL ERR_BADCHANMASK
+ ERR_NOSUCHCHANNEL ERR_TOOMANYCHANNELS
+ ERR_TOOMANYTARGETS ERR_UNAVAILRESOURCE
+ RPL_TOPIC
+
+ Examples:
+
+ :WiZ JOIN #Twilight_zone ; JOIN message from WiZ
+
+4.2.2 Njoin message
+
+ Command: NJOIN
+ Parameters: <channel> [ "@@" / "@" ] [ "+" ] <nickname>
+ *( "," [ "@@" / "@" ] [ "+" ] <nickname> )
+
+ The NJOIN message is used between servers only. If such a message is
+ received from a client, it MUST be ignored. It is used when two
+ servers connect to each other to exchange the list of channel members
+ for each channel.
+
+ Even though the same function can be performed by using a succession
+ of JOIN, this message SHOULD be used instead as it is more efficient.
+ The prefix "@@" indicates that the user is the "channel creator", the
+ character "@" alone indicates a "channel operator", and the character
+ '+' indicates that the user has the voice privilege.
+
+ Numeric Replies:
+
+ ERR_NEEDMOREPARAMS ERR_NOSUCHCHANNEL
+ ERR_ALREADYREGISTRED
+
+ Examples:
+
+ :ircd.stealth.net NJOIN #Twilight_zone :@WiZ,+syrk,avalon ; NJOIN
+ message from ircd.stealth.net
+ announcing users joining the
+ #Twilight_zone channel: WiZ with
+ channel operator status, syrk with
+ voice privilege and avalon with no
+ privilege.
+
+
+
+Kalt Informational [Page 15]
+
+RFC 2813 Internet Relay Chat: Server Protocol April 2000
+
+
+4.2.3 Mode message
+
+ The MODE message is a dual-purpose command in IRC. It allows both
+ usernames and channels to have their mode changed.
+
+ When parsing MODE messages, it is RECOMMENDED that the entire message
+ be parsed first, and then the changes which resulted passed on.
+
+ It is REQUIRED that servers are able to change channel modes so that
+ "channel creator" and "channel operators" may be created.
+
+5. Implementation details
+
+ A the time of writing, the only current implementation of this
+ protocol is the IRC server, version 2.10. Earlier versions may
+ implement some or all of the commands described by this document with
+ NOTICE messages replacing many of the numeric replies. Unfortunately,
+ due to backward compatibility requirements, the implementation of
+ some parts of this document varies with what is laid out. One
+ notable difference is:
+
+ * recognition that any LF or CR anywhere in a message marks
+ the end of that message (instead of requiring CR-LF);
+
+ The rest of this section deals with issues that are mostly of
+ importance to those who wish to implement a server but some parts
+ also apply directly to clients as well.
+
+5.1 Connection 'Liveness'
+
+ To detect when a connection has died or become unresponsive, the
+ server MUST poll each of its connections. The PING command (See "IRC
+ Client Protocol" [IRC-CLIENT]) is used if the server doesn't get a
+ response from its peer in a given amount of time.
+
+ If a connection doesn't respond in time, its connection is closed
+ using the appropriate procedures.
+
+5.2 Accepting a client to server connection
+
+5.2.1 Users
+
+ When a server successfully registers a new user connection, it is
+ REQUIRED to send to the user unambiguous messages stating: the user
+ identifiers upon which it was registered (RPL_WELCOME), the server
+ name and version (RPL_YOURHOST), the server birth information
+ (RPL_CREATED), available user and channel modes (RPL_MYINFO), and it
+ MAY send any introductory messages which may be deemed appropriate.
+
+
+
+Kalt Informational [Page 16]
+
+RFC 2813 Internet Relay Chat: Server Protocol April 2000
+
+
+ In particular the server SHALL send the current user/service/server
+ count (as per the LUSER reply) and finally the MOTD (if any, as per
+ the MOTD reply).
+
+ After dealing with registration, the server MUST then send out to
+ other servers the new user's nickname (NICK message), other
+ information as supplied by itself (USER message) and as the server
+ could discover (from DNS servers). The server MUST NOT send this
+ information out with a pair of NICK and USER messages as defined in
+ "IRC Client Protocol" [IRC-CLIENT], but MUST instead take advantage
+ of the extended NICK message defined in section 4.1.3.
+
+5.2.2 Services
+
+ Upon successfully registering a new service connection, the server is
+ subject to the same kind of REQUIREMENTS as for a user. Services
+ being somewhat different, only the following replies are sent:
+ RPL_YOURESERVICE, RPL_YOURHOST, RPL_MYINFO.
+
+ After dealing with this, the server MUST then send out to other
+ servers (SERVICE message) the new service's nickname and other
+ information as supplied by the service (SERVICE message) and as the
+ server could discover (from DNS servers).
+
+5.3 Establishing a server-server connection.
+
+ The process of establishing a server-to-server connection is fraught
+ with danger since there are many possible areas where problems can
+ occur - the least of which are race conditions.
+
+ After a server has received a connection following by a PASS/SERVER
+ pair which were recognized as being valid, the server SHOULD then
+ reply with its own PASS/SERVER information for that connection as
+ well as all of the other state information it knows about as
+ described below.
+
+ When the initiating server receives a PASS/SERVER pair, it too then
+ checks that the server responding is authenticated properly before
+ accepting the connection to be that server.
+
+5.3.1 Link options
+
+ Server links are based on a common protocol (defined by this
+ document) but a particular link MAY set specific options using the
+ PASS message (See Section 4.1.1).
+
+
+
+
+
+
+Kalt Informational [Page 17]
+
+RFC 2813 Internet Relay Chat: Server Protocol April 2000
+
+
+5.3.1.1 Compressed server to server links
+
+ If a server wishes to establish a compressed link with its peer, it
+ MUST set the 'Z' flag in the options parameter to the PASS message.
+ If both servers request compression and both servers are able to
+ initialize the two compressed streams, then the remainder of the
+ communication is to be compressed. If any server fails to initialize
+ the stream, it will send an uncompressed ERROR message to its peer
+ and close the connection.
+
+ The data format used for the compression is described by RFC 1950
+ [ZLIB], RFC 1951 [DEFLATE] and RFC 1952 [GZIP].
+
+5.3.1.2 Anti abuse protections
+
+ Most servers implement various kinds of protections against possible
+ abusive behaviours from non trusted parties (typically users). On
+ some networks, such protections are indispensable, on others they are
+ superfluous. To require that all servers implement and enable such
+ features on a particular network, the 'P' flag is used when two
+ servers connect. If this flag is present, it means that the server
+ protections are enabled, and that the server REQUIRES all its server
+ links to enable them as well.
+
+ Commonly found protections are described in sections 5.7 (Tracking
+ recently used nicknames) and 5.8 (Flood control of clients).
+
+5.3.2 State information exchange when connecting
+
+ The order of state information being exchanged between servers is
+ essential. The REQUIRED order is as follows:
+
+ * all known servers;
+
+ * all known client information;
+
+ * all known channel information.
+
+ Information regarding servers is sent via extra SERVER messages,
+ client information with NICK and SERVICE messages and channels with
+ NJOIN/MODE messages.
+
+ NOTE: channel topics SHOULD NOT be exchanged here because the TOPIC
+ command overwrites any old topic information, so at best, the two
+ sides of the connection would exchange topics.
+
+
+
+
+
+
+Kalt Informational [Page 18]
+
+RFC 2813 Internet Relay Chat: Server Protocol April 2000
+
+
+ By passing the state information about servers first, any collisions
+ with servers that already exist occur before nickname collisions
+ caused by a second server introducing a particular nickname. Due to
+ the IRC network only being able to exist as an acyclic graph, it may
+ be possible that the network has already reconnected in another
+ location. In this event, the place where the server collision occurs
+ indicates where the net needs to split.
+
+5.4 Terminating server-client connections
+
+ When a client connection unexpectedly closes, a QUIT message is
+ generated on behalf of the client by the server to which the client
+ was connected. No other message is to be generated or used.
+
+5.5 Terminating server-server connections
+
+ If a server-server connection is closed, either via a SQUIT command
+ or "natural" causes, the rest of the connected IRC network MUST have
+ its information updated by the server which detected the closure.
+ The terminating server then sends a list of SQUITs (one for each
+ server behind that connection). (See Section 4.1.6 (SQUIT)).
+
+5.6 Tracking nickname changes
+
+ All IRC servers are REQUIRED to keep a history of recent nickname
+ changes. This is important to allow the server to have a chance of
+ keeping in touch of things when nick-change race conditions occur
+ with commands manipulating them. Messages which MUST trace nick
+ changes are:
+
+ * KILL (the nick being disconnected)
+
+ * MODE (+/- o,v on channels)
+
+ * KICK (the nick being removed from channel)
+
+ No other commands need to check nick changes.
+
+ In the above cases, the server is required to first check for the
+ existence of the nickname, then check its history to see who that
+ nick now belongs to (if anyone!). This reduces the chances of race
+ conditions but they can still occur with the server ending up
+ affecting the wrong client. When performing a change trace for an
+ above command it is RECOMMENDED that a time range be given and
+ entries which are too old ignored.
+
+
+
+
+
+
+Kalt Informational [Page 19]
+
+RFC 2813 Internet Relay Chat: Server Protocol April 2000
+
+
+ For a reasonable history, a server SHOULD be able to keep previous
+ nickname for every client it knows about if they all decided to
+ change. This size is limited by other factors (such as memory, etc).
+
+5.7 Tracking recently used nicknames
+
+ This mechanism is commonly known as "Nickname Delay", it has been
+ proven to significantly reduce the number of nickname collisions
+ resulting from "network splits"/reconnections as well as abuse.
+
+ In addition of keeping track of nickname changes, servers SHOULD keep
+ track of nicknames which were recently used and were released as the
+ result of a "network split" or a KILL message. These nicknames are
+ then unavailable to the server local clients and cannot be re-used
+ (even though they are not currently in use) for a certain period of
+ time.
+
+ The duration for which a nickname remains unavailable SHOULD be set
+ considering many factors among which are the size (user wise) of the
+ IRC network, and the usual duration of "network splits". It SHOULD
+ be uniform on all servers for a given IRC network.
+
+5.8 Flood control of clients
+
+ With a large network of interconnected IRC servers, it is quite easy
+ for any single client attached to the network to supply a continuous
+ stream of messages that result in not only flooding the network, but
+ also degrading the level of service provided to others. Rather than
+ require every 'victim' to provide their own protection, flood
+ protection was written into the server and is applied to all clients
+ except services. The current algorithm is as follows:
+
+ * check to see if client's `message timer' is less than current time
+ (set to be equal if it is);
+
+ * read any data present from the client;
+
+ * while the timer is less than ten (10) seconds ahead of the current
+ time, parse any present messages and penalize the client by two (2)
+ seconds for each message;
+
+ * additional penalties MAY be used for specific commands which
+ generate a lot of traffic across the network.
+
+ This in essence means that the client may send one (1) message every
+ two (2) seconds without being adversely affected. Services MAY also
+ be subject to this mechanism.
+
+
+
+
+Kalt Informational [Page 20]
+
+RFC 2813 Internet Relay Chat: Server Protocol April 2000
+
+
+5.9 Non-blocking lookups
+
+ In a real-time environment, it is essential that a server process
+ does as little waiting as possible so that all the clients are
+ serviced fairly. Obviously this requires non-blocking IO on all
+ network read/write operations. For normal server connections, this
+ was not difficult, but there are other support operations that may
+ cause the server to block (such as disk reads). Where possible, such
+ activity SHOULD be performed with a short timeout.
+
+5.9.1 Hostname (DNS) lookups
+
+ Using the standard resolver libraries from Berkeley and others has
+ meant large delays in some cases where replies have timed out. To
+ avoid this, a separate set of DNS routines were written for the
+ current implementation. Routines were setup for non-blocking IO
+ operations with local cache, and then polled from within the main
+ server IO loop.
+
+5.9.2 Username (Ident) lookups
+
+ Although there are numerous ident libraries (implementing the
+ "Identification Protocol" [IDENT]) for use and inclusion into other
+ programs, these caused problems since they operated in a synchronous
+ manner and resulted in frequent delays. Again the solution was to
+ write a set of routines which would cooperate with the rest of the
+ server and work using non-blocking IO.
+
+6. Current problems
+
+ There are a number of recognized problems with this protocol, all of
+ which are hoped to be solved sometime in the near future during its
+ rewrite. Currently, work is underway to find working solutions to
+ these problems.
+
+6.1 Scalability
+
+ It is widely recognized that this protocol does not scale
+ sufficiently well when used in a large arena. The main problem comes
+ from the requirement that all servers know about all other servers
+ and clients and that information regarding them be updated as soon as
+ it changes. It is also desirable to keep the number of servers low
+ so that the path length between any two points is kept minimal and
+ the spanning tree as strongly branched as possible.
+
+
+
+
+
+
+
+Kalt Informational [Page 21]
+
+RFC 2813 Internet Relay Chat: Server Protocol April 2000
+
+
+6.2 Labels
+
+ The current IRC protocol has 4 types of labels: the nickname, the
+ channel name, the server name and the service name. Each of the four
+ types has its own domain and no duplicates are allowed inside that
+ domain. Currently, it is possible for users to pick the label for
+ any of the first three, resulting in collisions. It is widely
+ recognized that this needs reworking, with a plan for unique names
+ for nicks that don't collide being desirable as well as a solution
+ allowing a cyclic tree.
+
+6.2.1 Nicknames
+
+ The idea of the nickname on IRC is very convenient for users to use
+ when talking to each other outside of a channel, but there is only a
+ finite nickname space and being what they are, it's not uncommon for
+ several people to want to use the same nick. If a nickname is chosen
+ by two people using this protocol, either one will not succeed or
+ both will be removed by use of KILL (See Section 3.7.1 of "IRC Client
+ Protocol" [IRC-CLIENT]).
+
+6.2.2 Channels
+
+ The current channel layout requires that all servers know about all
+ channels, their inhabitants and properties. Besides not scaling
+ well, the issue of privacy is also a concern. A collision of
+ channels is treated as an inclusive event (people from both nets on
+ channel with common name are considered to be members of it) rather
+ than an exclusive one such as used to solve nickname collisions.
+
+ This protocol defines "Safe Channels" which are very unlikely to be
+ the subject of a channel collision. Other channel types are kept for
+ backward compatibility.
+
+6.2.3 Servers
+
+ Although the number of servers is usually small relative to the
+ number of users and channels, they too are currently REQUIRED to be
+ known globally, either each one separately or hidden behind a mask.
+
+6.3 Algorithms
+
+ In some places within the server code, it has not been possible to
+ avoid N^2 algorithms such as checking the channel list of a set of
+ clients.
+
+
+
+
+
+
+Kalt Informational [Page 22]
+
+RFC 2813 Internet Relay Chat: Server Protocol April 2000
+
+
+ In current server versions, there are only few database consistency
+ checks, most of the time each server assumes that a neighbouring
+ server is correct. This opens the door to large problems if a
+ connecting server is buggy or otherwise tries to introduce
+ contradictions to the existing net.
+
+ Currently, because of the lack of unique internal and global labels,
+ there are a multitude of race conditions that exist. These race
+ conditions generally arise from the problem of it taking time for
+ messages to traverse and effect the IRC network. Even by changing to
+ unique labels, there are problems with channel-related commands being
+ disrupted.
+
+7. Security Considerations
+
+7.1 Authentication
+
+ Servers only have two means of authenticating incoming connections:
+ plain text password, and DNS lookups. While these methods are weak
+ and widely recognized as unsafe, their combination has proven to be
+ sufficient in the past:
+
+ * public networks typically allow user connections with only few
+ restrictions, without requiring accurate authentication.
+
+ * private networks which operate in a controlled environment often
+ use home-grown authentication mechanisms not available on the
+ internet: reliable ident servers [IDENT], or other proprietary
+ mechanisms.
+
+ The same comments apply to the authentication of IRC Operators.
+
+ It should also be noted that while there has been no real demand over
+ the years for stronger authentication, and no real effort to provide
+ better means to safely authenticate users, the current protocol
+ offers enough to be able to easily plug-in external authentication
+ methods based on the information that a client can submit to the
+ server upon connection: nickname, username, password.
+
+7.2 Integrity
+
+ Since the PASS and OPER messages of the IRC protocol are sent in
+ clear text, a stream layer encryption mechanism (like "The TLS
+ Protocol" [TLS]) could be used to protect these transactions.
+
+
+
+
+
+
+
+Kalt Informational [Page 23]
+
+RFC 2813 Internet Relay Chat: Server Protocol April 2000
+
+
+8. Current support and availability
+
+ Mailing lists for IRC related discussion:
+ General discussion: ircd-users@irc.org
+ Protocol development: ircd-dev@irc.org
+
+ Software implementations:
+ ftp://ftp.irc.org/irc/server
+ ftp://ftp.funet.fi/pub/unix/irc
+ ftp://coombs.anu.edu.au/pub/irc
+
+ Newsgroup: alt.irc
+
+9. Acknowledgements
+
+ Parts of this document were copied from the RFC 1459 [IRC] which
+ first formally documented the IRC Protocol. It has also benefited
+ from many rounds of review and comments. In particular, the
+ following people have made significant contributions to this
+ document:
+
+ Matthew Green, Michael Neumayer, Volker Paulsen, Kurt Roeckx, Vesa
+ Ruokonen, Magnus Tjernstrom, Stefan Zehl.
+
+10. References
+
+ [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+ [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax
+ Specifications: ABNF", RFC 2234, November 1997.
+
+ [IRC] Oikarinen, J. and D. Reed, "Internet Relay Chat
+ Protocol", RFC 1459, May 1993.
+
+ [IRC-ARCH] Kalt, C., "Internet Relay Chat: Architecture", RFC 2810,
+ April 2000.
+
+ [IRC-CLIENT] Kalt, C., "Internet Relay Chat: Client Protocol", RFC
+ 2812, April 2000.
+
+
+ [IRC-CHAN] Kalt, C., "Internet Relay Chat: Channel Management", RFC
+ 2811, April 2000.
+
+ [ZLIB] Deutsch, P. and J-L. Gailly, "ZLIB Compressed Data
+ Format Specification version 3.3", RFC 1950, May 1996.
+
+
+
+
+Kalt Informational [Page 24]
+
+RFC 2813 Internet Relay Chat: Server Protocol April 2000
+
+
+ [DEFLATE] Deutsch, P., "DEFLATE Compressed Data Format
+ Specification version 1.3", RFC 1951, May 1996.
+
+ [GZIP] Deutsch, P., "GZIP file format specification version
+ 4.3", RFC 1952, May 1996.
+
+ [IDENT] St. Johns, M., "The Identification Protocol", RFC 1413,
+ February 1993.
+
+ [TLS] Dierks, T. and C. Allen, "The TLS Protocol", RFC 2246,
+ January 1999.
+
+11. Author's Address
+
+ Christophe Kalt
+ 99 Teaneck Rd, Apt #117
+ Ridgefield Park, NJ 07660
+ USA
+
+ EMail: kalt@stealth.net
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Kalt Informational [Page 25]
+
+RFC 2813 Internet Relay Chat: Server Protocol April 2000
+
+
+12. Full Copyright Statement
+
+ Copyright (C) The Internet Society (2000). All Rights Reserved.
+
+ This document and translations of it may be copied and furnished to
+ others, and derivative works that comment on or otherwise explain it
+ or assist in its implementation may be prepared, copied, published
+ and distributed, in whole or in part, without restriction of any
+ kind, provided that the above copyright notice and this paragraph are
+ included on all such copies and derivative works. However, this
+ document itself may not be modified in any way, such as by removing
+ the copyright notice or references to the Internet Society or other
+ Internet organizations, except as needed for the purpose of
+ developing Internet standards in which case the procedures for
+ copyrights defined in the Internet Standards process must be
+ followed, or as required to translate it into languages other than
+ English.
+
+ The limited permissions granted above are perpetual and will not be
+ revoked by the Internet Society or its successors or assigns.
+
+ This document and the information contained herein is provided on an
+ "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
+ TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
+ BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
+ HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
+ MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+Acknowledgement
+
+ Funding for the RFC Editor function is currently provided by the
+ Internet Society.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Kalt Informational [Page 26]
+
diff --git a/doc/rfcs/rfc4422.txt b/doc/rfcs/rfc4422.txt
new file mode 100644
index 0000000..049fa8c
--- /dev/null
+++ b/doc/rfcs/rfc4422.txt
@@ -0,0 +1,1851 @@
+
+
+
+
+
+
+Network Working Group A. Melnikov, Ed.
+Request for Comments: 4422 Isode Limited
+Obsoletes: 2222 K. Zeilenga, Ed.
+Category: Standards Track OpenLDAP Foundation
+ June 2006
+
+
+ Simple Authentication and Security Layer (SASL)
+
+Status of This Memo
+
+ This document specifies an Internet standards track protocol for the
+ Internet community, and requests discussion and suggestions for
+ improvements. Please refer to the current edition of the "Internet
+ Official Protocol Standards" (STD 1) for the standardization state
+ and status of this protocol. Distribution of this memo is unlimited.
+
+Copyright Notice
+
+ Copyright (C) The Internet Society (2006).
+
+Abstract
+
+ The Simple Authentication and Security Layer (SASL) is a framework
+ for providing authentication and data security services in
+ connection-oriented protocols via replaceable mechanisms. It
+ provides a structured interface between protocols and mechanisms.
+ The resulting framework allows new protocols to reuse existing
+ mechanisms and allows old protocols to make use of new mechanisms.
+ The framework also provides a protocol for securing subsequent
+ protocol exchanges within a data security layer.
+
+ This document describes how a SASL mechanism is structured, describes
+ how protocols include support for SASL, and defines the protocol for
+ carrying a data security layer over a connection. In addition, this
+ document defines one SASL mechanism, the EXTERNAL mechanism.
+
+ This document obsoletes RFC 2222.
+
+
+
+
+
+
+
+
+
+
+
+
+
+Melnikov & Zeilenga Standards Track [Page 1]
+
+RFC 4422 SASL June 2006
+
+
+Table of Contents
+
+ 1. Introduction ....................................................3
+ 1.1. Document Audiences .........................................4
+ 1.2. Relationship to Other Documents ............................4
+ 1.3. Conventions ................................................5
+ 2. Identity Concepts ...............................................5
+ 3. The Authentication Exchange .....................................6
+ 3.1. Mechanism Naming ...........................................8
+ 3.2. Mechanism Negotiation ......................................9
+ 3.3. Request Authentication Exchange ............................9
+ 3.4. Challenges and Responses ...................................9
+ 3.4.1. Authorization Identity String ......................10
+ 3.5. Aborting Authentication Exchanges .........................10
+ 3.6. Authentication Outcome ....................................11
+ 3.7. Security Layers ...........................................12
+ 3.8. Multiple Authentications ..................................12
+ 4. Protocol Requirements ..........................................13
+ 5. Mechanism Requirements .........................................16
+ 6. Security Considerations ........................................18
+ 6.1. Active Attacks ............................................19
+ 6.1.1. Hijack Attacks .....................................19
+ 6.1.2. Downgrade Attacks ..................................19
+ 6.1.3. Replay Attacks .....................................20
+ 6.1.4. Truncation Attacks .................................20
+ 6.1.5. Other Active Attacks ...............................20
+ 6.2. Passive Attacks ...........................................20
+ 6.3. Re-keying .................................................21
+ 6.4. Other Considerations ......................................21
+ 7. IANA Considerations ............................................22
+ 7.1. SASL Mechanism Registry ...................................22
+ 7.2. Registration Changes ......................................26
+ 8. References .....................................................26
+ 8.1. Normative References ......................................26
+ 8.2. Informative References ....................................27
+ 9. Acknowledgements ...............................................28
+ Appendix A. The SASL EXTERNAL Mechanism ..........................29
+ A.1. EXTERNAL Technical Specification ..........................29
+ A.2. SASL EXTERNAL Examples ....................................30
+ A.3. Security Considerations ...................................31
+ Appendix B. Changes since RFC 2222 ...............................31
+
+
+
+
+
+
+
+
+
+
+Melnikov & Zeilenga Standards Track [Page 2]
+
+RFC 4422 SASL June 2006
+
+
+1. Introduction
+
+ The Simple Authentication and Security Layer (SASL) is a framework
+ for providing authentication and data security services in
+ connection-oriented protocols via replaceable mechanisms. SASL
+ provides a structured interface between protocols and mechanisms.
+ SASL also provides a protocol for securing subsequent protocol
+ exchanges within a data security layer. The data security layer can
+ provide data integrity, data confidentiality, and other services.
+
+ SASL's design is intended to allow new protocols to reuse existing
+ mechanisms without requiring redesign of the mechanisms and allows
+ existing protocols to make use of new mechanisms without redesign of
+ protocols.
+
+ SASL is conceptually a framework that provides an abstraction layer
+ between protocols and mechanisms as illustrated in the following
+ diagram.
+
+ SMTP LDAP XMPP Other protocols ...
+ \ | | /
+ \ | | /
+ SASL abstraction layer
+ / | | \
+ / | | \
+ EXTERNAL GSSAPI PLAIN Other mechanisms ...
+
+ It is through the interfaces of this abstraction layer that the
+ framework allows any protocol to utilize any mechanism. While this
+ layer does generally hide the particulars of protocols from
+ mechanisms and the particulars of mechanisms from protocols, this
+ layer does not generally hide the particulars of mechanisms from
+ protocol implementations. For example, different mechanisms require
+ different information to operate, some of them use password-based
+ authentication, some of then require realm information, others make
+ use of Kerberos tickets, certificates, etc. Also, in order to
+ perform authorization, server implementations generally have to
+ implement identity mapping between authentication identities, whose
+ form is mechanism specific, and authorization identities, whose form
+ is application protocol specific. Section 2 discusses identity
+ concepts.
+
+ It is possible to design and implement this framework in ways that do
+ abstract away particulars of similar mechanisms. Such a framework
+ implementation, as well as mechanisms implementations, could be
+ designed not only to be shared by multiple implementations of a
+ particular protocol but to be shared by implementations of multiple
+ protocols.
+
+
+
+Melnikov & Zeilenga Standards Track [Page 3]
+
+RFC 4422 SASL June 2006
+
+
+ The framework incorporates interfaces with both protocols and
+ mechanisms in which authentication exchanges are carried out.
+ Section 3 discusses SASL authentication exchanges.
+
+ To use SASL, each protocol (amongst other items) provides a method
+ for identifying which mechanism is to be used, a method for exchange
+ of mechanism-specific server-challenges and client-responses, and a
+ method for communicating the outcome of the authentication exchange.
+ Section 4 discusses SASL protocol requirements.
+
+ Each SASL mechanism defines (amongst other items) a series of
+ server-challenges and client-responses that provide authentication
+ services and negotiate data security services. Section 5 discusses
+ SASL mechanism requirements.
+
+ Section 6 discusses security considerations. Section 7 discusses
+ IANA considerations. Appendix A defines the SASL EXTERNAL mechanism.
+
+1.1. Document Audiences
+
+ This document is written to serve several different audiences:
+
+ - protocol designers using this specification to support
+ authentication in their protocol,
+
+ - mechanism designers that define new SASL mechanisms, and
+
+ - implementors of clients or servers for those protocols that
+ support SASL.
+
+ While the document organization is intended to allow readers to focus
+ on details relevant to their engineering, readers are encouraged to
+ read and understand all aspects of this document.
+
+1.2. Relationship to Other Documents
+
+ This document obsoletes RFC 2222. It replaces all portions of RFC
+ 2222 excepting sections 7.1 (the KERBEROS_IV mechanism), 7.2 (the
+ GSSAPI mechanism), 7.3 (the SKEY mechanism). The KERBEROS_IV and
+ SKEY mechanisms are now viewed as obsolete and their specifications
+ provided in RFC 2222 are Historic. The GSSAPI mechanism is now
+ separately specified [SASL-GSSAPI].
+
+ Appendix B provides a summary of changes since RFC 2222.
+
+
+
+
+
+
+
+Melnikov & Zeilenga Standards Track [Page 4]
+
+RFC 4422 SASL June 2006
+
+
+1.3. Conventions
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+ document are to be interpreted as described in BCP 14 [RFC2119].
+
+ Character names in this document use the notation for code points and
+ names from the Unicode Standard [Unicode]. For example, the letter
+ "a" may be represented as either <U+0061> or <LATIN SMALL LETTER A>.
+
+ Note: a glossary of terms used in Unicode can be found in [Glossary].
+ Information on the Unicode character encoding model can be found in
+ [CharModel].
+
+ In examples, "C:" and "S:" indicate lines of data to be sent by the
+ client and server, respectively. Lines have been wrapped for
+ improved readability.
+
+2. Identity Concepts
+
+ In practice, authentication and authorization may involve multiple
+ identities, possibly in different forms (simple username, Kerberos
+ principal, X.500 Distinguished Name, etc.), possibly with different
+ representations (e.g., ABNF-described UTF-8 encoded Unicode character
+ string, BER-encoded Distinguished Name). While technical
+ specifications often prescribe both the identity form and
+ representation used on the network, different identity forms and/or
+ representations may be (and often are) used within implementations.
+ How identities of different forms relate to each other is, generally,
+ a local matter. In addition, the forms and representations used
+ within an implementation are a local matter.
+
+ However, conceptually, the SASL framework involves two identities:
+
+ 1) an identity associated with the authentication credentials
+ (termed the authentication identity), and
+
+ 2) an identity to act as (termed the authorization identity).
+
+ SASL mechanism specifications describe the credential form(s) (e.g.,
+ X.509 certificates, Kerberos tickets, simple username/password) used
+ to authenticate the client, including (where appropriate) the syntax
+ and semantics of authentication identities carried in the
+ credentials. SASL protocol specifications describe the identity
+ form(s) used in authorization and, in particular, prescribe the
+ syntax and semantics of the authorization identity character string
+ to be transferred by mechanisms.
+
+
+
+
+Melnikov & Zeilenga Standards Track [Page 5]
+
+RFC 4422 SASL June 2006
+
+
+ The client provides its credentials (which include or imply an
+ authentication identity) and, optionally, a character string
+ representing the requested authorization identity as part of the SASL
+ exchange. When this character string is omitted or empty, the client
+ is requesting to act as the identity associated with the credentials
+ (e.g., the user is requesting to act as the authentication identity).
+
+ The server is responsible for verifying the client's credentials and
+ verifying that the identity it associates with the client's
+ credentials (e.g., the authentication identity) is allowed to act as
+ the authorization identity. A SASL exchange fails if either (or
+ both) of these verifications fails. (The SASL exchange may fail for
+ other reasons, such as service authorization failure.)
+
+ However, the precise form(s) of the authentication identities (used
+ within the server in its verifications, or otherwise) and the precise
+ form(s) of the authorization identities (used in making authorization
+ decisions, or otherwise) are beyond the scope of SASL and this
+ specification. In some circumstances, the precise identity forms
+ used in some context outside of the SASL exchange may be dictated by
+ other specifications. For instance, an identity assumption
+ authorization (proxy authorization) policy specification may dictate
+ how authentication and authorization identities are represented in
+ policy statements.
+
+3. The Authentication Exchange
+
+ Each authentication exchange consists of a message from the client to
+ the server requesting authentication via a particular mechanism,
+ followed by one or more pairs of challenges from the server and
+ responses from the client, followed by a message from the server
+ indicating the outcome of the authentication exchange. (Note:
+ exchanges may also be aborted as discussed in Section 3.5.)
+
+ The following illustration provides a high-level overview of an
+ authentication exchange.
+
+ C: Request authentication exchange
+ S: Initial challenge
+ C: Initial response
+ <additional challenge/response messages>
+ S: Outcome of authentication exchange
+
+ If the outcome is successful and a security layer was negotiated,
+ this layer is then installed (see Section 3.7). This also applies to
+ the following illustrations.
+
+
+
+
+
+Melnikov & Zeilenga Standards Track [Page 6]
+
+RFC 4422 SASL June 2006
+
+
+ Some mechanisms specify that the first data sent in the
+ authentication exchange is from the client to the server. Protocols
+ may provide an optional initial response field in the request message
+ to carry this data. Where the mechanism specifies that the first
+ data sent in the exchange is from the client to the server, the
+ protocol provides an optional initial response field, and the client
+ uses this field, the exchange is shortened by one round-trip:
+
+ C: Request authentication exchange + Initial response
+ <additional challenge/response messages>
+ S: Outcome of authentication exchange
+
+ Where the mechanism specifies that the first data sent in the
+ exchange is from the client to the server and this field is
+ unavailable or unused, the client request is followed by an empty
+ challenge.
+
+ C: Request authentication exchange
+ S: Empty Challenge
+ C: Initial Response
+ <additional challenge/response messages>
+ S: Outcome of authentication exchange
+
+ Should a client include an initial response in its request where the
+ mechanism does not allow the client to send data first, the
+ authentication exchange fails.
+
+ Some mechanisms specify that the server is to send additional data to
+ the client when indicating a successful outcome. Protocols may
+ provide an optional additional data field in the outcome message to
+ carry this data. Where the mechanism specifies that the server is to
+ return additional data with the successful outcome, the protocol
+ provides an optional additional data field in the outcome message,
+ and the server uses this field, the exchange is shortened by one
+ round-trip:
+
+ C: Request authentication exchange
+ S: Initial challenge
+ C: Initial response
+ <additional challenge/response messages>
+ S: Outcome of authentication exchange with
+ additional data with success
+
+ Where the mechanism specifies that the server is to return additional
+ data to the client with a successful outcome and this field is
+ unavailable or unused, the additional data is sent as a challenge
+ whose response is empty. After receiving this response, the server
+ then indicates the successful outcome.
+
+
+
+Melnikov & Zeilenga Standards Track [Page 7]
+
+RFC 4422 SASL June 2006
+
+
+ C: Request authentication exchange
+ S: Initial challenge
+ C: Initial response
+ <additional challenge/response messages>
+ S: Additional data challenge
+ C: Empty Response
+ S: Outcome of authentication exchange
+
+ Where mechanisms specify that the first data sent in the exchange is
+ from the client to the server and additional data is sent to the
+ client along with indicating a successful outcome, and the protocol
+ provides fields supporting both, then the exchange takes two fewer
+ round-trips:
+
+ C: Request authentication exchange + Initial response
+ <additional challenge/response messages>
+ S: Outcome of authentication exchange
+ with additional data with success
+
+ instead of:
+
+ C: Request authentication exchange
+ S: Empty Challenge
+ C: Initial Response
+ <additional challenge/response messages>
+ S: Additional data challenge
+ C: Empty Response
+ S: Outcome of authentication exchange
+
+3.1. Mechanism Naming
+
+ SASL mechanisms are named by character strings, from 1 to 20
+ characters in length, consisting of ASCII [ASCII] uppercase letters,
+ digits, hyphens, and/or underscores. In the following Augmented
+ Backus-Naur Form (ABNF) [RFC4234] grammar, the <sasl-mech> production
+ defines the syntax of a SASL mechanism name.
+
+ sasl-mech = 1*20mech-char
+ mech-char = UPPER-ALPHA / DIGIT / HYPHEN / UNDERSCORE
+ ; mech-char is restricted to A-Z (uppercase only), 0-9, -, and _
+ ; from ASCII character set.
+
+ UPPER-ALPHA = %x41-5A ; A-Z (uppercase only)
+ DIGIT = %x30-39 ; 0-9
+ HYPHEN = %x2D ; hyphen (-)
+ UNDERSCORE = %x5F ; underscore (_)
+
+ SASL mechanism names are registered as discussed in Section 7.1.
+
+
+
+Melnikov & Zeilenga Standards Track [Page 8]
+
+RFC 4422 SASL June 2006
+
+
+3.2. Mechanism Negotiation
+
+ Mechanism negotiation is protocol specific.
+
+ Commonly, a protocol will specify that the server advertises
+ supported and available mechanisms to the client via some facility
+ provided by the protocol, and the client will then select the "best"
+ mechanism from this list that it supports and finds suitable.
+
+ Note that the mechanism negotiation is not protected by the
+ subsequent authentication exchange and hence is subject to downgrade
+ attacks if not protected by other means.
+
+ To detect downgrade attacks, a protocol can allow the client to
+ discover available mechanisms subsequent to the authentication
+ exchange and installation of data security layers with at least data
+ integrity protection. This allows the client to detect changes to
+ the list of mechanisms supported by the server.
+
+3.3. Request Authentication Exchange
+
+ The authentication exchange is initiated by the client by requesting
+ authentication via a mechanism it specifies. The client sends a
+ message that contains the name of the mechanism to the server. The
+ particulars of the message are protocol specific.
+
+ Note that the name of the mechanism is not protected by the
+ mechanism, and hence is subject to alteration by an attacker if not
+ integrity protected by other means.
+
+ Where the mechanism is defined to allow the client to send data
+ first, and the protocol's request message includes an optional
+ initial response field, the client may include the response to the
+ initial challenge in the authentication request message.
+
+3.4. Challenges and Responses
+
+ The authentication exchange involves one or more pairs of server-
+ challenges and client-responses, the particulars of which are
+ mechanism specific. These challenges and responses are enclosed in
+ protocol messages, the particulars of which are protocol specific.
+
+ Through these challenges and responses, the mechanism may:
+
+ - authenticate the client to the server,
+
+ - authenticate the server to the client,
+
+
+
+
+Melnikov & Zeilenga Standards Track [Page 9]
+
+RFC 4422 SASL June 2006
+
+
+ - transfer an authorization identity string,
+
+ - negotiate a security layer, and
+
+ - provide other services.
+
+ The negotiation of the security layer may involve negotiation of the
+ security services to be provided in the layer, how these services
+ will be provided, and negotiation of a maximum cipher-text buffer
+ size each side is able to receive in the layer (see Section 3.6).
+
+ After receiving an authentication request or any client response, the
+ server may issue a challenge, abort the exchange, or indicate the
+ outcome of an exchange. After receiving a challenge, a client
+ mechanism may issue a response or abort the exchange.
+
+3.4.1. Authorization Identity String
+
+ The authorization identity string is a sequence of zero or more
+ Unicode [Unicode] characters, excluding the NUL (U+0000) character,
+ representing the identity to act as.
+
+ If the authorization identity string is absent, the client is
+ requesting to act as the identity the server associates with the
+ client's credentials. An empty string is equivalent to an absent
+ authorization identity.
+
+ A non-empty authorization identity string indicates that the client
+ wishes to act as the identity represented by the string. In this
+ case, the form of identity represented by the string, as well as the
+ precise syntax and semantics of the string, is protocol specific.
+
+ While the character encoding schema used to transfer the
+ authorization identity string in the authentication exchange is
+ mechanism specific, mechanisms are expected to be capable of carrying
+ the entire Unicode repertoire (with the exception of the NUL
+ character).
+
+3.5. Aborting Authentication Exchanges
+
+ A client or server may desire to abort an authentication exchange if
+ it is unwilling or unable to continue (or enter into).
+
+ A client may abort the authentication exchange by sending a message,
+ the particulars of which are protocol specific, to the server,
+ indicating that the exchange is aborted. The server may be required
+ by the protocol to return a message in response to the client's abort
+ message.
+
+
+
+Melnikov & Zeilenga Standards Track [Page 10]
+
+RFC 4422 SASL June 2006
+
+
+ Likewise, a server may abort the authentication exchange by sending a
+ message, the particulars of which are protocol specific, to the
+ client, indicating that the exchange is aborted.
+
+3.6. Authentication Outcome
+
+ At the conclusion of the authentication exchange, the server sends a
+ message, the particulars of which are protocol specific, to the
+ client indicating the outcome of the exchange.
+
+ The outcome is not successful if
+
+ - the authentication exchange failed for any reason,
+
+ - the client's credentials could not be verified,
+
+ - the server cannot associate an identity with the client's
+ credentials,
+
+ - the client-provided authorization identity string is malformed,
+
+ - the identity associated with the client's credentials is not
+ authorized to act as the requested authorization identity,
+
+ - the negotiated security layer (or lack thereof) is not
+ suitable, or
+
+ - the server is not willing to provide service to the client for
+ any reason.
+
+ The protocol may include an optional additional data field in this
+ outcome message. This field can only include additional data when
+ the outcome is successful.
+
+ If the outcome is successful and a security layer was negotiated,
+ this layer is then installed. If the outcome is unsuccessful, or a
+ security layer was not negotiated, any existing security is left in
+ place.
+
+ The outcome message provided by the server can provide a way for the
+ client to distinguish between errors that are best dealt with by re-
+ prompting the user for her credentials, errors that are best dealt
+ with by telling the user to try again later, and errors where the
+ user must contact a system administrator for resolution (see the SYS
+ and AUTH POP Response Codes [RFC3206] specification for an example).
+ This distinction is particularly useful during scheduled server
+ maintenance periods as it reduces support costs. It is also
+ important that the server can be configured such that the outcome
+
+
+
+Melnikov & Zeilenga Standards Track [Page 11]
+
+RFC 4422 SASL June 2006
+
+
+ message will not distinguish between a valid user with invalid
+ credentials and an invalid user.
+
+3.7. Security Layers
+
+ SASL mechanisms may offer a wide range of services in security
+ layers. Typical services include data integrity and data
+ confidentiality. SASL mechanisms that do not provide a security
+ layer are treated as negotiating no security layer.
+
+ If use of a security layer is negotiated in the authentication
+ protocol exchange, the layer is installed by the server after
+ indicating the outcome of the authentication exchange and installed
+ by the client upon receipt of the outcome indication. In both cases,
+ the layer is installed before transfer of further protocol data. The
+ precise position upon which the layer takes effect in the protocol
+ data stream is protocol specific.
+
+ Once the security layer is in effect in the protocol data stream, it
+ remains in effect until either a subsequently negotiated security
+ layer is installed or the underlying transport connection is closed.
+
+ When in effect, the security layer processes protocol data into
+ buffers of protected data. If at any time the security layer is
+ unable or unwilling to continue producing buffers protecting protocol
+ data, the underlying transport connection MUST be closed. If the
+ security layer is not able to decode a received buffer, the
+ underlying connection MUST be closed. In both cases, the underlying
+ transport connection SHOULD be closed gracefully.
+
+ Each buffer of protected data is transferred over the underlying
+ transport connection as a sequence of octets prepended with a four-
+ octet field in network byte order that represents the length of the
+ buffer. The length of the protected data buffer MUST be no larger
+ than the maximum size that the other side expects. Upon the receipt
+ of a length field whose value is greater than the maximum size, the
+ receiver SHOULD close the connection, as this might be a sign of an
+ attack.
+
+ The maximum size that each side expects is fixed by the mechanism,
+ either through negotiation or by its specification.
+
+3.8. Multiple Authentications
+
+ Unless explicitly permitted in the protocol (as stated in the
+ protocol's technical specification), only one successful SASL
+ authentication exchange may occur in a protocol session. In this
+
+
+
+
+Melnikov & Zeilenga Standards Track [Page 12]
+
+RFC 4422 SASL June 2006
+
+
+ case, once an authentication exchange has successfully completed,
+ further attempts to initiate an authentication exchange fail.
+
+ Where multiple successful SASL authentication exchanges are permitted
+ in the protocol, then in no case may multiple SASL security layers be
+ simultaneously in effect. If a security layer is in effect and a
+ subsequent SASL negotiation selects a second security layer, then the
+ second security layer replaces the first. If a security layer is in
+ effect and a subsequent SASL negotiation selects no security layer,
+ the original security layer remains in effect.
+
+ Where multiple successful SASL negotiations are permitted in the
+ protocol, the effect of a failed SASL authentication exchange upon
+ the previously established authentication and authorization state is
+ protocol specific. The protocol's technical specification should be
+ consulted to determine whether the previous authentication and
+ authorization state remains in force, or changed to an anonymous
+ state, or otherwise was affected. Regardless of the protocol-
+ specific effect upon previously established authentication and
+ authorization state, the previously negotiated security layer remains
+ in effect.
+
+4. Protocol Requirements
+
+ In order for a protocol to offer SASL services, its specification
+ MUST supply the following information:
+
+ 1) A service name, to be selected from registry of "service" elements
+ for the Generic Security Service Application Program Interface
+ (GSSAPI) host-based service name form, as described in Section 4.1
+ of [RFC2743]. Note that this registry is shared by all GSSAPI and
+ SASL mechanisms.
+
+ 2) Detail any mechanism negotiation facility that the protocol
+ provides (see Section 3.2).
+
+ A protocol SHOULD specify a facility through which the client may
+ discover, both before initiation of the SASL exchange and after
+ installing security layers negotiated by the exchange, the names
+ of the SASL mechanisms that the server makes available to the
+ client. The latter is important to allow the client to detect
+ downgrade attacks. This facility is typically provided through
+ the protocol's extensions or capabilities discovery facility.
+
+ 3) Definition of the messages necessary for authentication exchange,
+ including the following:
+
+
+
+
+
+Melnikov & Zeilenga Standards Track [Page 13]
+
+RFC 4422 SASL June 2006
+
+
+ a) A message to initiate the authentication exchange (see Section
+ 3.3).
+
+ This message MUST contain a field for carrying the name of the
+ mechanism selected by the client.
+
+ This message SHOULD contain an optional field for carrying an
+ initial response. If the message is defined with this field,
+ the specification MUST describe how messages with an empty
+ initial response are distinguished from messages with no
+ initial response. This field MUST be capable of carrying
+ arbitrary sequences of octets (including zero-length sequences
+ and sequences containing zero-valued octets).
+
+ b) Messages to transfer server challenges and client responses
+ (see Section 3.4).
+
+ Each of these messages MUST be capable of carrying arbitrary
+ sequences of octets (including zero-length sequences and
+ sequences containing zero-valued octets).
+
+ c) A message to indicate the outcome of the authentication
+ exchange (see Section 3.6).
+
+ This message SHOULD contain an optional field for carrying
+ additional data with a successful outcome. If the message is
+ defined with this field, the specification MUST describe how
+ messages with an empty additional data are distinguished from
+ messages with no additional data. This field MUST be capable
+ of carrying arbitrary sequences of octets (including zero-
+ length sequences and sequences containing zero-valued octets).
+
+ 4) Prescribe the syntax and semantics of non-empty authorization
+ identity strings (see Section 3.4.1).
+
+ In order to avoid interoperability problems due to differing
+ normalizations, the protocol specification MUST detail precisely
+ how and where (client or server) non-empty authorization identity
+ strings are prepared, including all normalizations, for comparison
+ and other applicable functions to ensure proper function.
+
+ Specifications are encouraged to prescribe use of existing
+ authorization identity forms as well as existing string
+ representations, such as simple user names [RFC4013].
+
+ Where the specification does not precisely prescribe how
+ identities in SASL relate to identities used elsewhere in the
+ protocol, for instance, in access control policy statements, it
+
+
+
+Melnikov & Zeilenga Standards Track [Page 14]
+
+RFC 4422 SASL June 2006
+
+
+ may be appropriate for the protocol to provide a facility by which
+ the client can discover information (such as the representation of
+ the identity used in making access control decisions) about
+ established identities for these uses.
+
+ 5) Detail any facility the protocol provides that allows the client
+ and/or server to abort authentication exchange (see Section 3.5).
+
+ Protocols that support multiple authentications typically allow a
+ client to abort an ongoing authentication exchange by initiating a
+ new authentication exchange. Protocols that do not support
+ multiple authentications may require the client to close the
+ connection and start over to abort an ongoing authentication
+ exchange.
+
+ Protocols typically allow the server to abort ongoing
+ authentication exchanges by returning a non-successful outcome
+ message.
+
+ 6) Identify precisely where newly negotiated security layers start to
+ take effect, in both directions (see Section 3.7).
+
+ Typically, specifications require security layers to start taking
+ effect on the first octet following the outcome message in data
+ being sent by the server and on the first octet sent after receipt
+ of the outcome message in data being sent by the client.
+
+ 7) If the protocol supports other layered security services, such as
+ Transport Layer Security (TLS) [RFC4346], the specification MUST
+ prescribe the order in which security layers are applied to
+ protocol data.
+
+ For instance, where a protocol supports both TLS and SASL security
+ layers, the specification could prescribe any of the following:
+
+ a) SASL security layer is always applied first to data being sent
+ and, hence, applied last to received data,
+
+ b) SASL security layer is always applied last to data being sent
+ and, hence, applied first to received data,
+
+ c) Layers are applied in the order in which they were installed,
+
+ d) Layers are applied in the reverse order in which they were
+ installed, or
+
+ e) Both TLS and SASL security layers cannot be installed.
+
+
+
+
+Melnikov & Zeilenga Standards Track [Page 15]
+
+RFC 4422 SASL June 2006
+
+
+ 8) Indicate whether the protocol supports multiple authentications
+ (see Section 3.8). If so, the protocol MUST detail the effect a
+ failed SASL authentication exchange will have upon a previously
+ established authentication and authorization state.
+
+ Protocol specifications SHOULD avoid stating implementation
+ requirements that would hinder replacement of applicable mechanisms.
+ In general, protocol specifications SHOULD be mechanism neutral.
+ There are a number of reasonable exceptions to this recommendation,
+ including
+
+ - detailing how credentials (which are mechanism specific) are
+ managed in the protocol,
+
+ - detailing how authentication identities (which are mechanism
+ specific) and authorization identities (which are protocol
+ specific) relate to each other, and
+
+ - detailing which mechanisms are applicable to the protocol.
+
+5. Mechanism Requirements
+
+ SASL mechanism specifications MUST supply the following information:
+
+ 1) The name of the mechanism (see Section 3.1). This name MUST be
+ registered as discussed in Section 7.1.
+
+ 2) A definition of the server-challenges and client-responses of the
+ authentication exchange, as well as the following:
+
+ a) An indication of whether the mechanism is client-first,
+ variable, or server-first. If a SASL mechanism is defined as
+ client-first and the client does not send an initial response
+ in the authentication request, then the first server challenge
+ MUST be empty (the EXTERNAL mechanism is an example of this
+ case). If a SASL mechanism is defined as variable, then the
+ specification needs to state how the server behaves when the
+ initial client response in the authentication request is
+ omitted (the DIGEST-MD5 mechanism [DIGEST-MD5] is an example of
+ this case). If a SASL mechanism is defined as server-first,
+ then the client MUST NOT send an initial client response in the
+ authentication request (the CRAM-MD5 mechanism [CRAM-MD5] is an
+ example of this case).
+
+ b) An indication of whether the server is expected to provide
+ additional data when indicating a successful outcome. If so,
+ if the server sends the additional data as a challenge, the
+
+
+
+
+Melnikov & Zeilenga Standards Track [Page 16]
+
+RFC 4422 SASL June 2006
+
+
+ specification MUST indicate that the response to this challenge
+ is an empty response.
+
+ SASL mechanisms SHOULD be designed to minimize the number of
+ challenges and responses necessary to complete the exchange.
+
+ 3) An indication of whether the mechanism is capable of transferring
+ authorization identity strings (see Section 3.4.1). While some
+ legacy mechanisms are incapable of transmitting an authorization
+ identity (which means that for these mechanisms, the authorization
+ identity is always the empty string), newly defined mechanisms
+ SHOULD be capable of transferring authorization identity strings.
+ The mechanism SHOULD NOT be capable of transferring both no
+ authorization identity string and an empty authorization identity.
+
+ Mechanisms that are capable of transferring an authorization
+ identity string MUST be capable of transferring arbitrary non-
+ empty sequences of Unicode characters, excluding those that
+ contain the NUL (U+0000) character. Mechanisms SHOULD use the
+ UTF-8 [RFC3629] transformation format. The specification MUST
+ detail how any Unicode code points special to the mechanism that
+ might appear in the authorization identity string are escaped to
+ avoid ambiguity during decoding of the authorization identity
+ string. Typically, mechanisms that have special characters
+ require these special characters to be escaped or encoded in the
+ character string (after encoding it in a particular Unicode
+ transformation format) using a data encoding scheme such as Base64
+ [RFC3548].
+
+ 4) The specification MUST detail whether the mechanism offers a
+ security layer. If the mechanism does, the specification MUST
+ detail the security and other services offered in the layer as
+ well as how these services are to be implemented.
+
+ 5) If the underlying cryptographic technology used by a mechanism
+ supports data integrity, then the mechanism specification MUST
+ integrity protect the transmission of an authorization identity
+ and the negotiation of the security layer.
+
+ SASL mechanisms SHOULD be protocol neutral.
+
+ SASL mechanisms SHOULD reuse existing credential and identity forms,
+ as well as associated syntaxes and semantics.
+
+ SASL mechanisms SHOULD use the UTF-8 transformation format [RFC3629]
+ for encoding Unicode [Unicode] code points for transfer.
+
+
+
+
+
+Melnikov & Zeilenga Standards Track [Page 17]
+
+RFC 4422 SASL June 2006
+
+
+ In order to avoid interoperability problems due to differing
+ normalizations, when a mechanism calls for character data (other than
+ the authorization identity string) to be used as input to a
+ cryptographic and/or comparison function, the specification MUST
+ detail precisely how and where (client or server) the character data
+ is to be prepared, including all normalizations, for input into the
+ function to ensure proper operation.
+
+ For simple user names and/or passwords in authentication credentials,
+ SASLprep [RFC4013] (a profile of the StringPrep [RFC3454] preparation
+ algorithm), SHOULD be specified as the preparation algorithm.
+
+ The mechanism SHOULD NOT use the authorization identity string in
+ generation of any long-term cryptographic keys or hashes as there is
+ no requirement that the authorization identity string be canonical.
+ Long-term, here, means a term longer than the duration of the
+ authentication exchange in which they were generated. That is, as
+ different clients (of the same or different protocol) may provide
+ different authorization identity strings that are semantically
+ equivalent, use of authorization identity strings in generation of
+ cryptographic keys and hashes will likely lead to interoperability
+ and other problems.
+
+6. Security Considerations
+
+ Security issues are discussed throughout this memo.
+
+ Many existing SASL mechanisms do not provide adequate protection
+ against passive attacks, let alone active attacks, in the
+ authentication exchange. Many existing SASL mechanisms do not offer
+ security layers. It is hoped that future SASL mechanisms will
+ provide strong protection against passive and active attacks in the
+ authentication exchange, as well as security layers with strong basic
+ data security features (e.g., data integrity and data
+ confidentiality) services. It is also hoped that future mechanisms
+ will provide more advanced data security services like re-keying (see
+ Section 6.3).
+
+ Regardless, the SASL framework is susceptible to downgrade attacks.
+ Section 6.1.2 offers a variety of approaches for preventing or
+ detecting these attacks. In some cases, it is appropriate to use
+ data integrity protective services external to SASL (e.g., TLS) to
+ protect against downgrade attacks in SASL. Use of external
+ protective security services is also important when the mechanisms
+ available do not themselves offer adequate integrity and/or
+ confidentiality protection of the authentication exchange and/or
+ protocol data.
+
+
+
+
+Melnikov & Zeilenga Standards Track [Page 18]
+
+RFC 4422 SASL June 2006
+
+
+6.1. Active Attacks
+
+6.1.1. Hijack Attacks
+
+ When the client selects a SASL security layer with at least integrity
+ protection, this protection serves as a counter-measure against an
+ active attacker hijacking the connection and modifying protocol data
+ sent after establishment of the security layer. Implementations
+ SHOULD close the connection when the security services in a SASL
+ security layer report protocol data report lack of data integrity.
+
+6.1.2. Downgrade Attacks
+
+ It is important that any security-sensitive protocol negotiations be
+ performed after installation of a security layer with data integrity
+ protection. Protocols should be designed such that negotiations
+ performed prior to this installation should be revalidated after
+ installation is complete. Negotiation of the SASL mechanism is
+ security sensitive.
+
+ When a client negotiates the authentication mechanism with the server
+ and/or other security features, it is possible for an active attacker
+ to cause a party to use the least secure security services available.
+ For instance, an attacker can modify the server-advertised mechanism
+ list or can modify the client-advertised security feature list within
+ a mechanism response. To protect against this sort of attack,
+ implementations SHOULD NOT advertise mechanisms and/or features that
+ cannot meet their minimum security requirements, SHOULD NOT enter
+ into or continue authentication exchanges that cannot meet their
+ minimum security requirements, and SHOULD verify that completed
+ authentication exchanges result in security services that meet their
+ minimum security requirements. Note that each endpoint needs to
+ independently verify that its security requirements are met.
+
+ In order to detect downgrade attacks to the least (or less) secure
+ mechanism supported, the client can discover the SASL mechanisms that
+ the server makes available both before the SASL authentication
+ exchange and after the negotiated SASL security layer (with at least
+ data integrity protection) has been installed through the protocol's
+ mechanism discovery facility. If the client finds that the
+ integrity-protected list (the list obtained after the security layer
+ was installed) contains a stronger mechanism than those in the
+ previously obtained list, the client should assume that the
+ previously obtained list was modified by an attacker and SHOULD close
+ the underlying transport connection.
+
+ The client's initiation of the SASL exchange, including the selection
+ of a SASL mechanism, is done in the clear and may be modified by an
+
+
+
+Melnikov & Zeilenga Standards Track [Page 19]
+
+RFC 4422 SASL June 2006
+
+
+ active attacker. It is important for any new SASL mechanisms to be
+ designed such that an active attacker cannot obtain an authentication
+ with weaker security properties by modifying the SASL mechanism name
+ and/or the challenges and responses.
+
+ Multi-level negotiation of security features is prone to downgrade
+ attack. Protocol designers should avoid offering higher-level
+ negotiation of security features in protocols (e.g., above SASL
+ mechanism negotiation) and mechanism designers should avoid lower-
+ level negotiation of security features in mechanisms (e.g., below
+ SASL mechanism negotiation).
+
+6.1.3. Replay Attacks
+
+ Some mechanisms may be subject to replay attacks unless protected by
+ external data security services (e.g., TLS).
+
+6.1.4. Truncation Attacks
+
+ Most existing SASL security layers do not themselves offer protection
+ against truncation attack. In a truncation attack, the active
+ attacker causes the protocol session to be closed, causing a
+ truncation of the possibly integrity-protected data stream that leads
+ to behavior of one or both the protocol peers that inappropriately
+ benefits the attacker. Truncation attacks are fairly easy to defend
+ against in connection-oriented application-level protocols. A
+ protocol can defend against these attacks by ensuring that each
+ information exchange has a clear final result and that each protocol
+ session has a graceful closure mechanism, and that these are
+ integrity protected.
+
+6.1.5. Other Active Attacks
+
+ When use of a security layer is negotiated by the authentication
+ protocol exchange, the receiver SHOULD handle gracefully any
+ protected data buffer larger than the defined/negotiated maximal
+ size. In particular, it MUST NOT blindly allocate the amount of
+ memory specified in the buffer size field, as this might cause the
+ "out of memory" condition. If the receiver detects a large block, it
+ SHOULD close the connection.
+
+6.2. Passive Attacks
+
+ Many mechanisms are subject to various passive attacks, including
+ simple eavesdropping of unprotected credential information as well as
+ online and offline dictionary attacks of protected credential
+ information.
+
+
+
+
+Melnikov & Zeilenga Standards Track [Page 20]
+
+RFC 4422 SASL June 2006
+
+
+6.3. Re-keying
+
+ The secure or administratively permitted lifetimes of SASL
+ mechanisms' security layers are finite. Cryptographic keys weaken as
+ they are used and as time passes; the more time and/or cipher-text
+ that a cryptanalyst has after the first use of the a key, the easier
+ it is for the cryptanalyst to mount attacks on the key.
+
+ Administrative limits on a security layer's lifetime may take the
+ form of time limits expressed in X.509 certificates, in Kerberos V
+ tickets, or in directories, and are often desired. In practice, one
+ likely effect of administrative lifetime limits is that applications
+ may find that security layers stop working in the middle of
+ application protocol operation, such as, perhaps, during large data
+ transfers. As the result of this, the connection will be closed (see
+ Section 3.7), which will result in an unpleasant user experience.
+
+ Re-keying (key renegotiation process) is a way of addressing the
+ weakening of cryptographic keys. The SASL framework does not itself
+ provide for re-keying; SASL mechanisms may. Designers of future SASL
+ mechanisms should consider providing re-keying services.
+
+ Implementations that wish to re-key SASL security layers where the
+ mechanism does not provide for re-keying SHOULD reauthenticate the
+ same IDs and replace the expired or soon-to-expire security layers.
+ This approach requires support for reauthentication in the
+ application protocols (see Section 3.8).
+
+6.4. Other Considerations
+
+ Protocol designers and implementors should understand the security
+ considerations of mechanisms so they may select mechanisms that are
+ applicable to their needs.
+
+ Distributed server implementations need to be careful in how they
+ trust other parties. In particular, authentication secrets should
+ only be disclosed to other parties that are trusted to manage and use
+ those secrets in a manner acceptable to the disclosing party.
+ Applications using SASL assume that SASL security layers providing
+ data confidentiality are secure even when an attacker chooses the
+ text to be protected by the security layer. Similarly, applications
+ assume that the SASL security layer is secure even if the attacker
+ can manipulate the cipher-text output of the security layer. New
+ SASL mechanisms are expected to meet these assumptions.
+
+
+
+
+
+
+
+Melnikov & Zeilenga Standards Track [Page 21]
+
+RFC 4422 SASL June 2006
+
+
+ Unicode security considerations [UTR36] apply to authorization
+ identity strings, as well as UTF-8 [RFC3629] security considerations
+ where UTF-8 is used. SASLprep [RFC4013] and StringPrep [RFC3454]
+ security considerations also apply where used.
+
+7. IANA Considerations
+
+7.1. SASL Mechanism Registry
+
+ The SASL mechanism registry is maintained by IANA. The registry is
+ currently available at <http://www.iana.org/assignments/sasl-
+ mechanisms>.
+
+ The purpose of this registry is not only to ensure uniqueness of
+ values used to name SASL mechanisms, but also to provide a definitive
+ reference to technical specifications detailing each SASL mechanism
+ available for use on the Internet.
+
+ There is no naming convention for SASL mechanisms; any name that
+ conforms to the syntax of a SASL mechanism name can be registered.
+
+ The procedure detailed in Section 7.1.1 is to be used for
+ registration of a value naming a specific individual mechanism.
+
+ The procedure detailed in Section 7.1.2 is to be used for
+ registration of a value naming a family of related mechanisms.
+
+ Comments may be included in the registry as discussed in Section
+ 7.1.3 and may be changed as discussed in Section 7.1.4.
+
+ The SASL mechanism registry has been updated to reflect that this
+ document provides the definitive technical specification for SASL and
+ that this section provides the registration procedures for this
+ registry.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Melnikov & Zeilenga Standards Track [Page 22]
+
+RFC 4422 SASL June 2006
+
+
+7.1.1. Mechanism Name Registration Procedure
+
+ IANA will register new SASL mechanism names on a First Come First
+ Served basis, as defined in BCP 26 [RFC2434]. IANA has the right to
+ reject obviously bogus registration requests, but will perform no
+ review of claims made in the registration form.
+
+ Registration of a SASL mechanism is requested by filling in the
+ following template:
+
+ Subject: Registration of SASL mechanism X
+
+ SASL mechanism name (or prefix for the family):
+
+ Security considerations:
+
+ Published specification (recommended):
+
+ Person & email address to contact for further information:
+
+ Intended usage: (One of COMMON, LIMITED USE, or OBSOLETE)
+
+ Owner/Change controller:
+
+ Note: (Any other information that the author deems relevant may be
+ added here.)
+
+ and sending it via electronic mail to IANA at <iana@iana.org>.
+
+ While this registration procedure does not require expert review,
+ authors of SASL mechanisms are encouraged to seek community review
+ and comment whenever that is feasible. Authors may seek community
+ review by posting a specification of their proposed mechanism as an
+ Internet-Draft. SASL mechanisms intended for widespread use should
+ be standardized through the normal IETF process, when appropriate.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Melnikov & Zeilenga Standards Track [Page 23]
+
+RFC 4422 SASL June 2006
+
+
+7.1.2. Family Name Registration Procedure
+
+ As noted above, there is no general naming convention for SASL
+ mechanisms. However, specifications may reserve a portion of the
+ SASL mechanism namespace for a set of related SASL mechanisms, a
+ "family" of SASL mechanisms. Each family of SASL mechanisms is
+ identified by a unique prefix, such as X-. Registration of new SASL
+ mechanism family names requires expert review as defined in BCP 26
+ [RFC2434].
+
+ Registration of a SASL family name is requested by filling in the
+ following template:
+
+ Subject: Registration of SASL mechanism family X
+
+ SASL family name (or prefix for the family):
+
+ Security considerations:
+
+ Published specification (recommended):
+
+ Person & email address to contact for further information:
+
+ Intended usage: (One of COMMON, LIMITED USE, or OBSOLETE)
+
+ Owner/Change controller:
+
+ Note: (Any other information that the author deems relevant may be
+ added here.)
+
+ and sending it via electronic mail to the IETF SASL mailing list at
+ <ietf-sasl@imc.org> and carbon copying IANA at <iana@iana.org>.
+ After allowing two weeks for community input on the IETF SASL mailing
+ list, the expert will determine the appropriateness of the
+ registration request and either approve or disapprove the request
+ with notice to the requestor, the mailing list, and IANA.
+
+ The review should focus on the appropriateness of the requested
+ family name for the proposed use and the appropriateness of the
+ proposed naming and registration plan for existing and future
+ mechanism names in the family. The scope of this request review may
+ entail consideration of relevant aspects of any provided technical
+ specification, such as their IANA Considerations section. However,
+ this review is narrowly focused on the appropriateness of the
+ requested registration and not on the overall soundness of any
+ provided technical specification.
+
+
+
+
+
+Melnikov & Zeilenga Standards Track [Page 24]
+
+RFC 4422 SASL June 2006
+
+
+ Authors are encouraged to pursue community review by posting the
+ technical specification as an Internet-Draft and soliciting comment
+ by posting to appropriate IETF mailing lists.
+
+7.1.3. Comments on SASL Mechanism Registrations
+
+ Comments on a registered SASL mechanism/family should first be sent
+ to the "owner" of the mechanism/family and/or to the <ietf-
+ sasl@imc.org> mailing list.
+
+ Submitters of comments may, after a reasonable attempt to contact the
+ owner, request IANA to attach their comment to the SASL mechanism
+ registration itself by sending mail to <iana@iana.org>. At IANA's
+ sole discretion, IANA may attach the comment to the SASL mechanism's
+ registration.
+
+7.1.4. Change Control
+
+ Once a SASL mechanism registration has been published by IANA, the
+ author may request a change to its definition. The change request
+ follows the same procedure as the registration request.
+
+ The owner of a SASL mechanism may pass responsibility for the SASL
+ mechanism to another person or agency by informing IANA; this can be
+ done without discussion or review.
+
+ The IESG may reassign responsibility for a SASL mechanism. The most
+ common case of this will be to enable changes to be made to
+ mechanisms where the author of the registration has died, has moved
+ out of contact, or is otherwise unable to make changes that are
+ important to the community.
+
+ SASL mechanism registrations may not be deleted; mechanisms that are
+ no longer believed appropriate for use can be declared OBSOLETE by a
+ change to their "intended usage" field; such SASL mechanisms will be
+ clearly marked in the lists published by IANA.
+
+ The IESG is considered to be the owner of all SASL mechanisms that
+ are on the IETF standards track.
+
+
+
+
+
+
+
+
+
+
+
+
+Melnikov & Zeilenga Standards Track [Page 25]
+
+RFC 4422 SASL June 2006
+
+
+7.2. Registration Changes
+
+ The IANA has updated the SASL mechanisms registry as follows:
+
+ 1) Changed the "Intended usage" of the KERBEROS_V4 and SKEY mechanism
+ registrations to OBSOLETE.
+
+ 2) Changed the "Published specification" of the EXTERNAL mechanism to
+ this document as indicated below:
+
+ Subject: Updated Registration of SASL mechanism EXTERNAL
+ Family of SASL mechanisms: NO
+ SASL mechanism name: EXTERNAL
+ Security considerations: See A.3 of RFC 4422
+ Published specification (optional, recommended): RFC 4422
+ Person & email address to contact for further information:
+ Alexey Melnikov <Alexey.Melnikov@isode.com>
+ Intended usage: COMMON
+ Owner/Change controller: IESG <iesg@ietf.org>
+ Note: Updates existing entry for EXTERNAL
+
+8. References
+
+8.1. Normative References
+
+ [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+ [RFC2244] Newman, C. and J. G. Myers, "ACAP -- Application
+ Configuration Access Protocol", RFC 2244, November
+ 1997.
+
+ [RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing
+ an IANA Considerations Section in RFCs", BCP 26, RFC
+ 2434, October 1998.
+
+ [RFC2743] Linn, J., "Generic Security Service Application Program
+ Interface Version 2, Update 1", RFC 2743, January 2000.
+
+ [RFC3454] Hoffman, P. and M. Blanchet, "Preparation of
+ Internationalized Strings ("stringprep")", RFC 3454,
+ December 2002.
+
+ [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
+ 10646", STD 63, RFC 3629, November 2003.
+
+ [RFC4013] Zeilenga, K., "SASLprep: Stringprep Profile for User
+ Names and Passwords", RFC 4013, February 2005.
+
+
+
+Melnikov & Zeilenga Standards Track [Page 26]
+
+RFC 4422 SASL June 2006
+
+
+ [RFC4234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
+ Specifications: ABNF", RFC 4234, October 2005.
+
+ [ASCII] Coded Character Set--7-bit American Standard Code for
+ Information Interchange, ANSI X3.4-1986.
+
+ [Unicode] The Unicode Consortium, "The Unicode Standard, Version
+ 3.2.0" is defined by "The Unicode Standard, Version
+ 3.0" (Reading, MA, Addison-Wesley, 2000. ISBN 0-201-
+ 61633-5), as amended by the "Unicode Standard Annex
+ #27: Unicode 3.1"
+ (http://www.unicode.org/reports/tr27/) and by the
+ "Unicode Standard Annex #28: Unicode 3.2"
+ (http://www.unicode.org/reports/tr28/).
+
+ [CharModel] Whistler, K. and M. Davis, "Unicode Technical Report
+ #17, Character Encoding Model", UTR17,
+ <http://www.unicode.org/unicode/reports/tr17/>, August
+ 2000.
+
+ [Glossary] The Unicode Consortium, "Unicode Glossary",
+ <http://www.unicode.org/glossary/>.
+
+8.2. Informative References
+
+ [RFC3206] Gellens, R., "The SYS and AUTH POP Response Codes", RFC
+ 3206, February 2002.
+
+ [RFC3548] Josefsson, S., "The Base16, Base32, and Base64 Data
+ Encodings", RFC 3548, July 2003.
+
+ [RFC4301] Kent, S. and K. Seo, "Security Architecture for the
+ Internet Protocol", RFC 4301, December 2005.
+
+ [RFC4346] Dierks, T. and E. Rescorla, "The Transport Layer
+ Security (TLS) Protocol Version 1.1", RFC 4346, April
+ 2006.
+
+ [SASL-GSSAPI] Melnikov, A. (Editor), "The Kerberos V5 ("GSSAPI") SASL
+ Mechanism", Work in Progress, May 2006.
+
+ [UTR36] Davis, M., "(Draft) Unicode Technical Report #36,
+ Character Encoding Model", UTR17,
+ <http://www.unicode.org/unicode/reports/tr36/>,
+ February 2005.
+
+ [CRAM-MD5] Nerenberg, L., "The CRAM-MD5 SASL Mechanism", Work in
+ Progress.
+
+
+
+Melnikov & Zeilenga Standards Track [Page 27]
+
+RFC 4422 SASL June 2006
+
+
+ [DIGEST-MD5] Leach, P., C. Newman, and A. Melnikov, "Using Digest
+ Authentication as a SASL Mechanism", Work in Progress,
+ March 2006.
+
+9. Acknowledgements
+
+ This document is a revision of RFC 2222 written by John Myers.
+
+ This revision is a product of the IETF Simple Authentication and
+ Security Layer (SASL) Working Group.
+
+ The following individuals contributed significantly to this revision:
+ Abhijit Menon-Sen, Hallvard Furuseth, Jeffrey Hutzelman, John Myers,
+ Luke Howard, Magnus Nystrom, Nicolas Williams, Peter Saint-Andre, RL
+ 'Bob' Morgan, Rob Siemborski, Sam Hartman, Simon Josefsson, Tim
+ Alsop, and Tony Hansen.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Melnikov & Zeilenga Standards Track [Page 28]
+
+RFC 4422 SASL June 2006
+
+
+Appendix A. The SASL EXTERNAL Mechanism
+
+ This appendix is normative.
+
+ The EXTERNAL mechanism allows a client to request the server to use
+ credentials established by means external to the mechanism to
+ authenticate the client. The external means may be, for instance, IP
+ Security [RFC4301] or TLS [RFC4346] services. In absence of some a
+ priori agreement between the client and the server, the client cannot
+ make any assumption as to what external means the server has used to
+ obtain the client's credentials, nor make an assumption as to the
+ form of credentials. For example, the client cannot assume that the
+ server will use the credentials the client has established via TLS.
+
+A.1. EXTERNAL Technical Specification
+
+ The name of this mechanism is "EXTERNAL".
+
+ The mechanism does not provide a security layer.
+
+ The mechanism is capable of transferring an authorization identity
+ string. If empty, the client is requesting to act as the identity
+ the server has associated with the client's credentials. If non-
+ empty, the client is requesting to act as the identity represented by
+ the string.
+
+ The client is expected to send data first in the authentication
+ exchange. Where the client does not provide an initial response data
+ in its request to initiate the authentication exchange, the server is
+ to respond to the request with an empty initial challenge and then
+ the client is to provide its initial response.
+
+ The client sends the initial response containing the UTF-8 [RFC3629]
+ encoding of the requested authorization identity string. This
+ response is non-empty when the client is requesting to act as the
+ identity represented by the (non-empty) string. This response is
+ empty when the client is requesting to act as the identity the server
+ associated with its authentication credentials.
+
+ The syntax of the initial response is specified as a value of the
+ <extern-initial-resp> production detailed below using the Augmented
+ Backus-Naur Form (ABNF) [RFC4234] notation.
+
+ external-initial-resp = authz-id-string
+ authz-id-string = *( UTF8-char-no-nul )
+ UTF8-char-no-nul = UTF8-1-no-nul / UTF8-2 / UTF8-3 / UTF8-4
+ UTF8-1-no-nul = %x01-7F
+
+
+
+
+Melnikov & Zeilenga Standards Track [Page 29]
+
+RFC 4422 SASL June 2006
+
+
+ where the <UTF8-2>, <UTF8-3>, and <UTF8-4> productions are as defined
+ in [RFC3629].
+
+ There are no additional challenges and responses.
+
+ Hence, the server is to return the outcome of the authentication
+ exchange.
+
+ The exchange fails if
+
+ - the client has not established its credentials via external means,
+
+ - the client's credentials are inadequate,
+
+ - the client provided an empty authorization identity string and the
+ server is unwilling or unable to associate an authorization
+ identity with the client's credentials,
+
+ - the client provided a non-empty authorization identity string that
+ is invalid per the syntax requirements of the applicable
+ application protocol specification,
+
+ - the client provided a non-empty authorization identity string
+ representing an identity that the client is not allowed to act as,
+ or
+
+ - the server is unwilling or unable to provide service to the client
+ for any other reason.
+
+ Otherwise the exchange is successful. When indicating a successful
+ outcome, additional data is not provided.
+
+A.2. SASL EXTERNAL Examples
+
+ This section provides examples of EXTERNAL authentication exchanges.
+ The examples are intended to help the readers understand the above
+ text. The examples are not definitive. The Application
+ Configuration Access Protocol (ACAP) [RFC2244] is used in the
+ examples.
+
+ The first example shows use of EXTERNAL with an empty authorization
+ identity. In this example, the initial response is not sent in the
+ client's request to initiate the authentication exchange.
+
+ S: * ACAP (SASL "DIGEST-MD5")
+ C: a001 STARTTLS
+ S: a001 OK "Begin TLS negotiation now"
+ <TLS negotiation, further commands are under TLS layer>
+
+
+
+Melnikov & Zeilenga Standards Track [Page 30]
+
+RFC 4422 SASL June 2006
+
+
+ S: * ACAP (SASL "DIGEST-MD5" "EXTERNAL")
+ C: a002 AUTHENTICATE "EXTERNAL"
+ S: + ""
+ C: + ""
+ S: a002 OK "Authenticated"
+
+ The second example shows use of EXTERNAL with an authorization
+ identity of "fred@example.com". In this example, the initial
+ response is sent with the client's request to initiate the
+ authentication exchange. This saves a round-trip.
+
+ S: * ACAP (SASL "DIGEST-MD5")
+ C: a001 STARTTLS
+ S: a001 OK "Begin TLS negotiation now"
+ <TLS negotiation, further commands are under TLS layer>
+ S: * ACAP (SASL "DIGEST-MD5" "EXTERNAL")
+ C: a002 AUTHENTICATE "EXTERNAL" {16+}
+ C: fred@example.com
+ S: a002 NO "Cannot assume requested authorization identity"
+
+A.3. Security Considerations
+
+ The EXTERNAL mechanism provides no security protection; it is
+ vulnerable to spoofing by either client or server, active attack, and
+ eavesdropping. It should only be used when adequate security
+ services have been established.
+
+Appendix B. Changes since RFC 2222
+
+ This appendix is non-normative.
+
+ The material in RFC 2222 was significantly rewritten in the
+ production of this document.
+
+ RFC 2222, by not stating that the authorization identity string was a
+ string of Unicode characters, let alone character data, implied that
+ the authorization identity string was a string of octets.
+
+ - The authorization identity string is now defined as a string of
+ Unicode characters. The NUL (U+0000) character is prohibited.
+ While protocol specifications are responsible for defining the
+ authorization identity form, as well as the Unicode string syntax
+ and related semantics, mechanism specifications are responsible
+ for defining how the Unicode string is carried in the
+ authentication exchange.
+
+ - Deleted "If so, when the client does not send data first, the
+ initial challenge MUST be specified as being an empty challenge."
+
+
+
+Melnikov & Zeilenga Standards Track [Page 31]
+
+RFC 4422 SASL June 2006
+
+
+ The following technical change was made to the EXTERNAL mechanism:
+
+ - The authorization identity string is to be UTF-8 encoded.
+
+ Note that protocol and mechanism specification requirements have
+ been significantly tightened. Existing protocol and mechanism
+ specifications will need to be updated to meet these requirements.
+
+Editors' Addresses
+
+ Alexey Melnikov
+ Isode Limited
+ 5 Castle Business Village
+ 36 Station Road
+ Hampton, Middlesex,
+ TW12 2BX, United Kingdom
+
+ EMail: Alexey.Melnikov@isode.com
+ URI: http://www.melnikov.ca/
+
+
+ Kurt D. Zeilenga
+ OpenLDAP Foundation
+
+ EMail: Kurt@OpenLDAP.org
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Melnikov & Zeilenga Standards Track [Page 32]
+
+RFC 4422 SASL June 2006
+
+
+Full Copyright Statement
+
+ Copyright (C) The Internet Society (2006).
+
+ This document is subject to the rights, licenses and restrictions
+ contained in BCP 78, and except as set forth therein, the authors
+ retain all their rights.
+
+ This document and the information contained herein are provided on an
+ "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
+ OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
+ ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
+ INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
+ INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
+ WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+Intellectual Property
+
+ The IETF takes no position regarding the validity or scope of any
+ Intellectual Property Rights or other rights that might be claimed to
+ pertain to the implementation or use of the technology described in
+ this document or the extent to which any license under such rights
+ might or might not be available; nor does it represent that it has
+ made any independent effort to identify any such rights. Information
+ on the procedures with respect to rights in RFC documents can be
+ found in BCP 78 and BCP 79.
+
+ Copies of IPR disclosures made to the IETF Secretariat and any
+ assurances of licenses to be made available, or the result of an
+ attempt made to obtain a general license or permission for the use of
+ such proprietary rights by implementers or users of this
+ specification can be obtained from the IETF on-line IPR repository at
+ http://www.ietf.org/ipr.
+
+ The IETF invites any interested party to bring to its attention any
+ copyrights, patents or patent applications, or other proprietary
+ rights that may cover technology that may be required to implement
+ this standard. Please address the information to the IETF at
+ ietf-ipr@ietf.org.
+
+Acknowledgement
+
+ Funding for the RFC Editor function is provided by the IETF
+ Administrative Support Activity (IASA).
+
+
+
+
+
+
+
+Melnikov & Zeilenga Standards Track [Page 33]
+
diff --git a/doc/rfcs/rfc4616.txt b/doc/rfcs/rfc4616.txt
new file mode 100644
index 0000000..991189d
--- /dev/null
+++ b/doc/rfcs/rfc4616.txt
@@ -0,0 +1,619 @@
+
+
+
+
+
+
+Network Working Group K. Zeilenga, Ed.
+Request for Comments: 4616 OpenLDAP Foundation
+Updates: 2595 August 2006
+Category: Standards Track
+
+
+ The PLAIN Simple Authentication and Security Layer (SASL) Mechanism
+
+Status of This Memo
+
+ This document specifies an Internet standards track protocol for the
+ Internet community, and requests discussion and suggestions for
+ improvements. Please refer to the current edition of the "Internet
+ Official Protocol Standards" (STD 1) for the standardization state
+ and status of this protocol. Distribution of this memo is unlimited.
+
+Copyright Notice
+
+ Copyright (C) The Internet Society (2006).
+
+Abstract
+
+ This document defines a simple clear-text user/password Simple
+ Authentication and Security Layer (SASL) mechanism called the PLAIN
+ mechanism. The PLAIN mechanism is intended to be used, in
+ combination with data confidentiality services provided by a lower
+ layer, in protocols that lack a simple password authentication
+ command.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Zeilenga Standards Track [Page 1]
+
+RFC 4616 The PLAIN SASL Mechanism August 2006
+
+
+1. Introduction
+
+ Clear-text, multiple-use passwords are simple, interoperate with
+ almost all existing operating system authentication databases, and
+ are useful for a smooth transition to a more secure password-based
+ authentication mechanism. The drawback is that they are unacceptable
+ for use over network connections where data confidentiality is not
+ ensured.
+
+ This document defines the PLAIN Simple Authentication and Security
+ Layer ([SASL]) mechanism for use in protocols with no clear-text
+ login command (e.g., [ACAP] or [SMTP-AUTH]). This document updates
+ RFC 2595, replacing Section 6. Changes since RFC 2595 are detailed
+ in Appendix A.
+
+ The name associated with this mechanism is "PLAIN".
+
+ The PLAIN SASL mechanism does not provide a security layer.
+
+ The PLAIN mechanism should not be used without adequate data security
+ protection as this mechanism affords no integrity or confidentiality
+ protections itself. The mechanism is intended to be used with data
+ security protections provided by application-layer protocol,
+ generally through its use of Transport Layer Security ([TLS])
+ services.
+
+ By default, implementations SHOULD advertise and make use of the
+ PLAIN mechanism only when adequate data security services are in
+ place. Specifications for IETF protocols that indicate that this
+ mechanism is an applicable authentication mechanism MUST mandate that
+ implementations support an strong data security service, such as TLS.
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+ document are to be interpreted as described in [Keywords].
+
+2. PLAIN SASL Mechanism
+
+ The mechanism consists of a single message, a string of [UTF-8]
+ encoded [Unicode] characters, from the client to the server. The
+ client presents the authorization identity (identity to act as),
+ followed by a NUL (U+0000) character, followed by the authentication
+ identity (identity whose password will be used), followed by a NUL
+ (U+0000) character, followed by the clear-text password. As with
+ other SASL mechanisms, the client does not provide an authorization
+ identity when it wishes the server to derive an identity from the
+ credentials and use that as the authorization identity.
+
+
+
+
+Zeilenga Standards Track [Page 2]
+
+RFC 4616 The PLAIN SASL Mechanism August 2006
+
+
+ The formal grammar for the client message using Augmented BNF [ABNF]
+ follows.
+
+ message = [authzid] UTF8NUL authcid UTF8NUL passwd
+ authcid = 1*SAFE ; MUST accept up to 255 octets
+ authzid = 1*SAFE ; MUST accept up to 255 octets
+ passwd = 1*SAFE ; MUST accept up to 255 octets
+ UTF8NUL = %x00 ; UTF-8 encoded NUL character
+
+ SAFE = UTF1 / UTF2 / UTF3 / UTF4
+ ;; any UTF-8 encoded Unicode character except NUL
+
+ UTF1 = %x01-7F ;; except NUL
+ UTF2 = %xC2-DF UTF0
+ UTF3 = %xE0 %xA0-BF UTF0 / %xE1-EC 2(UTF0) /
+ %xED %x80-9F UTF0 / %xEE-EF 2(UTF0)
+ UTF4 = %xF0 %x90-BF 2(UTF0) / %xF1-F3 3(UTF0) /
+ %xF4 %x80-8F 2(UTF0)
+ UTF0 = %x80-BF
+
+ The authorization identity (authzid), authentication identity
+ (authcid), password (passwd), and NUL character deliminators SHALL be
+ transferred as [UTF-8] encoded strings of [Unicode] characters. As
+ the NUL (U+0000) character is used as a deliminator, the NUL (U+0000)
+ character MUST NOT appear in authzid, authcid, or passwd productions.
+
+ The form of the authzid production is specific to the application-
+ level protocol's SASL profile [SASL]. The authcid and passwd
+ productions are form-free. Use of non-visible characters or
+ characters that a user may be unable to enter on some keyboards is
+ discouraged.
+
+ Servers MUST be capable of accepting authzid, authcid, and passwd
+ productions up to and including 255 octets. It is noted that the
+ UTF-8 encoding of a Unicode character may be as long as 4 octets.
+
+ Upon receipt of the message, the server will verify the presented (in
+ the message) authentication identity (authcid) and password (passwd)
+ with the system authentication database, and it will verify that the
+ authentication credentials permit the client to act as the (presented
+ or derived) authorization identity (authzid). If both steps succeed,
+ the user is authenticated.
+
+ The presented authentication identity and password strings, as well
+ as the database authentication identity and password strings, are to
+ be prepared before being used in the verification process. The
+ [SASLPrep] profile of the [StringPrep] algorithm is the RECOMMENDED
+ preparation algorithm. The SASLprep preparation algorithm is
+
+
+
+Zeilenga Standards Track [Page 3]
+
+RFC 4616 The PLAIN SASL Mechanism August 2006
+
+
+ recommended to improve the likelihood that comparisons behave in an
+ expected manner. The SASLprep preparation algorithm is not mandatory
+ so as to allow the server to employ other preparation algorithms
+ (including none) when appropriate. For instance, use of a different
+ preparation algorithm may be necessary for the server to interoperate
+ with an external system.
+
+ When preparing the presented strings using [SASLPrep], the presented
+ strings are to be treated as "query" strings (Section 7 of
+ [StringPrep]) and hence unassigned code points are allowed to appear
+ in their prepared output. When preparing the database strings using
+ [SASLPrep], the database strings are to be treated as "stored"
+ strings (Section 7 of [StringPrep]) and hence unassigned code points
+ are prohibited from appearing in their prepared output.
+
+ Regardless of the preparation algorithm used, if the output of a
+ non-invertible function (e.g., hash) of the expected string is
+ stored, the string MUST be prepared before input to that function.
+
+ Regardless of the preparation algorithm used, if preparation fails or
+ results in an empty string, verification SHALL fail.
+
+ When no authorization identity is provided, the server derives an
+ authorization identity from the prepared representation of the
+ provided authentication identity string. This ensures that the
+ derivation of different representations of the authentication
+ identity produces the same authorization identity.
+
+ The server MAY use the credentials to initialize any new
+ authentication database, such as one suitable for [CRAM-MD5] or
+ [DIGEST-MD5].
+
+3. Pseudo-Code
+
+ This section provides pseudo-code illustrating the verification
+ process (using hashed passwords and the SASLprep preparation
+ function) discussed above. This section is not definitive.
+
+ boolean Verify(string authzid, string authcid, string passwd) {
+ string pAuthcid = SASLprep(authcid, true); # prepare authcid
+ string pPasswd = SASLprep(passwd, true); # prepare passwd
+ if (pAuthcid == NULL || pPasswd == NULL) {
+ return false; # preparation failed
+ }
+ if (pAuthcid == "" || pPasswd == "") {
+ return false; # empty prepared string
+ }
+
+
+
+
+Zeilenga Standards Track [Page 4]
+
+RFC 4616 The PLAIN SASL Mechanism August 2006
+
+
+ storedHash = FetchPasswordHash(pAuthcid);
+ if (storedHash == NULL || storedHash == "") {
+ return false; # error or unknown authcid
+ }
+
+ if (!Compare(storedHash, Hash(pPasswd))) {
+ return false; # incorrect password
+ }
+
+ if (authzid == NULL ) {
+ authzid = DeriveAuthzid(pAuthcid);
+ if (authzid == NULL || authzid == "") {
+ return false; # could not derive authzid
+ }
+ }
+
+ if (!Authorize(pAuthcid, authzid)) {
+ return false; # not authorized
+ }
+
+ return true;
+ }
+
+ The second parameter of the SASLprep function, when true, indicates
+ that unassigned code points are allowed in the input. When the
+ SASLprep function is called to prepare the password prior to
+ computing the stored hash, the second parameter would be false.
+
+ The second parameter provided to the Authorize function is not
+ prepared by this code. The application-level SASL profile should be
+ consulted to determine what, if any, preparation is necessary.
+
+ Note that the DeriveAuthzid and Authorize functions (whether
+ implemented as one function or two, whether designed in a manner in
+ which these functions or whether the mechanism implementation can be
+ reused elsewhere) require knowledge and understanding of mechanism
+ and the application-level protocol specification and/or
+ implementation details to implement.
+
+ Note that the Authorize function outcome is clearly dependent on
+ details of the local authorization model and policy. Both functions
+ may be dependent on other factors as well.
+
+
+
+
+
+
+
+
+
+Zeilenga Standards Track [Page 5]
+
+RFC 4616 The PLAIN SASL Mechanism August 2006
+
+
+4. Examples
+
+ This section provides examples of PLAIN authentication exchanges.
+ The examples are intended to help the readers understand the above
+ text. The examples are not definitive.
+
+ "C:" and "S:" indicate lines sent by the client and server,
+ respectively. "<NUL>" represents a single NUL (U+0000) character.
+ The Application Configuration Access Protocol ([ACAP]) is used in the
+ examples.
+
+ The first example shows how the PLAIN mechanism might be used for
+ user authentication.
+
+ S: * ACAP (SASL "CRAM-MD5") (STARTTLS)
+ C: a001 STARTTLS
+ S: a001 OK "Begin TLS negotiation now"
+ <TLS negotiation, further commands are under TLS layer>
+ S: * ACAP (SASL "CRAM-MD5" "PLAIN")
+ C: a002 AUTHENTICATE "PLAIN"
+ S: + ""
+ C: {21}
+ C: <NUL>tim<NUL>tanstaaftanstaaf
+ S: a002 OK "Authenticated"
+
+ The second example shows how the PLAIN mechanism might be used to
+ attempt to assume the identity of another user. In this example, the
+ server rejects the request. Also, this example makes use of the
+ protocol optional initial response capability to eliminate a round-
+ trip.
+
+ S: * ACAP (SASL "CRAM-MD5") (STARTTLS)
+ C: a001 STARTTLS
+ S: a001 OK "Begin TLS negotiation now"
+ <TLS negotiation, further commands are under TLS layer>
+ S: * ACAP (SASL "CRAM-MD5" "PLAIN")
+ C: a002 AUTHENTICATE "PLAIN" {20+}
+ C: Ursel<NUL>Kurt<NUL>xipj3plmq
+ S: a002 NO "Not authorized to requested authorization identity"
+
+5. Security Considerations
+
+ As the PLAIN mechanism itself provided no integrity or
+ confidentiality protections, it should not be used without adequate
+ external data security protection, such as TLS services provided by
+ many application-layer protocols. By default, implementations SHOULD
+ NOT advertise and SHOULD NOT make use of the PLAIN mechanism unless
+ adequate data security services are in place.
+
+
+
+Zeilenga Standards Track [Page 6]
+
+RFC 4616 The PLAIN SASL Mechanism August 2006
+
+
+ When the PLAIN mechanism is used, the server gains the ability to
+ impersonate the user to all services with the same password
+ regardless of any encryption provided by TLS or other confidentiality
+ protection mechanisms. Whereas many other authentication mechanisms
+ have similar weaknesses, stronger SASL mechanisms address this issue.
+ Clients are encouraged to have an operational mode where all
+ mechanisms that are likely to reveal the user's password to the
+ server are disabled.
+
+ General [SASL] security considerations apply to this mechanism.
+
+ Unicode, [UTF-8], and [StringPrep] security considerations also
+ apply.
+
+6. IANA Considerations
+
+ The SASL Mechanism registry [IANA-SASL] entry for the PLAIN mechanism
+ has been updated by the IANA to reflect that this document now
+ provides its technical specification.
+
+ To: iana@iana.org
+ Subject: Updated Registration of SASL mechanism PLAIN
+
+ SASL mechanism name: PLAIN
+ Security considerations: See RFC 4616.
+ Published specification (optional, recommended): RFC 4616
+ Person & email address to contact for further information:
+ Kurt Zeilenga <kurt@openldap.org>
+ IETF SASL WG <ietf-sasl@imc.org>
+ Intended usage: COMMON
+ Author/Change controller: IESG <iesg@ietf.org>
+ Note: Updates existing entry for PLAIN
+
+7. Acknowledgements
+
+ This document is a revision of RFC 2595 by Chris Newman. Portions of
+ the grammar defined in Section 2 were borrowed from [UTF-8] by
+ Francois Yergeau.
+
+ This document is a product of the IETF Simple Authentication and
+ Security Layer (SASL) Working Group.
+
+
+
+
+
+
+
+
+
+
+Zeilenga Standards Track [Page 7]
+
+RFC 4616 The PLAIN SASL Mechanism August 2006
+
+
+8. Normative References
+
+ [ABNF] Crocker, D., Ed. and P. Overell, "Augmented BNF for
+ Syntax Specifications: ABNF", RFC 4234, October 2005.
+
+ [Keywords] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+ [SASL] Melnikov, A., Ed., and K. Zeilenga, Ed., "Simple
+ Authentication and Security Layer (SASL)", RFC 4422,
+ June 2006.
+
+ [SASLPrep] Zeilenga, K., "SASLprep: Stringprep Profile for User
+ Names and Passwords", RFC 4013, February 2005.
+
+ [StringPrep] Hoffman, P. and M. Blanchet, "Preparation of
+ Internationalized Strings ("stringprep")", RFC 3454,
+ December 2002.
+
+ [Unicode] The Unicode Consortium, "The Unicode Standard, Version
+ 3.2.0" is defined by "The Unicode Standard, Version
+ 3.0" (Reading, MA, Addison-Wesley, 2000. ISBN 0-201-
+ 61633-5), as amended by the "Unicode Standard Annex
+ #27: Unicode 3.1"
+ (http://www.unicode.org/reports/tr27/) and by the
+ "Unicode Standard Annex #28: Unicode 3.2"
+ (http://www.unicode.org/reports/tr28/).
+
+ [UTF-8] Yergeau, F., "UTF-8, a transformation format of ISO
+ 10646", STD 63, RFC 3629, November 2003.
+
+ [TLS] Dierks, T. and E. Rescorla, "The Transport Layer
+ Security (TLS) Protocol Version 1.1", RFC 4346, April
+ 2006.
+
+9. Informative References
+
+ [ACAP] Newman, C. and J. Myers, "ACAP -- Application
+ Configuration Access Protocol", RFC 2244, November
+ 1997.
+
+ [CRAM-MD5] Nerenberg, L., Ed., "The CRAM-MD5 SASL Mechanism", Work
+ in Progress, June 2006.
+
+ [DIGEST-MD5] Melnikov, A., Ed., "Using Digest Authentication as a
+ SASL Mechanism", Work in Progress, June 2006.
+
+
+
+
+
+Zeilenga Standards Track [Page 8]
+
+RFC 4616 The PLAIN SASL Mechanism August 2006
+
+
+ [IANA-SASL] IANA, "SIMPLE AUTHENTICATION AND SECURITY LAYER (SASL)
+ MECHANISMS",
+ <http://www.iana.org/assignments/sasl-mechanisms>.
+
+ [SMTP-AUTH] Myers, J., "SMTP Service Extension for Authentication",
+ RFC 2554, March 1999.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Zeilenga Standards Track [Page 9]
+
+RFC 4616 The PLAIN SASL Mechanism August 2006
+
+
+Appendix A. Changes since RFC 2595
+
+ This appendix is non-normative.
+
+ This document replaces Section 6 of RFC 2595.
+
+ The specification details how the server is to compare client-
+ provided character strings with stored character strings.
+
+ The ABNF grammar was updated. In particular, the grammar now allows
+ LINE FEED (U+000A) and CARRIAGE RETURN (U+000D) characters in the
+ authzid, authcid, passwd productions. However, whether these control
+ characters may be used depends on the string preparation rules
+ applicable to the production. For passwd and authcid productions,
+ control characters are prohibited. For authzid, one must consult the
+ application-level SASL profile. This change allows PLAIN to carry
+ all possible authorization identity strings allowed in SASL.
+
+ Pseudo-code was added.
+
+ The example section was expanded to illustrate more features of the
+ PLAIN mechanism.
+
+Editor's Address
+
+ Kurt D. Zeilenga
+ OpenLDAP Foundation
+
+ EMail: Kurt@OpenLDAP.org
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Zeilenga Standards Track [Page 10]
+
+RFC 4616 The PLAIN SASL Mechanism August 2006
+
+
+Full Copyright Statement
+
+ Copyright (C) The Internet Society (2006).
+
+ This document is subject to the rights, licenses and restrictions
+ contained in BCP 78, and except as set forth therein, the authors
+ retain all their rights.
+
+ This document and the information contained herein are provided on an
+ "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
+ OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
+ ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
+ INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
+ INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
+ WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+Intellectual Property
+
+ The IETF takes no position regarding the validity or scope of any
+ Intellectual Property Rights or other rights that might be claimed to
+ pertain to the implementation or use of the technology described in
+ this document or the extent to which any license under such rights
+ might or might not be available; nor does it represent that it has
+ made any independent effort to identify any such rights. Information
+ on the procedures with respect to rights in RFC documents can be
+ found in BCP 78 and BCP 79.
+
+ Copies of IPR disclosures made to the IETF Secretariat and any
+ assurances of licenses to be made available, or the result of an
+ attempt made to obtain a general license or permission for the use of
+ such proprietary rights by implementers or users of this
+ specification can be obtained from the IETF on-line IPR repository at
+ http://www.ietf.org/ipr.
+
+ The IETF invites any interested party to bring to its attention any
+ copyrights, patents or patent applications, or other proprietary
+ rights that may cover technology that may be required to implement
+ this standard. Please address the information to the IETF at
+ ietf-ipr@ietf.org.
+
+Acknowledgement
+
+ Funding for the RFC Editor function is provided by the IETF
+ Administrative Support Activity (IASA).
+
+
+
+
+
+
+
+Zeilenga Standards Track [Page 11]
+
diff --git a/doc/rfcs/rfc5802.txt b/doc/rfcs/rfc5802.txt
new file mode 100644
index 0000000..971003a
--- /dev/null
+++ b/doc/rfcs/rfc5802.txt
@@ -0,0 +1,1571 @@
+
+
+
+
+
+
+Internet Engineering Task Force (IETF) C. Newman
+Request for Comments: 5802 Oracle
+Category: Standards Track A. Menon-Sen
+ISSN: 2070-1721 Oryx Mail Systems GmbH
+ A. Melnikov
+ Isode, Ltd.
+ N. Williams
+ Oracle
+ July 2010
+
+
+ Salted Challenge Response Authentication Mechanism (SCRAM)
+ SASL and GSS-API Mechanisms
+
+Abstract
+
+ The secure authentication mechanism most widely deployed and used by
+ Internet application protocols is the transmission of clear-text
+ passwords over a channel protected by Transport Layer Security (TLS).
+ There are some significant security concerns with that mechanism,
+ which could be addressed by the use of a challenge response
+ authentication mechanism protected by TLS. Unfortunately, the
+ challenge response mechanisms presently on the standards track all
+ fail to meet requirements necessary for widespread deployment, and
+ have had success only in limited use.
+
+ This specification describes a family of Simple Authentication and
+ Security Layer (SASL; RFC 4422) authentication mechanisms called the
+ Salted Challenge Response Authentication Mechanism (SCRAM), which
+ addresses the security concerns and meets the deployability
+ requirements. When used in combination with TLS or an equivalent
+ security layer, a mechanism from this family could improve the status
+ quo for application protocol authentication and provide a suitable
+ choice for a mandatory-to-implement mechanism for future application
+ protocol standards.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Newman, et al. Standards Track [Page 1]
+
+RFC 5802 SCRAM July 2010
+
+
+Status of This Memo
+
+ This is an Internet Standards Track document.
+
+ This document is a product of the Internet Engineering Task Force
+ (IETF). It represents the consensus of the IETF community. It has
+ received public review and has been approved for publication by the
+ Internet Engineering Steering Group (IESG). Further information on
+ Internet Standards is available in Section 2 of RFC 5741.
+
+ Information about the current status of this document, any errata,
+ and how to provide feedback on it may be obtained at
+ http://www.rfc-editor.org/info/rfc5802.
+
+Copyright Notice
+
+ Copyright (c) 2010 IETF Trust and the persons identified as the
+ document authors. All rights reserved.
+
+ This document is subject to BCP 78 and the IETF Trust's Legal
+ Provisions Relating to IETF Documents
+ (http://trustee.ietf.org/license-info) in effect on the date of
+ publication of this document. Please review these documents
+ carefully, as they describe your rights and restrictions with respect
+ to this document. Code Components extracted from this document must
+ include Simplified BSD License text as described in Section 4.e of
+ the Trust Legal Provisions and are provided without warranty as
+ described in the Simplified BSD License.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Newman, et al. Standards Track [Page 2]
+
+RFC 5802 SCRAM July 2010
+
+
+Table of Contents
+
+ 1. Introduction ....................................................4
+ 2. Conventions Used in This Document ...............................5
+ 2.1. Terminology ................................................5
+ 2.2. Notation ...................................................6
+ 3. SCRAM Algorithm Overview ........................................7
+ 4. SCRAM Mechanism Names ...........................................8
+ 5. SCRAM Authentication Exchange ...................................9
+ 5.1. SCRAM Attributes ..........................................10
+ 5.2. Compliance with SASL Mechanism Requirements ...............13
+ 6. Channel Binding ................................................14
+ 6.1. Default Channel Binding ...................................15
+ 7. Formal Syntax ..................................................15
+ 8. SCRAM as a GSS-API Mechanism ...................................19
+ 8.1. GSS-API Principal Name Types for SCRAM ....................19
+ 8.2. GSS-API Per-Message Tokens for SCRAM ......................20
+ 8.3. GSS_Pseudo_random() for SCRAM .............................20
+ 9. Security Considerations ........................................20
+ 10. IANA Considerations ...........................................22
+ 11. Acknowledgements ..............................................23
+ 12. References ....................................................24
+ 12.1. Normative References .....................................24
+ 12.2. Normative References for GSS-API Implementors ............24
+ 12.3. Informative References ...................................25
+ Appendix A. Other Authentication Mechanisms .......................27
+ Appendix B. Design Motivations ....................................27
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Newman, et al. Standards Track [Page 3]
+
+RFC 5802 SCRAM July 2010
+
+
+1. Introduction
+
+ This specification describes a family of authentication mechanisms
+ called the Salted Challenge Response Authentication Mechanism (SCRAM)
+ which addresses the requirements necessary to deploy a challenge-
+ response mechanism more widely than past attempts (see Appendix A and
+ Appendix B). When used in combination with Transport Layer Security
+ (TLS; see [RFC5246]) or an equivalent security layer, a mechanism
+ from this family could improve the status quo for application
+ protocol authentication and provide a suitable choice for a
+ mandatory-to-implement mechanism for future application protocol
+ standards.
+
+ For simplicity, this family of mechanisms does not presently include
+ negotiation of a security layer [RFC4422]. It is intended to be used
+ with an external security layer such as that provided by TLS or SSH,
+ with optional channel binding [RFC5056] to the external security
+ layer.
+
+ SCRAM is specified herein as a pure Simple Authentication and
+ Security Layer (SASL) [RFC4422] mechanism, but it conforms to the new
+ bridge between SASL and the Generic Security Service Application
+ Program Interface (GSS-API) called "GS2" [RFC5801]. This means that
+ this document defines both, a SASL mechanism and a GSS-API mechanism.
+
+ SCRAM provides the following protocol features:
+
+ o The authentication information stored in the authentication
+ database is not sufficient by itself to impersonate the client.
+ The information is salted to prevent a pre-stored dictionary
+ attack if the database is stolen.
+
+ o The server does not gain the ability to impersonate the client to
+ other servers (with an exception for server-authorized proxies).
+
+ o The mechanism permits the use of a server-authorized proxy without
+ requiring that proxy to have super-user rights with the back-end
+ server.
+
+ o Mutual authentication is supported, but only the client is named
+ (i.e., the server has no name).
+
+ o When used as a SASL mechanism, SCRAM is capable of transporting
+ authorization identities (see [RFC4422], Section 2) from the
+ client to the server.
+
+
+
+
+
+
+Newman, et al. Standards Track [Page 4]
+
+RFC 5802 SCRAM July 2010
+
+
+ A separate document defines a standard LDAPv3 [RFC4510] attribute
+ that enables storage of the SCRAM authentication information in LDAP.
+ See [RFC5803].
+
+ For an in-depth discussion of why other challenge response mechanisms
+ are not considered sufficient, see Appendix A. For more information
+ about the motivations behind the design of this mechanism, see
+ Appendix B.
+
+2. Conventions Used in This Document
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+ document are to be interpreted as described in [RFC2119].
+
+ Formal syntax is defined by [RFC5234] including the core rules
+ defined in Appendix B of [RFC5234].
+
+ Example lines prefaced by "C:" are sent by the client and ones
+ prefaced by "S:" by the server. If a single "C:" or "S:" label
+ applies to multiple lines, then the line breaks between those lines
+ are for editorial clarity only, and are not part of the actual
+ protocol exchange.
+
+2.1. Terminology
+
+ This document uses several terms defined in [RFC4949] ("Internet
+ Security Glossary") including the following: authentication,
+ authentication exchange, authentication information, brute force,
+ challenge-response, cryptographic hash function, dictionary attack,
+ eavesdropping, hash result, keyed hash, man-in-the-middle, nonce,
+ one-way encryption function, password, replay attack, and salt.
+ Readers not familiar with these terms should use that glossary as a
+ reference.
+
+ Some clarifications and additional definitions follow:
+
+ o Authentication information: Information used to verify an identity
+ claimed by a SCRAM client. The authentication information for a
+ SCRAM identity consists of salt, iteration count, "StoredKey" and
+ "ServerKey" (as defined in the algorithm overview) for each
+ supported cryptographic hash function.
+
+ o Authentication database: The database used to look up the
+ authentication information associated with a particular identity.
+ For application protocols, LDAPv3 (see [RFC4510]) is frequently
+
+
+
+
+
+Newman, et al. Standards Track [Page 5]
+
+RFC 5802 SCRAM July 2010
+
+
+ used as the authentication database. For network-level protocols
+ such as PPP or 802.11x, the use of RADIUS [RFC2865] is more
+ common.
+
+ o Base64: An encoding mechanism defined in [RFC4648] that converts
+ an octet string input to a textual output string that can be
+ easily displayed to a human. The use of base64 in SCRAM is
+ restricted to the canonical form with no whitespace.
+
+ o Octet: An 8-bit byte.
+
+ o Octet string: A sequence of 8-bit bytes.
+
+ o Salt: A random octet string that is combined with a password
+ before applying a one-way encryption function. This value is used
+ to protect passwords that are stored in an authentication
+ database.
+
+2.2. Notation
+
+ The pseudocode description of the algorithm uses the following
+ notations:
+
+ o ":=": The variable on the left-hand side represents the octet
+ string resulting from the expression on the right-hand side.
+
+ o "+": Octet string concatenation.
+
+ o "[ ]": A portion of an expression enclosed in "[" and "]" may not
+ be included in the result under some circumstances. See the
+ associated text for a description of those circumstances.
+
+ o Normalize(str): Apply the SASLprep profile [RFC4013] of the
+ "stringprep" algorithm [RFC3454] as the normalization algorithm to
+ a UTF-8 [RFC3629] encoded "str". The resulting string is also in
+ UTF-8. When applying SASLprep, "str" is treated as a "stored
+ strings", which means that unassigned Unicode codepoints are
+ prohibited (see Section 7 of [RFC3454]). Note that
+ implementations MUST either implement SASLprep or disallow use of
+ non US-ASCII Unicode codepoints in "str".
+
+ o HMAC(key, str): Apply the HMAC keyed hash algorithm (defined in
+ [RFC2104]) using the octet string represented by "key" as the key
+ and the octet string "str" as the input string. The size of the
+ result is the hash result size for the hash function in use. For
+ example, it is 20 octets for SHA-1 (see [RFC3174]).
+
+
+
+
+
+Newman, et al. Standards Track [Page 6]
+
+RFC 5802 SCRAM July 2010
+
+
+ o H(str): Apply the cryptographic hash function to the octet string
+ "str", producing an octet string as a result. The size of the
+ result depends on the hash result size for the hash function in
+ use.
+
+ o XOR: Apply the exclusive-or operation to combine the octet string
+ on the left of this operator with the octet string on the right of
+ this operator. The length of the output and each of the two
+ inputs will be the same for this use.
+
+ o Hi(str, salt, i):
+
+ U1 := HMAC(str, salt + INT(1))
+ U2 := HMAC(str, U1)
+ ...
+ Ui-1 := HMAC(str, Ui-2)
+ Ui := HMAC(str, Ui-1)
+
+ Hi := U1 XOR U2 XOR ... XOR Ui
+
+ where "i" is the iteration count, "+" is the string concatenation
+ operator, and INT(g) is a 4-octet encoding of the integer g, most
+ significant octet first.
+
+ Hi() is, essentially, PBKDF2 [RFC2898] with HMAC() as the
+ pseudorandom function (PRF) and with dkLen == output length of
+ HMAC() == output length of H().
+
+3. SCRAM Algorithm Overview
+
+ The following is a description of a full, uncompressed SASL SCRAM
+ authentication exchange. Nothing in SCRAM prevents either sending
+ the client-first message with the SASL authentication request defined
+ by an application protocol ("initial client response"), or sending
+ the server-final message as additional data of the SASL outcome of
+ authentication exchange defined by an application protocol. See
+ [RFC4422] for more details.
+
+ Note that this section omits some details, such as client and server
+ nonces. See Section 5 for more details.
+
+ To begin with, the SCRAM client is in possession of a username and
+ password (*) (or a ClientKey/ServerKey, or SaltedPassword). It sends
+ the username to the server, which retrieves the corresponding
+ authentication information, i.e., a salt, StoredKey, ServerKey, and
+ the iteration count i. (Note that a server implementation may choose
+
+
+
+
+
+Newman, et al. Standards Track [Page 7]
+
+RFC 5802 SCRAM July 2010
+
+
+ to use the same iteration count for all accounts.) The server sends
+ the salt and the iteration count to the client, which then computes
+ the following values and sends a ClientProof to the server:
+
+ (*) Note that both the username and the password MUST be encoded in
+ UTF-8 [RFC3629].
+
+ Informative Note: Implementors are encouraged to create test cases
+ that use both usernames and passwords with non-ASCII codepoints. In
+ particular, it's useful to test codepoints whose "Unicode
+ Normalization Form C" and "Unicode Normalization Form KC" are
+ different. Some examples of such codepoints include Vulgar Fraction
+ One Half (U+00BD) and Acute Accent (U+00B4).
+
+ SaltedPassword := Hi(Normalize(password), salt, i)
+ ClientKey := HMAC(SaltedPassword, "Client Key")
+ StoredKey := H(ClientKey)
+ AuthMessage := client-first-message-bare + "," +
+ server-first-message + "," +
+ client-final-message-without-proof
+ ClientSignature := HMAC(StoredKey, AuthMessage)
+ ClientProof := ClientKey XOR ClientSignature
+ ServerKey := HMAC(SaltedPassword, "Server Key")
+ ServerSignature := HMAC(ServerKey, AuthMessage)
+
+ The server authenticates the client by computing the ClientSignature,
+ exclusive-ORing that with the ClientProof to recover the ClientKey
+ and verifying the correctness of the ClientKey by applying the hash
+ function and comparing the result to the StoredKey. If the ClientKey
+ is correct, this proves that the client has access to the user's
+ password.
+
+ Similarly, the client authenticates the server by computing the
+ ServerSignature and comparing it to the value sent by the server. If
+ the two are equal, it proves that the server had access to the user's
+ ServerKey.
+
+ The AuthMessage is computed by concatenating messages from the
+ authentication exchange. The format of these messages is defined in
+ Section 7.
+
+4. SCRAM Mechanism Names
+
+ A SCRAM mechanism name is a string "SCRAM-" followed by the
+ uppercased name of the underlying hash function taken from the IANA
+ "Hash Function Textual Names" registry (see http://www.iana.org),
+ optionally followed by the suffix "-PLUS" (see below). Note that
+ SASL mechanism names are limited to 20 octets, which means that only
+
+
+
+Newman, et al. Standards Track [Page 8]
+
+RFC 5802 SCRAM July 2010
+
+
+ hash function names with lengths shorter or equal to 9 octets
+ (20-length("SCRAM-")-length("-PLUS") can be used. For cases when the
+ underlying hash function name is longer than 9 octets, an alternative
+ 9-octet (or shorter) name can be used to construct the corresponding
+ SCRAM mechanism name, as long as this alternative name doesn't
+ conflict with any other hash function name from the IANA "Hash
+ Function Textual Names" registry. In order to prevent future
+ conflict, such alternative names SHOULD be registered in the IANA
+ "Hash Function Textual Names" registry.
+
+ For interoperability, all SCRAM clients and servers MUST implement
+ the SCRAM-SHA-1 authentication mechanism, i.e., an authentication
+ mechanism from the SCRAM family that uses the SHA-1 hash function as
+ defined in [RFC3174].
+
+ The "-PLUS" suffix is used only when the server supports channel
+ binding to the external channel. If the server supports channel
+ binding, it will advertise both the "bare" and "plus" versions of
+ whatever mechanisms it supports (e.g., if the server supports only
+ SCRAM with SHA-1, then it will advertise support for both SCRAM-SHA-1
+ and SCRAM-SHA-1-PLUS). If the server does not support channel
+ binding, then it will advertise only the "bare" version of the
+ mechanism (e.g., only SCRAM-SHA-1). The "-PLUS" exists to allow
+ negotiation of the use of channel binding. See Section 6.
+
+5. SCRAM Authentication Exchange
+
+ SCRAM is a SASL mechanism whose client response and server challenge
+ messages are text-based messages containing one or more attribute-
+ value pairs separated by commas. Each attribute has a one-letter
+ name. The messages and their attributes are described in
+ Section 5.1, and defined in Section 7.
+
+ SCRAM is a client-first SASL mechanism (see [RFC4422], Section 5,
+ item 2a), and returns additional data together with a server's
+ indication of a successful outcome.
+
+ This is a simple example of a SCRAM-SHA-1 authentication exchange
+ when the client doesn't support channel bindings (username 'user' and
+ password 'pencil' are used):
+
+ C: n,,n=user,r=fyko+d2lbbFgONRv9qkxdawL
+ S: r=fyko+d2lbbFgONRv9qkxdawL3rfcNHYJY1ZVvWVs7j,s=QSXCR+Q6sek8bf92,
+ i=4096
+ C: c=biws,r=fyko+d2lbbFgONRv9qkxdawL3rfcNHYJY1ZVvWVs7j,
+ p=v0X8v3Bz2T0CJGbJQyF0X+HI4Ts=
+ S: v=rmF9pqV8S7suAoZWja4dJRkFsKQ=
+
+
+
+
+Newman, et al. Standards Track [Page 9]
+
+RFC 5802 SCRAM July 2010
+
+
+ First, the client sends the "client-first-message" containing:
+
+ o a GS2 header consisting of a flag indicating whether channel
+ binding is supported-but-not-used, not supported, or used, and an
+ optional SASL authorization identity;
+
+ o SCRAM username and a random, unique nonce attributes.
+
+ Note that the client's first message will always start with "n", "y",
+ or "p"; otherwise, the message is invalid and authentication MUST
+ fail. This is important, as it allows for GS2 extensibility (e.g.,
+ to add support for security layers).
+
+ In response, the server sends a "server-first-message" containing the
+ user's iteration count i and the user's salt, and appends its own
+ nonce to the client-specified one.
+
+ The client then responds by sending a "client-final-message" with the
+ same nonce and a ClientProof computed using the selected hash
+ function as explained earlier.
+
+ The server verifies the nonce and the proof, verifies that the
+ authorization identity (if supplied by the client in the first
+ message) is authorized to act as the authentication identity, and,
+ finally, it responds with a "server-final-message", concluding the
+ authentication exchange.
+
+ The client then authenticates the server by computing the
+ ServerSignature and comparing it to the value sent by the server. If
+ the two are different, the client MUST consider the authentication
+ exchange to be unsuccessful, and it might have to drop the
+ connection.
+
+5.1. SCRAM Attributes
+
+ This section describes the permissible attributes, their use, and the
+ format of their values. All attribute names are single US-ASCII
+ letters and are case-sensitive.
+
+ Note that the order of attributes in client or server messages is
+ fixed, with the exception of extension attributes (described by the
+ "extensions" ABNF production), which can appear in any order in the
+ designated positions. See Section 7 for authoritative reference.
+
+ o a: This is an optional attribute, and is part of the GS2 [RFC5801]
+ bridge between the GSS-API and SASL. This attribute specifies an
+ authorization identity. A client may include it in its first
+ message to the server if it wants to authenticate as one user, but
+
+
+
+Newman, et al. Standards Track [Page 10]
+
+RFC 5802 SCRAM July 2010
+
+
+ subsequently act as a different user. This is typically used by
+ an administrator to perform some management task on behalf of
+ another user, or by a proxy in some situations.
+
+ Upon the receipt of this value the server verifies its
+ correctness according to the used SASL protocol profile.
+ Failed verification results in failed authentication exchange.
+
+ If this attribute is omitted (as it normally would be), the
+ authorization identity is assumed to be derived from the
+ username specified with the (required) "n" attribute.
+
+ The server always authenticates the user specified by the "n"
+ attribute. If the "a" attribute specifies a different user,
+ the server associates that identity with the connection after
+ successful authentication and authorization checks.
+
+ The syntax of this field is the same as that of the "n" field
+ with respect to quoting of '=' and ','.
+
+ o n: This attribute specifies the name of the user whose password is
+ used for authentication (a.k.a. "authentication identity"
+ [RFC4422]). A client MUST include it in its first message to the
+ server. If the "a" attribute is not specified (which would
+ normally be the case), this username is also the identity that
+ will be associated with the connection subsequent to
+ authentication and authorization.
+
+ Before sending the username to the server, the client SHOULD
+ prepare the username using the "SASLprep" profile [RFC4013] of
+ the "stringprep" algorithm [RFC3454] treating it as a query
+ string (i.e., unassigned Unicode code points are allowed). If
+ the preparation of the username fails or results in an empty
+ string, the client SHOULD abort the authentication exchange
+ (*).
+
+ (*) An interactive client can request a repeated entry of the
+ username value.
+
+ Upon receipt of the username by the server, the server MUST
+ either prepare it using the "SASLprep" profile [RFC4013] of the
+ "stringprep" algorithm [RFC3454] treating it as a query string
+ (i.e., unassigned Unicode codepoints are allowed) or otherwise
+ be prepared to do SASLprep-aware string comparisons and/or
+ index lookups. If the preparation of the username fails or
+ results in an empty string, the server SHOULD abort the
+
+
+
+
+
+Newman, et al. Standards Track [Page 11]
+
+RFC 5802 SCRAM July 2010
+
+
+ authentication exchange. Whether or not the server prepares
+ the username using "SASLprep", it MUST use it as received in
+ hash calculations.
+
+ The characters ',' or '=' in usernames are sent as '=2C' and
+ '=3D' respectively. If the server receives a username that
+ contains '=' not followed by either '2C' or '3D', then the
+ server MUST fail the authentication.
+
+ o m: This attribute is reserved for future extensibility. In this
+ version of SCRAM, its presence in a client or a server message
+ MUST cause authentication failure when the attribute is parsed by
+ the other end.
+
+ o r: This attribute specifies a sequence of random printable ASCII
+ characters excluding ',' (which forms the nonce used as input to
+ the hash function). No quoting is applied to this string. As
+ described earlier, the client supplies an initial value in its
+ first message, and the server augments that value with its own
+ nonce in its first response. It is important that this value be
+ different for each authentication (see [RFC4086] for more details
+ on how to achieve this). The client MUST verify that the initial
+ part of the nonce used in subsequent messages is the same as the
+ nonce it initially specified. The server MUST verify that the
+ nonce sent by the client in the second message is the same as the
+ one sent by the server in its first message.
+
+ o c: This REQUIRED attribute specifies the base64-encoded GS2 header
+ and channel binding data. It is sent by the client in its second
+ authentication message. The attribute data consist of:
+
+ * the GS2 header from the client's first message (recall that the
+ GS2 header contains a channel binding flag and an optional
+ authzid). This header is going to include channel binding type
+ prefix (see [RFC5056]), if and only if the client is using
+ channel binding;
+
+ * followed by the external channel's channel binding data, if and
+ only if the client is using channel binding.
+
+ o s: This attribute specifies the base64-encoded salt used by the
+ server for this user. It is sent by the server in its first
+ message to the client.
+
+ o i: This attribute specifies an iteration count for the selected
+ hash function and user, and MUST be sent by the server along with
+ the user's salt.
+
+
+
+
+Newman, et al. Standards Track [Page 12]
+
+RFC 5802 SCRAM July 2010
+
+
+ For the SCRAM-SHA-1/SCRAM-SHA-1-PLUS SASL mechanism, servers
+ SHOULD announce a hash iteration-count of at least 4096. Note
+ that a client implementation MAY cache ClientKey&ServerKey (or
+ just SaltedPassword) for later reauthentication to the same
+ service, as it is likely that the server is going to advertise
+ the same salt value upon reauthentication. This might be
+ useful for mobile clients where CPU usage is a concern.
+
+ o p: This attribute specifies a base64-encoded ClientProof. The
+ client computes this value as described in the overview and sends
+ it to the server.
+
+ o v: This attribute specifies a base64-encoded ServerSignature. It
+ is sent by the server in its final message, and is used by the
+ client to verify that the server has access to the user's
+ authentication information. This value is computed as explained
+ in the overview.
+
+ o e: This attribute specifies an error that occurred during
+ authentication exchange. It is sent by the server in its final
+ message and can help diagnose the reason for the authentication
+ exchange failure. On failed authentication, the entire server-
+ final-message is OPTIONAL; specifically, a server implementation
+ MAY conclude the SASL exchange with a failure without sending the
+ server-final-message. This results in an application-level error
+ response without an extra round-trip. If the server-final-message
+ is sent on authentication failure, then the "e" attribute MUST be
+ included.
+
+ o As-yet unspecified mandatory and optional extensions. Mandatory
+ extensions are encoded as values of the 'm' attribute (see ABNF
+ for reserved-mext in section 7). Optional extensions use as-yet
+ unassigned attribute names.
+
+ Mandatory extensions sent by one peer but not understood by the
+ other MUST cause authentication failure (the server SHOULD send
+ the "extensions-not-supported" server-error-value).
+
+ Unknown optional extensions MUST be ignored upon receipt.
+
+5.2. Compliance with SASL Mechanism Requirements
+
+ This section describes compliance with SASL mechanism requirements
+ specified in Section 5 of [RFC4422].
+
+ 1) "SCRAM-SHA-1" and "SCRAM-SHA-1-PLUS".
+
+ 2a) SCRAM is a client-first mechanism.
+
+
+
+Newman, et al. Standards Track [Page 13]
+
+RFC 5802 SCRAM July 2010
+
+
+ 2b) SCRAM sends additional data with success.
+
+ 3) SCRAM is capable of transferring authorization identities from
+ the client to the server.
+
+ 4) SCRAM does not offer any security layers (SCRAM offers channel
+ binding instead).
+
+ 5) SCRAM has a hash protecting the authorization identity.
+
+6. Channel Binding
+
+ SCRAM supports channel binding to external secure channels, such as
+ TLS. Clients and servers may or may not support channel binding,
+ therefore the use of channel binding is negotiable. SCRAM does not
+ provide security layers, however, therefore it is imperative that
+ SCRAM provide integrity protection for the negotiation of channel
+ binding.
+
+ Use of channel binding is negotiated as follows:
+
+ o Servers that support the use of channel binding SHOULD advertise
+ both the non-PLUS (SCRAM-<hash-function>) and PLUS-variant (SCRAM-
+ <hash-function>-PLUS) mechanism name. If the server cannot
+ support channel binding, it SHOULD advertise only the non-PLUS-
+ variant. If the server would never succeed in the authentication
+ of the non-PLUS-variant due to policy reasons, it MUST advertise
+ only the PLUS-variant.
+
+ o If the client supports channel binding and the server does not
+ appear to (i.e., the client did not see the -PLUS name advertised
+ by the server), then the client MUST NOT use an "n" gs2-cbind-
+ flag.
+
+ o Clients that support mechanism negotiation and channel binding
+ MUST use a "p" gs2-cbind-flag when the server offers the PLUS-
+ variant of the desired GS2 mechanism.
+
+ o If the client does not support channel binding, then it MUST use
+ an "n" gs2-cbind-flag. Conversely, if the client requires the use
+ of channel binding then it MUST use a "p" gs2-cbind-flag. Clients
+ that do not support mechanism negotiation never use a "y" gs2-
+ cbind-flag, they use either "p" or "n" according to whether they
+ require and support the use of channel binding or whether they do
+ not, respectively.
+
+ o Upon receipt of the client-first message, the server checks the
+ channel binding flag (gs2-cbind-flag).
+
+
+
+Newman, et al. Standards Track [Page 14]
+
+RFC 5802 SCRAM July 2010
+
+
+ * If the flag is set to "y" and the server supports channel
+ binding, the server MUST fail authentication. This is because
+ if the client sets the channel binding flag to "y", then the
+ client must have believed that the server did not support
+ channel binding -- if the server did in fact support channel
+ binding, then this is an indication that there has been a
+ downgrade attack (e.g., an attacker changed the server's
+ mechanism list to exclude the -PLUS suffixed SCRAM mechanism
+ name(s)).
+
+ * If the channel binding flag was "p" and the server does not
+ support the indicated channel binding type, then the server
+ MUST fail authentication.
+
+ The server MUST always validate the client's "c=" field. The server
+ does this by constructing the value of the "c=" attribute and then
+ checking that it matches the client's c= attribute value.
+
+ For more discussions of channel bindings, and the syntax of channel
+ binding data for various security protocols, see [RFC5056].
+
+6.1. Default Channel Binding
+
+ A default channel binding type agreement process for all SASL
+ application protocols that do not provide their own channel binding
+ type agreement is provided as follows.
+
+ 'tls-unique' is the default channel binding type for any application
+ that doesn't specify one.
+
+ Servers MUST implement the "tls-unique" [RFC5929] channel binding
+ type, if they implement any channel binding. Clients SHOULD
+ implement the "tls-unique" [RFC5929] channel binding type, if they
+ implement any channel binding. Clients and servers SHOULD choose the
+ highest-layer/innermost end-to-end TLS channel as the channel to
+ which to bind.
+
+ Servers MUST choose the channel binding type indicated by the client,
+ or fail authentication if they don't support it.
+
+7. Formal Syntax
+
+ The following syntax specification uses the Augmented Backus-Naur
+ form (ABNF) notation as specified in [RFC5234]. "UTF8-2", "UTF8-3",
+ and "UTF8-4" non-terminal are defined in [RFC3629].
+
+
+
+
+
+
+Newman, et al. Standards Track [Page 15]
+
+RFC 5802 SCRAM July 2010
+
+
+ ALPHA = <as defined in RFC 5234 appendix B.1>
+ DIGIT = <as defined in RFC 5234 appendix B.1>
+ UTF8-2 = <as defined in RFC 3629 (STD 63)>
+ UTF8-3 = <as defined in RFC 3629 (STD 63)>
+ UTF8-4 = <as defined in RFC 3629 (STD 63)>
+
+ attr-val = ALPHA "=" value
+ ;; Generic syntax of any attribute sent
+ ;; by server or client
+
+ value = 1*value-char
+
+ value-safe-char = %x01-2B / %x2D-3C / %x3E-7F /
+ UTF8-2 / UTF8-3 / UTF8-4
+ ;; UTF8-char except NUL, "=", and ",".
+
+ value-char = value-safe-char / "="
+
+ printable = %x21-2B / %x2D-7E
+ ;; Printable ASCII except ",".
+ ;; Note that any "printable" is also
+ ;; a valid "value".
+
+ base64-char = ALPHA / DIGIT / "/" / "+"
+
+ base64-4 = 4base64-char
+
+ base64-3 = 3base64-char "="
+
+ base64-2 = 2base64-char "=="
+
+ base64 = *base64-4 [base64-3 / base64-2]
+
+ posit-number = %x31-39 *DIGIT
+ ;; A positive number.
+
+ saslname = 1*(value-safe-char / "=2C" / "=3D")
+ ;; Conforms to <value>.
+
+ authzid = "a=" saslname
+ ;; Protocol specific.
+
+ cb-name = 1*(ALPHA / DIGIT / "." / "-")
+ ;; See RFC 5056, Section 7.
+ ;; E.g., "tls-server-end-point" or
+ ;; "tls-unique".
+
+
+
+
+
+Newman, et al. Standards Track [Page 16]
+
+RFC 5802 SCRAM July 2010
+
+
+ gs2-cbind-flag = ("p=" cb-name) / "n" / "y"
+ ;; "n" -> client doesn't support channel binding.
+ ;; "y" -> client does support channel binding
+ ;; but thinks the server does not.
+ ;; "p" -> client requires channel binding.
+ ;; The selected channel binding follows "p=".
+
+ gs2-header = gs2-cbind-flag "," [ authzid ] ","
+ ;; GS2 header for SCRAM
+ ;; (the actual GS2 header includes an optional
+ ;; flag to indicate that the GSS mechanism is not
+ ;; "standard", but since SCRAM is "standard", we
+ ;; don't include that flag).
+
+ username = "n=" saslname
+ ;; Usernames are prepared using SASLprep.
+
+ reserved-mext = "m=" 1*(value-char)
+ ;; Reserved for signaling mandatory extensions.
+ ;; The exact syntax will be defined in
+ ;; the future.
+
+ channel-binding = "c=" base64
+ ;; base64 encoding of cbind-input.
+
+ proof = "p=" base64
+
+ nonce = "r=" c-nonce [s-nonce]
+ ;; Second part provided by server.
+
+ c-nonce = printable
+
+ s-nonce = printable
+
+ salt = "s=" base64
+
+ verifier = "v=" base64
+ ;; base-64 encoded ServerSignature.
+
+ iteration-count = "i=" posit-number
+ ;; A positive number.
+
+ client-first-message-bare =
+ [reserved-mext ","]
+ username "," nonce ["," extensions]
+
+ client-first-message =
+ gs2-header client-first-message-bare
+
+
+
+Newman, et al. Standards Track [Page 17]
+
+RFC 5802 SCRAM July 2010
+
+
+ server-first-message =
+ [reserved-mext ","] nonce "," salt ","
+ iteration-count ["," extensions]
+
+ client-final-message-without-proof =
+ channel-binding "," nonce [","
+ extensions]
+
+ client-final-message =
+ client-final-message-without-proof "," proof
+
+ server-error = "e=" server-error-value
+
+ server-error-value = "invalid-encoding" /
+ "extensions-not-supported" / ; unrecognized 'm' value
+ "invalid-proof" /
+ "channel-bindings-dont-match" /
+ "server-does-support-channel-binding" /
+ ; server does not support channel binding
+ "channel-binding-not-supported" /
+ "unsupported-channel-binding-type" /
+ "unknown-user" /
+ "invalid-username-encoding" /
+ ; invalid username encoding (invalid UTF-8 or
+ ; SASLprep failed)
+ "no-resources" /
+ "other-error" /
+ server-error-value-ext
+ ; Unrecognized errors should be treated as "other-error".
+ ; In order to prevent information disclosure, the server
+ ; may substitute the real reason with "other-error".
+
+ server-error-value-ext = value
+ ; Additional error reasons added by extensions
+ ; to this document.
+
+ server-final-message = (server-error / verifier)
+ ["," extensions]
+
+ extensions = attr-val *("," attr-val)
+ ;; All extensions are optional,
+ ;; i.e., unrecognized attributes
+ ;; not defined in this document
+ ;; MUST be ignored.
+
+ cbind-data = 1*OCTET
+
+
+
+
+
+Newman, et al. Standards Track [Page 18]
+
+RFC 5802 SCRAM July 2010
+
+
+ cbind-input = gs2-header [ cbind-data ]
+ ;; cbind-data MUST be present for
+ ;; gs2-cbind-flag of "p" and MUST be absent
+ ;; for "y" or "n".
+
+8. SCRAM as a GSS-API Mechanism
+
+ This section and its sub-sections and all normative references of it
+ not referenced elsewhere in this document are INFORMATIONAL for SASL
+ implementors, but they are NORMATIVE for GSS-API implementors.
+
+ SCRAM is actually also a GSS-API mechanism. The messages are the
+ same, but a) the GS2 header on the client's first message and channel
+ binding data is excluded when SCRAM is used as a GSS-API mechanism,
+ and b) the RFC2743 section 3.1 initial context token header is
+ prefixed to the client's first authentication message (context
+ token).
+
+ The GSS-API mechanism OID for SCRAM-SHA-1 is 1.3.6.1.5.5.14 (see
+ Section 10).
+
+ SCRAM security contexts always have the mutual_state flag
+ (GSS_C_MUTUAL_FLAG) set to TRUE. SCRAM does not support credential
+ delegation, therefore SCRAM security contexts alway have the
+ deleg_state flag (GSS_C_DELEG_FLAG) set to FALSE.
+
+8.1. GSS-API Principal Name Types for SCRAM
+
+ SCRAM does not explicitly name acceptor principals. However, the use
+ of acceptor principal names to find or prompt for passwords is
+ useful. Therefore, SCRAM supports standard generic name syntaxes for
+ acceptors such as GSS_C_NT_HOSTBASED_SERVICE (see [RFC2743], Section
+ 4.1). Implementations should use the target name passed to
+ GSS_Init_sec_context(), if any, to help retrieve or prompt for SCRAM
+ passwords.
+
+ SCRAM supports only a single name type for initiators:
+ GSS_C_NT_USER_NAME. GSS_C_NT_USER_NAME is the default name type for
+ SCRAM.
+
+ There is no name canonicalization procedure for SCRAM beyond applying
+ SASLprep as described in Section 5.1.
+
+ The query, display, and exported name syntaxes for SCRAM principal
+ names are all the same. There are no SCRAM-specific name syntaxes
+ (SCRAM initiator principal names are free-form); -- applications
+ should use generic GSS-API name types such as GSS_C_NT_USER_NAME and
+
+
+
+
+Newman, et al. Standards Track [Page 19]
+
+RFC 5802 SCRAM July 2010
+
+
+ GSS_C_NT_HOSTBASED_SERVICE (see [RFC2743], Section 4). The exported
+ name token does, of course, conform to [RFC2743], Section 3.2, but
+ the "NAME" part of the token is just a SCRAM user name.
+
+8.2. GSS-API Per-Message Tokens for SCRAM
+
+ The per-message tokens for SCRAM as a GSS-API mechanism SHALL be the
+ same as those for the Kerberos V GSS-API mechanism [RFC4121] (see
+ Section 4.2 and sub-sections), using the Kerberos V "aes128-cts-hmac-
+ sha1-96" enctype [RFC3962].
+
+ The replay_det_state (GSS_C_REPLAY_FLAG), sequence_state
+ (GSS_C_SEQUENCE_FLAG), conf_avail (GSS_C_CONF_FLAG) and integ_avail
+ (GSS_C_CONF_FLAG) security context flags are always set to TRUE.
+
+ The 128-bit session "protocol key" SHALL be derived by using the
+ least significant (right-most) 128 bits of HMAC(StoredKey, "GSS-API
+ session key" || ClientKey || AuthMessage). "Specific keys" are then
+ derived as usual as described in Section 2 of [RFC4121], [RFC3961],
+ and [RFC3962].
+
+ The terms "protocol key" and "specific key" are Kerberos V5 terms
+ [RFC3961].
+
+ SCRAM does support PROT_READY, and is PROT_READY on the initiator
+ side first upon receipt of the server's reply to the initial security
+ context token.
+
+8.3. GSS_Pseudo_random() for SCRAM
+
+ The GSS_Pseudo_random() [RFC4401] for SCRAM SHALL be the same as for
+ the Kerberos V GSS-API mechanism [RFC4402]. There is no acceptor-
+ asserted sub-session key for SCRAM, thus GSS_C_PRF_KEY_FULL and
+ GSS_C_PRF_KEY_PARTIAL are equivalent for SCRAM's GSS_Pseudo_random().
+ The protocol key to be used for the GSS_Pseudo_random() SHALL be the
+ same as the key defined in Section 8.2.
+
+9. Security Considerations
+
+ If the authentication exchange is performed without a strong security
+ layer (such as TLS with data confidentiality), then a passive
+ eavesdropper can gain sufficient information to mount an offline
+ dictionary or brute-force attack that can be used to recover the
+ user's password. The amount of time necessary for this attack
+ depends on the cryptographic hash function selected, the strength of
+ the password, and the iteration count supplied by the server. An
+ external security layer with strong encryption will prevent this
+ attack.
+
+
+
+Newman, et al. Standards Track [Page 20]
+
+RFC 5802 SCRAM July 2010
+
+
+ If the external security layer used to protect the SCRAM exchange
+ uses an anonymous key exchange, then the SCRAM channel binding
+ mechanism can be used to detect a man-in-the-middle attack on the
+ security layer and cause the authentication to fail as a result.
+ However, the man-in-the-middle attacker will have gained sufficient
+ information to mount an offline dictionary or brute-force attack.
+ For this reason, SCRAM allows to increase the iteration count over
+ time. (Note that a server that is only in possession of "StoredKey"
+ and "ServerKey" can't automatically increase the iteration count upon
+ successful authentication. Such an increase would require resetting
+ the user's password.)
+
+ If the authentication information is stolen from the authentication
+ database, then an offline dictionary or brute-force attack can be
+ used to recover the user's password. The use of salt mitigates this
+ attack somewhat by requiring a separate attack on each password.
+ Authentication mechanisms that protect against this attack are
+ available (e.g., the EKE class of mechanisms). RFC 2945 [RFC2945] is
+ an example of such technology. The WG elected not to use EKE like
+ mechanisms as a basis for SCRAM.
+
+ If an attacker obtains the authentication information from the
+ authentication repository and either eavesdrops on one authentication
+ exchange or impersonates a server, the attacker gains the ability to
+ impersonate that user to all servers providing SCRAM access using the
+ same hash function, password, iteration count, and salt. For this
+ reason, it is important to use randomly generated salt values.
+
+ SCRAM does not negotiate a hash function to use. Hash function
+ negotiation is left to the SASL mechanism negotiation. It is
+ important that clients be able to sort a locally available list of
+ mechanisms by preference so that the client may pick the appropriate
+ mechanism to use from a server's advertised mechanism list. This
+ preference order is not specified here as it is a local matter. The
+ preference order should include objective and subjective notions of
+ mechanism cryptographic strength (e.g., SCRAM with a successor to
+ SHA-1 may be preferred over SCRAM with SHA-1).
+
+ Note that to protect the SASL mechanism negotiation applications
+ normally must list the server mechanisms twice: once before and once
+ after authentication, the latter using security layers. Since SCRAM
+ does not provide security layers, the only ways to protect the
+ mechanism negotiation are a) use channel binding to an external
+ channel, or b) use an external channel that authenticates a user-
+ provided server name.
+
+
+
+
+
+
+Newman, et al. Standards Track [Page 21]
+
+RFC 5802 SCRAM July 2010
+
+
+ SCRAM does not protect against downgrade attacks of channel binding
+ types. The complexities of negotiating a channel binding type, and
+ handling down-grade attacks in that negotiation, were intentionally
+ left out of scope for this document.
+
+ A hostile server can perform a computational denial-of-service attack
+ on clients by sending a big iteration count value.
+
+ See [RFC4086] for more information about generating randomness.
+
+10. IANA Considerations
+
+ IANA has added the following family of SASL mechanisms to the SASL
+ Mechanism registry established by [RFC4422]:
+
+ To: iana@iana.org
+ Subject: Registration of a new SASL family SCRAM
+
+ SASL mechanism name (or prefix for the family): SCRAM-*
+ Security considerations: Section 7 of [RFC5802]
+ Published specification (optional, recommended): [RFC5802]
+ Person & email address to contact for further information:
+ IETF SASL WG <sasl@ietf.org>
+ Intended usage: COMMON
+ Owner/Change controller: IESG <iesg@ietf.org>
+ Note: Members of this family MUST be explicitly registered
+ using the "IETF Review" [RFC5226] registration procedure.
+ Reviews MUST be requested on the SASL mailing list
+ <sasl@ietf.org> (or a successor designated by the responsible
+ Security AD).
+
+ Note to future SCRAM-mechanism designers: each new SCRAM-SASL
+ mechanism MUST be explicitly registered with IANA and MUST comply
+ with SCRAM-mechanism naming convention defined in Section 4 of this
+ document.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Newman, et al. Standards Track [Page 22]
+
+RFC 5802 SCRAM July 2010
+
+
+ IANA has added the following entries to the SASL Mechanism registry
+ established by [RFC4422]:
+
+ To: iana@iana.org
+ Subject: Registration of a new SASL mechanism SCRAM-SHA-1
+
+ SASL mechanism name (or prefix for the family): SCRAM-SHA-1
+ Security considerations: Section 7 of [RFC5802]
+ Published specification (optional, recommended): [RFC5802]
+ Person & email address to contact for further information:
+ IETF SASL WG <sasl@ietf.org>
+ Intended usage: COMMON
+ Owner/Change controller: IESG <iesg@ietf.org>
+ Note:
+
+ To: iana@iana.org
+ Subject: Registration of a new SASL mechanism SCRAM-SHA-1-PLUS
+
+ SASL mechanism name (or prefix for the family): SCRAM-SHA-1-PLUS
+ Security considerations: Section 7 of [RFC5802]
+ Published specification (optional, recommended): [RFC5802]
+ Person & email address to contact for further information:
+ IETF SASL WG <sasl@ietf.org>
+ Intended usage: COMMON
+ Owner/Change controller: IESG <iesg@ietf.org>
+ Note:
+
+ Per this document, IANA has assigned a GSS-API mechanism OID for
+ SCRAM-SHA-1 from the iso.org.dod.internet.security.mechanisms prefix
+ (see "SMI Security for Mechanism Codes" registry).
+
+11. Acknowledgements
+
+ This document benefited from discussions on the SASL WG mailing list.
+ The authors would like to specially thank Dave Cridland, Simon
+ Josefsson, Jeffrey Hutzelman, Kurt Zeilenga, Pasi Eronen, Ben
+ Campbell, Peter Saint-Andre, and Tobias Markmann for their
+ contributions to this document. A special thank you to Simon
+ Josefsson for shepherding this document and for doing one of the
+ first implementations of this specification.
+
+
+
+
+
+
+
+
+
+
+
+Newman, et al. Standards Track [Page 23]
+
+RFC 5802 SCRAM July 2010
+
+
+12. References
+
+12.1. Normative References
+
+ [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed-
+ Hashing for Message Authentication", RFC 2104,
+ February 1997.
+
+ [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+ [RFC3174] Eastlake, D. and P. Jones, "US Secure Hash Algorithm 1
+ (SHA1)", RFC 3174, September 2001.
+
+ [RFC3454] Hoffman, P. and M. Blanchet, "Preparation of
+ Internationalized Strings ("stringprep")", RFC 3454,
+ December 2002.
+
+ [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
+ 10646", STD 63, RFC 3629, November 2003.
+
+ [RFC4013] Zeilenga, K., "SASLprep: Stringprep Profile for User Names
+ and Passwords", RFC 4013, February 2005.
+
+ [RFC4422] Melnikov, A. and K. Zeilenga, "Simple Authentication and
+ Security Layer (SASL)", RFC 4422, June 2006.
+
+ [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
+ Encodings", RFC 4648, October 2006.
+
+ [RFC5056] Williams, N., "On the Use of Channel Bindings to Secure
+ Channels", RFC 5056, November 2007.
+
+ [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
+ Specifications: ABNF", STD 68, RFC 5234, January 2008.
+
+ [RFC5929] Altman, J., Williams, N., and L. Zhu, "Channel Bindings
+ for TLS", RFC 5929, July 2010.
+
+12.2. Normative References for GSS-API Implementors
+
+ [RFC2743] Linn, J., "Generic Security Service Application Program
+ Interface Version 2, Update 1", RFC 2743, January 2000.
+
+ [RFC3961] Raeburn, K., "Encryption and Checksum Specifications for
+ Kerberos 5", RFC 3961, February 2005.
+
+
+
+
+
+Newman, et al. Standards Track [Page 24]
+
+RFC 5802 SCRAM July 2010
+
+
+ [RFC3962] Raeburn, K., "Advanced Encryption Standard (AES)
+ Encryption for Kerberos 5", RFC 3962, February 2005.
+
+ [RFC4121] Zhu, L., Jaganathan, K., and S. Hartman, "The Kerberos
+ Version 5 Generic Security Service Application Program
+ Interface (GSS-API) Mechanism: Version 2", RFC 4121,
+ July 2005.
+
+ [RFC4401] Williams, N., "A Pseudo-Random Function (PRF) API
+ Extension for the Generic Security Service Application
+ Program Interface (GSS-API)", RFC 4401, February 2006.
+
+ [RFC4402] Williams, N., "A Pseudo-Random Function (PRF) for the
+ Kerberos V Generic Security Service Application Program
+ Interface (GSS-API) Mechanism", RFC 4402, February 2006.
+
+ [RFC5801] Josefsson, S. and N. Williams, "Using Generic Security
+ Service Application Program Interface (GSS-API) Mechanisms
+ in Simple Authentication and Security Layer (SASL): The
+ GS2 Mechanism Family", RFC 5801, July 2010.
+
+12.3. Informative References
+
+ [CRAMHISTORIC]
+ Zeilenga, K., "CRAM-MD5 to Historic", Work in Progress,
+ November 2008.
+
+ [DIGESTHISTORIC]
+ Melnikov, A., "Moving DIGEST-MD5 to Historic", Work
+ in Progress, July 2008.
+
+ [RFC2865] Rigney, C., Willens, S., Rubens, A., and W. Simpson,
+ "Remote Authentication Dial In User Service (RADIUS)",
+ RFC 2865, June 2000.
+
+ [RFC2898] Kaliski, B., "PKCS #5: Password-Based Cryptography
+ Specification Version 2.0", RFC 2898, September 2000.
+
+ [RFC2945] Wu, T., "The SRP Authentication and Key Exchange System",
+ RFC 2945, September 2000.
+
+ [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness
+ Requirements for Security", BCP 106, RFC 4086, June 2005.
+
+ [RFC4510] Zeilenga, K., "Lightweight Directory Access Protocol
+ (LDAP): Technical Specification Road Map", RFC 4510,
+ June 2006.
+
+
+
+
+Newman, et al. Standards Track [Page 25]
+
+RFC 5802 SCRAM July 2010
+
+
+ [RFC4616] Zeilenga, K., "The PLAIN Simple Authentication and
+ Security Layer (SASL) Mechanism", RFC 4616, August 2006.
+
+ [RFC4949] Shirey, R., "Internet Security Glossary, Version 2",
+ RFC 4949, August 2007.
+
+ [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
+ IANA Considerations Section in RFCs", BCP 26, RFC 5226,
+ May 2008.
+
+ [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
+ (TLS) Protocol Version 1.2", RFC 5246, August 2008.
+
+ [RFC5803] Melnikov, A., "Lightweight Directory Access Protocol
+ (LDAP) Schema for Storing Salted Challenge Response
+ Authentication Mechanism (SCRAM) Secrets", RFC 5803,
+ July 2010.
+
+ [tls-server-end-point]
+ IANA, "Registration of TLS server end-point channel
+ bindings", available from http://www.iana.org, June 2008.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Newman, et al. Standards Track [Page 26]
+
+RFC 5802 SCRAM July 2010
+
+
+Appendix A. Other Authentication Mechanisms
+
+ The DIGEST-MD5 [DIGESTHISTORIC] mechanism has proved to be too
+ complex to implement and test, and thus has poor interoperability.
+ The security layer is often not implemented, and almost never used;
+ everyone uses TLS instead. For a more complete list of problems with
+ DIGEST-MD5 that led to the creation of SCRAM, see [DIGESTHISTORIC].
+
+ The CRAM-MD5 SASL mechanism, while widely deployed, also has some
+ problems. In particular, it is missing some modern SASL features
+ such as support for internationalized usernames and passwords,
+ support for passing of authorization identity, and support for
+ channel bindings. It also doesn't support server authentication.
+ For a more complete list of problems with CRAM-MD5, see
+ [CRAMHISTORIC].
+
+ The PLAIN [RFC4616] SASL mechanism allows a malicious server or
+ eavesdropper to impersonate the authenticating user to any other
+ server for which the user has the same password. It also sends the
+ password in the clear over the network, unless TLS is used. Server
+ authentication is not supported.
+
+Appendix B. Design Motivations
+
+ The following design goals shaped this document. Note that some of
+ the goals have changed since the initial version of the document.
+
+ o The SASL mechanism has all modern SASL features: support for
+ internationalized usernames and passwords, support for passing of
+ authorization identity, and support for channel bindings.
+
+ o The protocol supports mutual authentication.
+
+ o The authentication information stored in the authentication
+ database is not sufficient by itself to impersonate the client.
+
+ o The server does not gain the ability to impersonate the client to
+ other servers (with an exception for server-authorized proxies),
+ unless such other servers allow SCRAM authentication and use the
+ same salt and iteration count for the user.
+
+ o The mechanism is extensible, but (hopefully) not over-engineered
+ in this respect.
+
+ o The mechanism is easier to implement than DIGEST-MD5 in both
+ clients and servers.
+
+
+
+
+
+Newman, et al. Standards Track [Page 27]
+
+RFC 5802 SCRAM July 2010
+
+
+Authors' Addresses
+
+ Chris Newman
+ Oracle
+ 800 Royal Oaks
+ Monrovia, CA 91016
+ USA
+
+ EMail: chris.newman@oracle.com
+
+
+ Abhijit Menon-Sen
+ Oryx Mail Systems GmbH
+
+ EMail: ams@toroid.org
+
+
+ Alexey Melnikov
+ Isode, Ltd.
+
+ EMail: Alexey.Melnikov@isode.com
+
+
+ Nicolas Williams
+ Oracle
+ 5300 Riata Trace Ct
+ Austin, TX 78727
+ USA
+
+ EMail: Nicolas.Williams@oracle.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Newman, et al. Standards Track [Page 28]
+
diff --git a/doc/rfcs/rfc7628.txt b/doc/rfcs/rfc7628.txt
new file mode 100644
index 0000000..447786a
--- /dev/null
+++ b/doc/rfcs/rfc7628.txt
@@ -0,0 +1,1179 @@
+
+
+
+
+
+
+Internet Engineering Task Force (IETF) W. Mills
+Request for Comments: 7628 Microsoft
+Category: Standards Track T. Showalter
+ISSN: 2070-1721
+ H. Tschofenig
+ ARM Ltd.
+ August 2015
+
+
+ A Set of Simple Authentication and Security Layer (SASL) Mechanisms
+ for OAuth
+
+Abstract
+
+ OAuth enables a third-party application to obtain limited access to a
+ protected resource, either on behalf of a resource owner by
+ orchestrating an approval interaction or by allowing the third-party
+ application to obtain access on its own behalf.
+
+ This document defines how an application client uses credentials
+ obtained via OAuth over the Simple Authentication and Security Layer
+ (SASL) to access a protected resource at a resource server. Thereby,
+ it enables schemes defined within the OAuth framework for non-HTTP-
+ based application protocols.
+
+ Clients typically store the user's long-term credential. This does,
+ however, lead to significant security vulnerabilities, for example,
+ when such a credential leaks. A significant benefit of OAuth for
+ usage in those clients is that the password is replaced by a shared
+ secret with higher entropy, i.e., the token. Tokens typically
+ provide limited access rights and can be managed and revoked
+ separately from the user's long-term password.
+
+Status of This Memo
+
+ This is an Internet Standards Track document.
+
+ This document is a product of the Internet Engineering Task Force
+ (IETF). It represents the consensus of the IETF community. It has
+ received public review and has been approved for publication by the
+ Internet Engineering Steering Group (IESG). Further information on
+ Internet Standards is available in Section 2 of RFC 5741.
+
+ Information about the current status of this document, any errata,
+ and how to provide feedback on it may be obtained at
+ http://www.rfc-editor.org/info/rfc7628.
+
+
+
+
+
+Mills, et al. Standards Track [Page 1]
+
+RFC 7628 SASL OAuth August 2015
+
+
+Copyright Notice
+
+ Copyright (c) 2015 IETF Trust and the persons identified as the
+ document authors. All rights reserved.
+
+ This document is subject to BCP 78 and the IETF Trust's Legal
+ Provisions Relating to IETF Documents
+ (http://trustee.ietf.org/license-info) in effect on the date of
+ publication of this document. Please review these documents
+ carefully, as they describe your rights and restrictions with respect
+ to this document. Code Components extracted from this document must
+ include Simplified BSD License text as described in Section 4.e of
+ the Trust Legal Provisions and are provided without warranty as
+ described in the Simplified BSD License.
+
+Table of Contents
+
+ 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
+ 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5
+ 3. OAuth SASL Mechanism Specifications . . . . . . . . . . . . . 6
+ 3.1. Initial Client Response . . . . . . . . . . . . . . . . . 7
+ 3.1.1. Reserved Key/Values . . . . . . . . . . . . . . . . . 8
+ 3.2. Server's Response . . . . . . . . . . . . . . . . . . . . 8
+ 3.2.1. OAuth Identifiers in the SASL Context . . . . . . . . 9
+ 3.2.2. Server Response to Failed Authentication . . . . . . 9
+ 3.2.3. Completing an Error Message Sequence . . . . . . . . 10
+ 3.3. OAuth Access Token Types using Keyed Message Digests . . 11
+ 4. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 12
+ 4.1. Successful Bearer Token Exchange . . . . . . . . . . . . 12
+ 4.2. Successful OAuth 1.0a Token Exchange . . . . . . . . . . 13
+ 4.3. Failed Exchange . . . . . . . . . . . . . . . . . . . . . 14
+ 4.4. SMTP Example of a Failed Negotiation . . . . . . . . . . 15
+ 5. Security Considerations . . . . . . . . . . . . . . . . . . . 16
+ 6. Internationalization Considerations . . . . . . . . . . . . . 17
+ 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18
+ 7.1. SASL Registration . . . . . . . . . . . . . . . . . . . . 18
+ 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 19
+ 8.1. Normative References . . . . . . . . . . . . . . . . . . 19
+ 8.2. Informative References . . . . . . . . . . . . . . . . . 20
+ Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 21
+ Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 21
+
+
+
+
+
+
+
+
+
+
+Mills, et al. Standards Track [Page 2]
+
+RFC 7628 SASL OAuth August 2015
+
+
+1. Introduction
+
+ OAuth 1.0a [RFC5849] and OAuth 2.0 [RFC6749] are protocol frameworks
+ that enable a third-party application to obtain limited access to a
+ protected resource, either by orchestrating an approval interaction
+ on behalf of a resource owner or by allowing the third-party
+ application to obtain access on its own behalf.
+
+ The core OAuth 2.0 specification [RFC6749] specifies the interaction
+ between the OAuth client and the authorization server; it does not
+ define the interaction between the OAuth client and the resource
+ server for the access to a protected resource using an access token.
+ Instead, the OAuth client to resource server interaction is described
+ in separate specifications, such as the bearer token specification
+ [RFC6750]. OAuth 1.0a includes the protocol specification for the
+ communication between the OAuth client and the resource server in
+ [RFC5849].
+
+ The main use cases for OAuth 1.0a and OAuth 2.0 have so far focused
+ on an HTTP-based [RFC7230] environment only. This document
+ integrates OAuth 1.0a and OAuth 2.0 into non-HTTP-based applications
+ using the integration into the Simple Authentication and Security
+ Layer (SASL) [RFC4422]. Hence, this document takes advantage of the
+ OAuth protocol and its deployment base to provide a way to use SASL
+ to gain access to resources when using non-HTTP-based protocols, such
+ as the Internet Message Access Protocol (IMAP) [RFC3501] and the
+ Simple Mail Transfer Protocol (SMTP) [RFC5321]. This document gives
+ examples of use in IMAP and SMTP.
+
+ To illustrate the impact of integrating this specification into an
+ OAuth-enabled application environment, Figure 1 shows the abstract
+ message flow of OAuth 2.0 [RFC6749]. As indicated in the figure,
+ this document impacts the exchange of messages (E) and (F) since SASL
+ is used for interaction between the client and the resource server
+ instead of HTTP.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Mills, et al. Standards Track [Page 3]
+
+RFC 7628 SASL OAuth August 2015
+
+
+ ----+
+ +--------+ +---------------+ |
+ | |--(A)-- Authorization Request --->| Resource | |
+ | | | Owner | |Plain
+ | |<-(B)------ Access Grant ---------| | |OAuth
+ | | +---------------+ |2.0
+ | | |
+ | | Client Credentials & +---------------+ |
+ | |--(C)------ Access Grant -------->| Authorization | |
+ | Client | | Server | |
+ | |<-(D)------ Access Token ---------| | |
+ | | (w/ Optional Refresh Token) +---------------+ |
+ | | ----+
+ | | ----+
+ | | +---------------+ |
+ | | | | |OAuth
+ | |--(E)------ Access Token -------->| Resource | |over
+ | | | Server | |SASL
+ | |<-(F)---- Protected Resource -----| | |
+ | | | | |
+ +--------+ +---------------+ |
+ ----+
+
+ Figure 1: OAuth 2.0 Protocol Flow
+
+ SASL is a framework for providing authentication and data security
+ services in connection-oriented protocols via replaceable
+ authentication mechanisms. It provides a structured interface
+ between protocols and mechanisms. The resulting framework allows new
+ protocols to reuse existing authentication mechanisms and allows old
+ protocols to make use of new authentication mechanisms. The
+ framework also provides a protocol for securing subsequent exchanges
+ within a data security layer.
+
+ When OAuth is integrated into SASL, the high-level steps are as
+ follows:
+
+ (A) The client requests authorization from the resource owner. The
+ authorization request can be made directly to the resource owner
+ (as shown) or indirectly via the authorization server as an
+ intermediary.
+
+ (B) The client receives an authorization grant, which is a
+ credential representing the resource owner's authorization,
+ expressed using one of the grant types defined in [RFC6749] or
+ [RFC5849] or using an extension grant type. The authorization
+ grant type depends on the method used by the client to request
+
+
+
+
+Mills, et al. Standards Track [Page 4]
+
+RFC 7628 SASL OAuth August 2015
+
+
+ authorization and the types supported by the authorization
+ server.
+
+ (C) The client requests an access token by authenticating with the
+ authorization server and presenting the authorization grant.
+
+ (D) The authorization server authenticates the client and validates
+ the authorization grant, and if valid, it issues an access
+ token.
+
+ (E) The client requests the protected resource from the resource
+ server and authenticates it by presenting the access token.
+
+ (F) The resource server validates the access token, and if valid, it
+ indicates a successful authentication.
+
+ Again, steps (E) and (F) are not defined in [RFC6749] (but are
+ described in, for example, [RFC6750] for the OAuth bearer token
+ instead) and are the main functionality specified within this
+ document. Consequently, the message exchange shown in Figure 1 is
+ the result of this specification. The client will generally need to
+ determine the authentication endpoints (and perhaps the service
+ endpoints) before the OAuth 2.0 protocol exchange messages in steps
+ (A)-(D) are executed. The discovery of the resource owner,
+ authorization server endpoints, and client registration are outside
+ the scope of this specification. The client must discover the
+ authorization endpoints using a discovery mechanism such as OpenID
+ Connect Discovery (OIDCD) [OpenID.Discovery] or WebFinger using host-
+ meta [RFC7033]. Once credentials are obtained, the client proceeds
+ to steps (E) and (F) defined in this specification. Authorization
+ endpoints MAY require client registration, and generic clients SHOULD
+ support the Dynamic Client Registration protocol [RFC7591].
+
+ OAuth 1.0a follows a similar model but uses a different terminology
+ and does not separate the resource server from the authorization
+ server.
+
+2. Terminology
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
+ "OPTIONAL" in this document are to be interpreted as described in
+ [RFC2119].
+
+ The reader is assumed to be familiar with the terms used in the OAuth
+ 2.0 specification [RFC6749] and SASL [RFC4422].
+
+
+
+
+
+Mills, et al. Standards Track [Page 5]
+
+RFC 7628 SASL OAuth August 2015
+
+
+ In examples, "C:" and "S:" indicate lines sent by the client and
+ server, respectively. Line breaks have been inserted for
+ readability.
+
+ Note that the IMAP SASL specification requires base64 encoding, as
+ specified in Section 4 of [RFC4648].
+
+3. OAuth SASL Mechanism Specifications
+
+ SASL is used as an authentication framework in a variety of
+ application-layer protocols. This document defines the following
+ SASL mechanisms for usage with OAuth:
+
+ OAUTHBEARER: OAuth 2.0 bearer tokens, as described in [RFC6750].
+ RFC 6750 uses Transport Layer Security (TLS) [RFC5246] to
+ secure the protocol interaction between the client and the
+ resource server.
+
+ OAUTH10A: OAuth 1.0a Message Authentication Code (MAC) tokens
+ (using the HMAC-SHA1 keyed message digest), as described in
+ Section 3.4.2 of [RFC5849].
+
+ New extensions may be defined to add additional OAuth Access Token
+ Types. Such a new SASL OAuth mechanism can be added by registering
+ the new name(s) with IANA in the SASL Mechanisms registry and citing
+ this specification for the further definition.
+
+ SASL mechanisms using this document as their definition do not
+ provide a data security layer; that is, they cannot provide integrity
+ or confidentiality protection for application messages after the
+ initial authentication. If such protection is needed, TLS or some
+ similar solution should be used. Additionally, for the two
+ mechanisms specified in this document, TLS MUST be used for
+ OAUTHBEARER to protect the bearer token; for OAUTH10A, the use of TLS
+ is RECOMMENDED.
+
+ These mechanisms are client initiated and in lockstep, with the
+ server always replying to a client message. In the case where the
+ client has and correctly uses a valid token, the flow is:
+
+ 1. Client sends a valid and correct initial client response.
+
+ 2. Server responds with a successful authentication.
+
+ In the case where authentication fails, the server sends an error
+ result; the client MUST then send an additional message to the server
+ in order to allow the server to finish the exchange. Some protocols
+ and common SASL implementations do not support both sending a SASL
+
+
+
+Mills, et al. Standards Track [Page 6]
+
+RFC 7628 SASL OAuth August 2015
+
+
+ message and finalizing a SASL negotiation. The additional client
+ message in the error case deals with this problem. This exchange is:
+
+ 1. Client sends an invalid initial client response.
+
+ 2. Server responds with an error message.
+
+ 3. Client sends a dummy client response.
+
+ 4. Server fails the authentication.
+
+3.1. Initial Client Response
+
+ Client responses are a GS2 [RFC5801] header followed by zero or more
+ key/value pairs, or it may be empty. The gs2-header rule is defined
+ here as a placeholder for compatibility with GS2 if a GS2 mechanism
+ is formally defined, but this document does not define one. The key/
+ value pairs take the place of the corresponding HTTP headers and
+ values to convey the information necessary to complete an OAuth-style
+ HTTP authorization. Unknown key/value pairs MUST be ignored by the
+ server. The ABNF [RFC5234] syntax is:
+
+ kvsep = %x01
+ key = 1*(ALPHA)
+ value = *(VCHAR / SP / HTAB / CR / LF )
+ kvpair = key "=" value kvsep
+ ;;gs2-header = See RFC 5801
+ client-resp = (gs2-header kvsep *kvpair kvsep) / kvsep
+
+ The GS2 header MAY include the username associated with the resource
+ being accessed, the "authzid". It is worth noting that application
+ protocols are allowed to require an authzid, as are specific server
+ implementations.
+
+ The client response consisting of only a single kvsep is used only
+ when authentication fails and is only valid in that context. If sent
+ as the first message from the client, the server MAY simply fail the
+ authentication without returning discovery information since there is
+ no user or server name indication.
+
+ The following keys and corresponding values are defined in the client
+ response:
+
+ auth (REQUIRED): The payload that would be in the HTTP
+ Authorization header if this OAuth exchange was being carried
+ out over HTTP.
+
+
+
+
+
+Mills, et al. Standards Track [Page 7]
+
+RFC 7628 SASL OAuth August 2015
+
+
+ host: Contains the hostname to which the client connected. In an
+ HTTP context, this is the value of the HTTP Host header.
+
+ port: Contains the destination port that the client connected to,
+ represented as a decimal positive integer string without
+ leading zeros.
+
+ For OAuth token types such as OAuth 1.0a that use keyed message
+ digests, the client MUST send host and port number key/values, and
+ the server MUST fail an authorization request requiring keyed message
+ digests that are not accompanied by host and port values. In OAuth
+ 1.0a, for example, the so-called "signature base string calculation"
+ includes the reconstructed HTTP URL.
+
+3.1.1. Reserved Key/Values
+
+ In these mechanisms, values for path, query string and post body are
+ assigned default values. OAuth authorization schemes MAY define
+ usage of these in the SASL context and extend this specification.
+ For OAuth Access Token Types that include a keyed message digest of
+ the request, the default values MUST be used unless explicit values
+ are provided in the client response. The following key values are
+ reserved for future use:
+
+ mthd (RESERVED): HTTP method; the default value is "POST".
+
+ path (RESERVED): HTTP path data; the default value is "/".
+
+ post (RESERVED): HTTP post data; the default value is the empty
+ string ("").
+
+ qs (RESERVED): The HTTP query string; the default value is the
+ empty string ("").
+
+3.2. Server's Response
+
+ The server validates the response according to the specification for
+ the OAuth Access Token Types used. If the OAuth Access Token Type
+ utilizes a keyed message digest of the request parameters, then the
+ client must provide a client response that satisfies the data
+ requirements for the scheme in use.
+
+ The server fully validates the client response before generating a
+ server response; this will necessarily include the validation steps
+ listed in the specification for the OAuth Access Token Type used.
+ However, additional validation steps may be needed, depending on the
+ particular application protocol making use of SASL. In particular,
+ values included as kvpairs in the client response (such as host and
+
+
+
+Mills, et al. Standards Track [Page 8]
+
+RFC 7628 SASL OAuth August 2015
+
+
+ port) that correspond to values known to the application server by
+ some other mechanism (such as an application protocol data unit or
+ preconfigured values) MUST be validated to match between the initial
+ client response and the other source(s) of such information. As a
+ concrete example, when SASL is used over IMAP to an IMAP server for a
+ single domain, the hostname can be available via configuration; this
+ hostname must be validated to match the value sent in the 'host'
+ kvpair.
+
+ The server responds to a successfully verified client message by
+ completing the SASL negotiation. The authenticated identity reported
+ by the SASL mechanism is the identity securely established for the
+ client with the OAuth credential. The application, not the SASL
+ mechanism, based on local access policy determines whether the
+ identity reported by the mechanism is allowed access to the requested
+ resource. Note that the semantics of the authzid are specified by
+ the SASL framework [RFC4422].
+
+3.2.1. OAuth Identifiers in the SASL Context
+
+ In the OAuth framework, the client may be authenticated by the
+ authorization server, and the resource owner is authenticated to the
+ authorization server. OAuth access tokens may contain information
+ about the authentication of the resource owner and about the client
+ and may therefore make this information accessible to the resource
+ server.
+
+ If both identifiers are needed by an application the developer will
+ need to provide a way to communicate that from the SASL mechanism
+ back to the application.
+
+3.2.2. Server Response to Failed Authentication
+
+ For a failed authentication, the server returns an error result in
+ JSON [RFC7159] format and fails the authentication. The error result
+ consists of the following values:
+
+ status (REQUIRED): The authorization error code. Valid error
+ codes are defined in the IANA "OAuth Extensions Error Registry"
+ as specified in the OAuth 2.0 core specification.
+
+ scope (OPTIONAL): An OAuth scope that is valid to access the
+ service. This may be omitted, which implies that unscoped
+ tokens are required. If a scope is specified, then a single
+ scope is preferred. At the time this document was written,
+ there are several implementations that do not properly support
+ space-separated lists of scopes, so the use of a space-
+ separated list of scopes is NOT RECOMMENDED.
+
+
+
+Mills, et al. Standards Track [Page 9]
+
+RFC 7628 SASL OAuth August 2015
+
+
+ openid-configuration (OPTIONAL): The URL for a document following
+ the OpenID Provider Configuration Information schema as
+ described in OIDCD [OpenID.Discovery], Section 3 that is
+ appropriate for the user. As specified in OIDCD, this will
+ have the "https" URL scheme. This document MUST have all
+ OAuth-related data elements populated. The server MAY return
+ different URLs for users in different domains, and the client
+ SHOULD NOT cache a single returned value and assume it applies
+ for all users/domains that the server supports. The returned
+ discovery document SHOULD have all data elements required by
+ the OpenID Connect Discovery specification populated. In
+ addition, the discovery document SHOULD contain the
+ 'registration_endpoint' element to identify the endpoint to be
+ used with the Dynamic Client Registration protocol [RFC7591] to
+ obtain the minimum number of parameters necessary for the OAuth
+ protocol exchange to function. Another comparable discovery or
+ client registration mechanism MAY be used if available.
+
+ The use of the 'offline_access' scope, as defined in
+ [OpenID.Core], is RECOMMENDED to give clients the capability to
+ explicitly request a refresh token.
+
+ If the resource server provides a scope, then the client MUST always
+ request scoped tokens from the token endpoint. If the resource
+ server does not return a scope, the client SHOULD presume an unscoped
+ token is required to access the resource.
+
+ Since clients may interact with a number of application servers, such
+ as email servers and Extensible Messaging and Presence Protocol
+ (XMPP) [RFC6120] servers, they need to have a way to determine
+ whether dynamic client registration has been performed already and
+ whether an already available refresh token can be reused to obtain an
+ access token for the desired resource server. This specification
+ RECOMMENDS that a client uses the information in the 'iss' element
+ defined in OpenID Connect Core [OpenID.Core] to make this
+ determination.
+
+3.2.3. Completing an Error Message Sequence
+
+ Section 3.6 of SASL [RFC4422] explicitly prohibits additional
+ information in an unsuccessful authentication outcome. Therefore,
+ the error message is sent in a normal message. The client MUST then
+ send either an additional client response consisting of a single %x01
+ (control A) character to the server in order to allow the server to
+ finish the exchange or a SASL abort message as generally defined in
+ Section 3.5 of SASL [RFC4422]. A specific example of an abort
+ message is the "BAD" response to an AUTHENTICATE in IMAP [RFC3501],
+ Section 6.2.2.
+
+
+
+Mills, et al. Standards Track [Page 10]
+
+RFC 7628 SASL OAuth August 2015
+
+
+3.3. OAuth Access Token Types using Keyed Message Digests
+
+ OAuth Access Token Types may use keyed message digests, and the
+ client and the resource server may need to perform a cryptographic
+ computation for integrity protection and data origin authentication.
+
+ OAuth is designed for access to resources identified by URIs. SASL
+ is designed for user authentication and has no facility for more
+ fine-grained access control. In this specification, we require or
+ define default values for the data elements from an HTTP request that
+ allows the signature base string to be constructed properly. The
+ default HTTP path is "/", and the default post body is empty. These
+ atoms are defined as extension points so that no changes are needed
+ if there is a revision of SASL that supports more specific resource
+ authorization, e.g., IMAP access to a specific folder or FTP access
+ limited to a specific directory.
+
+ Using the example in the OAuth 1.0a specification as a starting
+ point, below is the authorization request in OAuth 1.0a style (with
+ %x01 shown as ^A and line breaks added for readability), assuming it
+ is on an IMAP server running on port 143:
+
+ n,a=user@example.com,^A
+ host=example.com^A
+ port=143^A
+ auth=OAuth realm="Example",
+ oauth_consumer_key="9djdj82h48djs9d2",
+ oauth_token="kkk9d7dh3k39sjv7",
+ oauth_signature_method="HMAC-SHA1",
+ oauth_timestamp="137131201",
+ oauth_nonce="7d8f3e4a",
+ oauth_signature="Tm90IGEgcmVhbCBzaWduYXR1cmU"^A^A
+
+ The signature base string would be constructed per the OAuth 1.0a
+ specification [RFC5849] with the following things noted:
+
+ o The method value is defaulted to POST.
+
+ o The scheme defaults to be "http", and any port number other than
+ 80 is included.
+
+ o The path defaults to "/".
+
+ o The query string defaults to "".
+
+
+
+
+
+
+
+Mills, et al. Standards Track [Page 11]
+
+RFC 7628 SASL OAuth August 2015
+
+
+ In this example, the signature base string with line breaks added for
+ readability would be:
+
+ POST&http%3A%2F%2Fexample.com:143%2F&oauth_consumer_key%3D9djdj82h4
+ 8djs9d2%26oauth_nonce%3D7d8f3e4a%26oauth_signature_method%3DHMAC-SH
+ A1%26oauth_timestamp%3D137131201%26oauth_token%3Dkkk9d7dh3k39sjv7
+
+4. Examples
+
+ These examples illustrate exchanges between IMAP and SMTP clients and
+ servers. All IMAP examples use SASL-IR [RFC4959] and send payload in
+ the initial client response. The bearer token examples assume
+ encrypted transport; if the underlying connection is not already TLS,
+ then STARTTLS MUST be used as TLS is required in the bearer token
+ specification.
+
+ Note to implementers: The SASL OAuth method names are case
+ insensitive. One example uses "Bearer" but that could as easily be
+ "bearer", "BEARER", or "BeArEr".
+
+4.1. Successful Bearer Token Exchange
+
+ This example shows a successful OAuth 2.0 bearer token exchange in
+ IMAP. Note that line breaks are inserted for readability.
+
+ [Initial connection and TLS establishment...]
+ S: * OK IMAP4rev1 Server Ready
+ C: t0 CAPABILITY
+ S: * CAPABILITY IMAP4rev1 AUTH=OAUTHBEARER SASL-IR
+ S: t0 OK Completed
+ C: t1 AUTHENTICATE OAUTHBEARER bixhPXVzZXJAZXhhbXBsZS5jb20sAWhv
+ c3Q9c2VydmVyLmV4YW1wbGUuY29tAXBvcnQ9MTQzAWF1dGg9QmVhcmVyI
+ HZGOWRmdDRxbVRjMk52YjNSbGNrQmhiSFJoZG1semRHRXVZMjl0Q2c9PQ
+ EB
+ S: t1 OK SASL authentication succeeded
+
+ As required by IMAP [RFC3501], the payloads are base64 encoded. The
+ decoded initial client response (with %x01 represented as ^A and long
+ lines wrapped for readability) is:
+
+ n,a=user@example.com,^Ahost=server.example.com^Aport=143^A
+ auth=Bearer vF9dft4qmTc2Nvb3RlckBhbHRhdmlzdGEuY29tCg==^A^A
+
+
+
+
+
+
+
+
+
+Mills, et al. Standards Track [Page 12]
+
+RFC 7628 SASL OAuth August 2015
+
+
+ The same credential used in an SMTP exchange is shown below. Again,
+ this example assumes that TLS is already established per the bearer
+ token specification requirements.
+
+ [connection begins]
+ S: 220 mx.example.com ESMTP 12sm2095603fks.9
+ C: EHLO sender.example.com
+ S: 250-mx.example.com at your service,[172.31.135.47]
+ S: 250-SIZE 35651584
+ S: 250-8BITMIME
+ S: 250-AUTH LOGIN PLAIN OAUTHBEARER
+ S: 250-ENHANCEDSTATUSCODES
+ S: 250-STARTTLS
+ S: 250 PIPELINING
+ [Negotiate TLS...]
+ C: t1 AUTH OAUTHBEARER bixhPXVzZXJAZXhhbXBsZS5jb20sAWhvc3Q9c2Vy
+ dmVyLmV4YW1wbGUuY29tAXBvcnQ9NTg3AWF1dGg9QmVhcmVyIHZGOWRmd
+ DRxbVRjMk52YjNSbGNrQmhiSFJoZG1semRHRXVZMjl0Q2c9PQEB
+ S: 235 Authentication successful.
+ [connection continues...]
+
+ The decoded initial client response is:
+
+ n,a=user@example.com,^Ahost=server.example.com^Aport=587^A
+ auth=Bearer vF9dft4qmTc2Nvb3RlckBhbHRhdmlzdGEuY29tCg==^A^A
+
+4.2. Successful OAuth 1.0a Token Exchange
+
+ This IMAP example shows a successful OAuth 1.0a token exchange. Note
+ that line breaks are inserted for readability. This example assumes
+ that TLS is already established. Signature computation is discussed
+ in Section 3.3.
+
+ S: * OK IMAP4rev1 Server Ready
+ C: t0 CAPABILITY
+ S: * CAPABILITY IMAP4rev1 AUTH=OAUTHBEARER AUTH=OAUTH10A SASL-IR
+ S: t0 OK Completed
+ C: t1 AUTHENTICATE OAUTH10A bixhPXVzZXJAZXhhbXBsZS5jb20sAWhvc3Q9ZXhhb
+ XBsZS5jb20BcG9ydD0xNDMBYXV0aD1PQXV0aCByZWFsbT0iRXhhbXBsZSIsb2F1
+ dGhfY29uc3VtZXJfa2V5PSI5ZGpkajgyaDQ4ZGpzOWQyIixvYXV0aF90b2tlbj0
+ ia2trOWQ3ZGgzazM5c2p2NyIsb2F1dGhfc2lnbmF0dXJlX21ldGhvZD0iSE1BQy
+ 1TSEExIixvYXV0aF90aW1lc3RhbXA9IjEzNzEzMTIwMSIsb2F1dGhfbm9uY2U9I
+ jdkOGYzZTRhIixvYXV0aF9zaWduYXR1cmU9IlRtOTBJR0VnY21WaGJDQnphV2R1
+ WVhSMWNtVSUzRCIBAQ==
+ S: t1 OK SASL authentication succeeded
+
+
+
+
+
+
+Mills, et al. Standards Track [Page 13]
+
+RFC 7628 SASL OAuth August 2015
+
+
+ As required by IMAP [RFC3501], the payloads are base64 encoded. The
+ decoded initial client response (with %x01 represented as ^A and
+ lines wrapped for readability) is:
+
+ n,a=user@example.com,^A
+ host=example.com^A
+ port=143^A
+ auth=OAuth realm="Example",
+ oauth_consumer_key="9djdj82h48djs9d2",
+ oauth_token="kkk9d7dh3k39sjv7",
+ oauth_signature_method="HMAC-SHA1",
+ oauth_timestamp="137131201",
+ oauth_nonce="7d8f3e4a",
+ oauth_signature="SSdtIGEgbGl0dGxlIHRlYSBwb3Qu"^A^A
+
+4.3. Failed Exchange
+
+ This IMAP example shows a failed exchange because of the empty
+ Authorization header, which is how a client can query for the needed
+ scope. Note that line breaks are inserted for readability.
+
+ S: * OK IMAP4rev1 Server Ready
+ C: t0 CAPABILITY
+ S: * CAPABILITY IMAP4rev1 AUTH=OAUTHBEARER SASL-IR
+ S: t0 OK Completed
+ C: t1 AUTHENTICATE OAUTHBEARER bixhPXVzZXJAZXhhbXBsZS5jb20sAW
+ hvc3Q9c2VydmVyLmV4YW1wbGUuY29tAXBvcnQ9MTQzAWF1dGg9AQE=
+ S: + eyJzdGF0dXMiOiJpbnZhbGlkX3Rva2VuIiwic2NvcGUiOiJleGFtcGxl
+ X3Njb3BlIiwib3BlbmlkLWNvbmZpZ3VyYXRpb24iOiJodHRwczovL2V4
+ YW1wbGUuY29tLy53ZWxsLWtub3duL29wZW5pZC1jb25maWd1cmF0aW9u
+ In0=
+ C: AQ==
+ S: t1 NO SASL authentication failed
+
+ The decoded initial client response is:
+
+ n,a=user@example.com,^Ahost=server.example.com^A
+ port=143^Aauth=^A^A
+
+ The decoded server error response is:
+
+ {
+ "status":"invalid_token",
+ "scope":"example_scope",
+ "openid-configuration":"https://example.com/.well-known/openid-config"
+ }
+
+
+
+
+
+Mills, et al. Standards Track [Page 14]
+
+RFC 7628 SASL OAuth August 2015
+
+
+ The client responds with the required dummy response; "AQ==" is the
+ base64 encoding of the ASCII value 0x01. The same exchange using the
+ IMAP-specific method of canceling an AUTHENTICATE command sends "*"
+ and is shown below.
+
+ S: * OK IMAP4rev1 Server Ready
+ C: t0 CAPABILITY
+ S: * CAPABILITY IMAP4rev1 AUTH=OAUTHBEARER SASL-IR IMAP4rev1
+ S: t0 OK Completed
+ C: t1 AUTHENTICATE OAUTHBEARER bixhPXVzZXJAZXhhbXBsZS5jb20sAW
+ hvc3Q9c2VydmVyLmV4YW1wbGUuY29tAXBvcnQ9MTQzAWF1dGg9AQE=
+ S: + eyJzdGF0dXMiOiJpbnZhbGlkX3Rva2VuIiwic2NvcGUiOiJleGFtcGxl
+ X3Njb3BlIiwib3BlbmlkLWNvbmZpZ3VyYXRpb24iOiJodHRwczovL2V4
+ YW1wbGUuY29tLy53ZWxsLWtub3duL29wZW5pZC1jb25maWd1cmF0aW9u
+ In0=
+ C: *
+ S: t1 NO SASL authentication failed
+
+4.4. SMTP Example of a Failed Negotiation
+
+ This example shows an authorization failure in an SMTP exchange. TLS
+ negotiation is not shown, but as noted above, it is required for the
+ use of bearer tokens.
+
+[connection begins]
+S: 220 mx.example.com ESMTP 12sm2095603fks.9
+C: EHLO sender.example.com
+S: 250-mx.example.com at your service,[172.31.135.47]
+S: 250-SIZE 35651584
+S: 250-8BITMIME
+S: 250-AUTH LOGIN PLAIN OAUTHBEARER
+S: 250-ENHANCEDSTATUSCODES
+S: 250 PIPELINING
+[Negotiate TLS...]
+C: AUTH OAUTHBEARER bix1c2VyPXNvbWV1c2VyQGV4YW1wbGUuY29tLAFhdXRoPUJlYXJl
+ ciB2RjlkZnQ0cW1UYzJOdmIzUmxja0JoZEhSaGRtbHpkR0V1WTI5dENnPT0BAQ==
+S: 334 eyJzdGF0dXMiOiJpbnZhbGlkX3Rva2VuIiwic2NoZW1lcyI6ImJlYXJlciBtYWMiL
+ CJzY29wZSI6Imh0dHBzOi8vbWFpbC5leGFtcGxlLmNvbS8ifQ==
+C: AQ==
+S: 535-5.7.1 Username and Password not accepted. Learn more at
+S: 535 5.7.1 http://support.example.com/mail/oauth
+[connection continues...]
+
+ The initial client response is:
+
+ n,user=someuser@example.com,^A
+ auth=Bearer vF9dft4qmTc2Nvb3RlckBhdHRhdmlzdGEuY29tCg==^A^A
+
+
+
+
+Mills, et al. Standards Track [Page 15]
+
+RFC 7628 SASL OAuth August 2015
+
+
+ The server returned an error message in the 334 SASL message; the
+ client responds with the required dummy response, and the server
+ finalizes the negotiation.
+
+ {
+ "status":"invalid_token",
+ "schemes":"bearer mac",
+ "scope":"https://mail.example.com/"
+ }
+
+5. Security Considerations
+
+ OAuth 1.0a and OAuth 2.0 allow for a variety of deployment scenarios,
+ and the security properties of these profiles vary. As shown in
+ Figure 1, this specification is aimed to be integrated into a larger
+ OAuth deployment. Application developers therefore need to
+ understand their security requirements based on a threat assessment
+ before selecting a specific SASL OAuth mechanism. For OAuth 2.0, a
+ detailed security document [RFC6819] provides guidance to select
+ those OAuth 2.0 components that help to mitigate threats for a given
+ deployment. For OAuth 1.0a, Section 4 of [RFC5849] provides guidance
+ specific to OAuth 1.0a.
+
+ This document specifies two SASL Mechanisms for OAuth and each comes
+ with different security properties.
+
+ OAUTHBEARER: This mechanism borrows from OAuth 2.0 bearer tokens
+ [RFC6750]. It relies on the application using TLS to protect the
+ OAuth 2.0 bearer token exchange; without TLS usage at the
+ application layer, this method is completely insecure.
+ Consequently, TLS MUST be provided by the application when
+ choosing this authentication mechanism.
+
+ OAUTH10A: This mechanism reuses OAuth 1.0a MAC tokens (using the
+ HMAC-SHA1 keyed message digest), as described in Section 3.4.2 of
+ [RFC5849]. To compute the keyed message digest in the same way as
+ in RFC 5839, this specification conveys additional parameters
+ between the client and the server. This SASL mechanism only
+ supports client authentication. If server-side authentication is
+ desirable, then it must be provided by the application underneath
+ the SASL layer. The use of TLS is strongly RECOMMENDED.
+
+
+
+
+
+
+
+
+
+
+Mills, et al. Standards Track [Page 16]
+
+RFC 7628 SASL OAuth August 2015
+
+
+ Additionally, the following aspects are worth pointing out:
+
+ An access token is not equivalent to the user's long term password.
+
+ Care has to be taken when these OAuth credentials are used for
+ actions like changing passwords (as it is possible with some
+ protocols, e.g., XMPP [RFC6120]). The resource server should
+ ensure that actions taken in the authenticated channel are
+ appropriate to the strength of the presented credential.
+
+ Lifetime of the application sessions.
+
+ It is possible that SASL will be used to authenticate a
+ connection, and the life of that connection may outlast the life
+ of the access token used to establish it. This is a common
+ problem in application protocols where connections are long lived
+ and not a problem with this mechanism, per se. Resource servers
+ may unilaterally disconnect clients in accordance with the
+ application protocol.
+
+ Access tokens have a lifetime.
+
+ Reducing the lifetime of an access token provides security
+ benefits, and OAuth 2.0 introduces refresh tokens to obtain new
+ access tokens on the fly without any need for human interaction.
+ Additionally, a previously obtained access token might be revoked
+ or rendered invalid at any time. The client MAY request a new
+ access token for each connection to a resource server, but it
+ SHOULD cache and reuse valid credentials.
+
+6. Internationalization Considerations
+
+ The identifier asserted by the OAuth authorization server about the
+ resource owner inside the access token may be displayed to a human.
+ For example, when SASL is used in the context of IMAP, the client may
+ assert the resource owner's email address to the IMAP server for
+ usage in an email-based application. The identifier may therefore
+ contain internationalized characters, and an application needs to
+ ensure that the mapping between the identifier provided by OAuth is
+ suitable for use with the application-layer protocol SASL is
+ incorporated into. An example of a SASL-compatible container is the
+ JSON Web Token (JWT) [RFC7519], which provides a standardized format
+ for exchanging authorization and identity information that supports
+ internationalized characters.
+
+
+
+
+
+
+
+Mills, et al. Standards Track [Page 17]
+
+RFC 7628 SASL OAuth August 2015
+
+
+7. IANA Considerations
+
+7.1. SASL Registration
+
+ The IANA has registered the following entry in the SASL Mechanisms
+ registry:
+
+ SASL mechanism name: OAUTHBEARER
+
+ Security Considerations: See this document
+
+ Published Specification: See this document
+
+ For further information: Contact the authors of this document.
+
+ Intended usage: COMMON
+
+ Owner/Change controller: the IESG
+
+ Note: None
+
+ The IANA has registered the following entry in the SASL Mechanisms
+ registry:
+
+ SASL mechanism name: OAUTH10A
+
+ Security Considerations: See this document
+
+ Published Specification: See this document
+
+ For further information: Contact the authors of this document.
+
+ Intended usage: COMMON
+
+ Owner/Change controller: the IESG
+
+ Note: None
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Mills, et al. Standards Track [Page 18]
+
+RFC 7628 SASL OAuth August 2015
+
+
+8. References
+
+8.1. Normative References
+
+ [OpenID.Core]
+ Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and
+ C. Mortimore, "OpenID Connect Core 1.0", November 2014,
+ <http://openid.net/specs/openid-connect-core-1_0.html>.
+
+ [OpenID.Discovery]
+ Sakimura, N., Bradley, J., Jones, M., and E. Jay, "OpenID
+ Connect Discovery 1.0", November 2014,
+ <http://openid.net/specs/
+ openid-connect-discovery-1_0.html>.
+
+ [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119,
+ DOI 10.17487/RFC2119, March 1997,
+ <http://www.rfc-editor.org/info/rfc2119>.
+
+ [RFC4422] Melnikov, A., Ed. and K. Zeilenga, Ed., "Simple
+ Authentication and Security Layer (SASL)", RFC 4422,
+ DOI 10.17487/RFC4422, June 2006,
+ <http://www.rfc-editor.org/info/rfc4422>.
+
+ [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
+ Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006,
+ <http://www.rfc-editor.org/info/rfc4648>.
+
+ [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
+ Specifications: ABNF", STD 68, RFC 5234,
+ DOI 10.17487/RFC5234, January 2008,
+ <http://www.rfc-editor.org/info/rfc5234>.
+
+ [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
+ (TLS) Protocol Version 1.2", RFC 5246,
+ DOI 10.17487/RFC5246, August 2008,
+ <http://www.rfc-editor.org/info/rfc5246>.
+
+ [RFC5801] Josefsson, S. and N. Williams, "Using Generic Security
+ Service Application Program Interface (GSS-API) Mechanisms
+ in Simple Authentication and Security Layer (SASL): The
+ GS2 Mechanism Family", RFC 5801, DOI 10.17487/RFC5801,
+ July 2010, <http://www.rfc-editor.org/info/rfc5801>.
+
+ [RFC5849] Hammer-Lahav, E., Ed., "The OAuth 1.0 Protocol", RFC 5849,
+ DOI 10.17487/RFC5849, April 2010,
+ <http://www.rfc-editor.org/info/rfc5849>.
+
+
+
+Mills, et al. Standards Track [Page 19]
+
+RFC 7628 SASL OAuth August 2015
+
+
+ [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
+ RFC 6749, DOI 10.17487/RFC6749, October 2012,
+ <http://www.rfc-editor.org/info/rfc6749>.
+
+ [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization
+ Framework: Bearer Token Usage", RFC 6750,
+ DOI 10.17487/RFC6750, October 2012,
+ <http://www.rfc-editor.org/info/rfc6750>.
+
+ [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
+ Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March
+ 2014, <http://www.rfc-editor.org/info/rfc7159>.
+
+ [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and
+ P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol",
+ RFC 7591, DOI 10.17487/RFC7591, July 2015,
+ <http://www.rfc-editor.org/info/rfc7591>.
+
+8.2. Informative References
+
+ [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
+ 4rev1", RFC 3501, DOI 10.17487/RFC3501, March 2003,
+ <http://www.rfc-editor.org/info/rfc3501>.
+
+ [RFC4959] Siemborski, R. and A. Gulbrandsen, "IMAP Extension for
+ Simple Authentication and Security Layer (SASL) Initial
+ Client Response", RFC 4959, DOI 10.17487/RFC4959,
+ September 2007, <http://www.rfc-editor.org/info/rfc4959>.
+
+ [RFC5321] Klensin, J., "Simple Mail Transfer Protocol", RFC 5321,
+ DOI 10.17487/RFC5321, October 2008,
+ <http://www.rfc-editor.org/info/rfc5321>.
+
+ [RFC6120] Saint-Andre, P., "Extensible Messaging and Presence
+ Protocol (XMPP): Core", RFC 6120, DOI 10.17487/RFC6120,
+ March 2011, <http://www.rfc-editor.org/info/rfc6120>.
+
+ [RFC6819] Lodderstedt, T., Ed., McGloin, M., and P. Hunt, "OAuth 2.0
+ Threat Model and Security Considerations", RFC 6819,
+ DOI 10.17487/RFC6819, January 2013,
+ <http://www.rfc-editor.org/info/rfc6819>.
+
+ [RFC7033] Jones, P., Salgueiro, G., Jones, M., and J. Smarr,
+ "WebFinger", RFC 7033, DOI 10.17487/RFC7033, September
+ 2013, <http://www.rfc-editor.org/info/rfc7033>.
+
+
+
+
+
+
+Mills, et al. Standards Track [Page 20]
+
+RFC 7628 SASL OAuth August 2015
+
+
+ [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
+ Protocol (HTTP/1.1): Message Syntax and Routing",
+ RFC 7230, DOI 10.17487/RFC7230, June 2014,
+ <http://www.rfc-editor.org/info/rfc7230>.
+
+ [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
+ (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015,
+ <http://www.rfc-editor.org/info/rfc7519>.
+
+Acknowledgements
+
+ The authors would like to thank the members of the KITTEN working
+ group and in addition and specifically: Simon Josefson, Torsten
+ Lodderstadt, Ryan Troll, Alexey Melnikov, Jeffrey Hutzelman, Nico
+ Williams, Matt Miller, and Benjamin Kaduk.
+
+ This document was produced under the chairmanship of Alexey Melnikov,
+ Tom Yu, Shawn Emery, Josh Howlett, Sam Hartman, Matthew Miller, and
+ Benjamin Kaduk. The supervising Area Director was Stephen Farrell.
+
+Authors' Addresses
+
+ William Mills
+ Microsoft
+
+ Email: wmills_92105@yahoo.com
+
+
+ Tim Showalter
+
+ Email: tjs@psaux.com
+
+
+ Hannes Tschofenig
+ ARM Ltd.
+ 110 Fulbourn Rd
+ Cambridge CB1 9NJ
+ United Kingdom
+
+ Email: Hannes.tschofenig@gmx.net
+ URI: http://www.tschofenig.priv.at
+
+
+
+
+
+
+
+
+
+
+Mills, et al. Standards Track [Page 21]
+
diff --git a/doc/rfcs/rfc7677.txt b/doc/rfcs/rfc7677.txt
new file mode 100644
index 0000000..d90ea86
--- /dev/null
+++ b/doc/rfcs/rfc7677.txt
@@ -0,0 +1,451 @@
+
+
+
+
+
+
+Internet Engineering Task Force (IETF) T. Hansen
+Request for Comments: 7677 AT&T Laboratories
+Updates: 5802 November 2015
+Category: Standards Track
+ISSN: 2070-1721
+
+
+ SCRAM-SHA-256 and SCRAM-SHA-256-PLUS
+ Simple Authentication and Security Layer (SASL) Mechanisms
+
+Abstract
+
+ This document registers the Simple Authentication and Security Layer
+ (SASL) mechanisms SCRAM-SHA-256 and SCRAM-SHA-256-PLUS, provides
+ guidance for secure implementation of the original SCRAM-SHA-1-PLUS
+ mechanism, and updates the SCRAM registration procedures of RFC 5802.
+
+Status of This Memo
+
+ This is an Internet Standards Track document.
+
+ This document is a product of the Internet Engineering Task Force
+ (IETF). It represents the consensus of the IETF community. It has
+ received public review and has been approved for publication by the
+ Internet Engineering Steering Group (IESG). Further information on
+ Internet Standards is available in Section 2 of RFC 5741.
+
+ Information about the current status of this document, any errata,
+ and how to provide feedback on it may be obtained at
+ http://www.rfc-editor.org/info/rfc7677.
+
+Copyright Notice
+
+ Copyright (c) 2015 IETF Trust and the persons identified as the
+ document authors. All rights reserved.
+
+ This document is subject to BCP 78 and the IETF Trust's Legal
+ Provisions Relating to IETF Documents
+ (http://trustee.ietf.org/license-info) in effect on the date of
+ publication of this document. Please review these documents
+ carefully, as they describe your rights and restrictions with respect
+ to this document. Code Components extracted from this document must
+ include Simplified BSD License text as described in Section 4.e of
+ the Trust Legal Provisions and are provided without warranty as
+ described in the Simplified BSD License.
+
+
+
+
+
+
+Hansen Standards Track [Page 1]
+
+RFC 7677 SASL SCRAM-SHA-256/SCRAM-SHA-256-PLUS November 2015
+
+
+Table of Contents
+
+ 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
+ 2. Key Word Definitions . . . . . . . . . . . . . . . . . . . . 2
+ 3. SCRAM-SHA-256 and SCRAM-SHA-256-PLUS . . . . . . . . . . . . 2
+ 4. Security Considerations . . . . . . . . . . . . . . . . . . . 3
+ 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 4
+ 5.1. Updates to SCRAM-* Registration . . . . . . . . . . . . . 4
+ 5.2. SASL-SCRAM Family Mechanisms Registration Procedure . . . 4
+ 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 6
+ 6.1. Normative References . . . . . . . . . . . . . . . . . . 6
+ 6.2. Informative References . . . . . . . . . . . . . . . . . 7
+ Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 7
+ Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 8
+
+1. Introduction
+
+ This document registers the SASL mechanisms SCRAM-SHA-256 and SCRAM-
+ SHA-256-PLUS. SHA-256 has stronger security properties than SHA-1,
+ and it is expected that SCRAM mechanisms based on it will have
+ greater predicted longevity than the SCRAM mechanisms based on SHA-1.
+
+ The registration form for the SCRAM family of algorithms is also
+ updated from [RFC5802].
+
+ After publication of [RFC5802], it was discovered that Transport
+ Layer Security (TLS) [RFC5246] does not have the expected properties
+ for the "tls-unique" channel binding to be secure [RFC7627].
+ Therefore, this document contains normative text that applies to both
+ the original SCRAM-SHA-1-PLUS and the newly introduced SCRAM-SHA-
+ 256-PLUS mechanism.
+
+2. Key Word Definitions
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+ document are to be interpreted as described in [RFC2119].
+
+3. SCRAM-SHA-256 and SCRAM-SHA-256-PLUS
+
+ The SCRAM-SHA-256 and SCRAM-SHA-256-PLUS SASL mechanisms are defined
+ in the same way that SCRAM-SHA-1 and SCRAM-SHA-1-PLUS are defined in
+ [RFC5802], except that the hash function for HMAC() and H() uses
+ SHA-256 instead of SHA-1 [RFC6234].
+
+ For the SCRAM-SHA-256 and SCRAM-SHA-256-PLUS SASL mechanisms, the
+ hash iteration-count announced by a server SHOULD be at least 4096.
+
+
+
+
+Hansen Standards Track [Page 2]
+
+RFC 7677 SASL SCRAM-SHA-256/SCRAM-SHA-256-PLUS November 2015
+
+
+ The GSS-API mechanism OID for SCRAM-SHA-256 is 1.3.6.1.5.5.18 (see
+ Section 5).
+
+ This is a simple example of a SCRAM-SHA-256 authentication exchange
+ when the client doesn't support channel bindings. The username
+ 'user' and password 'pencil' are being used.
+
+ C: n,,n=user,r=rOprNGfwEbeRWgbNEkqO
+
+ S: r=rOprNGfwEbeRWgbNEkqO%hvYDpWUa2RaTCAfuxFIlj)hNlF$k0,
+ s=W22ZaJ0SNY7soEsUEjb6gQ==,i=4096
+
+ C: c=biws,r=rOprNGfwEbeRWgbNEkqO%hvYDpWUa2RaTCAfuxFIlj)hNlF$k0,
+ p=dHzbZapWIk4jUhN+Ute9ytag9zjfMHgsqmmiz7AndVQ=
+
+ S: v=6rriTRBi23WpRR/wtup+mMhUZUn/dB5nLTJRsjl95G4=
+
+4. Security Considerations
+
+ The security considerations from [RFC5802] still apply.
+
+ To be secure, either SCRAM-SHA-256-PLUS and SCRAM-SHA-1-PLUS MUST be
+ used over a TLS channel that has had the session hash extension
+ [RFC7627] negotiated, or session resumption MUST NOT have been used.
+
+ See [RFC4270] and [RFC6194] for reasons to move from SHA-1 to a
+ strong security mechanism like SHA-256.
+
+ The strength of this mechanism is dependent in part on the hash
+ iteration-count, as denoted by "i" in [RFC5802]. As a rule of thumb,
+ the hash iteration-count should be such that a modern machine will
+ take 0.1 seconds to perform the complete algorithm; however, this is
+ unlikely to be practical on mobile devices and other relatively low-
+ performance systems. At the time this was written, the rule of thumb
+ gives around 15,000 iterations required; however, a hash iteration-
+ count of 4096 takes around 0.5 seconds on current mobile handsets.
+ This computational cost can be avoided by caching the ClientKey
+ (assuming the Salt and hash iteration-count is stable). Therefore,
+ the recommendation of this specification is that the hash iteration-
+ count SHOULD be at least 4096, but careful consideration ought to be
+ given to using a significantly higher value, particularly where
+ mobile use is less important.
+
+
+
+
+
+
+
+
+
+Hansen Standards Track [Page 3]
+
+RFC 7677 SASL SCRAM-SHA-256/SCRAM-SHA-256-PLUS November 2015
+
+
+5. IANA Considerations
+
+5.1. Updates to SCRAM-* Registration
+
+ The IANA registry for SCRAM-* (the SCRAM family of SASL mechanisms)
+ in the SASL mechanism registry ([RFC4422]) has been updated as
+ follows. The email address for reviews has been updated, and the
+ note at the end changed.
+
+ To: iana@iana.org
+ Subject: Registration of a new SASL family SCRAM
+
+ SASL mechanism name (or prefix for the family): SCRAM-*
+ Security considerations: Section 7 of [RFC5802]
+ Published specification (optional, recommended): RFC 7677
+ Person & email address to contact for further information:
+ IETF KITTEN WG <kitten@ietf.org>
+ Intended usage: COMMON
+ Owner/Change controller: IESG <iesg@ietf.org>
+ Note: Members of this family MUST be explicitly registered using
+ the "IETF Review" [RFC5226] registration procedure. Reviews
+ MUST be requested on the KITTEN mailing list kitten@ietf.org
+ (or a successor designated by the responsible Security AD).
+
+ Note to future SCRAM-mechanism designers: each new SASL SCRAM
+ mechanism MUST be explicitly registered with IANA within the SASL
+ SCRAM Family Mechanisms registry.
+
+5.2. SASL-SCRAM Family Mechanisms Registration Procedure
+
+ A new IANA registry has been added for members of the SCRAM family of
+ SASL mechanisms, named "SASL SCRAM Family Mechanisms". It adds two
+ new fields to the existing SCRAM mechanism registry: Minimum
+ iteration-count and Associated OID. Below is the template for
+ registration of a new SASL family SCRAM. (Note that the string
+ "TBD-BY-IANA" should be left as is, so that it may be filled in at
+ registration time by IANA.)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Hansen Standards Track [Page 4]
+
+RFC 7677 SASL SCRAM-SHA-256/SCRAM-SHA-256-PLUS November 2015
+
+
+ To: iana@iana.org
+ Subject: Registration of a new SASL SCRAM family mechanism
+
+ SASL mechanism name (or prefix for the family): SCRAM-<NAME>
+ Security considerations: Section 7 of [RFC5802]
+ Published specification (optional, recommended): RFC 7677
+ Minimum iteration-count: The minimum hash iteration-count that
+ servers SHOULD announce
+ Associated OID: TBD-BY-IANA
+ Person & email address to contact for further information:
+ IETF KITTEN WG <kitten@ietf.org>
+ Intended usage: COMMON
+ Owner/Change controller: IESG <iesg@ietf.org>
+
+ Note: Members of this family MUST be explicitly registered using
+ the "IETF Review" [RFC5226] registration procedure. Reviews MUST
+ be requested on the KITTEN mailing list kitten@ietf.org (or a
+ successor designated by the responsible Security Area Director).
+
+ Note: At publication of a new SASL SCRAM Family Mechanism, IANA
+ SHOULD assign a GSS-API mechanism OID for this mechanism from the
+ iso.org.dod.internet.security.mechanisms prefix (see the "SMI
+ Security for Mechanism Codes" registry) and fill in the value for
+ "TBD-BY-IANA" above. Only one OID needs to be assigned for a
+ SCRAM-<NAME> and SCRAM-<NAME>-PLUS pair. The same OID should be
+ assigned to both entries in the registry.
+
+ Note to future SASL SCRAM mechanism designers: each new SASL SCRAM
+ mechanism MUST be explicitly registered with IANA and MUST comply
+ with the SCRAM-mechanism naming convention defined in Section 4 of
+ [RFC5802].
+
+ The existing entries for SASL SCRAM-SHA-1 and SCRAM-SHA-1-PLUS have
+ been moved from the existing SASL mechanism registry to the "SASL
+ SCRAM Family Mechanisms" registry. At that time, the following
+ values were added:
+
+ Minimum iteration-count: 4096
+ OID: 1.3.6.1.5.5.14 (from [RFC5802])
+
+
+
+
+
+
+
+
+
+
+
+
+Hansen Standards Track [Page 5]
+
+RFC 7677 SASL SCRAM-SHA-256/SCRAM-SHA-256-PLUS November 2015
+
+
+ The following new SASL SCRAM mechanisms have been added to the "SASL
+ SCRAM Family Mechanisms" registry:
+
+ To: iana@iana.org
+ Subject: Registration of a new SASL SCRAM Family mechanism
+ SCRAM-SHA-256
+
+ SASL mechanism name (or prefix for the family): SCRAM-SHA-256
+ Security considerations: Section 4 of RFC 7677
+ Published specification (optional, recommended): RFC 7677
+ Minimum iteration-count: 4096
+ OID: 1.3.6.1.5.5.18
+ Person & email address to contact for further information:
+ IETF KITTEN WG <kitten@ietf.org>
+ Intended usage: COMMON
+ Owner/Change controller: IESG <iesg@ietf.org>
+ Note:
+
+ To: iana@iana.org
+ Subject: Registration of a new SASL SCRAM Family mechanism
+ SCRAM-SHA-256-PLUS
+
+ SASL mechanism name (or prefix for the family): SCRAM-SHA-256-PLUS
+ Security considerations: Section 4 of RFC 7677
+ Published specification (optional, recommended): RFC 7677
+ Minimum iteration-count: 4096
+ OID: 1.3.6.1.5.5.18
+ Person & email address to contact for further information:
+ IETF KITTEN WG <kitten@ietf.org>
+ Intended usage: COMMON
+ Owner/Change controller: IESG <iesg@ietf.org>
+ Note:
+
+6. References
+
+6.1. Normative References
+
+ [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119,
+ DOI 10.17487/RFC2119, March 1997,
+ <http://www.rfc-editor.org/info/rfc2119>.
+
+ [RFC4422] Melnikov, A., Ed. and K. Zeilenga, Ed., "Simple
+ Authentication and Security Layer (SASL)", RFC 4422,
+ DOI 10.17487/RFC4422, June 2006,
+ <http://www.rfc-editor.org/info/rfc4422>.
+
+
+
+
+
+Hansen Standards Track [Page 6]
+
+RFC 7677 SASL SCRAM-SHA-256/SCRAM-SHA-256-PLUS November 2015
+
+
+ [RFC5802] Newman, C., Menon-Sen, A., Melnikov, A., and N. Williams,
+ "Salted Challenge Response Authentication Mechanism
+ (SCRAM) SASL and GSS-API Mechanisms", RFC 5802,
+ DOI 10.17487/RFC5802, July 2010,
+ <http://www.rfc-editor.org/info/rfc5802>.
+
+ [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms
+ (SHA and SHA-based HMAC and HKDF)", RFC 6234,
+ DOI 10.17487/RFC6234, May 2011,
+ <http://www.rfc-editor.org/info/rfc6234>.
+
+ [RFC7627] Bhargavan, K., Ed., Delignat-Lavaud, A., Pironti, A.,
+ Langley, A., and M. Ray, "Transport Layer Security (TLS)
+ Session Hash and Extended Master Secret Extension",
+ RFC 7627, DOI 10.17487/RFC7627, September 2015,
+ <http://www.rfc-editor.org/info/rfc7627>.
+
+6.2. Informative References
+
+ [RFC4270] Hoffman, P. and B. Schneier, "Attacks on Cryptographic
+ Hashes in Internet Protocols", RFC 4270,
+ DOI 10.17487/RFC4270, November 2005,
+ <http://www.rfc-editor.org/info/rfc4270>.
+
+ [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
+ IANA Considerations Section in RFCs", BCP 26, RFC 5226,
+ DOI 10.17487/RFC5226, May 2008,
+ <http://www.rfc-editor.org/info/rfc5226>.
+
+ [RFC6194] Polk, T., Chen, L., Turner, S., and P. Hoffman, "Security
+ Considerations for the SHA-0 and SHA-1 Message-Digest
+ Algorithms", RFC 6194, DOI 10.17487/RFC6194, March 2011,
+ <http://www.rfc-editor.org/info/rfc6194>.
+
+ [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
+ (TLS) Protocol Version 1.2", RFC 5246,
+ DOI 10.17487/RFC5246, August 2008,
+ <http://www.rfc-editor.org/info/rfc5246>.
+
+Acknowledgements
+
+ This document benefited from discussions on the KITTEN WG mailing
+ list. The author would like to specially thank Russ Allbery, Dave
+ Cridland, Shawn Emery, Stephen Farrell, Simon Josefsson, Pearl Liang,
+ Alexey Melnikov, Peter Saint-Andre, Robert Sparks, Martin Thompson,
+ and Nico Williams for their comments on this topic.
+
+
+
+
+
+Hansen Standards Track [Page 7]
+
+RFC 7677 SASL SCRAM-SHA-256/SCRAM-SHA-256-PLUS November 2015
+
+
+Author's Address
+
+ Tony Hansen
+ AT&T Laboratories
+ 200 Laurel Ave. South
+ Middletown, NJ 07748
+ United States
+
+ Email: tony+scramsha256@maillennium.att.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Hansen Standards Track [Page 8]
+
generated by cgit v1.2.3 (git 2.50.1) at 2025-12-12 22:05:08 +0000