kamailio/modules/auth_identity

1. SIP Authenticated Identity Module

Gergely Kovacs

   Iptel.org

   Copyright © 2007 Iptel.org
     __________________________________________________________________

   1.1. Overview
   1.2. Dependencies
   1.3. Compilation
   1.4. Installation And Running
   1.5. Authorizer service parameters

        1.5.1. privatekey_path (string)
        1.5.2. certificate_path (string)
        1.5.3. certificate_url (string)
        1.5.4. msg_timeout (integer)

   1.6. Authorizer service functions

        1.6.1. auth_date_proc()

              1.6.1.1. Dependencies

        1.6.2. auth_add_identity()

              1.6.2.1. Dependencies

   1.7. Authorizer service examples
   1.8. Verifier service parameters

        1.8.1. auth_validity_time (integer)
        1.8.2. callid_cache_limit (integer)
        1.8.3. certificate_cache_limit (integer)
        1.8.4. cainfo_path (string)
        1.8.5. accept_pem_certs ([0|1])

   1.9. Verifier service functions

        1.9.1. vrfy_check_date()

              1.9.1.1. Dependencies

        1.9.2. vrfy_get_certificate()

              1.9.2.1. Dependencies

        1.9.3. vrfy_check_certificate()

              1.9.3.1. Dependencies

        1.9.4. vrfy_check_msgvalidity()

              1.9.4.1. Dependencies

        1.9.5. vrfy_check_callid()

              1.9.5.1. Dependencies

   1.10. Verifier service examples

1.1. Overview

   Auth Identity module provides functionalities for securely identifying
   originators of SIP messages. This module has two basic service:
     * 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

1.2. Dependencies

   This module does not depend any other module.

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

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

1.5. Authorizer service parameters

1.5.1. privatekey_path (string)

   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. Set privatekey_path parameter
...
modparam("auth_identity","privatekey_path","/etc/ssl/private/key.pem")
...

1.5.2. certificate_path (string)

   The path of certificate of the authentication service. The certificate
   must be in PEM format.

   This parameter is required by authentication service.

   Example 2. Set certificate_path parameter
...
modparam("auth_identity","certificate_path","/var/www/ssl/mycert.pem")
...

1.5.3. certificate_url (string)

   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 3. Set certificate_url parameter
...
modparam("auth_identity","certificate_url","https://foo.bar/mycert.der")
...

1.5.4. msg_timeout (integer)

   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 4. Set msg_timeout parameter
...
modparam("auth_identity","msg_timeout",600)
...

1.6. Authorizer service functions

1.6.1. auth_date_proc()

   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.

1.6.1.1. Dependencies

   No dependencies

1.6.2. auth_add_identity()

   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

1.6.2.1. Dependencies

   auth_date_proc() must be called before

1.7. Authorizer service examples

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

1.8. Verifier service parameters

1.8.1. auth_validity_time (integer)

   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 5. Set auth_validity_time parameter
...
modparam("auth_identity","auth_validity_time",3600)
...

1.8.2. callid_cache_limit (integer)

   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 6. Set auth_validity_time parameter
...
modparam("auth_identity","callid_cache_limit",32768)
...

1.8.3. certificate_cache_limit (integer)

   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 7. Set certificate_cache_limit parameter
...
modparam("auth_identity","certificate_cache_limit",4096)
...

1.8.4. cainfo_path (string)

   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 8. Set cainfo_path parameter
...
modparam("auth_identity","cainfo_path","/etc/ssl/certs/ca-certificates.crt")
...

1.8.5. accept_pem_certs ([0|1])

   Enables the acquired certificate processing if it is in PEM format.

   This parameter is optional. The default value is "0".

   Example 9. Set accept_pem_certs parameter
...
modparam("auth_identity","accept_pem_certs",1)
...

1.9. Verifier service functions

1.9.1. vrfy_check_date()

   Checks Date header of the incoming message whether falls in validity
   time (set by auth_validity_time parameter)

1.9.1.1. Dependencies

   No dependencies

1.9.2. vrfy_get_certificate()

   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.

1.9.2.1. Dependencies

   No dependencies

1.9.3. vrfy_check_certificate()

   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.

1.9.3.1. Dependencies

   vrfy_get_certificate() must be called before

1.9.4. vrfy_check_msgvalidity()

   Assembles digest-string from the message, create SHA1 hash and compares
   it with the decrypted value of Identity header.

1.9.4.1. Dependencies

   vrfy_get_certificate() must be called before and
   vrfy_check_certificate() should be called before

1.9.5. vrfy_check_callid()

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

1.9.5.1. Dependencies

   This function should be called for the last time.

1.10. Verifier service examples

...
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;
                }
        }
}
...