Next Previous Contents

8. Authentication Configuration

The following sections in the config file can be used to configure authentication.

8.1 Section [Gatekeeper::Auth]

The section defines the authentication mechanism / modules for the GNU Gatekeeper. After defining which modules to use, you have to add the corresponding config sections for each modulke that you want to use.

Syntax:

authrule=actions

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

A rule may results in one of these three codes: ok, fail, next.

There are also three ways to control a rule:

Currently supported modules: (most only support a subset of the ras or q931 actions)

You can also configure a rule to check only for specific RAS messages. The following example configures SimplePasswordAuth as an optional rule to check RRQ and ARQ. If a RRQ is not checked (does not contain tokens or cryptoTokens fields), it is checked by AliasAuth. The default is to check all supported requests.

Example 1:

SimplePasswordAuth=alternative;RRQ,ARQ
AliasAuth=sufficient;RRQ

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

Example 2:

RadAliasAuth=required;Setup
default=allow

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

Example 3:

RadAuth=alternative;RRQ,ARQ
RadAliasAuth=alternative;RRQ,ARQ,SetupUnreg
default=reject

8.2 Section [FileIPAuth]

This section defines a list of IP addresses/networks which are allowed to access gatekeeper resources. A list of allowed prefixes can be specified together with an IP address. Supported Gatekeeper::Auth events are: GRQ, RRQ, LRQ, Setup and SetupUnreg. Format of a single entry is:

IP=[allow | reject | onlyTLS][;prefix[,prefix...]]

where IP is a single IP address, a network address (in A.B.C.D/M.M.M.M or A.B.C.D/LENGTH format or IPv6 format) or a string 'any' or '*' to match any address. The access list can also be loaded from an external file using 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.

'onlyTLS' is equivalent to 'allow' if the call comes in via a TLS secured connection and means 'reject' for unencrypted calls.

In addition the to endpoint's IP, you can specify a list of prefixes that the endpoint may call. The destination prefixes are only checked on Setup messages.

Example #1:

