modules: readme files regenerated - crypto ... [skip ci]

src/modules/crypto/README

@@ -27,18 +27,37 @@ Daniel-Constantin Mierla
 
               3.1. salt (str)
               3.2. register_callid (int)
+              3.3. register_evcb (int)
+              3.4. kevcb_netio (str)
+              3.5. netio_key (str)
 
         4. Functions
 
               4.1. crypto_aes_encrypt(text, key, res)
               4.2. crypto_aes_decrypt(text, key, res)
+              4.3. crypto_netio_in)
+              4.4. crypto_netio_out()
+              4.5. crypto_netio_encrypt()
+              4.6. 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. crypto_aes_encrypt usage
-   1.4. crypto_aes_decrypt usage
+   1.3. Set register_evcb parameter
+   1.4. Set kevcb_netio parameter
+   1.5. Set netio_key parameter
+   1.6. crypto_aes_encrypt usage
+   1.7. crypto_aes_decrypt usage
+   1.8. crypto_netio_in usage
+   1.9. crypto_netio_out usage
+   1.10. crypto_netio_encrypt usage
+   1.11. crypto_netio_decrypt usage
+   1.12. event_route[crypto:netio] usage
 
 Chapter 1. Admin Guide
 
@@ -54,11 +73,22 @@ Chapter 1. Admin Guide
 
         3.1. salt (str)
         3.2. register_callid (int)
+        3.3. register_evcb (int)
+        3.4. kevcb_netio (str)
+        3.5. netio_key (str)
 
    4. Functions
 
         4.1. crypto_aes_encrypt(text, key, res)
         4.2. crypto_aes_decrypt(text, key, res)
+        4.3. crypto_netio_in)
+        4.4. crypto_netio_out()
+        4.5. crypto_netio_encrypt()
+        4.6. crypto_netio_decrypt()
+
+   5. Event Routes
+
+        5.1. event_route[crypto:netio]
 
 1. Overview
 
@@ -88,6 +118,9 @@ Chapter 1. Admin Guide
 
    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.1. salt (str)
 
@@ -122,10 +155,54 @@ modparam("crypto", "salt", "l0Bh2M8a")
 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 callbac functio 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")
+...
+
 4. Functions
 
    4.1. crypto_aes_encrypt(text, key, res)
    4.2. crypto_aes_decrypt(text, key, res)
+   4.3. crypto_netio_in)
+   4.4. crypto_netio_out()
+   4.5. crypto_netio_encrypt()
+   4.6. crypto_netio_decrypt()
 
 4.1.  crypto_aes_encrypt(text, key, res)
 
@@ -136,7 +213,7 @@ modparam("crypto", "register_callid", 1)
 
    This function can be used from ANY_ROUTE.
 
-   Example 1.3. crypto_aes_encrypt usage
+   Example 1.6. crypto_aes_encrypt usage
 ...
 crypto_aes_encrypt("$rb", "my-secret-key", "$var(encrypted)");
 ...
@@ -150,7 +227,103 @@ crypto_aes_encrypt("$rb", "my-secret-key", "$var(encrypted)");
 
    This function can be used from ANY_ROUTE.
 
-   Example 1.4. crypto_aes_decrypt usage
+   Example 1.7. crypto_aes_decrypt usage
 ...
 crypto_aes_decrypt("$var(encrypted)", "my-secret-key", "$var(text)");
 ...
+
+4.3.  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.8. crypto_netio_in usage
+...
+event_route[crypto:netio] {
+  if(crypto_netio_in()) {
+    crypto_netio_decrypt();
+  }
+...
+
+4.4.  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.9. crypto_netio_out usage
+...
+event_route[crypto:netio] {
+  if(crypto_netio_out()) {
+    crypto_netio_encrypt();
+  }
+...
+
+4.5.  crypto_netio_encrypt()
+
+   Mark the network message for encryption.
+
+   This function can be used from EVENT_ROUTE.
+
+   Example 1.10. crypto_netio_encrypt usage
+...
+event_route[crypto:netio] {
+  if(crypto_netio_out()) {
+    crypto_netio_encrypt();
+  }
+...
+
+4.6.  crypto_netio_decrypt()
+
+   Mark the network message for decryption.
+
+   This function can be used from EVENT_ROUTE.
+
+   Example 1.11. 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.12. 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;
+}
+...