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> L <account>[:<accountstamp>][ <fakehost>]
195 Example: 5 L Buddha Buddha.TestNet.com
198 Comments: Indicates a successfull LOC query. If the LOC query failed,
199 no message is sent but the iauthd must assume that the query failed
200 or was not done when it goes into the HURRY state.
201 The user gets automatically set "+xr <account>". If <fakehost> is
202 set, it also gets "+f <fakehost>". The iauthd cannot overwrite
203 these settings. If the iauthd believes them to be wrong, it must
205 Compatibility: This is an extension of the IRCu-Patchset.
208 Syntax: <id> H <class>
212 Comments: Indicates that the server is ready to register the client
213 except for needing a response from the iauth server. <class> is
214 a tentative connection class for the user, which will be used unless
215 iauth overrides it in a D or R message.
216 Compatibility: This is an Undernet extension and ircd does not send
217 it. It is enabled by the iauth instance requesting the U policy.
219 T - Client Registered
224 Comments: Indicates the server got tired of waiting for iauth to
225 finish and the client is being accepted. This message should
226 never be sent when the R policy is in effect.
227 Compatibility: ircd allows this message for clients in the REGISTER
231 Syntax: <id> E <type> :<additional text>
235 Comments: Indicates that a message received from the iauth instance
236 could not be rationally interpreted. This may be because the client
237 could not be found, the client was in an inappropriate state for the
238 message, or for other reasons. The <type> argument specifies the
239 general type of error and <additional text> provides details. <id>
242 M - Server Name and Capacity
243 Syntax: <id> M <servername> <capacity>
244 Example: -1 M irc.example.org 20000
247 Comments: Indicates the server's name and upper bound on client
249 Compatibility: ircd does not include the <capacity> information.
250 The <id> should be ignored: ircd sends 0 and ircu sends -1.
255 X - Example Message Description
256 Syntax: X <arguments>
261 Comments: This is an example message description. Each message is a
262 single character. If the Notify field is present and says yes,
263 interested operators (with SNO_AUTH set) should be notified of the
264 message. The States field, where present, indicate which states
265 accept this message. Clients in other states should ignore the
266 message or treat it as an error. The Next State field, where
267 present, indicates what the next state should be for the client.
268 Compatibility: If we believe ircu behavior is different than ircd's,
269 this describes ircd's behavior or expectations.
271 > - Operator Notification
272 Syntax: > :<message text>
273 Example: > :Hello Operators!
275 Comments: Contains a message that the iauth instance wants to send to
276 interested operators.
282 Comments: Sets a debug level for the server's end of the iauth
283 conversation. When enabled, debug messages should be sent to the
284 same channel (group, mask, etc) as other iauth notifications.
285 Debug level 0 suppresses iauth-related debug output, and positive
286 integers enable iauth debugging messages.
288 O - Set Policy Options
292 Comments: Sets policy options for the iauth conversation. Old policy
293 options should be forgotten. Valid policy options are:
294 A - Send username and password information.
295 This causes the server to send the U and P messages.
296 R - Require clients to be approved before registering them.
297 When this policy is in effect, it affects the behavior
298 of a registration timeout; for details, see the documentation
299 for the T server message.
300 T - When the R policy is in effect and the iauth service does not
301 respond for a client, this causes the server to count the number
302 of clients refused, to send a warning message to interested
303 operators periodically, and to send the count of rejected users
304 to interested operators when the iauth instance responds again.
305 U - Send nickname, confirmed username and hurry information.
306 This causes the server to send the n, u and H messages.
307 W - Allow extra time for iauth to respond based on hostname.
308 When this policy is in effect and a DNS message (N or d) is
309 sent for a client, that client's registration timeout is
311 Compatibility: The U policy is an Undernet extension and is not
314 V - iauth Program Version
315 Syntax: V :<version string>
316 Example: V :Undernet-iauthu v1.0
318 Comments: Indicates the iauth program version. This should only be
319 used in diagnostic messages, and must not change protocol behavior.
321 a - Start of new configuration
325 Comments: Indicates that a new configuration is being loaded by the
326 iauth instance. Any cached configuration records should be cleared.
328 A - Configuration Information
329 Syntax: A <hosts?> <module> :<options>
332 Comments: Indicates new configuration information.
334 s - Start of new statistics
338 Comments: Indicates a new set of statistics will be sent. Any cached
339 statistics records should be cleared.
341 S - Statistics Information
342 Syntax: S <module> :<module information>
343 Example: S rfc931 connected 0 unix 0 other 0 bad 0 out of 0
345 Comments: Indicates new or additional statistics information.
348 Syntax: o <id> <remoteip> <remoteport> <username>
349 Example: o 5 192.168.1.10 23367 bubba
350 States: REGISTER, HURRY
352 Comments: Indicates that the username should be used for the specified
353 client even if the normal sanity-checking would prohibit the
357 Syntax: U <id> <remoteip> <remoteport> <username>
358 Example: U 5 192.168.1.10 23367 buddha
359 States: REGISTER, HURRY
361 Comments: Indicates that the iauth instance believes <username> is
362 accurate for the specified client.
364 u - Untrusted Username
365 Syntax: u <id> <remoteip> <remoteport> <username>
366 Example: u 5 192.168.1.10 23367 enlightened_one
367 States: REGISTER, HURRY
369 Comments: Indicates that the iauth instance does not strongly trust
370 <username> to be accurate, but has no more trusted username.
373 Syntax: N <id> <remoteip> <remoteport> <hostname>
374 Example: N 5 192.168.1.10 23367 buddha.example.org
375 States: REGISTER, HURRY
377 Comments: Indicates that the iauth instance believes the specified
378 client should use the hostname given.
379 Compatibility: This is an Undernet extension and ircd does not support
382 I - Client IP Address
383 Syntax: I <id> <currentip> <remoteport> <newip>
384 Example: I 5 192.168.1.10 23367 127.128.129.130
385 States: REGISTER, HURRY
387 Comments: Indicates that the iauth instance wants the server to
388 present and treat the client as using <newip>. This means that
389 future iauth messages relating to the client must use <newip>
390 as the <remoteip> parameter.
391 Compatibility: This is an Undernet extension and ircd does not support
395 Syntax: M <id> <remoteip> <remoteport> +<mode changes>
396 Example: M 5 192.168.1.10 23367 +iwg
397 States: REGISTER, HURRY
399 Comments: Indicates a set of user mode changes to be applied to the
401 Compatibility: This is an Undernet extension and ircd does not support
405 Syntax: C <id> <remoteip> <remoteport> :<challenge string>
406 Example: C 5 192.168.1.10 23367 :In which year did Columbus sail the ocean blue?
407 States: REGISTER, HURRY
409 Comments: Indicates that the challenge string should be sent to the
410 specified user, for example via NOTICE AUTH :*** <challenge string>.
411 The client responds by sending PASS :<response>, which should be
412 relayed via the P server message. This requires that the A policy
414 Compatibility: This is an Undernet extension and ircd does not support
417 k - Quietly Kill Client
418 Syntax: k <id> <remoteip> <remoteport> :<reason>
419 Example: k 5 192.168.1.10 23367 :Open proxy found.
420 States: REGISTER, HURRY, NORMAL
422 Comments: Indicates that the specified client should be disconnected
423 for the reason given without notifying operators.
424 Compatibility: ircu does not use the same notification mechanism as
425 ircd, so operators are notified using SNO_CONNEXIT anyway.
428 Syntax: K <id> <remoteip> <remoteport> :<reason>
429 Example: K 5 192.168.1.10 23367 :We don't like you.
430 States: REGISTER, HURRY, NORMAL
432 Comments: Indicates that the specified client should be disconnected
433 for the reason given. Operators should be notified.
436 Syntax: D <id> <remoteip> <remoteport> [class]
437 Example: D 5 192.168.1.10 23367
438 States: REGISTER, HURRY
440 Comments: Indicates that the iauth instance believes the specified
441 client should be allowed onto the network. If a class parameter is
442 given, the client should be assigned to that class.
443 Compatibility: Specifying the class is an Undernet extension and ircd
444 does not support that parameter.
447 Syntax: R <id> <remoteip> <remoteport> <account> [class]
448 Example: R 5 192.168.1.10 23367 Buddha
449 States: REGISTER, HURRY
451 Comments: Indicates that the iauth instance believes the specified
452 client should be allowed onto the network, pre-authenticated to
453 the account listed. If a class parameter is given, the client
454 should be assigned to that class.
455 Compatibility: This is an Undernet extension and ircd does not support