[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;48,49,44
2a01:4f8:61:2243::2=allow
2a01:4f8:61:2243::10/128=allow
2a01:4f8:61:2243::/64=allow
any=reject

Example #2:

Placing the list of IP rules into another file.

[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

Example #3:

Allow all connects from the local network, but require TLS encryption and authentification for everything else.

[Gatekeeper::Auth]
FileIPAuth=required;Setup

[FileIPAuth]
192.168.1.0/24=allow
any=onlyTLS

8.3 Section [SimplePasswordAuth]

This section defines the userid and password pairs used by SimplePasswordAuth module. All passwords are encrypted using the addpasswd utility.

Usage: 

addpasswd config section userid password

Example: 

addpasswd config.ini SimplePasswordAuth frank secret

Options:

8.4 Section [SQLPasswordAuth]

Authenticate H.235 enabled endpoints using passwords stored in the SQL database. This section defines the SQL driver to use, SQL database connection parameters and the query to use to retrieve passwords.

Use the common database configuration options to define your database connection for this module.

8.5 Section [H350PasswordAuth]

8.6 Section [RasSrv::RRQAuth]

Specify the action on RRQ reception (confirm or deny) for 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.

Syntax:

<authrules> :=  empty  |  <authrule> "&" <authrules>

  <authrule>  := <authtype> ":" <authparams>
  <authtype>  := "sigaddr" | "sigip"
  <autparams> := [!&]*

The notation and meaning of <authparams> depends on <authtype>:

Example: 

[RasSrv::RRQAuth]
; The endpoint with alias 'cwhuang' must register from 10.0.1.10:1720
cwhuang=sigip:10.0.1.10:1720
; The endpoint with alias 'gw1' must register from 10.0.1.0/24
gw1=sigaddr:.*ipAddress .* ip = .* 0a 00 01 .*port = 1720.*
; The endpoint with alias 'gw2' must register from [2a01:4f8:61:2243::2]:1720
gw2=sigip:[2a01:4f8:61:2243::2]:1720

8.7 Section [SQLAliasAuth]

Authenticate endpoints using rules stored in the SQL database (the rules conform to the format defined in the [RasSrv::RRQAuth] section). This section defines which SQL driver to use, SQL database connection parameters and the query to use to retrieve the patterns.

Use the common database configuration options to define your database connection for this module.

8.8 Section [SQLAuth]

Authenticate and authorize endpoints/calls using a SQL database. Support for RRQ, ARQ, LRQ and Setup events is provided.

Use the common database configuration options to define your database connection for this module.

8.9 Section [PrefixAuth]

The section defines the authentication rule for the PrefixAuth module. Currently, only ARQs and LRQs can be authorized by this module.

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

Format:

prefix=authrule[|authrule|...]

Syntax:

<authrule> :=  <result> <authrule>

  <result>    := deny | allow
  <authrule>  := [!]ip:<iprule> | [!]ipv4:<iprule> | [!]ipv6:<iprule> | [!]alias:<aliasrule>

Where <iprule> can be specified in decimal dot notation or CIDR notation or IPv6 notation, <aliasrule> is expressed in regular expression. If the `!' flag precedes the rule, the sense is inverted. Rules for IP numbers with ip:, ipv4:, ipv6: all behave the same. The different prefixes are just for documentation and compatibility with older versions of GnuGk.

Example:

555=deny ipv4:10.0.0.0/27|allow ipv4:0/0
5555=allow ipv4:192.168.1.1|deny ipv4:192.168.1.0/255.255.255.0
86=deny !ipv4:172.16.0.0/24
09=deny alias:^188884.*
99=deny ipv6:2021:4ad0:ff00:99a::/64
ALL=allow ipv4:0/0|allow ipv6:::/0

In this configuration, all endpoints except those from network 10.0.0.0/27 are allowed to call prefix 555 (except 5555). Endpoints from 192.168.1.0/24 are not allowed to call prefix 5555, except 192.168.1.1. Endpoints not from 172.16.0.0/24 are denied to call prefix 86. Endpoints having an alias beginning with 188884 are not allowed to call prefix 09. IPv6 endpoints from 2021:4ad0:ff00:99a::/64 are not allowed to call prefix 99. All other situations are allowed.

8.10 Section [RadAuth]

This section defines configuration settings that enable RADIUS authentication based on H.235 CATs (Cisco Access Tokens) present in RRQ, ARQ RAS requests and Q.931 Setup messages.

[RadAuth] Access-Request Radius Attributes

For RRQs, the following RADIUS attributes are included within Access-Request packets:

For ARQ and Setup messages, the following RADIUS attributes are included inside Access-Request packets:

[RadAuth] Access-Accept Radius Attributes

For RRQs, the following RADIUS attributes are recognized inside Access-Accept packets:

For ARQs, the following RADIUS attributes are recognized within Access-Accept packets:

NOTE: If both Session-Timeout and h323-credit-time are present, the smaller value is used.

NOTE: If multiple failover mechanisms are specified, eg. multiple numbers in h323-redirect-number and multiple IPs in h323-redirect-ip-address, there is no guarantee that the the first number is used for the first IP and the 2nd number for the 2nd IP. This will usually the case, but for example when a capacity limit disables one IP, the association will change.

8.11 Section [RadAliasAuth]

This section defines configuration settings that enable RADIUS authentication based on endpoint aliases and/or IP addresses present in a RRQ RAS, ARQ RAS or Q.931 Setup request. This authentication scheme is useful both for endpoints registered at the gatekeeper (ARQ, RRQ) and calls from unregistered endpoints (Setup).

[RadAliasAuth] Access-Request Radius Attributes

For RRQs, the same attributes as with RadAuth are sent, with an exception of username/password attributes (CHAP-Password, CHAP-Challenge, User-Name):

For ARQ and Setup messages, the same attributes as with RadAuth are sent, with an exception of username/password attributes (CHAP-Password, CHAP-Challenge, User-Name):

[RadAliasAuth] Access-Accept Radius Attributes

Exactly the same attributes are recognized as with RadAuth module.

8.12 Section [CapacityControl]

This section contains a set of rules for controlling inbound call volume depending on various conditions. In order for this module to work, CapacityControl authentication and accounting modules have to be enabled like this: 

[Gatekeeper::Auth]
CapacityControl=required;Setup
 
[Gatekeeper::Acct]
CapacityControl=required;start,stop

A capacity rule can be matched by a caller's IP, caller's H.323 ID and/or caller's number (CLI) - in the order specified. In addition, the match can be narrowed by specifying a called number pattern. This module works by keeping lists of current call volume for each inbound route (rule) - this is done by having CapacityControl accounting module configured to add/remove active calls from matching routes. The CapacityControl authentication module checks rules and accepts/rejects a call based on current/max call volume for a matching inbound route.

Format for an inbound route rule:

[ip:CALLER_IP|h323id:CALLER_H323ID|cli:CALLER_NUMBER]=[CALLED NUMBER REGEX PATTERN] MAX_CAPACITY

ip:, h323id: and cli: prefixes define rule type. An inbound call will be matched either by caller's IP, H.323ID or CLI. The optional CALLED NUMBER REGEX PATTERN is a regular expression that the called number should match to apply this rule to. MAX_CAPACITY is maximum number of active calls for this route.

The rules are match in the following order:

The longest match in the first matching category is used.

Example 1:

[CapacityControl]
ip:192.168.1.0/24=30
ip:any=120

These rules tell that the 192.168.1.0/24 subnet can send up to 30 concurrent calls, while all other IPs can send up to 120 concurrent calls.

Example 2:

[CapacityControl]
%r1% cli:1001=30
%r2% cli:1001=^48(50|51) 5

These rules limit caller with CLI 1001 to send up to 5 calls to 4850/4851 destinations and up to 30 calls to other destinations. %r1% and %r2% are special constructs to allow having the same cli:1001 config key more than once.

8.13 Section [GkH350::Settings]

This section defines the LDAP server and standard H.350 directory operating parameters to be used.

8.14 Section [GkLDAP::Settings]

This section defines the LDAP server and connection parameters for the LDAP authentication modules (LDAPAliasAuth and LDAPPasswordAuth) and the LDAP routing policy ('ldap').

Example:

[GkLDAP::Settings]
ServerName=192.168.1.1
BindAuthMode=simple
SearchBaseDN=dc=gnugk,dc=org
BindUserDN=cn=admin,dc=gnugk,dc=org
BindUserPW=secret

8.15 Section [GkLDAP::LDAPAttributes]

With this section you can map the LDAP attributes GnuGk queries to your LDAP schema.

Example:

[GkLDAP::LDAPAttributeNames]
IPAddress=voIPIpAddress
H235PassWord=plaintextPassword
H323ID=sn
TelephonNo=telephoneNumber
CallDestination=roomNumber

Next Previous Contents