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> :<userinfo ...>
 166 Example: 5 U buddha :Gautama Siddhartha
 167 States: REGISTER(1+)
 168 Next State: -
 169 Comments: Indicates the client's claimed username and "GECOS"
 170   information.  This information is not reliable.  This message is
 171   enabled by requesting the A policy.
 172 Compatibility: ircd does not include the <userinfo> data.
 173
 174 u - Client Username
 175 Syntax: <id> u <username>
 176 Example: 5 u notbuddha
 177 States: REGISTER(1)
 178 Next State: -
 179 Comments: Indicates a more reliable username for the client.
 180 Compatibility: This is an Undernet extension and ircd does not send
 181   it.  It is enabled by the iauth instance requesting the U policy.
 182
 183 n - Client Nickname
 184 Syntax: <id> n <nickname>
 185 Example: 5 n Buddha
 186 States: REGISTER(1+), HURRY
 187 Next State: -
 188 Comments: Indicates the client's requested nickname.
 189 Compatibility: This is an Undernet extension and ircd does not send
 190   it.  It is enabled by the iauth instance requesting the U policy.
 191
 192 H - Hurry Up
 193 Syntax: <id> H <class>
 194 Example: 5 H Others
 195 States: REGISTER
 196 Next State: HURRY
 197 Comments: Indicates that the server is ready to register the client
 198   except for needing a response from the iauth server.  <class> is
 199   a tentative connection class for the user, which will be used unless
 200   iauth overrides it in a D or R message.
 201 Compatibility: This is an Undernet extension and ircd does not send
 202   it.  It is enabled by the iauth instance requesting the U policy.
 203
 204 T - Client Registered
 205 Syntax: <id> T
 206 Example: 5 T
 207 States: HURRY
 208 Next State: NORMAL
 209 Comments: Indicates the server got tired of waiting for iauth to
 210   finish and the client is being accepted.  This message should
 211   never be sent when the R policy is in effect.
 212 Compatibility: ircd allows this message for clients in the REGISTER
 213   state.
 214
 215 E - Error
 216 Syntax: <id> E <type> :<additional text>
 217 Example: 5 E Gone
 218 States: N/A
 219 Next State: -
 220 Comments: Indicates that a message received from the iauth instance
 221   could not be rationally interpreted.  This may be because the client
 222   could not be found, the client was in an inappropriate state for the
 223   message, or for other reasons.  The <type> argument specifies the
 224   general type of error and <additional text> provides details.  <id>
 225   may be -1.
 226
 227 M - Server Name and Capacity
 228 Syntax: <id> M <servername> <capacity>
 229 Example: -1 M irc.example.org 20000
 230 States: GONE(1)
 231 Next State: -
 232 Comments: Indicates the server's name and upper bound on client
 233   identifiers.
 234 Compatibility: ircd does not include the <capacity> information.
 235   The <id> should be ignored: ircd sends 0 and ircu sends -1.
 236
 237 IAUTH MESSAGES
 238 ==============
 239
 240 X - Example Message Description
 241 Syntax: X <arguments>
 242 Example: X something
 243 Notify: yes
 244 States: N/A
 245 Next State: N/A
 246 Comments: This is an example message description.  Each message is a
 247   single character.  If the Notify field is present and says yes,
 248   interested operators (with SNO_AUTH set) should be notified of the
 249   message.  The States field, where present, indicate which states
 250   accept this message.  Clients in other states should ignore the
 251   message or treat it as an error.  The Next State field, where
 252   present, indicates what the next state should be for the client.
 253 Compatibility: If we believe ircu behavior is different than ircd's,
 254   this describes ircd's behavior or expectations.
 255
 256 > - Operator Notification
 257 Syntax: > :<message text>
 258 Example: > :Hello Operators!
 259 Notify: yes
 260 Comments: Contains a message that the iauth instance wants to send to
 261   interested operators.
 262
 263 G - Set Debug Level
 264 Syntax: G <level>
 265 Example: G 1
 266 Notify: yes
 267 Comments: Sets a debug level for the server's end of the iauth
 268   conversation.  When enabled, debug messages should be sent to the
 269   same channel (group, mask, etc) as other iauth notifications.
 270   Debug level 0 suppresses iauth-related debug output, and positive
 271   integers enable iauth debugging messages.
 272
 273 O - Set Policy Options
 274 Syntax: O <options>
 275 Example: O RTAWU
 276 Notify: yes
 277 Comments: Sets policy options for the iauth conversation.  Old policy
 278   options should be forgotten.  Valid policy options are:
 279    A - Send username and password information.
 280        This causes the server to send the U and P messages.
 281    R - Require clients to be approved before registering them.
 282        When this policy is in effect, it affects the behavior
 283        of a registration timeout; for details, see the documentation
 284        for the T server message.
 285    T - When the R policy is in effect and the iauth service does not
 286        respond for a client, this causes the server to count the number
 287        of clients refused, to send a warning message to interested
 288        operators periodically, and to send the count of rejected users
 289        to interested operators when the iauth instance responds again.
 290    U - Send nickname, confirmed username and hurry information.
 291        This causes the server to send the n, u and H messages.
 292    W - Allow extra time for iauth to respond based on hostname.
 293        When this policy is in effect and a DNS message (N or d) is
 294        sent for a client, that client's registration timeout is
 295        extended or reset.
 296 Compatibility: The U policy is an Undernet extension and is not
 297   recognized by ircd.
 298
 299 V - iauth Program Version
 300 Syntax: V :<version string>
 301 Example: V :Undernet-iauthu v1.0
 302 Notify: yes
 303 Comments: Indicates the iauth program version.  This should only be
 304   used in diagnostic messages, and must not change protocol behavior.
 305
 306 a - Start of new configuration
 307 Syntax: a
 308 Example: a
 309 Notify: yes
 310 Comments: Indicates that a new configuration is being loaded by the
 311   iauth instance.  Any cached configuration records should be cleared.
 312
 313 A - Configuration Information
 314 Syntax: A <hosts?> <module> :<options>
 315 Example: A * rfc931
 316 Notify: yes
 317 Comments: Indicates new configuration information.
 318
 319 s - Start of new statistics
 320 Syntax: s
 321 Example: s
 322 Notify: yes
 323 Comments: Indicates a new set of statistics will be sent.  Any cached
 324   statistics records should be cleared.
 325
 326 S - Statistics Information
 327 Syntax: S <module> :<module information>
 328 Example: S rfc931 connected 0 unix 0 other 0 bad 0 out of 0
 329 Notify: yes
 330 Comments: Indicates new or additional statistics information.
 331
 332 o - Forced Username
 333 Syntax: o <id> <remoteip> <remoteport> <username>
 334 Example: o 5 192.168.1.10 23367 bubba
 335 States: REGISTER, HURRY
 336 Next State: -
 337 Comments: Indicates that the username should be used for the specified
 338   client even if the normal sanity-checking would prohibit the
 339   username.
 340
 341 U - Trusted Username
 342 Syntax: U <id> <remoteip> <remoteport> <username>
 343 Example: U 5 192.168.1.10 23367 buddha
 344 States: REGISTER, HURRY
 345 Next State: -
 346 Comments: Indicates that the iauth instance believes <username> is
 347   accurate for the specified client.
 348
 349 u - Untrusted Username
 350 Syntax: u <id> <remoteip> <remoteport> <username>
 351 Example: u 5 192.168.1.10 23367 enlightened_one
 352 States: REGISTER, HURRY
 353 Next State: -
 354 Comments: Indicates that the iauth instance does not strongly trust
 355   <username> to be accurate, but has no more trusted username.
 356
 357 N - Client Hostname
 358 Syntax: N <id> <remoteip> <remoteport> <hostname>
 359 Example: N 5 192.168.1.10 23367 buddha.example.org
 360 States: REGISTER, HURRY
 361 Next State: -
 362 Comments: Indicates that the iauth instance believes the specified
 363   client should use the hostname given.
 364 Compatibility: This is an Undernet extension and ircd does not support
 365   this message.
 366
 367 I - Client IP Address
 368 Syntax: N <id> <currentip> <remoteport> <newip>
 369 Example: N 5 192.168.1.10 23367 127.128.129.130
 370 States: REGISTER, HURRY
 371 Next State: -
 372 Comments: Indicates that the iauth instance wants the server to
 373   present and treat the client as using <newip>.  This means that
 374   future iauth messages relating to the client must use <newip>
 375   as the <remoteip> parameter.
 376 Compatibility: This is an Undernet extension and ircd does not support
 377   this message.
 378
 379 C - Challenge User
 380 Syntax: C <id> <remoteip> <remoteport> :<challenge string>
 381 Example: C 5 192.168.1.10 23367 :In which year did Columbus sail the ocean blue?
 382 States: REGISTER, HURRY
 383 Next State: -
 384 Comments: Indicates that the challenge string should be sent to the
 385   specified user, for example via NOTICE AUTH :*** <challenge string>.
 386   The client responds by sending PASS :<response>, which should be
 387   relayed via the P server message.  This requires that the A policy
 388   be in effect.
 389 Compatibility: This is an Undernet extension and ircd does not support
 390   this message.
 391
 392 k - Quietly Kill Client
 393 Syntax: k <id> <remoteip> <remoteport> :<reason>
 394 Example: k 5 192.168.1.10 23367 :Open proxy found.
 395 States: REGISTER, HURRY, NORMAL
 396 Next State: GONE
 397 Comments: Indicates that the specified client should be disconnected
 398   for the reason given without notifying operators.
 399 Compatibility: ircu does not use the same notification mechanism as
 400   ircd, so operators are notified using SNO_CONNEXIT anyway.
 401
 402 K - Kill Client
 403 Syntax: K <id> <remoteip> <remoteport> :<reason>
 404 Example: K 5 192.168.1.10 23367 :We don't like you.
 405 States: REGISTER, HURRY, NORMAL
 406 Next State: GONE
 407 Comments: Indicates that the specified client should be disconnected
 408   for the reason given.  Operators should be notified.
 409
 410 D - Done Checking
 411 Syntax: D <id> <remoteip> <remoteport> [class]
 412 Example: D 5 192.168.1.10 23367
 413 States: REGISTER, HURRY
 414 Next State: NORMAL
 415 Comments: Indicates that the iauth instance believes the specified
 416   client should be allowed onto the network.  If a class parameter is
 417   given, the client should be assigned to that class.
 418 Compatibility: Specifying the class is an Undernet extension and ircd
 419   does not support that parameter.
 420
 421 R - Registered User
 422 Syntax: R <id> <remoteip> <remoteport> <account> [class]
 423 Example: R 5 192.168.1.10 23367 Buddha
 424 States: REGISTER, HURRY
 425 Next State: NORMAL
 426 Comments: Indicates that the iauth instance believes the specified
 427   client should be allowed onto the network, pre-authenticated to
 428   the account listed.  If a class parameter is given, the client
 429   should be assigned to that class.
 430 Compatibility: This is an Undernet extension and ircd does not support
 431   this message.