doc/iauth.txt

   1 $Id: iauth.txt,v 1.1 2001-05-01 11:38:34 isomer Exp $
   2
   3 Patrick Alken <wnder@underworld.net>
   4 01/09/2000
   5
   6 Ircd Authentication
   7 ==== ==============
   8
   9 1. Introduction
  10
  11   This document describes the protocol used for the IAuth server.
  12 IAuth performs authorization checks for all clients that connect
  13 to the ircd server.
  14
  15 2. Protocol
  16
  17   Ircd and IAuth communicate through a TCP/IP connection. The
  18 Ircd server will always initiate the connection to the IAuth
  19 server.
  20
  21 2.1 Server
  22
  23   When an Ircd server first connects to an IAuth server, it will
  24 send IAuth a string of the form:
  25
  26     Server <name>
  27
  28       <name>     - Ircd server name
  29
  30   This is used for identification purposes in case more than one
  31 Ircd server is using an IAuth server.
  32
  33 2.2 Class
  34
  35 2.2.1 Class Add
  36
  37   When an Ircd server first connects to an IAuth server, it will
  38 send IAuth it's class list in the form:
  39
  40     Class Add <number> <maxlinks>
  41
  42       <number>   - Class number
  43       <maxlinks> - Maximum number of clients in this class
  44
  45   This is needed for the I-line check, in case the number of
  46 clients allowed to use a certain I-line is limited.
  47
  48 2.2.2 Class Clear
  49
  50   Upon a rehash, the Ircd server will send I-line a string of the
  51 form:
  52
  53     Class Clear [number]
  54
  55       [number]   - optional number
  56
  57   In case the Ircd server's Y: lines were changed prior to the
  58 rehash, IAuth will clear it's old class list to make room for
  59 the new one Ircd will send after the rehash (via Class Add).
  60
  61 2.3 DoAuth
  62
  63   When a client connects to the Ircd server, Ircd will send
  64 a string of the form:
  65
  66     DoAuth <id> <nickname> <username> <hostname> <IP> [password]
  67
  68       <id>       - A unique ID used to identify each client
  69       <nickname> - Client's nickname
  70       <username> - Client's username
  71       <hostname> - Client's hostname
  72       <IP>       - Client's IP Address in unsigned int format
  73       [password] - *Optional* Client password
  74
  75   The DoAuth directive will initiate an authorization check on
  76 the client. The following checks are performed.
  77
  78 2.3.1 I-line Check
  79
  80   This check will ensure that the client matches a valid I-line
  81 (as given in iauth.conf). If the client fails this check, he/she
  82 will not be allowed to remain connected to the Ircd server.
  83 The actual reason they failed authorization will be told to them.
  84 (See the BadAuth directive).
  85   See the section on iauth.conf for more information on I-lines.
  86
  87 2.3.2 Server Ban Check
  88
  89   K-lines are server-wide bans for individual (or groups of) clients.
  90 If a client matches a K-line, they will be disconnected from the
  91 Ircd server with the reason they are banned. The only exception to
  92 this is if they have an exemption flag in their I-line. See the
  93 iauth.conf section for more details on this.
  94
  95 2.3.3 Quarantine Check
  96
  97   Q-lines specify nicknames which are not allowed to be used on
  98 the Ircd server. If a client's nickname matches that of a Q-lined
  99 nickname, they will be informed they have selected a quarantined
 100 nickname and be disconnected from the server.
 101
 102 2.4 DoneAuth
 103
 104   If a client passes all of the above checks, they will pass
 105 authorization and be allowed to continue their connection to
 106 the Ircd server. IAuth will send a string back to the Ircd
 107 server of the form:
 108
 109     DoneAuth <id> <username> <hostname> <class>
 110
 111       <id>       - Client's unique ID
 112       <username> - Client's username
 113       <hostname> - Client's hostname (may be different from original
 114                    if they are allowed a spoof)
 115       <class>    - Client's I-line class
 116
 117   This will inform the Ircd server that the specified client is
 118 authorized to connect.
 119
 120 2.5 BadAuth
 121
 122   If a client fails any of the above checks, IAuth will send a
 123 string to the Ircd server of the form:
 124
 125     BadAuth <id> :<reason>
 126
 127       <id>       - Client's unique ID
 128       <reason>   - Reason client failed authorization
 129
 130   The Ircd server will then send an error back to the client
 131 containing <reason> and disconnect them.
 132
 133 3. Configuration file (iauth.conf)
 134
 135   IAuth reads a configuration file upon startup. The name of the
 136 file is located in setup.h, under #define CONFFILE. The format
 137 of this file is identical to that of ircd.conf, except it supports
 138 less directives.
 139
 140 3.1 I-lines (Server Access)
 141
 142   I-lines allow clients access to the Ircd server and are of the
 143 form:
 144
 145     I:<spoofhost>:[password]:[flags][user@]<host>::<class>
 146
 147       <spoofhost> - Hostname to give client if SPOOF_FREEFORM
 148                     is defined.
 149       [password]  - *Optional* password that clients will
 150                     be required to supply to gain access.
 151       [flags]     - *Optional* flags (see below)
 152       [user]      - *Optional* username (if not given, defaults
 153                     to "*")
 154       <host>      - Client's hostname
 155       <class>     - I-line class (see section Class Add)
 156
 157   Possible values to go in the [flags] section are:
 158
 159                 = - Spoof their IP Address (requires #define
 160                     SPOOF_FREEFORM)
 161                 ! - Limit 1 client per IP Address
 162                 - - Do not give them a tilde (~) character if they
 163                     are not running identd
 164                 + - Do not allow them to connect if they are not
 165                     running identd
 166                 ^ - Client is exempt from K/G lines
 167                 > - Client is also exempt from connection limits
 168
 169 3.2 K-lines (Server Bans)
 170
 171   K-lines specify clients who are banned from the Ircd server and
 172 are of the form:
 173
 174     K:<username>@<hostname>:<reason>
 175
 176       <username>  - Client's username
 177       <hostname>  - Client's hostname
 178       <reason>    - Reason client is banned
 179
 180 3.3 Q-lines (Quarantined Nicknames)
 181
 182   Q-lines specify illegal nicknames. A client that attempts to use
 183 a quarantined nickname will be exited from the Ircd server. Q-lines
 184 are of the form:
 185
 186     Q:<nickname>:<reason>:[[username@]hostname]]
 187
 188       <nickname>  - Quarantined nickname
 189       <reason>    - Reason nickname is quarantined
 190       [username]  - *Optional* exempted username
 191       [hostname]  - *Optional* exempted hostname
 192
 193   Examples:
 194
 195     Q:dcc*:Dcc bots not allowed
 196     Q:GoodOper:GoodOper may use this nick:goodoper@oper.irc.server.com
 197
 198 3.4 P-lines (Ports)
 199
 200   P-lines specify ports on which the IAuth server will listen for
 201 incoming Ircd server connections. They are of the form:
 202
 203     P:<portnum>
 204
 205       <portnum>   - Port number