kamailio/modules/auth_identity

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

   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

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

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

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 
...
modparam("auth_identity","certificate_path","/var/www/ssl/mycert.pem")
...

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

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

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

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

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

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

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 
...
modparam("auth_identity","accept_pem_certs",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

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

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

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