auth.sgml

H.323网守实现

<sect>Authentication Configuration
<p>
The following sections in the config file can be used to configure authentication.

<sect1>Section &lsqb;Gatekeeper::Auth&rsqb;
<label id="gkauth">
<p>
The section defines the authentication mechanism for the gatekeeper.

<descrip>
<tag/Syntax:/
<tscreen><verb>
authrule=actions

 <authrule> := SimplePasswordAuth | AliasAuth | FileIPAuth | PrefixAuth | RadAuth | RadAliasAuth | SQLAuth | SQLAliasAuth | SQLPasswordAuth | ...
 <actions>  := <control>[;<ras>|<q931>,<ras>|<q931>,...]
 <control>  := optional | required | sufficient
 <ras>      := GRQ | RRQ | URQ | ARQ | BRQ | DRQ | LRQ | IRQ
 <q931>     := Setup | SetupUnreg

</verb></tscreen>
</descrip>
A rule may results in one of the three codes: ok, fail, pass.
<itemize>
<item><tt/ok/ - The request is authenticated by this module.
<item><tt/fail/ - The authentication fails and should be rejected.
<item><tt/next/ - The rule cannot determine the request.
</itemize>
There are also three ways to control a rule:
<itemize>
<item><tt/optional/ - If the rule cannot determine the request, it is passed to next rule.
<item><tt/required/ - The requests should be authenticated by this module, or it would be rejected. The authenticated request would then be passwd to next rule.
<item><tt/sufficient/ - If the request is authenticated, it is accepted, or it would be rejected. That is, the rule determines the fate of the request. No rule should be put after a sufficient rule, since it won't take effect.
</itemize>

Currently supported modules:
<itemize>
<item><tt>SimplePasswordAuth/SQLPasswordAuth</tt>
<p>
These modules check the <bf/tokens/ or <bf/cryptoTokens/ fields of RAS message.
The tokens should contain at least generalID and password.
For <bf/cryptoTokens/, <bf/cryptoEPPwdHash/ tokens hashed by simple MD5 and
<bf/nestedcryptoToken/ tokens hashed by HMAC-SHA1-96 (libssl must be installed!)
are supported now. For <bf/tokens/ tokens hashed by CAT (Cisco Access Token)
and a clear text username/password are supported now.
The ID and password are read from <ref id="password" name="[SimplePasswordAuth]"> section,
an SQL database for <tt/SimplePasswordAuth/ and <tt/SQLPasswordAuth/
modules. <tt/MySQLPasswordAuth/
module is supported for backward compatibility.

<item><tt>AliasAuth/SQLAliasAuth</tt>
<p>
The module can only be used to authenticate RegistrationRequest (RRQ).
The IP of an endpoint with a given alias should match a specified pattern.
For <tt/AliasAuth/ the pattern is defined in
<ref id="rrqauth" name="[RasSrv::RRQAuth]"> section.
For <tt/SQLAliasAuth/, the pattern is retrieved from an SQL database, 
defined in <ref id="sqlaliasauth" name="[SQLAliasAuth]"> section.

<item><tt>FileIPAuth</tt>
<p>
This module provides a simple way to restrict access to the gatekeeper
based on caller's IP/network.

<item><tt>PrefixAuth</tt>
<p>
The IP or aliases of a request with a given prefix must match a specified
pattern. See section <ref id="prefixauth" name="[PrefixAuth]"> for details.
Currently the module can only authorize
AdmissionRequest (ARQ) and LocationRequest (LRQ).

<item><tt>RadAuth</tt>
<p>
Provides authentication based on H.235 username/password
security scheme. Authenticates RRQ, ARQ and Q.931 Setup through remote
RADIUS servers. It passes to RADIUS servers usernames and passwords
extracted from CAT (Cisco Access Tokens) <bf/tokens/ carried
inside RRQ, ARQ or Setup packets. Therefore if your endpoints do not
support CATs or you do not need authentication scheme based on
individually assigned usernames/password - this module will not
work for you (but you may check <tt/RadAliasAuth/ module).
See section <ref id="radauth" name="[RadAuth]"> for details.

<item><tt>RadAliasAuth</tt>
<p>
Provides authentication based on endpoint aliases
and/or call signalling IP addresses with remote RADIUS servers.
It does not need any H.235 <bf/tokens/ inside RAS messages,
so it can be used on a wider range of systems as compared to <tt/RadAuth/.
RRQ, ARQ and Q.931 Setup messages can be authenticated using this module.
See section <ref id="radaliasauth" name="[RadAliasAuth]"> for details.

