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>
178 Example: 5 u notbuddha
181 Comments: Indicates a more reliable username for the client.
182 Compatibility: This is an Undernet extension and ircd does not send
183 it. It is enabled by the iauth instance requesting the U policy.
184 If the identd lookup fails for a user, no username is passed.
187 Syntax: <id> n <nickname>
189 States: REGISTER(1+), HURRY
191 Comments: Indicates the client's requested nickname.
192 Compatibility: This is an Undernet extension and ircd does not send
193 it. It is enabled by the iauth instance requesting the U policy.
196 Syntax: <id> H <class>
200 Comments: Indicates that the server is ready to register the client
201 except for needing a response from the iauth server. <class> is
202 a tentative connection class for the user, which will be used unless
203 iauth overrides it in a D or R message.
204 Compatibility: This is an Undernet extension and ircd does not send
205 it. It is enabled by the iauth instance requesting the U policy.
207 T - Client Registered
212 Comments: Indicates the server got tired of waiting for iauth to
213 finish and the client is being accepted. This message should
214 never be sent when the R policy is in effect.
215 Compatibility: ircd allows this message for clients in the REGISTER
219 Syntax: <id> E <type> :<additional text>
223 Comments: Indicates that a message received from the iauth instance
224 could not be rationally interpreted. This may be because the client
225 could not be found, the client was in an inappropriate state for the
226 message, or for other reasons. The <type> argument specifies the
227 general type of error and <additional text> provides details. <id>
230 M - Server Name and Capacity
231 Syntax: <id> M <servername> <capacity>
232 Example: -1 M irc.example.org 20000
235 Comments: Indicates the server's name and upper bound on client
237 Compatibility: ircd does not include the <capacity> information.
238 The <id> should be ignored: ircd sends 0 and ircu sends -1.
240 X - Extension Query Reply
241 Syntax: <id> X <servername> <routing> :<reply>
242 Example: -1 X channels.undernet.org 5/127.0.0.1/6667 :OK kev Logged in
245 Comments: Used to deliver the reply to an extension query to the iauth
246 instance. The <servername> parameter indicates the origin of the
247 reply. The <routing> parameter is the same as was used in the X
248 message from the iauth instance, and can be used to pair the reply
249 with the original request. The <reply> parameter contains the text
251 Compatibility: This is an Undernet extension and ircd does not send
254 x - Extension Query Server Not Linked
255 Syntax: <id> x <servername> <routing> :Server not online
256 Example: -1 x channels.undernet.org 5/127.0.0.1/6667 :Server not online
259 Comments: Used to indicate to the iauth instance that the server
260 specified in the X message is not presently linked to the network.
261 This will not detect the extension query being lost due to a network
262 break, so iauth instances should further implement a timeout
263 mechanism for extension queries.
264 Compatibility: This is an Undernet extension and ircd does not send
270 X - Example Message Description
271 Syntax: X <arguments>
276 Comments: This is an example message description. Each message is a
277 single character. If the Notify field is present and says yes,
278 interested operators (with SNO_AUTH set) should be notified of the
279 message. The States field, where present, indicate which states
280 accept this message. Clients in other states should ignore the
281 message or treat it as an error. The Next State field, where
282 present, indicates what the next state should be for the client.
283 This is an example, not a description of the actual X message.
284 Compatibility: If we believe ircu behavior is different than ircd's,
285 this describes ircd's behavior or expectations.
287 > - Operator Notification
288 Syntax: > :<message text>
289 Example: > :Hello Operators!
291 Comments: Contains a message that the iauth instance wants to send to
292 interested operators.
298 Comments: Sets a debug level for the server's end of the iauth
299 conversation. When enabled, debug messages should be sent to the
300 same channel (group, mask, etc) as other iauth notifications.
301 Debug level 0 suppresses iauth-related debug output, and positive
302 integers enable iauth debugging messages.
304 O - Set Policy Options
308 Comments: Sets policy options for the iauth conversation. Old policy
309 options should be forgotten. Valid policy options are:
310 A - Send username and password information.
311 This causes the server to send the U and P messages.
312 R - Require clients to be approved before registering them.
313 When this policy is in effect, it affects the behavior
314 of a registration timeout; for details, see the documentation
315 for the T server message.
316 T - When the R policy is in effect and the iauth service does not
317 respond for a client, this causes the server to count the number
318 of clients refused, to send a warning message to interested
319 operators periodically, and to send the count of rejected users
320 to interested operators when the iauth instance responds again.
321 U - Send nickname, confirmed username and hurry information.
322 This causes the server to send the n, u and H messages.
323 W - Allow extra time for iauth to respond based on hostname.
324 When this policy is in effect and a DNS message (N or d) is
325 sent for a client, that client's registration timeout is
327 Compatibility: The U policy is an Undernet extension and is not
330 V - iauth Program Version
331 Syntax: V :<version string>
332 Example: V :Undernet-iauthu v1.0
334 Comments: Indicates the iauth program version. This should only be
335 used in diagnostic messages, and must not change protocol behavior.
337 a - Start of new configuration
341 Comments: Indicates that a new configuration is being loaded by the
342 iauth instance. Any cached configuration records should be cleared.
344 A - Configuration Information
345 Syntax: A <hosts?> <module> :<options>
348 Comments: Indicates new configuration information.
350 s - Start of new statistics
354 Comments: Indicates a new set of statistics will be sent. Any cached
355 statistics records should be cleared.
357 S - Statistics Information
358 Syntax: S <module> :<module information>
359 Example: S rfc931 connected 0 unix 0 other 0 bad 0 out of 0
361 Comments: Indicates new or additional statistics information.
364 Syntax: o <id> <remoteip> <remoteport> <username>
365 Example: o 5 192.168.1.10 23367 bubba
366 States: REGISTER, HURRY
368 Comments: Indicates that the username should be used for the specified
369 client even if the normal sanity-checking would prohibit the
373 Syntax: U <id> <remoteip> <remoteport> <username>
374 Example: U 5 192.168.1.10 23367 buddha
375 States: REGISTER, HURRY
377 Comments: Indicates that the iauth instance believes <username> is
378 accurate for the specified client.
380 u - Untrusted Username
381 Syntax: u <id> <remoteip> <remoteport> <username>
382 Example: u 5 192.168.1.10 23367 enlightened_one
383 States: REGISTER, HURRY
385 Comments: Indicates that the iauth instance does not strongly trust
386 <username> to be accurate, but has no more trusted username.
389 Syntax: N <id> <remoteip> <remoteport> <hostname>
390 Example: N 5 192.168.1.10 23367 buddha.example.org
391 States: REGISTER, HURRY
393 Comments: Indicates that the iauth instance believes the specified
394 client should use the hostname given.
395 Compatibility: This is an Undernet extension and ircd does not support
398 I - Client IP Address
399 Syntax: I <id> <currentip> <remoteport> <newip>
400 Example: I 5 192.168.1.10 23367 127.128.129.130
401 States: REGISTER, HURRY
403 Comments: Indicates that the iauth instance wants the server to
404 present and treat the client as using <newip>. This means that
405 future iauth messages relating to the client must use <newip>
406 as the <remoteip> parameter.
407 Compatibility: This is an Undernet extension and ircd does not support
411 Syntax: M <id> <remoteip> <remoteport> +<mode changes>
412 Example: M 5 192.168.1.10 23367 +iwg
413 States: REGISTER, HURRY
415 Comments: Indicates a set of user mode changes to be applied to the
417 Compatibility: This is an Undernet extension and ircd does not support
421 Syntax: C <id> <remoteip> <remoteport> :<challenge string>
422 Example: C 5 192.168.1.10 23367 :In which year did Columbus sail the ocean blue?
423 States: REGISTER, HURRY
425 Comments: Indicates that the challenge string should be sent to the
426 specified user, for example via NOTICE AUTH :*** <challenge string>.
427 The client responds by sending PASS :<response>, which should be
428 relayed via the P server message. This requires that the A policy
430 Compatibility: This is an Undernet extension and ircd does not support
433 k - Quietly Kill Client
434 Syntax: k <id> <remoteip> <remoteport> :<reason>
435 Example: k 5 192.168.1.10 23367 :Open proxy found.
436 States: REGISTER, HURRY, NORMAL
438 Comments: Indicates that the specified client should be disconnected
439 for the reason given without notifying operators.
440 Compatibility: ircu does not use the same notification mechanism as
441 ircd, so operators are notified using SNO_CONNEXIT anyway.
444 Syntax: K <id> <remoteip> <remoteport> :<reason>
445 Example: K 5 192.168.1.10 23367 :We don't like you.
446 States: REGISTER, HURRY, NORMAL
448 Comments: Indicates that the specified client should be disconnected
449 for the reason given. Operators should be notified.
451 d - "Soft" Done Checking
452 Syntax: d <id> <remoteip> <remoteport>
453 Example: d 5 192.168.1.10 23367
454 States: REGISTER, HURRY
456 Comments: Indicates that the iauth instance has no objection to letting
457 the specified client onto the network, but that some further work is
458 in process. In particular, an account stamp and/or connection class
459 might be available later.
460 Compatibility: This is an Undernet extension and ircd does not support
464 Syntax: D <id> <remoteip> <remoteport> [class]
465 Example: D 5 192.168.1.10 23367
466 States: REGISTER, HURRY
468 Comments: Indicates that the iauth instance believes the specified
469 client should be allowed onto the network. If a class parameter is
470 given, the client should be assigned to that class.
471 Compatibility: Specifying the class is an Undernet extension and ircd
472 does not support that parameter.
475 Syntax: R <id> <remoteip> <remoteport> <account> [class]
476 Example: R 5 192.168.1.10 23367 Buddha
477 States: REGISTER, HURRY
479 Comments: Indicates that the iauth instance believes the specified
480 client should be allowed onto the network, pre-authenticated to
481 the account listed. If a class parameter is given, the client
482 should be assigned to that class.
483 Compatibility: This is an Undernet extension and ircd does not support
487 Syntax: X <servername> <routing> :<query>
488 Example: X channels.undernet.org 5/127.0.0.1/6667 :login kev pass
489 Comments: Used by the iauth instance to send an extension query to
490 the server specified by <servername>. The <routing> parameter is
491 not interpreted by the servers; it will be returned unchanged in
492 the extension query reply message (the X server message) and may be
493 used to pair the query with its reply. The <query> parameter is
494 sent to <servername>.
495 Compatibility: This is an Undernet extension and ircd does not support