generate and add README for auth_identity module

modules_s/auth_identity/README

@@ -0,0 +1,404 @@
+1. Auth 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 only 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
+
+   Authorizer service needs an opportunity 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 its 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 adds one.
+   This function also checks whether the certificate of auth service (set
+   by certificate_path parameter) has not 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,
+   encrypt it with the private key (set by privatekey_path parameter) of
+   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 not signed by a trusted 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;
+                }
+        }
+}
+...