Documentation based on repostory git version commit 2.1.0-alpha-185-g9bf71c35 

Module Authentication

The authentication module challenges and authenticates SIP requests using two possible methods:

  • if the request is received via a TLS transport and 'require-peer-certificate' is set in transport definition in [Global] section for this transport, then the From header of the request is matched with the CN claimed by the client certificate. The CN must contain sip:user@domain or alternate name with URI=sip:user@domain corresponding to the URI in the from header for the request to be accepted. Optionnaly, the property tls-client-certificate-required-subject may contain a regular expression for additional checks to execute on certificate subjects.
  • if no TLS client based authentication can be performed, or has failed, then a SIP digest authentication is performed. The password verification is made by querying a database or a password file on disk.
    ----

Configuration options:

NameDescriptionDefault ValueType
enabled

Indicate whether the module is activated.

 falseBoolean
filter

A request/response enters module if the boolean filter evaluates to true. Ex: from.uri.domain contains 'sip.linphone.org', from.uri.domain in 'a.org b.org c.org', (to.uri.domain in 'a.org b.org c.org') && (user-agent == 'Linphone v2'). You can consult the full filter documentation here : https://wiki.linphone.org/xwiki/wiki/public/view/Flexisip/Configuration/Filter%20syntax/

 BooleanExpr
auth-domains

List of whitespace separated domains to challenge. Others are automatically denied. The wildcard domain '*' is accepted, which means that requests are challenged whatever the originating domain is. This is convenient for a proxy serving multiple SIP domains.

 localhostStringList
available-algorithms

List of digest algorithms to use for password hashing. Think this setting as filter applied after fetching the credentials of a user from the user database. For example, if a user has its password hashed by MD5 and SHA-256 but 'available-algorithms' only has MD5, then only a MD5-based challenged will be submited to the UAC.
Furthermore, should a user have several hashed passwords and these are present in the list, then a challenge header will be put in the 401 response for each fetched password in the order given by the list.
Supported algorithems are MD5 and SHA-256.

 MD5StringList
disable-qop-auth

Disable the QOP authentication method. Default is to use it, use this flag to disable it if needed.

 falseBoolean
no-403

Don't reply 403 when authentication fails. Instead, generate a new 401 (or 407) response containing a new challenge.

 falseBooleanExpr
nonce-expires

Expiration time before generating a new nonce.
Unit: second

 3600Integer
realm

The realm to use for digest authentication. It will used whatever the domain of the From-URI.
If the value starts with 'regex:', then this parameter will have the same effect than 'realm-regex', using all the remaining string as regular expression.
WARNING: this parameter is exclusive with 'realm-regex'

Examples:
 realm=sip.example.org
 realm=regex:sip:.*@sip\.(.*)\.com

 String
realm-regex

Extraction regex applied on the URI of the 'from' header (or P-Prefered-Identity header if present) in order to extract the realm. The realm is found out by getting the first slice of the URI that matches the regular expression. If it has one or more capturing parentheses, the content of the first one is used as realm.
If no regex is specified, then the realm will be the domain part of the URI.

For instance, given auth-domains=sip.example.com, you might use 'sip:.*@sip\.(.*)\.com' in order to use 'example' as realm.

WARNING: this parameter is exclusive with 'realm'

 String
trusted-hosts

List of whitespace-separated IP addresses which will be judged as trustful. Messages coming from these addresses won't be challenged.

 StringList
reject-wrong-client-certificates

If set to true, the module will simply reject with "403 forbidden" any request coming from clients which have presented a bad TLS certificate (regardless of reason: improper signature, unmatched subjects). Otherwise, the module will fallback to a digest authentication.
This policy applies only for transports configured which have 'required-peer-certificate=1' parameter; indeed no certificate is requested to the client otherwise.

 falseBoolean
tls-client-certificate-required-subject

An optional regular expression used to accept or deny a request basing on subject fields of the client certificate. The request is allowed if one of the subjects matches the regular expression.
The list of subjects to check is built by extracting the following fields, in order:
 subjectAltNames.DNS, subjectAltNames.URI, subjectAltNames.IP and CN

 String
trust-domain-certificates

Accept requests which the client certificate enables to trust the domaine of its Request-URI.

 falseBoolean
new-auth-on-407

When receiving a proxy authenticate challenge, generate a new challenge for this proxy.

 falseBoolean
db-implementation

Database backend implementation for digest authentication [soci,file].

 fileString
cache-expire

Duration of the validity of the credentials added to the cache in seconds.

 1800Integer
file-path

Path of the file in which user credentials are stored.
The file must start with 'version:1' as the first line, and then contains lines in the form of:
user@domain clrtxt:clear-text-password md5:md5-password sha256:sha256-password ;
For example:
bellesip@sip.linphone.org clrtxt:secret ;
bellesip@sip.linphone.org md5:97ffb1c6af18e5687bf26cdf35e45d30 ;
bellesip@sip.linphone.org clrtxt:secret md5:97ffb1c6af18e5687bf26cdf35e45d30 sha256:d7580069de562f5c7fd932cc986472669122da91a0f72f30ef1b20ad6e4f61a3 ;

 String
soci-backend

Choose the type of backend that Soci will use for the connection.
Depending on your Soci package and the modules you installed, this could be 'mysql', 'oracle', 'postgresql' or something else.

 mysqlString
soci-connection-string

The configuration parameters of the Soci backend.
The basic format is "key=value key2=value2". For a mysql backend, this is a valid config: "db=mydb user=user password='pass' host=myhost.com".
Please refer to the Soci documentation of your backend, for intance: http://soci.sourceforge.net/doc/release/4.0/backends/mysql/

 db=mydb user=myuser password='mypass' host=myhost.comString
soci-password-request

Soci SQL request used to obtain the password of a given user.
Each keywords starting with ':' character will be replaced by strings extracted from the SIP request to authenticate.

Only these keywords are supported: - ':id'     : the user found in the from header (mandatory)
 - ':domain' : the authorization realm
 - ':authid' : the authorization username

The request MUST returns a two-columns table, which columns are defined as follow:
 - 1st column: hashed password of the user or plain password if the associated algorithm is CLRTXT.
 - 2nd column: the algorithm used to hash the associated password. Supported values: 'CLRTXT', 'MD5', 'SHA-256'

Examples:
 - the password and algorithm are both available in the database
 select password, algorithm from accounts where login = :id and domain = :domain

 - all the passwords from the database are MD5
 select password, 'MD5' from accounts where login = :id and domain = :domain

 select password, 'MD5' from accounts where login = :id and domain = :domainString
soci-max-queue-size

Amount of queries that will be allowed to be queued before bailing password requests.
This value should be chosen accordingly with 'soci-poolsize', so that you have a coherent behavior.
This limit is here mainly as a safeguard against out-of-control growth of the queue in the event of a flood or big delays in the database backend.

 1000Integer
soci-poolsize

Size of the pool of connections that Soci will use. A thread is opened for each DB query, and this pool will allow each thread to get a connection.
The threads are blocked until a connection is released back to the pool, so increasing the pool size will allow more connections to occur simultaneously.
On the other hand, you should not keep too many open connections to your DB at the same time.

 100Integer
Tags:
Created by Buildbot on 2020/05/25 11:41