Documentation based on repostory git version commit 2.2.0-alpha-28-g78d628e4 

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

Indicate whether the module is activated.


A request/response enters module if the boolean filter evaluates to true. Ex: from.uri.domain contains '', from.uri.domain in '', (to.uri.domain in '') && (user-agent == 'Linphone v2'). You can consult the full filter documentation here :


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.


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.


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


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


Expiration time before generating a new nonce.
Unit: second


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'



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, you might use 'sip:.*@sip\.(.*)\.com' in order to use 'example' as realm.

WARNING: this parameter is exclusive with 'realm'


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


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.


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


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


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


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


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


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: clrtxt:secret ; md5:97ffb1c6af18e5687bf26cdf35e45d30 ; clrtxt:secret md5:97ffb1c6af18e5687bf26cdf35e45d30 sha256:d7580069de562f5c7fd932cc986472669122da91a0f72f30ef1b20ad6e4f61a3 ;


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.


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'".
Please refer to the Soci documentation of your backend, for intance:

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

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'

 - 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

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.


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.