CRYPTO Module

Daniel-Constantin Mierla

   <miconda@gmail.com>

Edited by

Daniel-Constantin Mierla

   <miconda@gmail.com>

   Copyright © 2016 asipto.com
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. Dependencies

              2.1. Kamailio Modules
              2.2. External Libraries or Applications

        3. Parameters

              3.1. salt (str)
              3.2. register_callid (int)
              3.3. register_evcb (int)
              3.4. kevcb_netio (str)
              3.5. netio_key (str)
              3.6. key_derivation (str)
              3.7. init_vector (str)

        4. Functions

              4.1. crypto_aes_encrypt(text, key, res)
              4.2. crypto_aes_decrypt(text, key, res)
              4.3. crypto_hmac_sha256(text, key, res)
              4.4. crypto_netio_in)
              4.5. crypto_netio_out()
              4.6. crypto_netio_encrypt()
              4.7. crypto_netio_decrypt()

        5. Event Routes

              5.1. event_route[crypto:netio]

   List of Examples

   1.1. Set salt parameter
   1.2. Set register_callid parameter
   1.3. Set register_evcb parameter
   1.4. Set kevcb_netio parameter
   1.5. Set netio_key parameter
   1.6. Set key_derivation parameter
   1.7. Set init_vector parameter
   1.8. crypto_aes_encrypt usage
   1.9. crypto_aes_decrypt usage
   1.10. crypto_hmac_sha256 usage
   1.11. crypto_netio_in usage
   1.12. crypto_netio_out usage
   1.13. crypto_netio_encrypt usage
   1.14. crypto_netio_decrypt usage
   1.15. event_route[crypto:netio] usage

Chapter 1. Admin Guide

   Table of Contents

   1. Overview
   2. Dependencies

        2.1. Kamailio Modules
        2.2. External Libraries or Applications

   3. Parameters

        3.1. salt (str)
        3.2. register_callid (int)
        3.3. register_evcb (int)
        3.4. kevcb_netio (str)
        3.5. netio_key (str)
        3.6. key_derivation (str)
        3.7. init_vector (str)

   4. Functions

        4.1. crypto_aes_encrypt(text, key, res)
        4.2. crypto_aes_decrypt(text, key, res)
        4.3. crypto_hmac_sha256(text, key, res)
        4.4. crypto_netio_in)
        4.5. crypto_netio_out()
        4.6. crypto_netio_encrypt()
        4.7. crypto_netio_decrypt()

   5. Event Routes

        5.1. event_route[crypto:netio]

1. Overview

   This module provides various cryptography tools for use in Kamailio
   configuration file. For compatibility with existing crypto libraries
   its internal operation mode can be configured as well. This allows the
   module to be used e.g. with existing Java applications or PostgreSQL DB
   functions.

   It relies on OpenSSL libraries for cryptographic operations (libssl,
   libcrypto).

2. Dependencies

   2.1. Kamailio Modules
   2.2. External Libraries or Applications

2.1. Kamailio Modules

   The following modules must be loaded before this module:
     * none.

2.2. External Libraries or Applications

   The following libraries or applications must be installed before
   running Kamailio with this module loaded:
     * libcrypto - part of OpenSSL project

3. Parameters

   3.1. salt (str)
   3.2. register_callid (int)
   3.3. register_evcb (int)
   3.4. kevcb_netio (str)
   3.5. netio_key (str)
   3.6. key_derivation (str)
   3.7. init_vector (str)

3.1. salt (str)

   A keyword to generate salt for encryption. It must be at least 8 chars
   long. If set to empty, no salt is used for encryption.

   The salt is a binary array that is appended to the encryption password
   for better protection against dictionary attacks. Same salt and
   password need to be used when encrypting and decrypting.

   Default value is "..." (see code).

   Example 1.1. Set salt parameter
...
modparam("crypto", "salt", "l0Bh2M8a")
...

3.2. register_callid (int)

   Set it to 1 in order to register a callback to core for generation of
   callid values for requests generated by Kamailio tm module.

   This callid generator uses libssl random and hashing functions for
   generating RFC 4122 version 4 UUID with high quality entropy. It is
   useful when wanting to have new callids that cannot be predicted from
   previous values.

   Default value is 0.

   Example 1.2. Set register_callid parameter
...
modparam("crypto", "register_callid", 1)
...

3.3. register_evcb (int)

   Set it to 1 in order to register the event route callbacks, in case AES
   encryption/decryption of SIP traffic is wanted. The
   event_route[crypto:netio] or corresponding KEMI callback are executed.

   Default value is 0.

   Example 1.3. Set register_evcb parameter
...
modparam("crypto", "register_evcb", 1)
...

3.4. kevcb_netio (str)

   Name of the KEMI callback function for netio events. It receives a
   string parameter with event route name.

   Default value is not set.

   Example 1.4. Set kevcb_netio parameter
...
modparam("crypto", "kevcb_netio", "ksr_crypto_netio")
...
function ksr_crypto_netio(evname)
  ...
end
...

3.5. netio_key (str)

   The shared secret used to encrypt/decrypt network traffic.

   Default value is not set.

   Example 1.5. Set netio_key parameter
