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.  This is an example, not a description of the
 118   actual X message.
 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 Syntax: <id> u
 178 Example: 5 u notbuddha
 179 States: REGISTER(1)
 180 Next State: -
 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.
 185
 186 n - Client Nickname
 187 Syntax: <id> n <nickname>
 188 Example: 5 n Buddha
 189 States: REGISTER(1+), HURRY
 190 Next State: -
 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.
 194
 195 H - Hurry Up
 196 Syntax: <id> H <class>
 197 Example: 5 H Others
 198 States: REGISTER
 199 Next State: HURRY
 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.
 206
 207 T - Client Registered
 208 Syntax: <id> T
 209 Example: 5 T
 210 States: HURRY
 211 Next State: NORMAL
 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
 216   state.
 217
 218 E - Error
 219 Syntax: <id> E <type> :<additional text>
 220 Example: 5 E Gone
 221 States: N/A
 222 Next State: -
 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>
 228   may be -1.
 229
 230 M - Server Name and Capacity
 231 Syntax: <id> M <servername> <capacity>
 232 Example: -1 M irc.example.org 20000
 233 States: GONE(1)
 234 Next State: -
 235 Comments: Indicates the server's name and upper bound on client
 236   identifiers.
 237 Compatibility: ircd does not include the <capacity> information.
 238   The <id> should be ignored: ircd sends 0 and ircu sends -1.
 239
 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
 243 States: N/A
 244 Next State: -
 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
 250   of the reply.
 251 Compatibility: This is an Undernet extension and ircd does not send
 252   it.
 253
 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
 257 States: N/A
 258 Next State: -
 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
 265   it.
 266
 267 IAUTH MESSAGES
 268 ==============
 269
 270 X - Example Message Description
 271 Syntax: X <arguments>
 272 Example: X something
 273 Notify: yes
 274 States: N/A
 275 Next State: N/A
 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.
 286
 287 > - Operator Notification
 288 Syntax: > :<message text>
 289 Example: > :Hello Operators!
 290 Notify: yes
 291 Comments: Contains a message that the iauth instance wants to send to
 292   interested operators.
 293
 294 G - Set Debug Level
 295 Syntax: G <level>
 296 Example: G 1
 297 Notify: yes
 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.
 303
 304 O - Set Policy Options
 305 Syntax: O <options>
 306 Example: O RTAWU
 307 Notify: yes
 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
 326        extended or reset.
 327 Compatibility: The U policy is an Undernet extension and is not
 328   recognized by ircd.
 329
 330 V - iauth Program Version
 331 Syntax: V :<version string>
 332 Example: V :Undernet-iauthu v1.0
 333 Notify: yes
 334 Comments: Indicates the iauth program version.  This should only be
 335   used in diagnostic messages, and must not change protocol behavior.
 336
 337 a - Start of new configuration
 338 Syntax: a
 339 Example: a
 340 Notify: yes
 341 Comments: Indicates that a new configuration is being loaded by the
 342   iauth instance.  Any cached configuration records should be cleared.
 343
 344 A - Configuration Information
 345 Syntax: A <hosts?> <module> :<options>
 346 Example: A * rfc931
 347 Notify: yes
 348 Comments: Indicates new configuration information.
 349
 350 s - Start of new statistics
 351 Syntax: s
 352 Example: s
 353 Notify: yes
 354 Comments: Indicates a new set of statistics will be sent.  Any cached
 355   statistics records should be cleared.
 356
 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
 360 Notify: yes
 361 Comments: Indicates new or additional statistics information.
 362
 363 o - Forced Username
 364 Syntax: o <id> <remoteip> <remoteport> <username>
 365 Example: o 5 192.168.1.10 23367 bubba
 366 States: REGISTER, HURRY
 367 Next State: -
 368 Comments: Indicates that the username should be used for the specified
 369   client even if the normal sanity-checking would prohibit the
 370   username.
 371
 372 U - Trusted Username
 373 Syntax: U <id> <remoteip> <remoteport> <username>
 374 Example: U 5 192.168.1.10 23367 buddha
 375 States: REGISTER, HURRY
 376 Next State: -
 377 Comments: Indicates that the iauth instance believes <username> is
 378   accurate for the specified client.
 379
 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
 384 Next State: -
 385 Comments: Indicates that the iauth instance does not strongly trust
 386   <username> to be accurate, but has no more trusted username.
 387
 388 N - Client Hostname
 389 Syntax: N <id> <remoteip> <remoteport> <hostname>
 390 Example: N 5 192.168.1.10 23367 buddha.example.org
 391 States: REGISTER, HURRY
 392 Next State: -
 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
 396   this message.
 397
 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
 402 Next State: -
 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
 408   this message.
 409
 410 M - Adjust User Mode
 411 Syntax: M <id> <remoteip> <remoteport> +<mode changes>
 412 Example: M 5 192.168.1.10 23367 +iwg
 413 States: REGISTER, HURRY
 414 Next State: -
 415 Comments: Indicates a set of user mode changes to be applied to the
 416   client.
 417 Compatibility: This is an Undernet extension and ircd does not support
 418   this message.
 419
 420 C - Challenge User
 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
 424 Next State: -
 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
 429   be in effect.
 430 Compatibility: This is an Undernet extension and ircd does not support
 431   this message.
 432
 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
 437 Next State: GONE
 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.
 442
 443 K - Kill Client
 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
 447 Next State: GONE
 448 Comments: Indicates that the specified client should be disconnected
 449   for the reason given.  Operators should be notified.
 450
 451 d - "Soft" Done Checking
 452 Syntax: d <id> <remoteip> <remoteport>
 453 Example: d 5 192.168.1.10 23367
 454 States: REGISTER, HURRY
 455 Next State: -
 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
 461   this message.
 462
 463 D - Done Checking
 464 Syntax: D <id> <remoteip> <remoteport> [class]
 465 Example: D 5 192.168.1.10 23367
 466 States: REGISTER, HURRY
 467 Next State: NORMAL
 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.
 473
 474 R - Registered User
 475 Syntax: R <id> <remoteip> <remoteport> <account> [class]
 476 Example: R 5 192.168.1.10 23367 Buddha
 477 States: REGISTER, HURRY
 478 Next State: NORMAL
 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
 484   this message.
 485
 486 X - Extension Query
 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
 496   this message.