initial commit

extensions/account-notify-3.1

@@ -0,0 +1,57 @@
+account-notify client capability specification
+----------------------------------------------
+
+Copyright (c) 2010 William Pitcock <nenolod@atheme.org>.
+
+Unlimited redistribution and modification of this document is allowed
+provided that the above copyright notice and this permission notice
+remains in tact.
+
+The account-notify client capability allows a client to be notified
+when another client's accountname changes.  This capability MUST be
+referred to as 'account-notify' at capability negotiation time.
+
+When enabled, clients will get the ACCOUNT message to designate the
+accountname changes for clients on common channels with them.
+
+The ACCOUNT message is one of the following:
+
+   :nick!user@host ACCOUNT accountname
+
+This message represents that the user identified by nick!user@host has
+logged into a new account.  The last parameter is the display name of
+that account.
+
+   :nick!user@host ACCOUNT *
+
+This message represents that the user identified by nick!user@host has
+logged out of their account.  As the last parameter is an asterisk, this
+means that an asterisk is not a valid account name (which it is not in P10
+or TS6 or ESVID).
+
+In order to take full advantage of the ACCOUNT message, WHOX must be
+supported by the ircd.  In this case, the appropriate strategy to ensuring
+you always have the accountname to display is to do the following:
+
+1) Enable the account-notify capability at capability negotiation time during
+   the login handshake.
+
+2) When joining a channel, query the channel using WHO and ensure that you
+   include the 'a' format token in your WHOX token request.  When you get
+   a reply, do appropriate caching.
+
+3) If the extended-join capability is available, enable it at client capability
+   negotiation time during the login handshake, and then set the accountname
+   based on what is sent in the extended JOIN command.
+
+   Otherwise, if extended-join is unavailable:
+   When new users join a channel that your client does not know the accountname
+   for yet, do a WHO query against that client, again including the 'a' format
+   token in your WHOX token request field.  When you get a reply, do appropriate
+   caching.
+
+4) In the event of a netsplit, the client should query the channel again using
+   WHO with the 'a' format token in the WHOX request field.
+
+5) When the client receives an ACCOUNT message, update the accountname for the
+   client in question in your accountname cache.

extensions/away-notify-3.1

@@ -0,0 +1,43 @@
+away-notify client capability specification
+----------------------------------------------
+
+Copyright (c) 2012 Keith Buck <mr_flea@esper.net>.
+
+Unlimited redistribution and modification of this document is allowed
+provided that the above copyright notice and this permission notice
+remains in tact.
+
+The away-notify client capability allows a client to specify that it
+would like to be notified when users are marked/unmarked as away. This
+capability is referred to as 'away-notify' at capability negotiation
+time.
+
+This capability is designed to replace polling of WHO as a more
+efficient method of tracking the away state of users in a channel. The
+away-notify capability both conserves bandwidth as WHO requests are
+not continually sent and allows the client to be notified immediately
+upon a user setting or removing their away state (as opposed to when
+WHO is next polled).
+
+When this capability is enabled, clients will be sent an AWAY message
+when a user sharing a channel with them sets or removes their away
+state, as well as when a user joins and has an away message set.
+(Note that AWAY will not be sent for joining users with no away
+message set.)
+
+The format of the AWAY message is as follows:
+
+   :nick!user@host AWAY [:message]
+
+If the message is present, the user (specified by the nick!user@host
+mask) is going away.  If the message is not present, the user is
+removing their away message/state.
+
+To fully track the away state of users, clients should:
+
+1) Enable the away-notify capability at negotiation time.
+
+2) Execute WHO when joining a channel to capture the current away
+   state of all users in that channel.
+
+3) Update state appropriately upon receiving an AWAY message.

extensions/extended-join-3.1

