Kamailio-开源SIP软交换平台

中国第一个专注Kamailio SIP 软交换技术分享平台

用户工具

站点工具


auth_identity_identity_authentication_module_released

差别

这里会显示出您选择的修订版和当前版本之间的差别。

到此差别页面的链接

auth_identity_identity_authentication_module_released [2017/09/06 09:53] (当前版本)
james_zhu 创建
行 1: 行 1:
 +====== SIP Authenticated Identity Module ======
  
 +==== Gergely Kovacs ====
 +
 +Iptel.org\\ ​
 +
 +Copyright © 2007 Iptel.org
 +
 +----
 +
 +**Table of Contents**
 +
 +  * **1. Admin Guide** ​
 +    * **1. Overview** ​
 +    * **2. Dependencies** ​
 +    * **3. Compilation** ​
 +    * **4. Installation And Running** ​
 +    * **5. Parameters** ​
 +      * **5.1. privatekey_path (string)** ​
 +      * **5.2. certificate_path (string)** ​
 +      * **5.3. certificate_url (string)** ​
 +      * **5.4. msg_timeout (integer)** ​
 +      * **5.5. auth_validity_time (integer)** ​
 +      * **5.6. callid_cache_limit (integer)** ​
 +      * **5.7. certificate_cache_limit (integer)** ​
 +      * **5.8. cainfo_path (string)** ​
 +      * **5.9. accept_pem_certs %%([%%0|1])** ​
 +    * **6. Functions** ​
 +      * **6.1. auth_date_proc()** ​
 +        * **6.1.1. Dependencies** ​
 +      * **6.2. auth_add_identity()** ​
 +        * **6.2.1. Dependencies** ​
 +      * **6.3. vrfy_check_date()** ​
 +        * **6.3.1. Dependencies** ​
 +      * **6.4. vrfy_get_certificate()** ​
 +        * **6.4.1. Dependencies** ​
 +      * **6.5. vrfy_check_certificate()** ​
 +        * **6.5.1. Dependencies** ​
 +      * **6.6. vrfy_check_msgvalidity()** ​
 +        * **6.6.1. Dependencies** ​
 +      * **6.7. vrfy_check_callid()** ​
 +        * **6.7.1. Dependencies** ​
 +    * **7. Authorizer service examples** ​
 +    * **8. Verifier service examples** ​
 +    * **9. Remarks** ​
 +
 +**List of Examples**
 +
 +  * **1.1. Set privatekey_path parameter** ​
 +  * **1.2. Set certificate_path parameter** ​
 +  * **1.3. Set certificate_url parameter** ​
 +  * **1.4. Set msg_timeout parameter** ​
 +  * **1.5. Set auth_validity_time parameter** ​
 +  * **1.6. Set auth_validity_time parameter** ​
 +  * **1.7. Set certificate_cache_limit parameter** ​
 +  * **1.8. Set cainfo_path parameter** ​
 +  * **1.9. Set accept_pem_certs parameter** ​
 +
 +====== Chapter 1. Admin Guide ======
 +
 +**Table of Contents**
 +
 +  * **1. Overview** ​
 +  * **2. Dependencies** ​
 +  * **3. Compilation** ​
 +  * **4. Installation And Running** ​
 +  * **5. Parameters** ​
 +    * **5.1. privatekey_path (string)** ​
 +    * **5.2. certificate_path (string)** ​
 +    * **5.3. certificate_url (string)** ​
 +    * **5.4. msg_timeout (integer)** ​
 +    * **5.5. auth_validity_time (integer)** ​
 +    * **5.6. callid_cache_limit (integer)** ​
 +    * **5.7. certificate_cache_limit (integer)** ​
 +    * **5.8. cainfo_path (string)** ​
 +    * **5.9. accept_pem_certs %%([%%0|1])** ​
 +  * **6. Functions** ​
 +    * **6.1. auth_date_proc()** ​
 +      * **6.1.1. Dependencies** ​
 +    * **6.2. auth_add_identity()** ​
 +      * **6.2.1. Dependencies** ​
 +    * **6.3. vrfy_check_date()** ​
 +      * **6.3.1. Dependencies** ​
 +    * **6.4. vrfy_get_certificate()** ​
 +      * **6.4.1. Dependencies** ​
 +    * **6.5. vrfy_check_certificate()** ​
 +      * **6.5.1. Dependencies** ​
 +    * **6.6. vrfy_check_msgvalidity()** ​
 +      * **6.6.1. Dependencies** ​
 +    * **6.7. vrfy_check_callid()** ​
 +      * **6.7.1. Dependencies** ​
 +  * **7. Authorizer service examples** ​
 +  * **8. Verifier service examples** ​
 +  * **9. Remarks** ​
 +
 +===== 1. Overview =====
 +
 +Auth Identity module provides functionalities for securely identifying originators of SIP messages. It implements the SIP Identity standard where a SIP proxy signs messages that is sent to other domains. This module has two basic services:
 +
 +  * authorizer - authorizes a message and adds Identity and Identity-Info headers ​
 +  * verifier - verifies an authorized message ​
 +
 +Known limitations in this version:
 +
 +  * authorizer and verifier support all SIP requests except for CANCEL and REGISTER ​
 +  * verifier does not support the subjectAltName extension of certificates ​
 +
 +===== 2. Dependencies =====
 +
 +This module does not depend any other module.
 +
 +===== 3. Compilation =====
 +
 +This module needs the following headers and libraries:
 +
 +  * OpenSSL (version 0.9.8 or higher) for cryptographic functions ​
 +  * libcurl for HTTP, HTTPS functions ​
 +
 +If you'd like to use TLS module too then use the corresponding LIB line in auth_identity'​s Makefile
 +
 +===== 4. Installation And Running =====
 +
 +the Authorizer service needs to make the public key, which conveyed in a certificate,​ available over HTTPS or HTTP for verifiers. The domain the authorizer is responsible for and the domain part of the URL of the certificate must be the same. This service needs access to the private key too.
 +
 +===== 5. Parameters =====
 +
 +==== 5.1. privatekey_path (string) ====
 +
 +Note: this parameter is for authorizer service.
 +
 +The path of private key of the authentication service. The key must be in PEM format.
 +
 +This parameter is required by authentication service.
 +
 +**Example 1.1. Set ''​privatekey_path''​ parameter**
 +
 +<​code>​
 +...
 +modparam("​auth_identity","​privatekey_path","/​etc/​ssl/​private/​key.pem"​)
 +...
 +</​code>​
 +
 +\\ ==== 5.2. certificate_path (string) ====
 +
 +Note: this parameter is for authorizer service.
 +
 +The path of certificate of the authentication service. The certificate must be in PEM format.
 +
 +This parameter is required by authentication service.
 +
 +**Example 1.2. Set ''​certificate_path''​ parameter**
 +
 +<​code>​
 +...
 +modparam("​auth_identity","​certificate_path","/​var/​www/​ssl/​mycert.pem"​)
 +...
 +</​code>​
 +
 +\\ ==== 5.3. certificate_url (string) ====
 +
 +Note: this parameter is for authorizer service.
 +
 +The url where certificate is available for other verifier services. (value of Identity-info header) The certificate should be in DER format.
 +
 +This parameter is required by authentication service.
 +
 +**Example 1.3. Set ''​certificate_url''​ parameter**
 +
 +<​code>​
 +...
 +modparam("​auth_identity","​certificate_url","​https://​foo.bar/​mycert.der"​)
 +...
 +</​code>​
 +
 +\\ ==== 5.4. msg_timeout (integer) ====
 +
 +Note: this parameter is for authorizer service.
 +
 +If the Date header of message which is needed to be authenticated contains a time different by more than this seconds from the current time noted by the authentication service then it rejects the message.
 +
 +This parameter is optional. The default value is "​600"​.
 +
 +**Example 1.4. Set ''​msg_timeout''​ parameter**
 +
 +<​code>​
 +...
 +modparam("​auth_identity","​msg_timeout",​600)
 +...
 +</​code>​
 +
 +\\ ==== 5.5. auth_validity_time (integer) ====
 +
 +Note: this parameter is for verifier service.
 +
 +The validity time of an authenticated message. The message will be refused if it contains a time different by more than this seconds from the current time noted by the verification service.
 +
 +This parameter is optional. The default value is "​3600"​.
 +
 +**Example 1.5. Set ''​auth_validity_time''​ parameter**
 +
 +<​code>​
 +...
 +modparam("​auth_identity","​auth_validity_time",​3600)
 +...
 +</​code>​
 +
 +\\ ==== 5.6. callid_cache_limit (integer) ====
 +
 +Note: this parameter is for verifier service.
 +
 +The number of Call-IDs stored in order to recognize call replay attacks. A Call-ID is stored ''​auth_validity_time''​ long and uses approximately 100 bytes memory.
 +
 +This parameter is optional. The default value is "​32768"​. (you should increase the size of shared memory with -m command line switch if you liked to store more callid than 10000)
 +
 +**Example 1.6. Set ''​auth_validity_time''​ parameter**
 +
 +<​code>​
 +...
 +modparam("​auth_identity","​callid_cache_limit",​32768)
 +...
 +</​code>​
 +
 +\\ ==== 5.7. certificate_cache_limit (integer) ====
 +
 +Note: this parameter is for verifier service.
 +
 +The number of certificates stored in order to avoid needless download. A certificate is stored until its expiration date and uses approximately 600 bytes memory.
 +
 +This parameter is optional. The default value is "​4096"​.
 +
 +**Example 1.7. Set ''​certificate_cache_limit''​ parameter**
 +
 +<​code>​
 +...
 +modparam("​auth_identity","​certificate_cache_limit",​4096)
 +...
 +</​code>​
 +
 +\\ ==== 5.8. cainfo_path (string) ====
 +
 +Note: this parameter is for verifier service.
 +
 +A file of trusted certificates. The file should contain multiple certificates in PEM format concatenated together. It could be useful for verifying a certificate signed by a private CA.
 +
 +This parameter is optional. It has not got default value.
 +
 +**Example 1.8. Set ''​cainfo_path''​ parameter**
 +
 +<​code>​
 +...
 +modparam("​auth_identity","​cainfo_path","/​etc/​ssl/​certs/​ca-certificates.crt"​)
 +...
 +</​code>​
 +
 +\\ ==== 5.9. accept_pem_certs %%([%%0|1]) ====
 +
 +Note: this parameter is for verifier service.
 +
 +Enables the acquired certificate processing if it is in PEM format.
 +
 +This parameter is optional. The default value is "​0"​.
 +
 +**Example 1.9. Set ''​accept_pem_certs''​ parameter**
 +
 +<​code>​
 +...
 +modparam("​auth_identity","​accept_pem_certs",​1)
 +...
 +</​code>​
 +
 +\\ ===== 6. Functions =====
 +
 +==== 6.1. auth_date_proc() ====
 +
 +Note: this function is for authorizer service.
 +
 +If a message, the auth service should authorize, contains Date header then this function checks whether it falls in message timeout (set by msg_timeout parameter). If there is not any Date header then the module adds one. This function also checks whether the certificate of the authentication service (set by certificate_path parameter) has been expired.
 +
 +=== 6.1.1. Dependencies ===
 +
 +No dependencies
 +
 +==== 6.2. auth_add_identity() ====
 +
 +Note: this function is for authorizer service.
 +
 +Assembles digest-string from the message, calculates its SHA1 hash, encrypts it with the private key (set by privatekey_path parameter) of the authorizer service, base64 encodes it and adds to the outgoing message as the value of Identity header. This function also adds Identity-Info header which contains an URI (set by certificate_url parameter) from which the certificate of auth service can be acquired.
 +
 +Note: this function needs the final outgoing message for authorization,​ so no module may modify any digest string related headers (From, To, Call-ID, CSeq, Date, Contact) and body after auth_add_identity()'​s been called
 +
 +=== 6.2.1. Dependencies ===
 +
 +auth_date_proc() must be called before
 +
 +==== 6.3. vrfy_check_date() ====
 +
 +Note: this function is for verifier service.
 +
 +Checks Date header of the incoming message whether falls in validity time (set by auth_validity_time parameter)
 +
 +=== 6.3.1. Dependencies ===
 +
 +No dependencies
 +
 +==== 6.4. vrfy_get_certificate() ====
 +
 +Note: this function is for verifier service.
 +
 +Tries to get certificate defined by the value of Identity-info header from certificate table (which size is set by certificate_cache_limit parameter). If the required certificate is not found there then this function downloads it.
 +
 +=== 6.4.1. Dependencies ===
 +
 +No dependencies
 +
 +==== 6.5. vrfy_check_certificate() ====
 +
 +Note: this function is for verifier service.
 +
 +Checks whether the downloaded certificate is valid (is not expired, its subject and the domain part of the URL are the same) and adds it to certificate table.
 +
 +=== 6.5.1. Dependencies ===
 +
 +vrfy_get_certificate() must be called before
 +
 +==== 6.6. vrfy_check_msgvalidity() ====
 +
 +Note: this function is for verifier service.
 +
 +Assembles digest-string from the message, create SHA1 hash and compares it with the decrypted value of Identity header.
 +
 +=== 6.6.1. Dependencies ===
 +
 +vrfy_get_certificate() must be called before and vrfy_check_certificate() should be called before
 +
 +==== 6.7. vrfy_check_callid() ====
 +
 +Note: this function is for verifier service.
 +
 +Checks whether the current call's been already processed in validity time (set by auth_validity_time) to recognize call replay attacks. If this call (identified by Call-id, Cseq, and tag of From header triple) has not been replayed then adds it to callid table (which size is set by callid_cache_limit parameter).
 +
 +=== 6.7.1. Dependencies ===
 +
 +This function should be called for the last time.
 +
 +===== 7. Authorizer service examples =====
 +
 +<​code>​
 +...
 +route[INIT]
 +{
 +        # we process new transactions only
 +        if (!t_newtran()) {
 +                sl_reply("​500",​ "​Internal error newtran"​);​
 +                drop;
 +        }
 +...
 +route[OUTBOUND]
 +{
 +        # If we are responsible for the domain of the sender of this message
 +        if ($f.did && !$t.did) {
 +                # Authentication service
 +                if (method=="​INVITE"​ || method=="​BYE"​
 +                        || method=="​OPTION"​ || method=="​ACK"​) {
 +                        # Identity and Identity-info headers must not exist
 +                        if (@identity) {
 +                                t_reply("​403",​ "​Invalid Identity header"​);​
 +                                drop;
 +                        }
 +                        if (@identity_info) {
 +                                t_reply("​403",​ "​Invalid Identity-info header"​);​
 +                                drop;
 +                        }
 +
 +                        if (!auth_date_proc()) {
 +                                t_reply("​403",​ "​Invalid Date value"​);​
 +                                drop;
 +                        }
 +
 +                        if (!auth_add_identity()) {
 +                                t_reply("​480",​ "​Authentication error"​);​
 +                                drop;
 +                        }
 +                }
 +                route(FORWARD);​
 +        }
 +}
 +...
 +</​code>​
 +
 +===== 8. Verifier service examples =====
 +
 +<​code>​
 +...
 +route[INIT]
 +{
 +        # we process new transactions only
 +        if (!t_newtran()) {
 +                sl_reply("​500",​ "​Internal error newtran"​);​
 +                drop;
 +        }
 +...
 +route[VERIFY]
 +{
 +        # if we've already processed this message then we drop it
 +        if (!t_newtran()) {
 +                sl_reply("​500",​ "​Internal error newtran"​);​
 +                drop;
 +        }
 +
 +        if (method=="​INVITE"​ || method=="​BYE"​
 +                || method=="​OPTION"​ || method=="​ACK"​) {
 +                # Identity and Identity-info are required for verification
 +                if (!@identity) {
 +                        t_reply("​428",​ "Use Identity Header"​);​
 +                        drop;
 +                }
 +                if (!@identity_info) {
 +                        t_reply("​436",​ "Bad Identity-Info"​);​
 +                        drop;
 +                }
 +
 +                if (!vrfy_check_date()) {
 +                        t_reply("​403",​ "​Outdated Date header value"​);​
 +                        drop;
 +                }
 +
 +                if (!vrfy_get_certificate()) {
 +                        t_reply("​436",​ "Bad Identity-Info"​);​
 +                        drop;
 +                }
 +
 +                if (!vrfy_check_certificate()) {
 +                        t_reply("​437",​ "​Unsupported Certificate"​);​
 +                        drop;
 +                }
 +
 +                if (!vrfy_check_msgvalidity()) {
 +                        t_reply("​438",​ "​Invalid Identity Header"​);​
 +                        drop;
 +                }
 +
 +                if (!vrfy_check_callid()) {
 +                        t_reply("​403",​ "​Message is replayed"​);​
 +                        drop;
 +                }
 +        }
 +}
 +...
 +</​code>​
 +
 +===== 9. Remarks =====
 +
 +Note: libcurl leak in CentOS 6 - this module uses libcurl library and in case if you are using CentOS 6, be aware that standard libcurl-7.19.7-52 has a memory leak. To fix this memory, install libcurl from city-fan repository. More details at: https://​www.digitalocean.com/​community/​questions/​how-to-upgrade-curl-in-centos6
auth_identity_identity_authentication_module_released.txt · 最后更改: 2017/09/06 09:53 由 james_zhu