113 index
@@ -0,0 +1,113 @@
%pragma page-title("IRCv3 Working Group");

# Atheme.org IRCv3 Working Group

The IRCv3 Working Group is a group of IRC client and server software authors working to
enhance, improve, maintain and standardize the current IRC protocol. Logically, it is
an activity of [atheme.org](http://atheme.org) but represents the interests of many parties.

Other stakeholders in the IRC protocol, such as IRC networks and IRC network operators are
invited to participate. If you would like to discuss IRCv3 standardization efforts over
IRC itself, you may find us at `irc.atheme.org #ircv3`.

The IRCv3 working group is incubated by [atheme.org](http://www.atheme.org).

## Participants

The IRCv3 working group contains participants from the following organizations (and more):

* [atheme.org](http://www.atheme.org)
* [EsperNet](http://www.esper.net)
* [freenode](http://www.freenode.net)
* [InspIRCd](http://inspircd.github.com)
* [IRCCloud](http://www.irccloud.com)
* [Mibbit](http://www.mibbit.com)
* [mIRC](http://www.mirc.co.uk)
* [Nefarious IRCu](http://evilnet.sourceforge.net)
* [QuakeNet](http://www.quakenet.org)
* [Undernet](http://www.undernet.org)
* [UnrealIRCd](http://www.unrealircd.org)

To participate, contribute to our specifications and extensions registry on [GitHub](http://github.com/atheme/ircv3-specifications).

## Specifications

Right now the IRCv3 specification is distributed as a series of extension specifications to
IRC protocol version 2.7, also known as RFC1459. To understand the basis of the IRC version 3
protocol, please read RFC1459 followed by the extension specifications. A unified specification
draft is being worked on which will replace RFC1459 at a later date.

### Base Extensions

The following extensions comprise the core functionality of the IRC version 3.1 client protocol.

* [IRC Version 3.1: Capability Negotiation](/specification/capability-negotiation-3.1)

* [IRC Version 3.1: `multi-prefix` Extension](/extensions/multi-prefix-3.1)

* [IRC Version 3.1: `sasl` Extension](/extensions/sasl-3.1)

### Optional Extensions

The following extensions comprise the extended functionality of the IRC version 3.1 client protocol.

* [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: `tls` Extension](/extensions/tls-3.1)

## Next Version

There is no work presently being done as 3.1 has been released. Submit new extensions for
consideration for 3.2!

## Extension Registry

The IRCv3 Working Group maintains a registry of "work-in-progress" extensions that have not yet
been accepted as part of an IRC protocol version. IRC software vendors may provide additional
extensions that have not yet been added to this registry. We recommend that extensions not in
the registry use appropriate namespacing as described in the capability negotiation specification.

A [list of extensions](/extensions/index) documented in the extension registry is available.

To submit an extension to the extension registry, please contact us via IRC for now. Extension
specifications should be submitted in Markdown format.

## IRCv3.1 Compliant Software

This software is compliant natively; other software may be compliant with extensions.

### Servers

* [charybdis](http://www.stack.nl/~jilles/irc/#charybdis) 3.0 or later
* [InspIRCd](http://inspircd.github.com) 1.2 or later
* [shadowircd](http://www.shadowircd.net/) 6.0 or later
* [UnrealIRCd](http://www.unrealircd.org/) 3.2.10 or later

### Desktop Clients

* [Colloquy](http://www.colloquy.info) 2.4 or later
* [Konversation](http://konversation.kde.org/) 1.5 or later
* [KVirc](http://www.kvirc.org) 4.0 or later
* [Limechat](http://www.limechat.net/mac/) 2.23 or later
* [Quassel](http://www.quassel-irc.org) 0.6.1 or later
* [Textual](http://www.codeux-software.com/textual) 2.1 or later

### Web Clients

* [Iris](http://www.atheme.net/download-iris.php)
* [Mibbit](http://www.mibbit.com)

### Mobile Clients

* [AndChat](http://www.andchat.com/) 1.3.8 or later
* [Android IRC](http://www.countercultured.net/android/) 1.8.21 or later
* [AndroIRC](http://www.androirc.com/) 2.0 or later
* [Colloquy](http://www.colloquy.info)
* [IRC7](http://www.softwaremk.org/irc/) 1.6 or later
* [Limechat](http://www.limechat.net/iphone/) 2.10 or later
* [YAAIC](http://www.yaaic.org/) 0.9 or later

@@ -0,0 +1,189 @@
# IRCv3 Client Capability Negotiation

Copyright (c) 2004-2012 Kevin L. Mitchell <klmitch@mit.edu>.

Copyright (c) 2004-2012 Perry Lorier <isomer@undernet.org>.

Copyright (c) 2004-2012 Lee Hardy <lee@leeh.co.uk>.

Copyright (c) 2009-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.

## What IRCv3 Client Capability Negotiation attempts to solve

IRC is an asynchronous protocol, which means that IRC clients may issue additional
IRC commands while a command is being processed. Additionally, there is no guarantee
of a specific kind of banner being issued upon connection. Some servers also do not
complain about unknown commands during registration, which means that a client cannot
reliably do passive implementation discovery at registration time.

If a client had to wait for a banner message, it would be incompatible with previous
versions of the IRC client protocol.

The solution to these problems is to extend the registration process with actual
capability negotiation. If the server supports capability negotiation, the registration
process will be suspended until negotiation is completed. If the server does not support
capability negotiation, then registration will complete immediately, and the client will
not use any IRCv3 capabilities.

## The CAP command

The client capability negotiation extension is implemented by the addition of one command
with several subcommands. The command added is named `CAP`. `CAP` takes a single
required subcommand, optionally followed by a single parameter of space-seperated capability
identifiers. Each capability in the list may be preceded by a capability modifier.

The subcommands for `CAP` are: `LS`, `LIST`, `REQ`, `ACK`, `NAK`, `CLEAR` and `END`.

The `LS`, `LIST`, `REQ`, `ACK` and `NAK` subcommands may be followed by a single parameter
containing a space-seperated list of capabilities. If more than one capability is named,
the RFC1459 designated sentinel (`:`) for a multi-parameter argument must be present.

If a client sends a subcommand which is not in the list above or otherwise issues an
invalid command, then numeric 410 (ERR_INVALIDCAPCMD) should be sent. The first parameter
after the client identifier (usually nickname) should be the commandname; the second parameter
should be a human-readable description of the error.

Replies from the server must contain the client identifier name or asterisk if one is not yet
available.

### The CAP LS subcommand

The LS subcommand is used to list the capabilities supported by the server. The client
should send an LS subcommand with no other arguments to solicit a list of all capabilities.

If a client issues an LS subcommand, registration must be suspended until an END subcommand
is received.

Example:

```
Client: CAP LS
Server: CAP * LS :multi-prefix sasl
```

### The CAP LIST subcommand

The LIST subcommand is used to list the capabilities associated with the active connection.
The client should send a LIST subcommand with no other arguments to solicit a list of
active capabilities.

If no capabilities are active, an empty parameter must be sent.

Example:

```
Client: CAP LIST
Server: CAP * LIST :multi-prefix
```

### The CAP REQ subcommand

The REQ subcommand is used to request a change in capabilities associated with the active
connection. It's sole parameter must be a list of space-separated capability identifiers.
Each capability identifier may be prefixed with a dash (`-`) to designate that the capability
should be disabled.

The capability identifier set must be accepted as a whole, or rejected entirely.

If a client issues a REQ subcommand, registration must be suspended until an END subcommand
is received.

Example:

```
Client: CAP REQ :multi-prefix sasl
Server: CAP * ACK :multi-prefix sasl
```

### The CAP ACK subcommand

The ACK subcommand has three uses:

* the server sends it to acknowledge a REQ subcommand;
* the server sends it to acknowledge a CLEAR subcommand;
* the client sends it to acknowledge capabilities which require client-side acknowledgement.

If an ACK reply originating from the server is spread across multiple lines, a client MUST NOT
change capabilities until the last ACK of the set is received. Equally, a server MUST NOT change
the capabilities of the client until the last ACK of the set has been sent.

In the first usage, acknowledging a REQ subcommand, the ACK subcommand has a single parameter
consisting of a space separated list of capability names, which may optionally be preceded with
one or more modifiers.

The second usage, acknowledging a CLEAR subcommand, is similar to the first usage. When a CLEAR
subcommand is issued, all non-"sticky" capabilities are disabled, and a set of ACK subcommands
will be generated by the server with the disable modifier preceding each capability.

The third usage is when, in the preceding two cases, some capability names have been preceded
with the ack modifier. ACK in this case is used to fully enable or disable the capability. Clients
MUST NOT issue an ACK subcommand for any capability not marked with the ack modifier in a
server-generated ACK subcommand.

### The CAP NAK subcommand

The NAK subcommand designates that the requested capability change was rejected. The server
MUST NOT make any change to any capabilities if it replies with a NAK subcommand.

The argument of the NAK subcommand MUST consist of at least the first 100 characters of the
capability list in the REQ subcommand which triggered the NAK.

### The CAP CLEAR subcommand

The CLEAR subcommand requests that the server clear the capability set for the client.
The server MUST respond with a set of ACK subcommands indicating the capabilities being
deactivated.

### The CAP END subcommand

The END subcommand signals to the server that capability negotiation is complete and requests
that the server continue with client registration. If the client is already registered, this
command MUST be ignored by the server.

Clients that support capabilities but do not wish to enter negotiation SHOULD send CAP END
upon connection to the server.

## Capability Negotiation Procedure

Clients should take one of the following actions upon connection:

* issue a CAP LS subcommand with an empty capability list to discover available capabilities;
* issue a CAP REQ subcommand to request a particular set of capabilities blindly;
* issue a CAP END subcommand to immediately end capability negotiation.

While a client is permitted to not issue any CAP commands upon connection, this may have
unintentional side effects (such as forcing a downgrade to RFC1459 client protocol).

Once capability negotiation is completed with the END subcommand, registration should
continue as normal.

## Rules for naming capabilities

There are two capability namespaces:

* Vendor-Specific: Names which contain a period character (`.`) designate a vendor-specific
capability namespace. These names are prefixed by a valid DNS domain name, and slash.
For example: `znc.in/server-time`. Vendor-Specific capabilities should be submitted to the
IRCv3 working group for consideration.

* Standardized: Names for which a corresponding document sits in the IRCv3 Extension Registry.
Names in the IRCv3 Extension Registry are reserved for your capability.

## Capability Modifiers

There are three capability modifiers specified by this standard. If a capability modifier is
to be used, it MUST directly procede the capability identifier.

The capability modifiers are:

* `-` modifier (disable): this modifier indicates that the capability is being disabled.

* `~` modifier (ack): this modifier indicates the client must acknowledge the capability using
an ACK subcommand.

* `=` modifier (sticky): this modifier indicates that the specified capability may not be
disabled.