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 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 IAUTH MESSAGES
 239 ==============
 240
 241 X - Example Message Description
 242 Syntax: X <arguments>
 243 Example: X something
 244 Notify: yes
 245 States: N/A
 246 Next State: N/A
 247 Comments: This is an example message description.  Each message is a
 248   single character.  If the Notify field is present and says yes,
 249   interested operators (with SNO_AUTH set) should be notified of the
 250   message.  The States field, where present, indicate which states
 251   accept this message.  Clients in other states should ignore the
 252   message or treat it as an error.  The Next State field, where
 253   present, indicates what the next state should be for the client.
 254 Compatibility: If we believe ircu behavior is different than ircd's,
 255   this describes ircd's behavior or expectations.
 256
 257 > - Operator Notification
 258 Syntax: > :<message text>
 259 Example: > :Hello Operators!
 260 Notify: yes
 261 Comments: Contains a message that the iauth instance wants to send to
 262   interested operators.
 263
 264 G - Set Debug Level
 265 Syntax: G <level>
 266 Example: G 1
 267 Notify: yes
 268 Comments: Sets a debug level for the server's end of the iauth
 269   conversation.  When enabled, debug messages should be sent to the
 270   same channel (group, mask, etc) as other iauth notifications.
 271   Debug level 0 suppresses iauth-related debug output, and positive
 272   integers enable iauth debugging messages.
 273
 274 O - Set Policy Options
 275 Syntax: O <options>
 276 Example: O RTAWU
 277 Notify: yes
 278 Comments: Sets policy options for the iauth conversation.  Old policy
 279   options should be forgotten.  Valid policy options are:
 280    A - Send username and password information.
 281        This causes the server to send the U and P messages.
 282    R - Require clients to be approved before registering them.
 283        When this policy is in effect, it affects the behavior
 284        of a registration timeout; for details, see the documentation
 285        for the T server message.
 286    T - When the R policy is in effect and the iauth service does not
 287        respond for a client, this causes the server to count the number
 288        of clients refused, to send a warning message to interested
 289        operators periodically, and to send the count of rejected users
 290        to interested operators when the iauth instance responds again.
 291    U - Send nickname, confirmed username and hurry information.
 292        This causes the server to send the n, u and H messages.
 293    W - Allow extra time for iauth to respond based on hostname.
 294        When this policy is in effect and a DNS message (N or d) is
 295        sent for a client, that client's registration timeout is
 296        extended or reset.
 297 Compatibility: The U policy is an Undernet extension and is not
 298   recognized by ircd.
 299
 300 V - iauth Program Version
 301 Syntax: V :<version string>
 302 Example: V :Undernet-iauthu v1.0
 303 Notify: yes
 304 Comments: Indicates the iauth program version.  This should only be
 305   used in diagnostic messages, and must not change protocol behavior.
 306
 307 a - Start of new configuration
 308 Syntax: a
 309 Example: a
 310 Notify: yes
 311 Comments: Indicates that a new configuration is being loaded by the
 312   iauth instance.  Any cached configuration records should be cleared.
 313
 314 A - Configuration Information
 315 Syntax: A <hosts?> <module> :<options>
 316 Example: A * rfc931
 317 Notify: yes
 318 Comments: Indicates new configuration information.
 319
 320 s - Start of new statistics
 321 Syntax: s
 322 Example: s
 323 Notify: yes
 324 Comments: Indicates a new set of statistics will be sent.  Any cached
 325   statistics records should be cleared.
 326
 327 S - Statistics Information
 328 Syntax: S <module> :<module information>
 329 Example: S rfc931 connected 0 unix 0 other 0 bad 0 out of 0
 330 Notify: yes
 331 Comments: Indicates new or additional statistics information.
 332
 333 o - Forced Username
 334 Syntax: o <id> <remoteip> <remoteport> <username>
 335 Example: o 5 192.168.1.10 23367 bubba
 336 States: REGISTER, HURRY
 337 Next State: -
 338 Comments: Indicates that the username should be used for the specified
 339   client even if the normal sanity-checking would prohibit the
 340   username.
 341
 342 U - Trusted Username
 343 Syntax: U <id> <remoteip> <remoteport> <username>
 344 Example: U 5 192.168.1.10 23367 buddha
 345 States: REGISTER, HURRY
 346 Next State: -
 347 Comments: Indicates that the iauth instance believes <username> is
 348   accurate for the specified client.
 349
 350 u - Untrusted Username
 351 Syntax: u <id> <remoteip> <remoteport> <username>
 352 Example: u 5 192.168.1.10 23367 enlightened_one
 353 States: REGISTER, HURRY
 354 Next State: -
 355 Comments: Indicates that the iauth instance does not strongly trust
 356   <username> to be accurate, but has no more trusted username.
 357
 358 N - Client Hostname
 359 Syntax: N <id> <remoteip> <remoteport> <hostname>
 360 Example: N 5 192.168.1.10 23367 buddha.example.org
 361 States: REGISTER, HURRY
 362 Next State: -
 363 Comments: Indicates that the iauth instance believes the specified
 364   client should use the hostname given.
 365 Compatibility: This is an Undernet extension and ircd does not support
 366   this message.
 367
 368 I - Client IP Address
 369 Syntax: N <id> <currentip> <remoteport> <newip>
 370 Example: N 5 192.168.1.10 23367 127.128.129.130
 371 States: REGISTER, HURRY
 372 Next State: -
 373 Comments: Indicates that the iauth instance wants the server to
 374   present and treat the client as using <newip>.  This means that
 375   future iauth messages relating to the client must use <newip>
 376   as the <remoteip> parameter.
 377 Compatibility: This is an Undernet extension and ircd does not support
 378   this message.
 379
 380 C - Challenge User
 381 Syntax: C <id> <remoteip> <remoteport> :<challenge string>
 382 Example: C 5 192.168.1.10 23367 :In which year did Columbus sail the ocean blue?
 383 States: REGISTER, HURRY
 384 Next State: -
 385 Comments: Indicates that the challenge string should be sent to the
 386   specified user, for example via NOTICE AUTH :*** <challenge string>.
 387   The client responds by sending PASS :<response>, which should be
 388   relayed via the P server message.  This requires that the A policy
 389   be in effect.
 390 Compatibility: This is an Undernet extension and ircd does not support
 391   this message.
 392
 393 k - Quietly Kill Client
 394 Syntax: k <id> <remoteip> <remoteport> :<reason>
 395 Example: k 5 192.168.1.10 23367 :Open proxy found.
 396 States: REGISTER, HURRY, NORMAL
 397 Next State: GONE
 398 Comments: Indicates that the specified client should be disconnected
 399   for the reason given without notifying operators.
 400 Compatibility: ircu does not use the same notification mechanism as
 401   ircd, so operators are notified using SNO_CONNEXIT anyway.
 402
 403 K - Kill Client
 404 Syntax: K <id> <remoteip> <remoteport> :<reason>
 405 Example: K 5 192.168.1.10 23367 :We don't like you.
 406 States: REGISTER, HURRY, NORMAL
 407 Next State: GONE
 408 Comments: Indicates that the specified client should be disconnected
 409   for the reason given.  Operators should be notified.
 410
 411 D - Done Checking
 412 Syntax: D <id> <remoteip> <remoteport> [class]
 413 Example: D 5 192.168.1.10 23367
 414 States: REGISTER, HURRY
 415 Next State: NORMAL
 416 Comments: Indicates that the iauth instance believes the specified
 417   client should be allowed onto the network.  If a class parameter is
 418   given, the client should be assigned to that class.
 419 Compatibility: Specifying the class is an Undernet extension and ircd
 420   does not support that parameter.
 421
 422 R - Registered User
 423 Syntax: R <id> <remoteip> <remoteport> <account> [class]
 424 Example: R 5 192.168.1.10 23367 Buddha
 425 States: REGISTER, HURRY
 426 Next State: NORMAL
 427 Comments: Indicates that the iauth instance believes the specified
 428   client should be allowed onto the network, pre-authenticated to
 429   the account listed.  If a class parameter is given, the client
 430   should be assigned to that class.
 431 Compatibility: This is an Undernet extension and ircd does not support
 432   this message.