auth.sgml

gnugk软交换产品

<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 | PrefixAuth | RadAuth | RadAliasAuth | ...
 <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/LDAPPasswordAuth</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 or LDAP
for <tt/SimplePasswordAuth/, <tt/SQLPasswordAuth/ and <tt/LDAPPasswordAuth/
modules, respectively. <tt/MySQLPasswordAuth/
module is supported for backward compatibility.

<item><tt>AliasAuth/SQLAliasAuth/LDAPAliasAuth</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.
For <tt/LDAPAliasAuth/ the alias (default: mail attribute) and IP
(default: voIPIpAddress attribute) must be found in one LDAP entry.

<item><tt>PrefixAuth</tt>
<p>
Originally known as <tt/GkAuthorize/.
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.

</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;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>
sigip:192.168.242.165:1720
</verb></tscreen>

<item><tt/allow/ - always accept the alias.

<item><tt/deny/ - always reject the alias.

</itemize>

<sect1>Section &lsqb;SQLAliasAuth&rsqb;
<label id="sqlaliasauth">
<p>
Authenticate endpoints using rules stored in the SQL database
(the rules conform to the format defined in the <ref id="rrqauth" name="[RasSrv::RRQAuth]"> section). 
This section defines SQL driver to use, SQL database connection parameters 
and the query to use to retrieve the patterns.

<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 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;authrule) 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 rules, 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 alias rule 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/SQLAliasAuth/ two parameters are defined:
<itemize>
<item><tt/%1/ - the actual alias to query the rule for
<item><tt/%2/ - the gatekeeper identifier
</itemize>
<p>
Sample query strings:
<tscreen><verb>
SELECT authrule FROM users WHERE alias = '%1' AND active
SELECT 'sigip:' || host(ip) || port FROM users WHERE alias = '%1'
</verb></tscreen>

</itemize>


<sect1>Section &lsqb;PrefixAuth&rsqb;
<label id="prefixauth">
<p>
The section defines the authentication rule for <tt/PrefixAuth/ module.
Currently, only ARQs and LRQs can be authorized by this module.

First, a most specific prefix is selected according to the <bf/destinationInfo/
field of the received request. Then the request is accepted or rejected
according to the matched rules with most specific netmask.
If no matched prefix is found,
and the <tt/default/ option is specified, the request is accepted
or rejected according to that. Otherwise
it is rejected or passed to next authentication module
according to the module requirement.