<item><tt>SQLAuth</tt>
<p>
A powerful module to authenticate and authorize RRQ, ARQ, LRQ and Setup
messages. It can perform checks based on various parameters, like
caller's number, destination number, username and more. It also supports
enforcing call duration limit, number rewritting, call routing, alias
verification and assignment.
See section <ref id="sqlauth" name="[SQLAuth]"> for more details.

</itemize>

You can also configure a rule to check only for some particular RAS messages.
The following example configures <tt/SimplePasswordAuth/ as an optional rule
to check RRQ and ARQ. If an RRQ is not checked (not contains
<bf/tokens/ or <bf/cryptoTokens/ fields), it is checked by <tt/AliasAuth/.
The default is to accept all requests.

<descrip>
<tag/Example 1:/
<tt/SimplePasswordAuth=optional;RRQ,ARQ/<newline>
<tt/AliasAuth=sufficient;RRQ/<newline>
</descrip>

The example below authenticates all calls, checking signalling Setup
message details, using RadAliasAuth module.

<descrip>
<tag/Example 2:/
<tt/RadAliasAuth=required;Setup/<newline>
<tt/default=allow/
</descrip>

This example checks endpoint registrations (RRQ) and call admissions (ARQ)
either by means of username/password (RadAuth) or alias/IP (RadAliasAuth).
Additionally, if the call is from an unregistered endpoint (and therefore
no RRQ or ARQ authentication has been performed), Setup message authentication
using RadAliasAuth takes place (SetupUnreg).

<descrip>
<tag/Example 3:/
<tt/RadAuth=optional;RRQ,ARQ/<newline>
<tt/RadAliasAuth=required;RRQ,ARQ,SetupUnreg/<newline>
<tt/default=allow/
</descrip>

<sect1>Section &lsqb;FileIPAuth&rsqb;
<label id="fileipauth">
<p>
This section defines a list of IP addresses/networks which are allowed
to access gatekeeper resources. Supported Gatekeeper::Auth events are:
<tt/GRQ/, <tt/RRQ/, <tt/LRQ/, <tt/Setup/ and <tt/SetupUnreg/. Format
of a single entry is:
<p><tt/IP=[allow | reject]/
<p>
where IP is a single IP addresss, a network address (in A.B.C.D/M.M.M.M or A.B.C.D/LENGTH format) or a string <tt/'any'/ or <tt/'*'/ to match any address.
The access list can also be loaded from an external file using <tt/include/ directive. During authentication, network mask length defines a priority for each
entry, so rule 192.168.1.1=allow takes precedence over 192.168.1.0/24=reject.

<descrip><tag/Example #1:/
<tscreen><verb>
[Gatekeeper::Auth]
FileIPAuth=required;RRQ,LRQ,Setup

[FileIPAuth]
192.168.1.240=reject
192.168.1.0/24=allow
192.168.2.0/255.255.255.0=allow
any=reject
</verb></tscreen>
</descrip>

<descrip><tag/Example #2:/
<tscreen><verb>
[Gatekeeper::Auth]
FileIPAuth=required;Setup

[FileIPAuth]
include=/etc/gnugk/accesslist.ini

(EOF)

Contents of /etc/gnugk/accesslist.ini:

[FileIPAuth]
192.168.1.1=allow
192.168.1.100=allow
any=reject
</verb></tscreen>
</descrip>

<sect1>Section &lsqb;SimplePasswordAuth&rsqb;
<label id="password">
<p>
The section defines the userid and password pairs used by
<tt/SimplePasswordAuth/ module. All passwords are encrypted
using the <tt/addpasswd/ utility.

Usage:
<tscreen><verb>
addpasswd config section userid password
</verb></tscreen>

Options:
<itemize>
<item><tt/KeyFilled=123/<newline>
Default: <tt/0/
<p>
Default value to use as a padding byte during password encryption/decryption.

<item><tt/CheckID=1/<newline>
Default: <tt/0/
<p>
Check if the aliases match the ID in the tokens.

<item><tt/PasswordTimeout=120/<newline>
Default: <tt/-1/
<p>
The module <tt/SimplePasswordAuth/ and all its descendants will cache an
authenticated password. This field define the cache timeout value in second.
<tt/0/ means never cache the password, while a negative value
means the cache never expires.
</itemize>

