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. This is an example, not a description of the
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.
238 X - Extension Query Reply
239 Syntax: <id> X <servername> <routing> :<reply>
240 Example: -1 X channels.undernet.org 5/127.0.0.1/6667 :OK kev Logged in
243 Comments: Used to deliver the reply to an extension query to the iauth
244 instance. The <servername> parameter indicates the origin of the
245 reply. The <routing> parameter is the same as was used in the X
246 message from the iauth instance, and can be used to pair the reply
247 with the original request. The <reply> parameter contains the text
249 Compatibility: This is an Undernet extension and ircd does not send
252 x - Extension Query Server Not Linked
253 Syntax: <id> x <servername> <routing> :Server not online
254 Example: -1 x channels.undernet.org 5/127.0.0.1/6667 :Server not online
257 Comments: Used to indicate to the iauth instance that the server
258 specified in the X message is not presently linked to the network.
259 This will not detect the extension query being lost due to a network
260 break, so iauth instances should further implement a timeout
261 mechanism for extension queries.
262 Compatibility: This is an Undernet extension and ircd does not send
268 X - Example Message Description
269 Syntax: X <arguments>
274 Comments: This is an example message description. Each message is a
275 single character. If the Notify field is present and says yes,
276 interested operators (with SNO_AUTH set) should be notified of the
277 message. The States field, where present, indicate which states
278 accept this message. Clients in other states should ignore the
279 message or treat it as an error. The Next State field, where
280 present, indicates what the next state should be for the client.
281 This is an example, not a description of the actual X message.
282 Compatibility: If we believe ircu behavior is different than ircd's,
283 this describes ircd's behavior or expectations.
285 > - Operator Notification
286 Syntax: > :<message text>
287 Example: > :Hello Operators!
289 Comments: Contains a message that the iauth instance wants to send to
290 interested operators.
296 Comments: Sets a debug level for the server's end of the iauth
297 conversation. When enabled, debug messages should be sent to the
298 same channel (group, mask, etc) as other iauth notifications.
299 Debug level 0 suppresses iauth-related debug output, and positive
300 integers enable iauth debugging messages.
302 O - Set Policy Options
306 Comments: Sets policy options for the iauth conversation. Old policy
307 options should be forgotten. Valid policy options are:
308 A - Send username and password information.
309 This causes the server to send the U and P messages.
310 R - Require clients to be approved before registering them.
311 When this policy is in effect, it affects the behavior
312 of a registration timeout; for details, see the documentation
313 for the T server message.
314 T - When the R policy is in effect and the iauth service does not
315 respond for a client, this causes the server to count the number
316 of clients refused, to send a warning message to interested
317 operators periodically, and to send the count of rejected users
318 to interested operators when the iauth instance responds again.
319 U - Send nickname, confirmed username and hurry information.
320 This causes the server to send the n, u and H messages.
321 W - Allow extra time for iauth to respond based on hostname.
322 When this policy is in effect and a DNS message (N or d) is
323 sent for a client, that client's registration timeout is
325 Compatibility: The U policy is an Undernet extension and is not
328 V - iauth Program Version
329 Syntax: V :<version string>
330 Example: V :Undernet-iauthu v1.0
332 Comments: Indicates the iauth program version. This should only be
333 used in diagnostic messages, and must not change protocol behavior.
335 a - Start of new configuration
339 Comments: Indicates that a new configuration is being loaded by the
340 iauth instance. Any cached configuration records should be cleared.
342 A - Configuration Information
343 Syntax: A <hosts?> <module> :<options>
346 Comments: Indicates new configuration information.
348 s - Start of new statistics
352 Comments: Indicates a new set of statistics will be sent. Any cached
353 statistics records should be cleared.
355 S - Statistics Information
356 Syntax: S <module> :<module information>
357 Example: S rfc931 connected 0 unix 0 other 0 bad 0 out of 0
359 Comments: Indicates new or additional statistics information.
362 Syntax: o <id> <remoteip> <remoteport> <username>
363 Example: o 5 192.168.1.10 23367 bubba
364 States: REGISTER, HURRY
366 Comments: Indicates that the username should be used for the specified
367 client even if the normal sanity-checking would prohibit the
371 Syntax: U <id> <remoteip> <remoteport> <username>
372 Example: U 5 192.168.1.10 23367 buddha
373 States: REGISTER, HURRY
375 Comments: Indicates that the iauth instance believes <username> is
376 accurate for the specified client.
378 u - Untrusted Username
379 Syntax: u <id> <remoteip> <remoteport> <username>
380 Example: u 5 192.168.1.10 23367 enlightened_one
381 States: REGISTER, HURRY
383 Comments: Indicates that the iauth instance does not strongly trust
384 <username> to be accurate, but has no more trusted username.
387 Syntax: N <id> <remoteip> <remoteport> <hostname>
388 Example: N 5 192.168.1.10 23367 buddha.example.org
389 States: REGISTER, HURRY
391 Comments: Indicates that the iauth instance believes the specified
392 client should use the hostname given.
393 Compatibility: This is an Undernet extension and ircd does not support
396 I - Client IP Address
397 Syntax: I <id> <currentip> <remoteport> <newip>
398 Example: I 5 192.168.1.10 23367 127.128.129.130
399 States: REGISTER, HURRY
401 Comments: Indicates that the iauth instance wants the server to
402 present and treat the client as using <newip>. This means that
403 future iauth messages relating to the client must use <newip>
404 as the <remoteip> parameter.
405 Compatibility: This is an Undernet extension and ircd does not support
409 Syntax: M <id> <remoteip> <remoteport> +<mode changes>
410 Example: M 5 192.168.1.10 23367 +iwg
411 States: REGISTER, HURRY
413 Comments: Indicates a set of user mode changes to be applied to the
415 Compatibility: This is an Undernet extension and ircd does not support
419 Syntax: C <id> <remoteip> <remoteport> :<challenge string>
420 Example: C 5 192.168.1.10 23367 :In which year did Columbus sail the ocean blue?
421 States: REGISTER, HURRY
423 Comments: Indicates that the challenge string should be sent to the
424 specified user, for example via NOTICE AUTH :*** <challenge string>.
425 The client responds by sending PASS :<response>, which should be
426 relayed via the P server message. This requires that the A policy
428 Compatibility: This is an Undernet extension and ircd does not support
431 k - Quietly Kill Client
432 Syntax: k <id> <remoteip> <remoteport> :<reason>
433 Example: k 5 192.168.1.10 23367 :Open proxy found.
434 States: REGISTER, HURRY, NORMAL
436 Comments: Indicates that the specified client should be disconnected
437 for the reason given without notifying operators.
438 Compatibility: ircu does not use the same notification mechanism as
439 ircd, so operators are notified using SNO_CONNEXIT anyway.
442 Syntax: K <id> <remoteip> <remoteport> :<reason>
443 Example: K 5 192.168.1.10 23367 :We don't like you.
444 States: REGISTER, HURRY, NORMAL
446 Comments: Indicates that the specified client should be disconnected
447 for the reason given. Operators should be notified.
449 d - "Soft" Done Checking
450 Syntax: d <id> <remoteip> <remoteport>
451 Example: d 5 192.168.1.10 23367
452 States: REGISTER, HURRY
454 Comments: Indicates that the iauth instance has no objection to letting
455 the specified client onto the network, but that some further work is
456 in process. In particular, an account stamp and/or connection class
457 might be available later.
458 Compatibility: This is an Undernet extension and ircd does not support
462 Syntax: D <id> <remoteip> <remoteport> [class]
463 Example: D 5 192.168.1.10 23367
464 States: REGISTER, HURRY
466 Comments: Indicates that the iauth instance believes the specified
467 client should be allowed onto the network. If a class parameter is
468 given, the client should be assigned to that class.
469 Compatibility: Specifying the class is an Undernet extension and ircd
470 does not support that parameter.
473 Syntax: R <id> <remoteip> <remoteport> <account> [class]
474 Example: R 5 192.168.1.10 23367 Buddha
475 States: REGISTER, HURRY
477 Comments: Indicates that the iauth instance believes the specified
478 client should be allowed onto the network, pre-authenticated to
479 the account listed. If a class parameter is given, the client
480 should be assigned to that class.
481 Compatibility: This is an Undernet extension and ircd does not support
485 Syntax: X <servername> <routing> :<query>
486 Example: X channels.undernet.org 5/127.0.0.1/6667 :login kev pass
487 Comments: Used by the iauth instance to send an extension query to
488 the server specified by <servername>. The <routing> parameter is
489 not interpreted by the servers; it will be returned unchanged in
490 the extension query reply message (the X server message) and may be
491 used to pair the query with its reply. The <query> parameter is
492 sent to <servername>.
493 Compatibility: This is an Undernet extension and ircd does not support