4 The iauth protocol used here is based on the one in irc2.11.1, with
5 minor changes to support challenge-response protocols and
6 login-on-connect. Reference to that version's iauth-internals.txt and
7 source code may be useful. For clarity, this document uses "server"
8 to refer to any IRC server implementing this protocol, "ircu" to refer
9 to Undernet ircd, and "ircd" to refer to IRCnet ircd.
11 Certain messages are relayed to interested operators. ircu implements
12 this by using the 131072 (SNO_AUTH) server notice mask. ircd
13 implements this by using the &AUTH local channel.
18 The path to the iauth program is specified in the server configuration
19 file. The server spawns that program when reading the configuration
20 file or when the previous iauth instance terminates. To protect
21 against a series of crashes, the server will refuse to restart an
22 iauth instance that it spawned in the last five seconds. A rehash
23 operation will clear this behavior. The server and iauth instance
24 communicate over the iauth instance's stdin and stdout.
26 Every message from the server to the iauth instance is a single line.
27 The line starts with an integer client identifier. This may be -1 to
28 indicate no particular client or a non-negative number to indicate a
29 client connected to the server.
31 When the server starts the iauth instance, it sends a line formatted
32 like "-1 M irc.example.org 20000" to indicate its name and an
33 exclusive upper bound on valid client identifiers. In that example,
34 possible client identifiers would be from 0 through 19999 inclusive.
35 This upper bound is called MAXCONNECTIONS in the server code.
37 When the iauth instance starts, it sends a V message to indicate its
40 The server should provide /stats subcommands that report the iauth
41 instance's version, configuration and statistics.
43 Line formats in both direction are IRC-like in format: space
44 characters separate arguments and a colon at the start of an argument
45 indicates that the remainder of the line is one argument. To avoid
46 problems, IPv6 address arguments with a leading colon may have to be
47 prefixed with a 0 -- for example, ::1 sent as 0::1.
49 When the iauth instance sends messages that relate to a particular
50 client, that client is identified by three parameters from the
51 server's Client Introduction message (<id>, <remoteip> and
52 <remoteport>). If any of these disagree with the server's current
53 user tables, it is an error.
58 Each client is conceptually in one of four states: GONE, REGISTER,
59 HURRY or NORMAL. Each client starts in the GONE state. Certain
60 messages from the server signal a client's transition from one state
61 to another, and certain messages from the iauth instance cause a state
64 To be pedantic, the REGISTER state is a collection of sub-states since
65 certain commands must occur at most and/or at least one time during
66 the REGISTER state. The distinctions between these sub-states are
67 distracting and not important, so they are described as one state and
68 the repetition limitations are described for each command.
70 The rationale for the HURRY state is to give explicit input to the
71 iauth instance as to when the server believes it has sent the complete
72 set of data for the client. Rather than defining the complete set of
73 information in this protocol document, that is left to the server.
74 ircd does not indicate this state.
76 POLICIES AND USE CASES
77 ======================
79 The historical application of iauth has been to block users that
80 appear to be drones early, before they have a chance to disrupt the
81 network, and without affecting other users on the same host (which
82 K-lines do). This protocol extends that application by adding the n
83 server message and by allowing challenge-response exchanges with the
86 Eventually it would be nice to move the DNS and ident lookups into
87 iauth, and remove that code from the IRC server. ircd already does
88 this; since ircu does not, it adds the u server message.
90 For trusted proxies, this protocol gives the capability for clients
91 connecting through those proxies to be displayed with their actual
92 username, IP address and hostname. The same functions allow other
93 clients to use iauth-assigned spoofs, for example to hide the IP
94 addresses used by operators.
96 This protocol allows login-on-connect, for example by clients that
97 send their account name and password in PASS, through the R iauth
100 This protocol allows iauth to assign a client to a particular class by
101 specifying a class name in the D or R iauth message.
106 X - Example Message Description
107 Syntax: <id> X <several> <arguments>
108 Example: 5 X arguments vary
109 States: REGISTER(1), HURRY, NORMAL
111 Comments: This is an example message description. Each message is a
112 single character. The States field indicates which states the
113 message may occur in and any restrictions on how many times the
114 message may be sent during those states (restrictions only make
115 sense when Next State is -). The Next State field indicates which
116 new state is implied by the message; a hyphen indicates no state
117 change is implied. The X (Example) message is not a real message
119 Compatibility: If we believe ircu behavior is different than ircd's,
120 this describes ircd's behavior or expectations.
122 C - Client Introduction
123 Syntax: <id> C <remoteip> <remoteport> <localip> <localport>
124 Example: 5 C 192.168.1.10 23367 192.168.0.1 6667
127 Comments: Indicates that <localport> on <localip> accepted a client
128 connection from <remoteport> on <remoteip>.
130 D - Client Disconnect
133 States: REGISTER, HURRY, NORMAL
135 Comments: Indicates that a client is disconnecting from the server.
137 N - Hostname Received
138 Syntax: <id> N <hostname>
139 Example: 5 N host-1-10.example.org
142 Comments: Indicates that the server received hostname information for
143 a client. Only one of 'N' and 'd' is sent.
150 Comments: Indicates that the server did not receive hostname
151 information for a client in a timely fashion. Only one of 'N' and
155 Syntax: <id> P :<password ...>
156 Example: 5 P :buddha n1rvan4
159 Comments: Indicates the client's password information. This may be a
160 traditional client password, an account and pass phrase pair, or the
161 response to a challenge (see the iauth C message). This message is
162 enabled by requesting the A policy.
165 Syntax: <id> U <username> <hostname> <servername> :<userinfo ...>
166 Example: 5 U buddha bodhisattva.example.com irc.undernet.org :Gautama Siddhartha
169 Comments: Indicates the client's claimed username and "GECOS"
170 information, along with client hostname and server name. This
171 information is not reliable. This message is enabled by requesting
173 Compatibility: ircd only sends the <username> parameter.
176 Syntax: <id> u <username>
177 Example: 5 u notbuddha
180 Comments: Indicates a more reliable username for the client.
181 Compatibility: This is an Undernet extension and ircd does not send
182 it. It is enabled by the iauth instance requesting the U policy.
185 Syntax: <id> n <nickname>
187 States: REGISTER(1+), HURRY
189 Comments: Indicates the client's requested nickname.
190 Compatibility: This is an Undernet extension and ircd does not send
191 it. It is enabled by the iauth instance requesting the U policy.
194 Syntax: <id> H <class>
198 Comments: Indicates that the server is ready to register the client
199 except for needing a response from the iauth server. <class> is
200 a tentative connection class for the user, which will be used unless
201 iauth overrides it in a D or R message.
202 Compatibility: This is an Undernet extension and ircd does not send
203 it. It is enabled by the iauth instance requesting the U policy.
205 T - Client Registered
210 Comments: Indicates the server got tired of waiting for iauth to
211 finish and the client is being accepted. This message should
212 never be sent when the R policy is in effect.
213 Compatibility: ircd allows this message for clients in the REGISTER
217 Syntax: <id> E <type> :<additional text>
221 Comments: Indicates that a message received from the iauth instance
222 could not be rationally interpreted. This may be because the client
223 could not be found, the client was in an inappropriate state for the
224 message, or for other reasons. The <type> argument specifies the
225 general type of error and <additional text> provides details. <id>
228 M - Server Name and Capacity
229 Syntax: <id> M <servername> <capacity>
230 Example: -1 M irc.example.org 20000
233 Comments: Indicates the server's name and upper bound on client
235 Compatibility: ircd does not include the <capacity> information.
236 The <id> should be ignored: ircd sends 0 and ircu sends -1.
241 X - Example Message Description
242 Syntax: X <arguments>
247 Comments: This is an example message description. Each message is a
248 single character. If the Notify field is present and says yes,
249 interested operators (with SNO_AUTH set) should be notified of the
250 message. The States field, where present, indicate which states
251 accept this message. Clients in other states should ignore the
252 message or treat it as an error. The Next State field, where
253 present, indicates what the next state should be for the client.
254 Compatibility: If we believe ircu behavior is different than ircd's,
255 this describes ircd's behavior or expectations.
257 > - Operator Notification
258 Syntax: > :<message text>
259 Example: > :Hello Operators!
261 Comments: Contains a message that the iauth instance wants to send to
262 interested operators.
268 Comments: Sets a debug level for the server's end of the iauth
269 conversation. When enabled, debug messages should be sent to the
270 same channel (group, mask, etc) as other iauth notifications.
271 Debug level 0 suppresses iauth-related debug output, and positive
272 integers enable iauth debugging messages.
274 O - Set Policy Options
278 Comments: Sets policy options for the iauth conversation. Old policy
279 options should be forgotten. Valid policy options are:
280 A - Send username and password information.
281 This causes the server to send the U and P messages.
282 R - Require clients to be approved before registering them.
283 When this policy is in effect, it affects the behavior
284 of a registration timeout; for details, see the documentation
285 for the T server message.
286 T - When the R policy is in effect and the iauth service does not
287 respond for a client, this causes the server to count the number
288 of clients refused, to send a warning message to interested
289 operators periodically, and to send the count of rejected users
290 to interested operators when the iauth instance responds again.
291 U - Send nickname, confirmed username and hurry information.
292 This causes the server to send the n, u and H messages.
293 W - Allow extra time for iauth to respond based on hostname.
294 When this policy is in effect and a DNS message (N or d) is
295 sent for a client, that client's registration timeout is
297 Compatibility: The U policy is an Undernet extension and is not
300 V - iauth Program Version
301 Syntax: V :<version string>
302 Example: V :Undernet-iauthu v1.0
304 Comments: Indicates the iauth program version. This should only be
305 used in diagnostic messages, and must not change protocol behavior.
307 a - Start of new configuration
311 Comments: Indicates that a new configuration is being loaded by the
312 iauth instance. Any cached configuration records should be cleared.
314 A - Configuration Information
315 Syntax: A <hosts?> <module> :<options>
318 Comments: Indicates new configuration information.
320 s - Start of new statistics
324 Comments: Indicates a new set of statistics will be sent. Any cached
325 statistics records should be cleared.
327 S - Statistics Information
328 Syntax: S <module> :<module information>
329 Example: S rfc931 connected 0 unix 0 other 0 bad 0 out of 0
331 Comments: Indicates new or additional statistics information.
334 Syntax: o <id> <remoteip> <remoteport> <username>
335 Example: o 5 192.168.1.10 23367 bubba
336 States: REGISTER, HURRY
338 Comments: Indicates that the username should be used for the specified
339 client even if the normal sanity-checking would prohibit the
343 Syntax: U <id> <remoteip> <remoteport> <username>
344 Example: U 5 192.168.1.10 23367 buddha
345 States: REGISTER, HURRY
347 Comments: Indicates that the iauth instance believes <username> is
348 accurate for the specified client.
350 u - Untrusted Username
351 Syntax: u <id> <remoteip> <remoteport> <username>
352 Example: u 5 192.168.1.10 23367 enlightened_one
353 States: REGISTER, HURRY
355 Comments: Indicates that the iauth instance does not strongly trust
356 <username> to be accurate, but has no more trusted username.
359 Syntax: N <id> <remoteip> <remoteport> <hostname>
360 Example: N 5 192.168.1.10 23367 buddha.example.org
361 States: REGISTER, HURRY
363 Comments: Indicates that the iauth instance believes the specified
364 client should use the hostname given.
365 Compatibility: This is an Undernet extension and ircd does not support
368 I - Client IP Address
369 Syntax: N <id> <currentip> <remoteport> <newip>
370 Example: N 5 192.168.1.10 23367 127.128.129.130
371 States: REGISTER, HURRY
373 Comments: Indicates that the iauth instance wants the server to
374 present and treat the client as using <newip>. This means that
375 future iauth messages relating to the client must use <newip>
376 as the <remoteip> parameter.
377 Compatibility: This is an Undernet extension and ircd does not support
381 Syntax: C <id> <remoteip> <remoteport> :<challenge string>
382 Example: C 5 192.168.1.10 23367 :In which year did Columbus sail the ocean blue?
383 States: REGISTER, HURRY
385 Comments: Indicates that the challenge string should be sent to the
386 specified user, for example via NOTICE AUTH :*** <challenge string>.
387 The client responds by sending PASS :<response>, which should be
388 relayed via the P server message. This requires that the A policy
390 Compatibility: This is an Undernet extension and ircd does not support
393 k - Quietly Kill Client
394 Syntax: k <id> <remoteip> <remoteport> :<reason>
395 Example: k 5 192.168.1.10 23367 :Open proxy found.
396 States: REGISTER, HURRY, NORMAL
398 Comments: Indicates that the specified client should be disconnected
399 for the reason given without notifying operators.
400 Compatibility: ircu does not use the same notification mechanism as
401 ircd, so operators are notified using SNO_CONNEXIT anyway.
404 Syntax: K <id> <remoteip> <remoteport> :<reason>
405 Example: K 5 192.168.1.10 23367 :We don't like you.
406 States: REGISTER, HURRY, NORMAL
408 Comments: Indicates that the specified client should be disconnected
409 for the reason given. Operators should be notified.
412 Syntax: D <id> <remoteip> <remoteport> [class]
413 Example: D 5 192.168.1.10 23367
414 States: REGISTER, HURRY
416 Comments: Indicates that the iauth instance believes the specified
417 client should be allowed onto the network. If a class parameter is
418 given, the client should be assigned to that class.
419 Compatibility: Specifying the class is an Undernet extension and ircd
420 does not support that parameter.
423 Syntax: R <id> <remoteip> <remoteport> <account> [class]
424 Example: R 5 192.168.1.10 23367 Buddha
425 States: REGISTER, HURRY
427 Comments: Indicates that the iauth instance believes the specified
428 client should be allowed onto the network, pre-authenticated to
429 the account listed. If a class parameter is given, the client
430 should be assigned to that class.
431 Compatibility: This is an Undernet extension and ircd does not support