Show last authors
1 // Documentation based on repostory git version commit 2.2.0-alpha-10-ge6a6109b //
2
3 =Module Authentication=
4
5 The authentication module challenges and authenticates SIP requests using two possible methods:
6 * 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.
7 * 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.
8 {{{--}}}{{{--}}}
9
10 Configuration options:
11 |=(% style="text-align: center; border: 1px solid #999" %)Name|=(% style="text-align: center; border: 1px solid #999" %)Description|=(% style="text-align: center; border: 1px solid #999" %)Default Value|=(% style="text-align: center; border: 1px solid #999" %)Type
12 |=(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %)enabled|(% style="text-align: left; border: 1px solid #999" %)(((Indicate whether the module is activated~.)))|(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %) ##false##|(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %)Boolean
13 |=(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %)filter|(% style="text-align: left; border: 1px solid #999" %)(((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~/)))|(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %) ####|(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %)BooleanExpr
14 |=(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %)auth-domains|(% style="text-align: left; border: 1px solid #999" %)(((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~. )))|(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %) ##localhost##|(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %)StringList
15 |=(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %)available-algorithms|(% style="text-align: left; border: 1px solid #999" %)(((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~.
16 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~.
17 Supported algorithems are MD5 and SHA~-256~.)))|(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %) ##MD5##|(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %)StringList
18 |=(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %)disable-qop-auth|(% style="text-align: left; border: 1px solid #999" %)(((Disable the QOP authentication method~. Default is to use it~, use this flag to disable it if needed~.)))|(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %) ##false##|(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %)Boolean
19 |=(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %)no-403|(% style="text-align: left; border: 1px solid #999" %)(((Don~'t reply 403 when authentication fails~. Instead~, generate a new 401 ~(or 407~) response containing a new challenge~.)))|(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %) ##false##|(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %)BooleanExpr
20 |=(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %)nonce-expires|(% style="text-align: left; border: 1px solid #999" %)(((Expiration time before generating a new nonce~.
21 Unit~: second)))|(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %) ##3600##|(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %)Integer
22 |=(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %)realm|(% style="text-align: left; border: 1px solid #999" %)(((The realm to use for digest authentication~. It will used whatever the domain of the From~-URI~.
23 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~.
24 WARNING~: this parameter is exclusive with ~'realm~-regex~'
25
26 Examples~:
27 realm~=sip~.example~.org
28 realm~=regex~:sip~:~.~*~@sip~\~.~(~.~*~)~\~.com
29 )))|(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %) ####|(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %)String
30 |=(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %)realm-regex|(% style="text-align: left; border: 1px solid #999" %)(((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~.
31 If no regex is specified~, then the realm will be the domain part of the URI~.
32
33 For instance~, given auth~-domains~=sip~.example~.com~, you might use ~'sip~:~.~*~@sip~\~.~(~.~*~)~\~.com~' in order to use ~'example~' as realm~.
34
35 WARNING~: this parameter is exclusive with ~'realm~')))|(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %) ####|(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %)String
36 |=(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %)trusted-hosts|(% style="text-align: left; border: 1px solid #999" %)(((List of whitespace~-separated IP addresses which will be judged as trustful~. Messages coming from these addresses won~'t be challenged~.)))|(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %) ####|(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %)StringList
37 |=(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %)reject-wrong-client-certificates|(% style="text-align: left; border: 1px solid #999" %)(((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~.
38 This policy applies only for transports configured which have ~'required~-peer~-certificate~=1~' parameter~; indeed no certificate is requested to the client otherwise~. )))|(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %) ##false##|(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %)Boolean
39 |=(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %)tls-client-certificate-required-subject|(% style="text-align: left; border: 1px solid #999" %)(((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~.
40 The list of subjects to check is built by extracting the following fields~, in order~:
41 subjectAltNames~.DNS~, subjectAltNames~.URI~, subjectAltNames~.IP and CN)))|(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %) ####|(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %)String
42 |=(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %)trust-domain-certificates|(% style="text-align: left; border: 1px solid #999" %)(((Accept requests which the client certificate enables to trust the domaine of its Request~-URI~.)))|(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %) ##false##|(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %)Boolean
43 |=(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %)new-auth-on-407|(% style="text-align: left; border: 1px solid #999" %)(((When receiving a proxy authenticate challenge~, generate a new challenge for this proxy~.)))|(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %) ##false##|(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %)Boolean
44 |=(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %)db-implementation|(% style="text-align: left; border: 1px solid #999" %)(((Database backend implementation for digest authentication ~[soci~,file~]~.)))|(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %) ##file##|(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %)String
45 |=(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %)cache-expire|(% style="text-align: left; border: 1px solid #999" %)(((Duration of the validity of the credentials added to the cache in seconds~.)))|(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %) ##1800##|(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %)Integer
46 |=(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %)file-path|(% style="text-align: left; border: 1px solid #999" %)(((Path of the file in which user credentials are stored~.
47 The file must start with ~'version~:1~' as the first line~, and then contains lines in the form of~:
48 user~@domain clrtxt~:clear~-text~-password md5~:md5~-password sha256~:sha256~-password ~;
49 For example~:
50 bellesip~@sip~.linphone~.org clrtxt~:secret ~;
51 bellesip~@sip~.linphone~.org md5~:97ffb1c6af18e5687bf26cdf35e45d30 ~;
52 bellesip~@sip~.linphone~.org clrtxt~:secret md5~:97ffb1c6af18e5687bf26cdf35e45d30 sha256~:d7580069de562f5c7fd932cc986472669122da91a0f72f30ef1b20ad6e4f61a3 ~;)))|(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %) ####|(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %)String
53 |=(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %)soci-backend|(% style="text-align: left; border: 1px solid #999" %)(((Choose the type of backend that Soci will use for the connection~.
54 Depending on your Soci package and the modules you installed~, this could be ~'mysql~'~, ~'oracle~'~, ~'postgresql~' or something else~.)))|(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %) ##mysql##|(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %)String
55 |=(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %)soci-connection-string|(% style="text-align: left; border: 1px solid #999" %)(((The configuration parameters of the Soci backend~.
56 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~"~.
57 Please refer to the Soci documentation of your backend~, for intance~: http~:~/~/soci~.sourceforge~.net~/doc~/release~/4~.0~/backends~/mysql~/)))|(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %) ##db~=mydb user~=myuser password~=~'mypass~' host~=myhost~.com##|(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %)String
58 |=(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %)soci-password-request|(% style="text-align: left; border: 1px solid #999" %)(((Soci SQL request used to obtain the password of a given user~.
59 Each keywords starting with ~'~:~' character will be replaced by strings extracted from the SIP request to authenticate~.
60
61 Only these keywords are supported~: ~- ~'~:id~' ~: the user found in the from header ~(mandatory~)
62 ~- ~'~:domain~' ~: the authorization realm
63 ~- ~'~:authid~' ~: the authorization username
64
65 The request MUST returns a two~-columns table~, which columns are defined as follow~:
66 ~- 1st column~: hashed password of the user or plain password if the associated algorithm is CLRTXT~.
67 ~- 2nd column~: the algorithm used to hash the associated password~. Supported values~: ~'CLRTXT~'~, ~'MD5~'~, ~'SHA~-256~'
68
69 Examples~:
70 ~- the password and algorithm are both available in the database
71 select password~, algorithm from accounts where login ~= ~:id and domain ~= ~:domain
72
73 ~- all the passwords from the database are MD5
74 select password~, ~'MD5~' from accounts where login ~= ~:id and domain ~= ~:domain)))|(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %) ##select password~, ~'MD5~' from accounts where login ~= ~:id and domain ~= ~:domain##|(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %)String
75 |=(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %)soci-max-queue-size|(% style="text-align: left; border: 1px solid #999" %)(((Amount of queries that will be allowed to be queued before bailing password requests~.
76 This value should be chosen accordingly with ~'soci~-poolsize~'~, so that you have a coherent behavior~.
77 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~.)))|(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %) ##1000##|(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %)Integer
78 |=(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %)soci-poolsize|(% style="text-align: left; border: 1px solid #999" %)(((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~.
79 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~.
80 On the other hand~, you should not keep too many open connections to your DB at the same time~.)))|(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %) ##100##|(% style="text-align: center; vertical-align: middle; border: 1px solid #999" %)Integer