@@ -0,0 +1,36 @@
+extended-join client capability specification
+---------------------------------------------
+
+Copyright (c) 2011 Kiyoshi Aman <kiyoshi.aman@gmail.com>
+
+Unlimited redistribution and modification of this document is allowed
+provided that the above copyright notice and this permission notice
+remains intact.
+
+The extended-join capability extends the JOIN message to include the
+account name, or a placeholder if the user hasn't identified with
+services. This capability MUST be referred to as 'extended-join' at
+capability negotiation time.
+
+When enabled, the JOIN message will designate the account name of the
+user when he/she joins a channel.
+
+The JOIN message is one of the following:
+
+    :nick!user@host JOIN #channelname accountname :Real Name
+
+This message represents that the user identified by nick!user@host has
+logged in to an acount prior to channel ingress. The penultimate
+parameter is the display name of that account. The last parameter is
+the user's GECOS.
+
+    :nick!user@host JOIN #channelname * :Real Name
+
+This message represents that the user has not logged in to an account
+prior to channel ingress. As the penultimate parameter is an asterisk,
+this means that an asterisk is not a valid account name (which it is
+not in P10 or TS6 or ESVID).
+
+Please see the documentation in account-notify.txt for how to take
+advantage of this capability.
+

extensions/index

@@ -0,0 +1,13 @@
+## Extensions list
+
+ * [IRC Version 3.1: `account-notify` Extension](/extensions/account-notify-3.1)
+
+ * [IRC Version 3.1: `away-notify` Extension](/extensions/away-notify-3.1)
+
+ * [IRC Version 3.1: `extended-join` Extension](/extensions/extended-join-3.1)
+
+ * [IRC Version 3.1: `multi-prefix` Extension](/extensions/multi-prefix-3.1)
+
+ * [IRC Version 3.1: `sasl` Extension](/extensions/sasl-3.1)
+
+ * [IRC Version 3.1: `tls` Extension](/extensions/tls-3.1)

extensions/multi-prefix-3.1

@@ -0,0 +1,16 @@
+multi-prefix Client Capability Extension
+----------------------------------------
+
+Copyright (c) 2012 William Pitcock <nenolod@atheme.org>.
+
+Unlimited redistribution and modification of this document is allowed provided
+that the above copyright notice and this permission notice remains in tact.
+
+The multi-prefix Client Capability
+----------------------------------
+
+When requested, the multi-prefix client capability will cause the IRC server to send
+all possible prefixes which apply to a user in NAMES and WHO output.
+
+These prefixes MUST be in order of 'rank', from highest to lowest.
+

extensions/sasl-3.1

