import of 2.10.12.07

[irc/quakenet/snircd.git] / doc / readme.iauth

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.  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: <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> :<userinfo ...>
Example: 5 U buddha :Gautama Siddhartha
States: REGISTER(1+)
Next State: -
Comments: Indicates the client's claimed username and "GECOS"
  information.  This information is not reliable.  This message is
  enabled by requesting the A policy.
Compatibility: ircd does not include the <userinfo> data.

u - Client Username
Syntax: <id> u <username>
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: <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.

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.
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: N <id> <currentip> <remoteport> <newip>
Example: N 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.

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 - 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.