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 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 H - Hurry Up
 194 Syntax: <id> H <class>
 195 Example: 5 H Others
 196 States: REGISTER
 197 Next State: HURRY
 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.
 204
 205 T - Client Registered
 206 Syntax: <id> T
 207 Example: 5 T
 208 States: HURRY
 209 Next State: NORMAL
 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
 214   state.
 215
 216 E - Error
 217 Syntax: <id> E <type> :<additional text>
 218 Example: 5 E Gone
 219 States: N/A
 220 Next State: -
 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>
 226   may be -1.
 227
 228 M - Server Name and Capacity
 229 Syntax: <id> M <servername> <capacity>
 230 Example: -1 M irc.example.org 20000
 231 States: GONE(1)
 232 Next State: -
 233 Comments: Indicates the server's name and upper bound on client
 234   identifiers.
 235 Compatibility: ircd does not include the <capacity> information.
 236   The <id> should be ignored: ircd sends 0 and ircu sends -1.
 237
 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
 241 States: N/A
 242 Next State: -
 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
 248   of the reply.
 249 Compatibility: This is an Undernet extension and ircd does not send
 250   it.
 251
 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
 255 States: N/A
 256 Next State: -
 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
 263   it.
 264
 265 IAUTH MESSAGES
 266 ==============
 267
 268 X - Example Message Description
 269 Syntax: X <arguments>
 270 Example: X something
 271 Notify: yes
 272 States: N/A
 273 Next State: N/A
 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.
 284
 285 > - Operator Notification
 286 Syntax: > :<message text>
 287 Example: > :Hello Operators!
 288 Notify: yes
 289 Comments: Contains a message that the iauth instance wants to send to
 290   interested operators.
 291
 292 G - Set Debug Level
 293 Syntax: G <level>
 294 Example: G 1
 295 Notify: yes
 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.
 301
 302 O - Set Policy Options
 303 Syntax: O <options>
 304 Example: O RTAWU
 305 Notify: yes
 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
 324        extended or reset.
 325 Compatibility: The U policy is an Undernet extension and is not
 326   recognized by ircd.
 327
 328 V - iauth Program Version
 329 Syntax: V :<version string>
 330 Example: V :Undernet-iauthu v1.0
 331 Notify: yes
 332 Comments: Indicates the iauth program version.  This should only be
 333   used in diagnostic messages, and must not change protocol behavior.
 334
 335 a - Start of new configuration
 336 Syntax: a
 337 Example: a
 338 Notify: yes
 339 Comments: Indicates that a new configuration is being loaded by the
 340   iauth instance.  Any cached configuration records should be cleared.
 341
 342 A - Configuration Information
 343 Syntax: A <hosts?> <module> :<options>
 344 Example: A * rfc931
 345 Notify: yes
 346 Comments: Indicates new configuration information.
 347
 348 s - Start of new statistics
 349 Syntax: s
 350 Example: s
 351 Notify: yes
 352 Comments: Indicates a new set of statistics will be sent.  Any cached
 353   statistics records should be cleared.
 354
 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
 358 Notify: yes
 359 Comments: Indicates new or additional statistics information.
 360
 361 o - Forced Username
 362 Syntax: o <id> <remoteip> <remoteport> <username>
 363 Example: o 5 192.168.1.10 23367 bubba
 364 States: REGISTER, HURRY
 365 Next State: -
 366 Comments: Indicates that the username should be used for the specified
 367   client even if the normal sanity-checking would prohibit the
 368   username.
 369
 370 U - Trusted Username
 371 Syntax: U <id> <remoteip> <remoteport> <username>
 372 Example: U 5 192.168.1.10 23367 buddha
 373 States: REGISTER, HURRY
 374 Next State: -
 375 Comments: Indicates that the iauth instance believes <username> is
 376   accurate for the specified client.
 377
 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
 382 Next State: -
 383 Comments: Indicates that the iauth instance does not strongly trust
 384   <username> to be accurate, but has no more trusted username.
 385
 386 N - Client Hostname
 387 Syntax: N <id> <remoteip> <remoteport> <hostname>
 388 Example: N 5 192.168.1.10 23367 buddha.example.org
 389 States: REGISTER, HURRY
 390 Next State: -
 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
 394   this message.
 395
 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
 400 Next State: -
 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
 406   this message.
 407
 408 M - Adjust User Mode
 409 Syntax: M <id> <remoteip> <remoteport> +<mode changes>
 410 Example: M 5 192.168.1.10 23367 +iwg
 411 States: REGISTER, HURRY
 412 Next State: -
 413 Comments: Indicates a set of user mode changes to be applied to the
 414   client.
 415 Compatibility: This is an Undernet extension and ircd does not support
 416   this message.
 417
 418 C - Challenge User
 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
 422 Next State: -
 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
 427   be in effect.
 428 Compatibility: This is an Undernet extension and ircd does not support
 429   this message.
 430
 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
 435 Next State: GONE
 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.
 440
 441 K - Kill Client
 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
 445 Next State: GONE
 446 Comments: Indicates that the specified client should be disconnected
 447   for the reason given.  Operators should be notified.
 448
 449 d - "Soft" Done Checking
 450 Syntax: d <id> <remoteip> <remoteport>
 451 Example: d 5 192.168.1.10 23367
 452 States: REGISTER, HURRY
 453 Next State: -
 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
 459   this message.
 460
 461 D - Done Checking
 462 Syntax: D <id> <remoteip> <remoteport> [class]
 463 Example: D 5 192.168.1.10 23367
 464 States: REGISTER, HURRY
 465 Next State: NORMAL
 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.
 471
 472 R - Registered User
 473 Syntax: R <id> <remoteip> <remoteport> <account> [class]
 474 Example: R 5 192.168.1.10 23367 Buddha
 475 States: REGISTER, HURRY
 476 Next State: NORMAL
 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
 482   this message.
 483
 484 X - Extension Query
 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
 494   this message.