OVERVIEW ======== The iauth protocol used here is based on the one in irc2.11.1, with minor changes to support challenge-response protocols and login-on-connect. Reference to that version's iauth-internals.txt and source code may be useful. For clarity, this document uses "server" to refer to any IRC server implementing this protocol, "ircu" to refer to Undernet ircd, and "ircd" to refer to IRCnet ircd. Certain messages are relayed to interested operators. ircu implements this by using the 131072 (SNO_AUTH) server notice mask. ircd implements this by using the &AUTH local channel. STARTING IAUTH ============== The path to the iauth program is specified in the server configuration file. The server spawns that program when reading the configuration file or when the previous iauth instance terminates. To protect against a series of crashes, the server will refuse to restart an iauth instance that it spawned in the last five seconds. A rehash operation will clear this behavior. The server and iauth instance communicate over the iauth instance's stdin and stdout. Every message from the server to the iauth instance is a single line. The line starts with an integer client identifier. This may be -1 to indicate no particular client or a non-negative number to indicate a client connected to the server. When the server starts the iauth instance, it sends a line formatted like "-1 M irc.example.org 20000" to indicate its name and an exclusive upper bound on valid client identifiers. In that example, possible client identifiers would be from 0 through 19999 inclusive. This upper bound is called MAXCONNECTIONS in the server code. When the iauth instance starts, it sends a V message to indicate its version. The server should provide /stats subcommands that report the iauth instance's version, configuration and statistics. Line formats in both direction are IRC-like in format: space characters separate arguments and a colon at the start of an argument indicates that the remainder of the line is one argument. To avoid problems, IPv6 address arguments with a leading colon may have to be prefixed with a 0 -- for example, ::1 sent as 0::1. When the iauth instance sends messages that relate to a particular client, that client is identified by three parameters from the server's Client Introduction message (, and ). If any of these disagree with the server's current user tables, it is an error. CLIENT STATES ============= Each client is conceptually in one of four states: GONE, REGISTER, HURRY or NORMAL. Each client starts in the GONE state. Certain messages from the server signal a client's transition from one state to another, and certain messages from the iauth instance cause a state transition. To be pedantic, the REGISTER state is a collection of sub-states since certain commands must occur at most and/or at least one time during the REGISTER state. The distinctions between these sub-states are distracting and not important, so they are described as one state and the repetition limitations are described for each command. The rationale for the HURRY state is to give explicit input to the iauth instance as to when the server believes it has sent the complete set of data for the client. Rather than defining the complete set of information in this protocol document, that is left to the server. ircd does not indicate this state. POLICIES AND USE CASES ====================== The historical application of iauth has been to block users that appear to be drones early, before they have a chance to disrupt the network, and without affecting other users on the same host (which K-lines do). This protocol extends that application by adding the n server message and by allowing challenge-response exchanges with the client. Eventually it would be nice to move the DNS and ident lookups into iauth, and remove that code from the IRC server. ircd already does this; since ircu does not, it adds the u server message. For trusted proxies, this protocol gives the capability for clients connecting through those proxies to be displayed with their actual username, IP address and hostname. The same functions allow other clients to use iauth-assigned spoofs, for example to hide the IP addresses used by operators. This protocol allows login-on-connect, for example by clients that send their account name and password in PASS, through the R iauth message. This protocol allows iauth to assign a client to a particular class by specifying a class name in the D or R iauth message. SERVER MESSAGES =============== X - Example Message Description Syntax: X Example: 5 X arguments vary States: REGISTER(1), HURRY, NORMAL Next State: - Comments: This is an example message description. Each message is a single character. The States field indicates which states the message may occur in and any restrictions on how many times the message may be sent during those states (restrictions only make sense when Next State is -). The Next State field indicates which new state is implied by the message; a hyphen indicates no state change is implied. The X (Example) message is not a real message type. Compatibility: If we believe ircu behavior is different than ircd's, this describes ircd's behavior or expectations. C - Client Introduction Syntax: C Example: 5 C 192.168.1.10 23367 192.168.0.1 6667 States: GONE Next State: REGISTER Comments: Indicates that on accepted a client connection from on . D - Client Disconnect Syntax: D Example: 5 D States: REGISTER, HURRY, NORMAL Next State: GONE Comments: Indicates that a client is disconnecting from the server. N - Hostname Received Syntax: N Example: 5 N host-1-10.example.org States: REGISTER(1) Next State: - Comments: Indicates that the server received hostname information for a client. Only one of 'N' and 'd' is sent. d - Hostname Timeout Syntax: d Example: 5 d States: REGISTER(1) Next State: - Comments: Indicates that the server did not receive hostname information for a client in a timely fashion. Only one of 'N' and 'd' is sent. P - Client Password Syntax: P : Example: 5 P :buddha n1rvan4 States: REGISTER Next State: - Comments: Indicates the client's password information. This may be a traditional client password, an account and pass phrase pair, or the response to a challenge (see the iauth C message). This message is enabled by requesting the A policy. U - Client Username Syntax: U : Example: 5 U buddha bodhisattva.example.com irc.undernet.org :Gautama Siddhartha States: REGISTER(1+) Next State: - Comments: Indicates the client's claimed username and "GECOS" information, along with client hostname and server name. This information is not reliable. This message is enabled by requesting the A policy. Compatibility: ircd only sends the parameter. u - Client Username Syntax: u Example: 5 u notbuddha States: REGISTER(1) Next State: - Comments: Indicates a more reliable username for the client. Compatibility: This is an Undernet extension and ircd does not send it. It is enabled by the iauth instance requesting the U policy. n - Client Nickname Syntax: n Example: 5 n Buddha States: REGISTER(1+), HURRY Next State: - Comments: Indicates the client's requested nickname. Compatibility: This is an Undernet extension and ircd does not send it. It is enabled by the iauth instance requesting the U policy. L - Login On Connect Syntax: L [:][ ] Example: 5 L Buddha Buddha.TestNet.com States: REGISTER(1) Next State: - Comments: Indicates a successfull LOC query. If the LOC query failed, no message is sent but the iauthd must assume that the query failed or was not done when it goes into the HURRY state. The user gets automatically set "+xr ". If is set, it also gets "+f ". The iauthd cannot overwrite these settings. If the iauthd believes them to be wrong, it must reject the client. Compatibility: This is an extension of the IRCu-Patchset. H - Hurry Up Syntax: H Example: 5 H Others States: REGISTER Next State: HURRY Comments: Indicates that the server is ready to register the client except for needing a response from the iauth server. is a tentative connection class for the user, which will be used unless iauth overrides it in a D or R message. Compatibility: This is an Undernet extension and ircd does not send it. It is enabled by the iauth instance requesting the U policy. T - Client Registered Syntax: T Example: 5 T States: HURRY Next State: NORMAL Comments: Indicates the server got tired of waiting for iauth to finish and the client is being accepted. This message should never be sent when the R policy is in effect. Compatibility: ircd allows this message for clients in the REGISTER state. E - Error Syntax: E : Example: 5 E Gone States: N/A Next State: - Comments: Indicates that a message received from the iauth instance could not be rationally interpreted. This may be because the client could not be found, the client was in an inappropriate state for the message, or for other reasons. The argument specifies the general type of error and provides details. may be -1. M - Server Name and Capacity Syntax: M Example: -1 M irc.example.org 20000 States: GONE(1) Next State: - Comments: Indicates the server's name and upper bound on client identifiers. Compatibility: ircd does not include the information. The should be ignored: ircd sends 0 and ircu sends -1. IAUTH MESSAGES ============== X - Example Message Description Syntax: X Example: X something Notify: yes States: N/A Next State: N/A Comments: This is an example message description. Each message is a single character. If the Notify field is present and says yes, interested operators (with SNO_AUTH set) should be notified of the message. The States field, where present, indicate which states accept this message. Clients in other states should ignore the message or treat it as an error. The Next State field, where present, indicates what the next state should be for the client. Compatibility: If we believe ircu behavior is different than ircd's, this describes ircd's behavior or expectations. > - Operator Notification Syntax: > : Example: > :Hello Operators! Notify: yes Comments: Contains a message that the iauth instance wants to send to interested operators. G - Set Debug Level Syntax: G Example: G 1 Notify: yes Comments: Sets a debug level for the server's end of the iauth conversation. When enabled, debug messages should be sent to the same channel (group, mask, etc) as other iauth notifications. Debug level 0 suppresses iauth-related debug output, and positive integers enable iauth debugging messages. O - Set Policy Options Syntax: O Example: O RTAWU Notify: yes Comments: Sets policy options for the iauth conversation. Old policy options should be forgotten. Valid policy options are: A - Send username and password information. This causes the server to send the U and P messages. R - Require clients to be approved before registering them. When this policy is in effect, it affects the behavior of a registration timeout; for details, see the documentation for the T server message. T - When the R policy is in effect and the iauth service does not respond for a client, this causes the server to count the number of clients refused, to send a warning message to interested operators periodically, and to send the count of rejected users to interested operators when the iauth instance responds again. U - Send nickname, confirmed username and hurry information. This causes the server to send the n, u and H messages. W - Allow extra time for iauth to respond based on hostname. When this policy is in effect and a DNS message (N or d) is sent for a client, that client's registration timeout is extended or reset. Compatibility: The U policy is an Undernet extension and is not recognized by ircd. V - iauth Program Version Syntax: V : Example: V :Undernet-iauthu v1.0 Notify: yes Comments: Indicates the iauth program version. This should only be used in diagnostic messages, and must not change protocol behavior. a - Start of new configuration Syntax: a Example: a Notify: yes Comments: Indicates that a new configuration is being loaded by the iauth instance. Any cached configuration records should be cleared. A - Configuration Information Syntax: A : Example: A * rfc931 Notify: yes Comments: Indicates new configuration information. s - Start of new statistics Syntax: s Example: s Notify: yes Comments: Indicates a new set of statistics will be sent. Any cached statistics records should be cleared. S - Statistics Information Syntax: S : Example: S rfc931 connected 0 unix 0 other 0 bad 0 out of 0 Notify: yes Comments: Indicates new or additional statistics information. o - Forced Username Syntax: o Example: o 5 192.168.1.10 23367 bubba States: REGISTER, HURRY Next State: - Comments: Indicates that the username should be used for the specified client even if the normal sanity-checking would prohibit the username. U - Trusted Username Syntax: U Example: U 5 192.168.1.10 23367 buddha States: REGISTER, HURRY Next State: - Comments: Indicates that the iauth instance believes is accurate for the specified client. u - Untrusted Username Syntax: u Example: u 5 192.168.1.10 23367 enlightened_one States: REGISTER, HURRY Next State: - Comments: Indicates that the iauth instance does not strongly trust to be accurate, but has no more trusted username. N - Client Hostname Syntax: N Example: N 5 192.168.1.10 23367 buddha.example.org States: REGISTER, HURRY Next State: - Comments: Indicates that the iauth instance believes the specified client should use the hostname given. Compatibility: This is an Undernet extension and ircd does not support this message. I - Client IP Address Syntax: I Example: I 5 192.168.1.10 23367 127.128.129.130 States: REGISTER, HURRY Next State: - Comments: Indicates that the iauth instance wants the server to present and treat the client as using . This means that future iauth messages relating to the client must use as the parameter. Compatibility: This is an Undernet extension and ircd does not support this message. M - Adjust User Mode Syntax: M + Example: M 5 192.168.1.10 23367 +iwg States: REGISTER, HURRY Next State: - Comments: Indicates a set of user mode changes to be applied to the client. Compatibility: This is an Undernet extension and ircd does not support this message. C - Challenge User Syntax: C : Example: C 5 192.168.1.10 23367 :In which year did Columbus sail the ocean blue? States: REGISTER, HURRY Next State: - Comments: Indicates that the challenge string should be sent to the specified user, for example via NOTICE AUTH :*** . The client responds by sending PASS :, which should be relayed via the P server message. This requires that the A policy be in effect. Compatibility: This is an Undernet extension and ircd does not support this message. k - Quietly Kill Client Syntax: k : Example: k 5 192.168.1.10 23367 :Open proxy found. States: REGISTER, HURRY, NORMAL Next State: GONE Comments: Indicates that the specified client should be disconnected for the reason given without notifying operators. Compatibility: ircu does not use the same notification mechanism as ircd, so operators are notified using SNO_CONNEXIT anyway. K - Kill Client Syntax: K : Example: K 5 192.168.1.10 23367 :We don't like you. States: REGISTER, HURRY, NORMAL Next State: GONE Comments: Indicates that the specified client should be disconnected for the reason given. Operators should be notified. D - Done Checking Syntax: D [class] Example: D 5 192.168.1.10 23367 States: REGISTER, HURRY Next State: NORMAL Comments: Indicates that the iauth instance believes the specified client should be allowed onto the network. If a class parameter is given, the client should be assigned to that class. Compatibility: Specifying the class is an Undernet extension and ircd does not support that parameter. R - Registered User Syntax: R [class] Example: R 5 192.168.1.10 23367 Buddha States: REGISTER, HURRY Next State: NORMAL Comments: Indicates that the iauth instance believes the specified client should be allowed onto the network, pre-authenticated to the account listed. If a class parameter is given, the client should be assigned to that class. Compatibility: This is an Undernet extension and ircd does not support this message.