Log in | Back to darenet.org

DareNET P10

The goal of this document is to be a complete reference of DareNET's extensions to the existing implementation of the P10 protocol. It is based on the P10 protocol and interface specification as of ircu 2.10.11, raw data sent by ircu and the ircu source code.

Terminology

Below is some of the terminology used within this document.

Term Definition
Byte A unit of 8 bits of data.
Character One byte, notated as a decimal number in the range of 0-255, or a printable ASCII character (example: 65, 'A').
Char Character.
String A sequence of bytes.
Parser The implementation which receives and processes the stream.
Generate Sending data which has not been received, as opposed to passing data on which has been received.
TS TimeStamp. An ASCII decimal notation of a date+time (number of seconds, not counting leap seconds, since Jan-1-1970, 00:00:00 UTC.
Nick Refers to a client's nickname.
Numnick Refers to a client's numeric nickname.

Keywords

MUST - This word, or the terms "REQUIRED" or "SHALL", mean that the definition is an absolute requirement of the specification.

MUST NOT - This phrase, or the phrase "SHALL NOT" or "DISALLOWED", mean that the definition is an absolute prohibition of the specification.

SHOULD - This word, or the adjective "RECOMMENDED", mean that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course.

SHOULD NOT - This phrase, or the phrase "NOT RECOMMENDED" mean that there may exist valid reasons in particular circumstances when the particular behavior is acceptable or even useful, but the full implications should be understood and the case carefully weighed before implementing any behavior described with this label.

Hexadecimals

Hexadecimal numbers within this document use the pascal notation: a $ prefix. The number of hex digits (nibbles) represents the size of the data, for example, a byte can be anything between $00 and $ff.

Stream of Data, Lines, Line Termination

P10 is a "text" protocol, that is, it is human readable/writable.

  • CR: Carriage Return. Character 13.
  • LF: Line feed. Chracter 10.
  • CRLF: <CRLF>
  • NULL: Chracter 0.
  • EOL: End of Line (line termination).

So the definition of the stream would be as follows:
<line><EOL><line><EOL> .... <garbage>

Line termination (EOL)

When sending, line termination may be either <CRLF> or <LF>. It must not be anything else.

The parser must accept <LF> and <CRLF> as line termination. It may accept any other sequence of <CR> and <LF> as EOL. It must not parse anything else as "line termination."

Line

A sequence of characters, minimum length 1 byte, maximum length 510 bytes, not including the EOL. If a parser encounters a line with a length of 0 bytes, it must be silently ignored, and it must not do anything else. A line which is longer than the maximum length is disallowed.

NULL, CR and LF are disallowed in a line, any other character is allowed.

NOTE on NULL character: A parser can encounter a line which contains a NULL character. It may terminate the line at the first NULL character (remove anything after and including the first NULL character from the line).

Garbage

Any data between the last EOL and the end of the stream. It must not be parsed as a line.

P10 Base64

The P10 protocol uses a base64 notation for numerics to uniquely identify a client or server, and for the IP parameter in the N token. The Base64 character set used in ircd-darenet (ircu) is included below, this defines all valid characters allowed in a Base64 numeric with "A" representing 0 and "]" representing 63.

ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789[]

They are from now referred to as the P10 base64 characters.

A P10 base64 string is a sequence of P10 base64 characters, with a minimum length of 1 character. it must not contain any other character. If the string has a length of more than one character, the string begins with the most significant character and ends with the least significant character.

Note: P10 base64 strings are case significant. Whenever this document mentions "base64", read it as "P10 base64".

Numerics

As mentioned earlier, the P10 protocol uses a scheme of "numerics" to uniquely identify a client or server within the network. Each server has its own unique numeric (0 -> 4095) and each client has its own numeric within that server (0 -> 262,143). The numeric is a base64 string or 2 concatenated base64 strings.

Server numerics consist of 2 characters, with the minimum, 0, being represented by "AA", and the maximum, 4095, being represented by "]]". Client numerics are 3 characters long, with the minimum, 0, being represented by "AAA", and the maximum, 262,143, being represented by "]]]". The unique identifier of a client on the network consists of a combination of both the server and client numeric in the format SSCCC.

A server has a "max client numeric." This is sent in SERVER messages (detailed later in this document). A client numeric on a server, ANDed with the max server numeric, must be unique. For example, if server YY's max client numeric is YYA]] (4095), clients YYBXX and YYCXC can't exist at the same time, doing this would cause a "numeric collision," which is a protocol violation. But, such numerics which occupy the same "slot" are not identical - a message sent to use YYBXX in this example must not reach user YYCXX.

Described above are "extended numerics", as used on DareNET.

Short Numerics

P10 short numerics use 1 char for server numerics, allowing 64 servers on the net, and a 3 chars for client numerics: server numeric + 2 characters for the client on that server, allowing 4096 clients on one server.

  • SS = extended numerics, server.
  • SSCCC = extended numerics, client
  • S = short numerics server
  • SCC = short numerics client.

In any example numeric with S and C, interpret "S" as a character of the server number, "C" as the client on the server.

Extended vs Short

We've covered two different standards which are not compatible with each other, so let's break it down a bit more:

Extended Numerics Only: The P10 protocol, as used by DareNET (and most other networks, including Undernet), one must parse and send extended numerics. One may parse short numerics. One must not generate short numerics.

General Purpose P10 (mixed short/extended numerics): One must parse both short and extended numerics, and may generate both short and extended numerics. This also implies that any numeric which is ASACC or AS may be sent as a short numeric.

If one can parse short numerics, it must consider the short numeric SCC and extended numeric ASACC, and also the short numeric S and extended numeric AS, as being equivalent; both can identify the same thing.

An implementation coplies with both standards if it can parse short numerics and extended numerics, and generates only extended numerics. This is true of ircd-darenet.

NOTE (1): universial-ircu can send 4 character numerics (SCCC). This is not valid according to this protocol definition, one must not send them. However, right now, one may parse them, if they are translated to ASCCC. Doing this allows a P10 implementation to link to universal. This may change later, 4 char numerics may later be used for something different, such as services.

NOTE (2): An implementation can be or not be transparent to numerics -- sending them as it receives them, preserving short/extended. ircd-darenet is transparent to numerics. This means, it can't be between something which sends short numerics, and something which can't parse short numerics.

Syntax of a Line

Space is character 32 ($20).

The source, command and parameters are separated by spaces.

<source> <command> [<parameters>]

  • One must send only the short command token (detailed in the next section). One may parse both short and long command token, and if one does, they must be considered equivalent; for example, N = NICK. So, say if we were to say "receives a NICK line," it may actually be a N token.
  • Command tokens are uppercase. One must not send lowercase command tokens. One may parse them.