--- /dev/null
+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 (<id>, <remoteip> and
+<remoteport>). 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: <id> X <several> <arguments>
+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. This is an example, not a description of the
+ actual X message.
+Compatibility: If we believe ircu behavior is different than ircd's,
+ this describes ircd's behavior or expectations.
+
+C - Client Introduction
+Syntax: <id> C <remoteip> <remoteport> <localip> <localport>
+Example: 5 C 192.168.1.10 23367 192.168.0.1 6667
+States: GONE
+Next State: REGISTER
+Comments: Indicates that <localport> on <localip> accepted a client
+ connection from <remoteport> on <remoteip>.
+
+D - Client Disconnect
+Syntax: <id> 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: <id> N <hostname>
+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: <id> 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: <id> P :<password ...>
+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: <id> U <username> <hostname> <servername> :<userinfo ...>
+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 <username> parameter.
+
+u - Client Username
+Syntax: <id> u <username>
+Syntax: <id> 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.
+ If the identd lookup fails for a user, no username is passed.
+
+n - Client Nickname
+Syntax: <id> n <nickname>
+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.
+
+H - Hurry Up
+Syntax: <id> H <class>
+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. <class> 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: <id> 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: <id> E <type> :<additional text>
+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 <type> argument specifies the
+ general type of error and <additional text> provides details. <id>
+ may be -1.
+
+M - Server Name and Capacity
+Syntax: <id> M <servername> <capacity>
+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 <capacity> information.
+ The <id> should be ignored: ircd sends 0 and ircu sends -1.
+
+X - Extension Query Reply
+Syntax: <id> X <servername> <routing> :<reply>
+Example: -1 X channels.undernet.org 5/127.0.0.1/6667 :OK kev Logged in
+States: N/A
+Next State: -
+Comments: Used to deliver the reply to an extension query to the iauth
+ instance. The <servername> parameter indicates the origin of the
+ reply. The <routing> parameter is the same as was used in the X
+ message from the iauth instance, and can be used to pair the reply
+ with the original request. The <reply> parameter contains the text
+ of the reply.
+Compatibility: This is an Undernet extension and ircd does not send
+ it.
+
+x - Extension Query Server Not Linked
+Syntax: <id> x <servername> <routing> :Server not online
+Example: -1 x channels.undernet.org 5/127.0.0.1/6667 :Server not online
+States: N/A
+Next State: -
+Comments: Used to indicate to the iauth instance that the server
+ specified in the X message is not presently linked to the network.
+ This will not detect the extension query being lost due to a network
+ break, so iauth instances should further implement a timeout
+ mechanism for extension queries.
+Compatibility: This is an Undernet extension and ircd does not send
+ it.
+
+IAUTH MESSAGES
+==============
+
+X - Example Message Description
+Syntax: X <arguments>
+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.
+ This is an example, not a description of the actual X message.
+Compatibility: If we believe ircu behavior is different than ircd's,
+ this describes ircd's behavior or expectations.
+
+> - Operator Notification
+Syntax: > :<message text>
+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 <level>
+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 <options>
+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 :<version string>
+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 <hosts?> <module> :<options>
+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 <module> :<module information>
+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 <id> <remoteip> <remoteport> <username>
+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 <id> <remoteip> <remoteport> <username>
+Example: U 5 192.168.1.10 23367 buddha
+States: REGISTER, HURRY
+Next State: -
+Comments: Indicates that the iauth instance believes <username> is
+ accurate for the specified client.
+
+u - Untrusted Username
+Syntax: u <id> <remoteip> <remoteport> <username>
+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
+ <username> to be accurate, but has no more trusted username.
+
+N - Client Hostname
+Syntax: N <id> <remoteip> <remoteport> <hostname>
+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 <id> <currentip> <remoteport> <newip>
+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 <newip>. This means that
+ future iauth messages relating to the client must use <newip>
+ as the <remoteip> parameter.
+Compatibility: This is an Undernet extension and ircd does not support
+ this message.
+
+M - Adjust User Mode
+Syntax: M <id> <remoteip> <remoteport> +<mode changes>
+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 <id> <remoteip> <remoteport> :<challenge string>
+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 :*** <challenge string>.
+ The client responds by sending PASS :<response>, 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 <id> <remoteip> <remoteport> :<reason>
+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 <id> <remoteip> <remoteport> :<reason>
+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 - "Soft" Done Checking
+Syntax: d <id> <remoteip> <remoteport>
+Example: d 5 192.168.1.10 23367
+States: REGISTER, HURRY
+Next State: -
+Comments: Indicates that the iauth instance has no objection to letting
+ the specified client onto the network, but that some further work is
+ in process. In particular, an account stamp and/or connection class
+ might be available later.
+Compatibility: This is an Undernet extension and ircd does not support
+ this message.
+
+D - Done Checking
+Syntax: D <id> <remoteip> <remoteport> [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 <id> <remoteip> <remoteport> <account> [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.
+
+X - Extension Query
+Syntax: X <servername> <routing> :<query>
+Example: X channels.undernet.org 5/127.0.0.1/6667 :login kev pass
+Comments: Used by the iauth instance to send an extension query to
+ the server specified by <servername>. The <routing> parameter is
+ not interpreted by the servers; it will be returned unchanged in
+ the extension query reply message (the X server message) and may be
+ used to pair the query with its reply. The <query> parameter is
+ sent to <servername>.
+Compatibility: This is an Undernet extension and ircd does not support
+ this message.
projects / ircu2.10.12-pk.git / blobdiff