<sect1>Section &lsqb;SQLPasswordAuth&rsqb;
<label id="sqlpasswordauth">
<p>
Authenticate H.235 enabled endpoints using passwords stored
in the SQL database. This section defines SQL driver to use,
SQL database connection parameters and the query to use to retrieve passwords.

<itemize>
<item><tt/Driver=MySQL | PostgreSQL/<newline>
Default: N/A
<p>
SQL database driver to use. Currently, <tt/MySQL/ and <tt/PostgreSQL/ drivers
are implemented.

<item><tt/Host=DNS[:PORT] | IP[:PORT]/<newline>
Default: <tt/localhost/
<p>
SQL server host address. Can be in the form of <tt/DNS[:PORT]/ or <tt/IP[:PORT]/.
Like <tt/sql.mycompany.com/ or <tt/sql.mycompany.com:3306/ or <tt/192.168.3.100/.

<item><tt/Database=billing/<newline>
Default: <tt/billing/
<p>
The database name to connect to.

<item><tt/Username=gnugk/<newline>
<p>
The username used to connect to the database.

<item><tt/Password=secret/<newline>
<p>
The password used to connect to the database.
If the password is not specified, a database connection attempt 
without any password will be made.
If <tt/EncryptAllPasswords/ is enabled, or a <tt/KeyFilled/ variable is defined
in this section, the password is in an encrypted form and should be created using
the <tt/addpasswd/ utility.

<item><tt/CacheTimeout=120/<newline>
Default: <tt/0/
<p>
This field defines how long (alias;password) pairs retrieved from the database 
will be cached in the local memory. The cache timeout value is expressed in seconds.
<tt/0/ means to not cache passwords, while a negative value
means the cache never expires (only <tt/reload/ command will refresh the cache).

<item><tt/MinPoolSize=5/<newline>
Default: <tt/1/
<p>
Define the number of active SQL connections. This allows better peformance
under heave load, because more than 1 concurrent query can be executed 
at the same time. <tt/MinPoolSize=1/ setting simulates old behaviour, 
when access to the SQL database is serialized (one query at time).

<item><tt/Query=SELECT .../<newline>
Default: <tt>N/A</tt>
<p>
Defines SQL query used to retrieve H.235 password from the database. The query
is parametrized - that means parameter replacement is made before each query
is executed. Parameter placeholders are denoted by <bf/%1/, <bf/%2/, ... strings.
Specify %% to embed a percent character before a digit into string (like <bf/%%1/),
specify <bf/%{1}/ to allow expansion inside complex expressions like <bf/%{1}123/.
For <tt/SQLPasswordAuth/ two parameters are defined:
<itemize>
<item><tt/%1/ - the actual alias to query the password for
<item><tt/%2/ - the gatekeeper identifier
</itemize>
<p>
Sample query strings:
<tscreen><verb>
SELECT h235password FROM users WHERE alias = '%1' AND active
SELECT h235password FROM users WHERE alias = '%1' AND gk = '%2'
</verb></tscreen>

</itemize>

<sect1>Section &lsqb;RasSrv::RRQAuth&rsqb;
<label id="rrqauth">
<p>
Specify the action on RRQ reception (confirm or deny) for <tt/AliasAuth/ module.
The first alias (this will mostly be an H323ID) of the endpoint to
register is looked up in this section. If a parameter is found the value will
apply as a rule. A rule consists of conditions separated by "&".
A registration is accepted when all conditions apply.

<descrip>
<tag/Syntax:/
<tscreen><verb>
&lt;authrules&gt; :=  empty  |  &lt;authrule&gt; "&" &lt;authrules&gt;

  &lt;authrule&gt;  := &lt;authtype&gt; ":" &lt;authparams&gt;
  &lt;authtype&gt;  := "sigaddr" | "sigip"
  &lt;autparams&gt; := [!&]*
</verb></tscreen>
</descrip>

The notation and meaning of <tt/&lt;authparams&gt;/ depends on
<tt/&lt;authtype&gt;/:

<itemize>
<item><tt/sigaddr/ - extended regular expression that has to match agains the
``PrintOn(ostream)'' representation of the signal address of the request.
<p>
Example:
<tscreen><verb>
sigaddr:.*ipAddress .* ip = .* c0 a8 e2 a5 .*port = 1720.*
</verb></tscreen>

<item><tt/sigip/ - specialized form of `<tt/sigaddr/'.
Write the signalling ip adresse using (commonly used) decimal notation:
``<tt/byteA.byteB.byteC.byteD:port/''.
<p>
Example:
<tscreen><verb>