doc/readme.iauth

   1 OVERVIEW
   2 ========
   3
   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.
  10
  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.
  14
  15 STARTING IAUTH
  16 ==============
  17
  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.
  25
  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.
  30
  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.
  36
  37 When the iauth instance starts, it sends a V message to indicate its
  38 version.
  39
  40 The server should provide /stats subcommands that report the iauth
  41 instance's version, configuration and statistics.
  42
  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.
  48
  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.
  54
  55 CLIENT STATES
  56 =============
  57
  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
  62 transition.
  63
  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.
  69
  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.
  75
  76 POLICIES AND USE CASES
  77 ======================
  78
  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
  84 client.
  85
  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.
  89
  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.
  95
  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
  98 message.
  99
 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.
 102
 103 SERVER MESSAGES
 104 ===============
 105
 106 X - Example Message Description
 107 Syntax: <id> X <several> <arguments>
 108 Example: 5 X arguments vary
 109 States: REGISTER(1), HURRY, NORMAL
 110 Next State: -
 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
 118   type.
 119 Compatibility: If we believe ircu behavior is different than ircd's,
 120   this describes ircd's behavior or expectations.
 121
 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
 125 States: GONE
 126 Next State: REGISTER
 127 Comments: Indicates that <localport> on <localip> accepted a client
 128   connection from <remoteport> on <remoteip>.
 129
 130 D - Client Disconnect
 131 Syntax: <id> D
 132 Example: 5 D
 133 States: REGISTER, HURRY, NORMAL
 134 Next State: GONE
 135 Comments: Indicates that a client is disconnecting from the server.
 136
 137 N - Hostname Received
 138 Syntax: <id> N <hostname>
 139 Example: 5 N host-1-10.example.org
 140 States: REGISTER(1)
 141 Next State: -
 142 Comments: Indicates that the server received hostname information for
 143   a client.  Only one of 'N' and 'd' is sent.
 144
 145 d - Hostname Timeout
 146 Syntax: <id> d
 147 Example: 5 d
 148 States: REGISTER(1)
 149 Next State: -
 150 Comments: Indicates that the server did not receive hostname
 151   information for a client in a timely fashion.  Only one of 'N' and
 152   'd' is sent.
 153
 154 P - Client Password
 155 Syntax: <id> P :<password ...>
 156 Example: 5 P :buddha n1rvan4
 157 States: REGISTER
 158 Next State: -
 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.
 163
 164 U - Client Username
 165 Syntax: <id> U <username> <hostname> <servername> :<userinfo ...>
 166 Example: 5 U buddha bodhisattva.example.com irc.undernet.org :Gautama Siddhartha
 167 States: REGISTER(1+)
 168 Next State: -
 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
 172   the A policy.
 173 Compatibility: ircd only sends the <username> parameter.
 174
 175 u - Client Username
 176 Syntax: <id> u <username>
 177 Example: 5 u notbuddha
 178 States: REGISTER(1)
 179 Next State: -
 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.
 183
 184 n - Client Nickname
 185 Syntax: <id> n <nickname>
 186 Example: 5 n Buddha
 187 States: REGISTER(1+), HURRY
 188 Next State: -
 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.
 192
 193 L - Login On Connect
 194 Syntax: <id> L <account>[:<accountstamp>][ <fakehost>]
 195 Example: 5 L Buddha Buddha.TestNet.com
 196 States: REGISTER(1)
 197 Next State: -
 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
 204   reject the client.
 205 Compatibility: This is an extension of the IRCu-Patchset.
 206
 207 H - Hurry Up
 208 Syntax: <id> H <class>
 209 Example: 5 H Others
 210 States: REGISTER
 211 Next State: HURRY
 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.
 218
 219 T - Client Registered
 220 Syntax: <id> T
 221 Example: 5 T
 222 States: HURRY
 223 Next State: NORMAL
 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
 228   state.
 229
 230 E - Error
 231 Syntax: <id> E <type> :<additional text>
 232 Example: 5 E Gone
 233 States: N/A
 234 Next State: -
 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>
 240   may be -1.
 241
 242 M - Server Name and Capacity
 243 Syntax: <id> M <servername> <capacity>
 244 Example: -1 M irc.example.org 20000
 245 States: GONE(1)
 246 Next State: -
 247 Comments: Indicates the server's name and upper bound on client
 248   identifiers.
 249 Compatibility: ircd does not include the <capacity> information.
 250   The <id> should be ignored: ircd sends 0 and ircu sends -1.
 251
 252 IAUTH MESSAGES
 253 ==============
 254
 255 X - Example Message Description
 256 Syntax: X <arguments>
 257 Example: X something
 258 Notify: yes
 259 States: N/A
 260 Next State: N/A
 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.
 270
 271 > - Operator Notification
 272 Syntax: > :<message text>
 273 Example: > :Hello Operators!
 274 Notify: yes
 275 Comments: Contains a message that the iauth instance wants to send to
 276   interested operators.
 277
 278 G - Set Debug Level
 279 Syntax: G <level>
 280 Example: G 1
 281 Notify: yes
 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.
 287
 288 O - Set Policy Options
 289 Syntax: O <options>
 290 Example: O RTAWU
 291 Notify: yes
 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
 310        extended or reset.
 311 Compatibility: The U policy is an Undernet extension and is not
 312   recognized by ircd.
 313
 314 V - iauth Program Version
 315 Syntax: V :<version string>
 316 Example: V :Undernet-iauthu v1.0
 317 Notify: yes
 318 Comments: Indicates the iauth program version.  This should only be
 319   used in diagnostic messages, and must not change protocol behavior.
 320
 321 a - Start of new configuration
 322 Syntax: a
 323 Example: a
 324 Notify: yes
 325 Comments: Indicates that a new configuration is being loaded by the
 326   iauth instance.  Any cached configuration records should be cleared.
 327
 328 A - Configuration Information
 329 Syntax: A <hosts?> <module> :<options>
 330 Example: A * rfc931
 331 Notify: yes
 332 Comments: Indicates new configuration information.
 333
 334 s - Start of new statistics
 335 Syntax: s
 336 Example: s
 337 Notify: yes
 338 Comments: Indicates a new set of statistics will be sent.  Any cached
 339   statistics records should be cleared.
 340
 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
 344 Notify: yes
 345 Comments: Indicates new or additional statistics information.
 346
 347 o - Forced Username
 348 Syntax: o <id> <remoteip> <remoteport> <username>
 349 Example: o 5 192.168.1.10 23367 bubba
 350 States: REGISTER, HURRY
 351 Next State: -
 352 Comments: Indicates that the username should be used for the specified
 353   client even if the normal sanity-checking would prohibit the
 354   username.
 355
 356 U - Trusted Username
 357 Syntax: U <id> <remoteip> <remoteport> <username>
 358 Example: U 5 192.168.1.10 23367 buddha
 359 States: REGISTER, HURRY
 360 Next State: -
 361 Comments: Indicates that the iauth instance believes <username> is
 362   accurate for the specified client.
 363
 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
 368 Next State: -
 369 Comments: Indicates that the iauth instance does not strongly trust
 370   <username> to be accurate, but has no more trusted username.
 371
 372 N - Client Hostname
 373 Syntax: N <id> <remoteip> <remoteport> <hostname>
 374 Example: N 5 192.168.1.10 23367 buddha.example.org
 375 States: REGISTER, HURRY
 376 Next State: -
 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
 380   this message.
 381
 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
 386 Next State: -
 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
 392   this message.
 393
 394 M - Adjust User Mode
 395 Syntax: M <id> <remoteip> <remoteport> +<mode changes>
 396 Example: M 5 192.168.1.10 23367 +iwg
 397 States: REGISTER, HURRY
 398 Next State: -
 399 Comments: Indicates a set of user mode changes to be applied to the
 400   client.
 401 Compatibility: This is an Undernet extension and ircd does not support
 402   this message.
 403
 404 C - Challenge User
 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
 408 Next State: -
 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
 413   be in effect.
 414 Compatibility: This is an Undernet extension and ircd does not support
 415   this message.
 416
 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
 421 Next State: GONE
 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.
 426
 427 K - Kill Client
 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
 431 Next State: GONE
 432 Comments: Indicates that the specified client should be disconnected
 433   for the reason given.  Operators should be notified.
 434
 435 D - Done Checking
 436 Syntax: D <id> <remoteip> <remoteport> [class]
 437 Example: D 5 192.168.1.10 23367
 438 States: REGISTER, HURRY
 439 Next State: NORMAL
 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.
 445
 446 R - Registered User
 447 Syntax: R <id> <remoteip> <remoteport> <account> [class]
 448 Example: R 5 192.168.1.10 23367 Buddha
 449 States: REGISTER, HURRY
 450 Next State: NORMAL
 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
 456   this message.