# &adminguide;

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

## Dependencies

### &kamailio; Modules

The following modules must be loaded before this module:

- none.

### External Libraries or Applications

The following libraries or applications must be installed before running &kamailio; with this module loaded:

- libcrypto - part of OpenSSL project

## Parameters

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

#### Set `salt` parameter

    ...
    modparam("crypto", "salt", "l0Bh2M8a")
    ...

### `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.

#### Set `register_callid` parameter

    ...
    modparam("crypto", "register_callid", 1)
    ...

### `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.

#### Set `register_evcb` parameter

    ...
    modparam("crypto", "register_evcb", 1)
    ...

### `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.

#### Set `kevcb_netio` parameter

    ...
    modparam("crypto", "kevcb_netio", "ksr_crypto_netio")
    ...
    function ksr_crypto_netio(evname)
      ...
    end
    ...

### `netio_key` (str)

The shared secret used to encrypt/decrypt network traffic.

Default value is not set.

#### Set `netio_key` parameter

    ...
    modparam("crypto", "netio_key", "strong-password-here")
    ...

### `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

#### Set `key_derivation` parameter

    ...
    modparam("crypto", "key_derivation", 0)
    ...

### `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.

#### Set `init_vector` parameter

    ...
    modparam("crypto", "init_vector", "MTIzNDU2Nzg5MTIzNDU2Nw==")
    ...

## Functions

### `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.

#### `crypto_aes_encrypt` usage

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

### `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.

#### `crypto_aes_decrypt` usage

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

### `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.

#### `crypto_hmac_sha256` usage

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

### `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.

#### `crypto_netio_in` usage

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

### `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.

#### `crypto_netio_out` usage

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

### `crypto_netio_encrypt()`

Mark the network message for encryption.

This function can be used from EVENT_ROUTE.

#### `crypto_netio_encrypt` usage

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

### `crypto_netio_decrypt()`

Mark the network message for decryption.

This function can be used from EVENT_ROUTE.

#### `crypto_netio_decrypt` usage

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

## Event Routes

### `event_route[crypto:netio]`

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