@@ -0,0 +1,110 @@
+# SASL authentication
+
+This document describes the client protocol for SASL authentication, as
+implemented in charybdis and atheme.
+
+SASL authentication relies on the
+[CAP client capability framework](/specifications/capability-negotiation-3.1).
+
+Support for SASL authentication is indicated with the "sasl" capability.
+The client MUST enable the sasl capability before using the AUTHENTICATE
+command defined by this specification.
+
+## The AUTHENTICATE command
+
+The AUTHENTICATE command MUST be used before registration is complete and
+with the sasl capability enabled. To enforce the former, it is RECOMMENDED
+to only send CAP END when the SASL exchange is completed or needs to be
+aborted. Clients SHOULD be prepared for timeouts at all times during the SASL
+authentication.
+
+There are two forms of the AUTHENTICATE command: initial client message and
+later messages.
+
+The initial client message specifies the SASL mechanism to be used. (When this
+is received, the IRCD will attempt to establish an association with a SASL
+agent.) If this fails, a 904 numeric will be sent and the session state remains
+unchanged; the client MAY try another mechanism. Otherwise, the server sends
+a set of regular AUTHENTICATE messages with the initial server response.
+
+`initial-authenticate = "AUTHENTICATE" SP mechanism CRLF`
+
+A set of regular AUTHENTICATE messages transmits a response from client to
+server or vice versa. The server MAY intersperse other IRC protocol messages
+between the AUTHENTICATE messages of a set. The "+" form is used for an empty
+response. The server MAY place a limit on the total length of a response.
+
+```regular-authenticate-set = *("AUTHENTICATE" SP 400BASE64 CRLF)
+	"AUTHENTICATE" SP (1*399BASE64 / "+") CRLF```
+
+The client can abort an authentication by sending an asterisk as the data.
+The server will send a 904 numeric.
+
+`authenticate-abort = "AUTHENTICATE" SP "*" CRLF`
+
+If authentication fails, a 904 or 905 numeric will be sent and the
+client MAY retry from the AUTHENTICATE <mechanism> command.
+If authentication is successful, a 900 and 903 numeric will be sent.
+
+If the client attempts to issue the AUTHENTICATE command after already
+authenticating successfully, the server MUST reject it with a 907 numeric.
+
+If the client completes registration (with CAP END, NICK, USER and any other
+necessary messages) while the SASL authentication is still in progress, the
+server SHOULD abort it and send a 906 numeric, then register the client
+without authentication.
+
+This document does not specify use of the AUTHENTICATE command in
+registered (person) state.
+
+Example protocol exchange
+
+C: indicates lines sent by the client, S: indicates lines sent by the server.
+
+The client is using the PLAIN SASL mechanism with authentication identity
+jilles, authorization identity jilles and password sesame.
+
+<pre>
+C: CAP REQ :sasl
+C: NICK jilles
+C: USER jilles cheetah.stack.nl 1 :Jilles Tjoelker
+S: NOTICE AUTH :*** Processing connection to jaguar.test
+S: NOTICE AUTH :*** Looking up your hostname...
+S: NOTICE AUTH :*** Checking Ident
+S: NOTICE AUTH :*** No Ident response
+S: NOTICE AUTH :*** Found your hostname
+S: :jaguar.test CAP jilles ACK :sasl 
+C: AUTHENTICATE PLAIN
+S: AUTHENTICATE +
+C: AUTHENTICATE amlsbGVzAGppbGxlcwBzZXNhbWU=
+S: :jaguar.test 900 jilles jilles!jilles@localhost.stack.nl jilles :You are now logged in as jilles.
+S: :jaguar.test 903 jilles :SASL authentication successful
+C: CAP END
+S: :jaguar.test 001 jilles :Welcome to the jillestest Internet Relay Chat Network jilles
+(usual welcome messages)
+</pre>
+
+Alternatively the client could request the list of capabilities and enable
+an additional capability.
+
+<pre>
+C: CAP LS
+C: NICK jilles
+C: USER jilles cheetah.stack.nl 1 :Jilles Tjoelker
+S: NOTICE AUTH :*** Processing connection to jaguar.test
+S: NOTICE AUTH :*** Looking up your hostname...
+S: NOTICE AUTH :*** Checking Ident
+S: NOTICE AUTH :*** No Ident response
+S: NOTICE AUTH :*** Found your hostname
+S: :jaguar.test CAP * LS :multi-prefix sasl
+C: CAP REQ :multi-prefix sasl
+S: :jaguar.test CAP jilles ACK :multi-prefix sasl 
+C: AUTHENTICATE PLAIN
+S: AUTHENTICATE +
+C: AUTHENTICATE amlsbGVzAGppbGxlcwBzZXNhbWU=
+S: :jaguar.test 900 jilles jilles!jilles@localhost.stack.nl jilles :You are now logged in as jilles.
+S: :jaguar.test 903 jilles :SASL authentication successful
+C: CAP END
+S: :jaguar.test 001 jilles :Welcome to the jillestest Internet Relay Chat Network jilles
+(usual welcome messages)
+</pre>

extensions/tls-3.1

@@ -0,0 +1,23 @@
+# tls Client Capability Extension
+
+Copyright (c) 2012 William Pitcock <nenolod@atheme.org>.
+
+Unlimited redistribution and modification of this document is allowed provided
+that the above copyright notice and this permission notice remains in tact.
+
+## The tls Client Capability
+
+The tls client capability indicates that the server supports the STARTTLS command.
+
+It is worth noting here that a client may request the tls capability with CAP REQ,
+but this won't affect that client's ability to later send the STARTTLS command.
+The STARTTLS command will always operate on servers which advertise the capability
+regardless of if the client requests the capability or not. 
+
+To use STARTTLS a client simply sends the STARTTLS command to the server before the
+client registers with the server using the NICK and USER commands, the server then
+sends numeric 670 (RPL_STARTTLS), and the client initiates a SSL/TLS handshake.
+
+If there is an error with setting up TLS on the server side, the server must send
+numeric 691 (ERR_STARTTLS) containing a human-readable description of the error as
+it's parameter.