...
modparam("crypto", "netio_key", "strong-password-here")
...

3.6. key_derivation (str)

   Specify if the module should use an internal derivation function to
   generate the initialization vector for encryption operations. This is
   the default mode. If set to 0 the initialization vector will be
   generated randomly or read from the configuration file.

   The source of the initialization vector is configured with the
   init_vector parameter.

   Default value is 1 - generate the initialization vector internally

   Example 1.6. Set key_derivation parameter
...
modparam("crypto", "key_derivation", 0)
...

3.7. init_vector (str)

   The initialization vector used for the cryptographic operations. This
   needs to be a Base64 encoded value with 16 bytes lengths.

   If this parameter is not set and the key_derivation parameter is also
   set to 0, the module will create a random initialization vector for
   decryption operations. For encryption operations the initialization
   vector will be read from the first 16 bytes of the cipher text.

   Default value is not set.

   Example 1.7. Set init_vector parameter
...
modparam("crypto", "init_vector", "MTIzNDU2Nzg5MTIzNDU2Nw==")
...

4. Functions

   4.1. crypto_aes_encrypt(text, key, res)
   4.2. crypto_aes_decrypt(text, key, res)
   4.3. crypto_hmac_sha256(text, key, res)
   4.4. crypto_netio_in)
   4.5. crypto_netio_out()
   4.6. crypto_netio_encrypt()
   4.7. crypto_netio_decrypt()

4.1.  crypto_aes_encrypt(text, key, res)

   Encrypts the text with the key using AES encryption algorithm. The
   result is encoded in base64 format and stored in res. The parameter res
   must be a read-write variables. The parameters text and key can be
   static strings or strings with variables (dynamic strings).

   This function can be used from ANY_ROUTE.

   Example 1.8. crypto_aes_encrypt usage
...
crypto_aes_encrypt("$rb", "my-secret-key", "$var(encrypted)");
...

4.2.  crypto_aes_decrypt(text, key, res)

   Decrypts the text with the key using AES encryption algorithm. The text
   has to be encoded in base64 format. The parameter res must be a
   read-write variables. The parameters text and key can be static strings
   or strings with variables (dynamic strings).

   This function can be used from ANY_ROUTE.

   Example 1.9. crypto_aes_decrypt usage
...
crypto_aes_decrypt("$var(encrypted)", "my-secret-key", "$var(text)");
...

4.3.  crypto_hmac_sha256(text, key, res)

   Calculates HMAC (keyed-hash message authentication code) with SHA256 as
   a cryptographic hash function. The result is encoded in base64 url
   encoded format and stored in res. The parameter res must be a
   read-write variable. The parameters text and key can be static strings
   or strings with variables (dynamic strings).

   This function can be used from ANY_ROUTE.

   Example 1.10. crypto_hmac_sha256 usage
...
crypto_hmac_sha256("$var(text)", "my-secret-key", "$var(hmac)");
...

4.4.  crypto_netio_in)

   Return 1 (true) if it is an incoming net message, or -1 (false)
   otherwise.

   This function can be used from EVENT_ROUTE.

   Example 1.11. crypto_netio_in usage
...
event_route[crypto:netio] {
  if(crypto_netio_in()) {
    crypto_netio_decrypt();
  }
...

4.5.  crypto_netio_out()

   Return 1 (true) if it is an outgoing net message, or -1 (false)
   otherwise.

   This function can be used from EVENT_ROUTE.

   Example 1.12. crypto_netio_out usage
...
event_route[crypto:netio] {
  if(crypto_netio_out()) {
    crypto_netio_encrypt();
  }
...

4.6.  crypto_netio_encrypt()

   Mark the network message for encryption.

   This function can be used from EVENT_ROUTE.

   Example 1.13. crypto_netio_encrypt usage
...
event_route[crypto:netio] {
  if(crypto_netio_out()) {
    crypto_netio_encrypt();
  }
...

4.7.  crypto_netio_decrypt()

   Mark the network message for decryption.

   This function can be used from EVENT_ROUTE.

   Example 1.14. crypto_netio_decrypt usage
...
event_route[crypto:netio] {
  if(crypto_netio_in()) {
    crypto_netio_decrypt();
  }
...

5. Event Routes

   5.1. event_route[crypto:netio]

5.1.  event_route[crypto:netio]

   Example 1.15. event_route[crypto:netio] usage
...
# ----- crypto params -----
modparam("crypto", "register_evcb", 1)
modparam("crypto", "netio_key", "strong-password-here")
...
event_route[crypto:netio] {
        if(crypto_netio_in()) {
                if(src_port==5060) {
                        crypto_netio_decrypt();
                }
        } else {
                if($sndto(port)==5060) {
                        crypto_netio_encrypt();
                }
        }
}

# Main SIP request routing logic
request_route {
        sl_send_reply("200", "ok");
        if(src_port==5060) {
                $du = "sip:127.0.0.1:9";
                forward();
        } else {
                $du = "sip:127.0.0.1:5060";
                forward();
        }
        exit;
}
...
