From c09daf26a58f23483c2b8cf1f40c990f20e4d215 Mon Sep 17 00:00:00 2001 From: Kamailio Dev Date: Fri, 1 Apr 2022 14:16:20 +0200 Subject: [PATCH] modules: readme files regenerated - ims_qos ... [skip ci] --- src/modules/ims_qos/README | 594 ++++++++++++++++++++++++++++++++++ src/modules/mqueue/README | 61 +++- src/modules/stirshaken/README | 557 +++++++++++++++++++++++++++++++ 3 files changed, 1198 insertions(+), 14 deletions(-) diff --git a/src/modules/ims_qos/README b/src/modules/ims_qos/README index 8b137891791..ea7eea5e1ff 100644 --- a/src/modules/ims_qos/README +++ b/src/modules/ims_qos/README @@ -1 +1,595 @@ +The IMS QoS Module +Dragos Vingarzan + + Core Network Dynamics (ex FhG Fokus) + + +Jason Penton + + Smile Communications + + +Richard Good + + Smile Communications + + +Carsten Bock + + ng-voice GmbH + + + Copyright © 2007 FhG FOKUS + + Copyright © 2012 Smile Communications + + Copyright © 2015 ng-voice GmbH + + Copyright © 2016 Core Network Dynamics GmbH + __________________________________________________________________ + + Table of Contents + + 1. Admin Guide + + 1. Overview + 2. Dependencies + + 2.1. Kamailio Modules + 2.2. External Libraries or Applications + + 3. Parameters + + 3.1. rx_dest_realm (string) + 3.2. rx_forced_peer (string) + 3.3. rx_auth_expiry (integer) + 3.4. cdp_event_latency (integer) + 3.5. cdp_event_threshold (integer) + 3.6. cdp_event_latency_log (integer) + 3.7. authorize_video_flow (integer) + 3.8. cdp_event_list_size_threshold (integer) + 3.9. audio_default_bandwidth (integer) + 3.10. video_default_bandwidth (integer) + 3.11. early_qosrelease_reason (String) + 3.12. confirmed_qosrelease_headers (String) + 3.13. regex_sdp_ip_prefix_to_maintain_in_fd (String) + 3.14. terminate_dialog_on_rx_failure integer + 3.15. delete_contact_on_rx_failure integer + 3.16. include_rtcp_fd integer + 3.17. af_signaling_ip (String) + 3.18. af_signaling_ip6 (String) + 3.19. media_type (String) + 3.20. flow_protocol (String) + 3.21. omit_flow_ports integer + 3.22. rs_default_bandwidth integer + 3.23. rr_default_bandwidth integer + + 4. Functions + + 4.1. Rx_AAR_Register(route_block, domain) + 4.2. Rx_AAR(route_block, direction, subscription_id, + subscription_id_type) + + 5. Statistics + + 5.1. AAR Timeouts (aar_timeouts) + 5.2. Average AAR Response Time (aar_avg_response_time) + + List of Examples + + 1.1. rx_dest_realm parameter usage + 1.2. rx_forced_peer parameter usage + 1.3. rx_auth_expiry parameter usage + 1.4. cdp_event_latency parameter usage + 1.5. cdp_event_threshold parameter usage + 1.6. cdp_event_latency_log parameter usage + 1.7. authorize_video_flow parameter usage + 1.8. cdp_event_list_size_threshold parameter usage + 1.9. audio_default_bandwidth parameter usage + 1.10. video_default_bandwidth parameter usage + 1.11. early_qosrelease_reason parameter usage + 1.12. confirmed_qosrelease_headers parameter usage + 1.13. regex_sdp_ip_prefix_to_maintain_in_fd parameter usage + 1.14. terminate_dialog_on_rx_failure parameter usage + 1.15. delete_contact_on_rx_failure parameter usage + 1.16. include_rtcp_fd parameter usage + 1.17. af_signaling_ip parameter usage + 1.18. af_signaling_ip6 parameter usage + 1.19. media_type parameter usage + 1.20. flow_protocol parameter usage + 1.21. omit_flow_ports parameter usage + 1.22. rs_default_bandwidth parameter usage + 1.23. rr_default_bandwidth parameter usage + 1.24. Rx_AAR_Register + 1.25. Rx_AAR + +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. rx_dest_realm (string) + 3.2. rx_forced_peer (string) + 3.3. rx_auth_expiry (integer) + 3.4. cdp_event_latency (integer) + 3.5. cdp_event_threshold (integer) + 3.6. cdp_event_latency_log (integer) + 3.7. authorize_video_flow (integer) + 3.8. cdp_event_list_size_threshold (integer) + 3.9. audio_default_bandwidth (integer) + 3.10. video_default_bandwidth (integer) + 3.11. early_qosrelease_reason (String) + 3.12. confirmed_qosrelease_headers (String) + 3.13. regex_sdp_ip_prefix_to_maintain_in_fd (String) + 3.14. terminate_dialog_on_rx_failure integer + 3.15. delete_contact_on_rx_failure integer + 3.16. include_rtcp_fd integer + 3.17. af_signaling_ip (String) + 3.18. af_signaling_ip6 (String) + 3.19. media_type (String) + 3.20. flow_protocol (String) + 3.21. omit_flow_ports integer + 3.22. rs_default_bandwidth integer + 3.23. rr_default_bandwidth integer + + 4. Functions + + 4.1. Rx_AAR_Register(route_block, domain) + 4.2. Rx_AAR(route_block, direction, subscription_id, + subscription_id_type) + + 5. Statistics + + 5.1. AAR Timeouts (aar_timeouts) + 5.2. Average AAR Response Time (aar_avg_response_time) + +1. Overview + + This module contains all method related to the IMS policy and charging + control functions performed by an Application Function (e.g. P-CSCF) + over the Rx interface. This module is dependent on the CDP (C Diameter + Peer) modules for communicating with PCRF as specified in 3GPP + specification TS 29.214. + +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: + * Dialog + * Usrloc PCSCF + * TM - Transaction Manager + * CDP - C Diameter Peer + * CDP_AVP - CDP AVP Applications + +2.2. External Libraries or Applications + + This modules requires the internal IMS library. + +3. Parameters + + 3.1. rx_dest_realm (string) + 3.2. rx_forced_peer (string) + 3.3. rx_auth_expiry (integer) + 3.4. cdp_event_latency (integer) + 3.5. cdp_event_threshold (integer) + 3.6. cdp_event_latency_log (integer) + 3.7. authorize_video_flow (integer) + 3.8. cdp_event_list_size_threshold (integer) + 3.9. audio_default_bandwidth (integer) + 3.10. video_default_bandwidth (integer) + 3.11. early_qosrelease_reason (String) + 3.12. confirmed_qosrelease_headers (String) + 3.13. regex_sdp_ip_prefix_to_maintain_in_fd (String) + 3.14. terminate_dialog_on_rx_failure integer + 3.15. delete_contact_on_rx_failure integer + 3.16. include_rtcp_fd integer + 3.17. af_signaling_ip (String) + 3.18. af_signaling_ip6 (String) + 3.19. media_type (String) + 3.20. flow_protocol (String) + 3.21. omit_flow_ports integer + 3.22. rs_default_bandwidth integer + 3.23. rr_default_bandwidth integer + +3.1. rx_dest_realm (string) + + This is the name of the Diameter realm of the Diameter server + (typically a PCRF). + + Default value is 'ims.smilecoms.com'. + + Example 1.1. rx_dest_realm parameter usage +... +modparam("ims_qos", "rx_dest_realm", "ims.smilecoms.com") +... + +3.2. rx_forced_peer (string) + + FQDN of the Diameter server (typically a PCRF) to communicate with. If + not set then realm routing is used. If you use this, the routing + defined in your diameter xml configuration file (CDP) will be ignored + and as a result you will lose the benefits of load balancing and + failover. + + Default value is ''. + + Example 1.2. rx_forced_peer parameter usage +... +modparam("ims_qos", "rx_forced_peer", "pcrf.ims.smilecoms.com") +... + +3.3. rx_auth_expiry (integer) + + This is the expiry length in seconds of the initiated Diameter + sessions. + + Default value is 7200. + + Example 1.3. rx_auth_expiry parameter usage +... +modparam("ims_qos", "rx_auth_expiry", 14400) +... + +3.4. cdp_event_latency (integer) + + This is a flag to determine whether or slow CDP responses should be + reported in the log file. 1 is enabled and 0 is disabled. + + Default value is 1. + + Example 1.4. cdp_event_latency parameter usage +... +modparam("ims_qos", "cdp_event_latency", 1) +... + +3.5. cdp_event_threshold (integer) + + This time in milliseconds is the limit we should report a CDP response + as slow. i.e. if a CDP response exceeds this limit it will be reported + in the log file. This is only relevant is cdp_event_latency is enabled + (set to 0). + + Default value is 500. + + Example 1.5. cdp_event_threshold parameter usage +... +modparam("ims_qos", "cdp_event_threshold", 500) +... + +3.6. cdp_event_latency_log (integer) + + This time log level at which we should report slow CDP responses. 0 is + ERROR, 1 is WARN, 2 is INFO and 3 is DEBUG. This is only relevant is + cdp_event_latency is enabled (set to 0) + + Default value is 0. + + Example 1.6. cdp_event_latency_log parameter usage +... +modparam("ims_qos", "cdp_event_latency_log", 1) +... + +3.7. authorize_video_flow (integer) + + This is a flag that specifies whether or not to authorize video flows. + 1 means video flows will be authorized over Rx and 0 means video flows + will not be authorized over Rx + + Default value is 1. + + Example 1.7. authorize_video_flow parameter usage +... +modparam("ims_qos", "authorize_video_flow", 0) +... + +3.8. cdp_event_list_size_threshold (integer) + + This is a threshold on the size of the cdp event list. Once the queue + exceeds this length a warning is logged. 0 disables this feature + + Default value is 0. + + Example 1.8. cdp_event_list_size_threshold parameter usage +... +modparam("ims_qos", "cdp_event_list_size_threshold", 10) +... + +3.9. audio_default_bandwidth (integer) + + This parameters defines the default bandwidth for Audio, if no + "b=AS"-Parameter is found in the SDP. + + Default value is 64 (64 kBit) + + Example 1.9. audio_default_bandwidth parameter usage +... +modparam("ims_qos", "audio_default_bandwidth", 32) +... + +3.10. video_default_bandwidth (integer) + + This parameters defines the default bandwidth for Video, if no + "b=AS"-Parameter is found in the SDP. + + Default value is 128 (128 kBit) + + Example 1.10. video_default_bandwidth parameter usage +... +modparam("ims_qos", "video_default_bandwidth", 256) +... + +3.11. early_qosrelease_reason (String) + + This sets the default Reason, when a call is terminated in early stage + due to QoS-failure. + + Default value is "QoS released", an call in early stage would be + released with "488 QoS released". + + Example 1.11. early_qosrelease_reason parameter usage +... +modparam("ims_qos", "early_qosrelease_reason", "Sorry - QoS failed") +... + +3.12. confirmed_qosrelease_headers (String) + + These headers are added to the BYE-Message, when an confirmed call is + terminated due to a QoS failure. + + Default value is "", no Extra-Headers + + The headers must end with CRLF. + + Example 1.12. confirmed_qosrelease_headers parameter usage +... +modparam("ims_qos", "confirmed_qosrelease_headers", "X-Reason: QoS failed\r\n") +... + +3.13. regex_sdp_ip_prefix_to_maintain_in_fd (String) + + The flow-description AVP is typically populated using IP:port + information present in the SDP. Certain (buggy) UEs can change ports + midway during calls which causes the flow-description to no longer + match the traffic. This parameter allows the flow-description AVP to + use to the any keyword instead of certain IP:port combinations in the + SDP. The parameter is a regex that if set adds an extra filter for all + IPs that do not match the regex with the any keyword in the + flow-description AVP + + Default value is "", no extra filters added + + Example 1.13. regex_sdp_ip_prefix_to_maintain_in_fd parameter usage +... +modparam("ims_qos", "regex_sdp_ip_prefix_to_maintain_in_fd", "10.21.0.1") +... + +3.14. terminate_dialog_on_rx_failure integer + + If set then active dialogs associated with an Rx session are torn down + in the Rx session fails + + Default value is 1, dialogs are torn down + + Example 1.14. terminate_dialog_on_rx_failure parameter usage +... +modparam("ims_qos", "terminate_dialog_on_rx_failure", 0) +... + +3.15. delete_contact_on_rx_failure integer + + If set then contacts associated with signalling Rx sessions are deleted + if the Rx session fails + + Default value is 1, contacts are deleted + + Example 1.15. delete_contact_on_rx_failure parameter usage +... +modparam("ims_qos", "delete_contact_on_rx_failure", 0) +... + +3.16. include_rtcp_fd integer + + If set then a flow description is added for media flows - next + available odd port is used as the default for RTCP traffic + + Default value is 0, RTCP flow description not added + + Example 1.16. include_rtcp_fd parameter usage +... +modparam("ims_qos", "include_rtcp_fd", 1) +... + +3.17. af_signaling_ip (String) + + Set P-CSCF IPv4 address to generate the flows for the UE - PCSCF + signaling path. Used only for AAR register, Flow-Description AVP (507) + + Default value is 127.0.0.1 + + Example 1.17. af_signaling_ip parameter usage +... +modparam("ims_qos", "af_signaling_ip", "127.0.0.1") +... + +3.18. af_signaling_ip6 (String) + + Set P-CSCF IPv6 address to generate the flows for the UE - PCSCF + signaling path. Used only for AAR register, Flow-Description AVP (507) + + Default value is "" + + Example 1.18. af_signaling_ip6 parameter usage +... +modparam("ims_qos", "af_signaling_ip6", "fd16::205:2dee:ce4a:ab22") +... + +3.19. media_type (String) + + Describe Media Type AVP(520) for AAR register + + Default value is 'control' + + Example 1.19. media_type parameter usage +... +modparam("ims_qos", "media_type", "audio") +... + +3.20. flow_protocol (String) + + Describe Flow protocol for Flow-Description AVP (507). Used only for + AAR register + + Default value is 'IP' + + Example 1.20. flow_protocol parameter usage +... +modparam("ims_qos", "flow_protocol", "UDP") +... + +3.21. omit_flow_ports integer + + If set to 1 ommit ports for Flow-Description AVP (507). Used only for + AAR register + + Default value is 0, Add ports to Flow-Description AVP (507) + + Example 1.21. omit_flow_ports parameter usage +... +modparam("ims_qos", "omit_flow_ports", 1) +... + +3.22. rs_default_bandwidth integer + + Describe default RS-Bandwidth AVP(522) for AAR + + Default value is 0 + + Example 1.22. rs_default_bandwidth parameter usage +... +modparam("ims_qos", "rs_default_bandwidth", 600) +... + +3.23. rr_default_bandwidth integer + + Describe default RR-Bandwidth AVP(521) for AAR + + Default value is 0 + + Example 1.23. rr_default_bandwidth parameter usage +... +modparam("ims_qos", "rr_default_bandwidth", 2000) +... + +4. Functions + + 4.1. Rx_AAR_Register(route_block, domain) + 4.2. Rx_AAR(route_block, direction, subscription_id, + subscription_id_type) + +4.1. Rx_AAR_Register(route_block, domain) + + Perform a AAR on Diameter RX interface to subscribe to signalling + status. This purpose of this is tell a Diameter server (typically a + PCRF) to inform the requesting Diameter client on changes to the status + of signalling bearer for the same framed IP address. For more details + see 3GGP TS 29.214. + + Meaning of the parameters is as follows: + * Route block to resume after async UAR Diameter reply. + * domain that usrloc_pcscf uses to store user information. + + Return codes: + * -1 - error: There was an error, so we must either ignore it (no + subscription) or send 403 (depends on behaviour you want) + 0 - Success: AAR-Request sent, reply is processed asynchronously. + 1 - Success: No need to send AAR-Request, as a subscription still + exists (continue as normal) + + This function can be used from REQUEST_ROUTE. + + p.s. this is executed asynchronously. See example on how to retrieve + return value + + Example 1.24. Rx_AAR_Register +... +if(Rx_AAR_Register("REG_AAR_REPLY","location")==0){ + exit; +} +... +route[REG_AAR_REPLY] +{ + switch ($avp(s:aar_return_code)) { + case 1: + xlog("L_DBG", "Diameter: AAR success on subscription to signalling\n +"); + break; + default: + xlog("L_ERR", "Diameter: AAR failed on subscription to signalling\n" +); + t_reply("403", "Can't register to QoS for signalling"); + exit; + } +... + +4.2. Rx_AAR(route_block, direction, subscription_id, subscription_id_type) + + Perform a AAR on Diameter RX interface to request resource + authorisation from a Diameter server (typically a PCRF). For more + details see 3GGP TS 29.214. + + Meaning of the parameters is as follows: + * Route block to resume after async UAR Diameter reply. + * direction of this message - orig, term, etc. + * subscription_id to hard code subscription ID for AAR. Used for some + broken PCRFs. Leave blank to use default + * subscription_id_type to hard code subscription ID type for AAR. + Only applicable if subscription_id is set. Set to -1 to use + default. This is as per RFC 4006: END_USER_E164 0, END_USER_IMSI 1, + END_USER_SIP_URI 2, END_USER_NAI 3, END_USER_PRIVATE 4 + + This function can be used from REQUEST_ROUTE or ONREPLY_ROUTE. + + p.s. this is executed asynchronously. See example on how to retrieve + return value + + Example 1.25. Rx_AAR +... +if(Rx_AAR("ORIG_SESSION_AAR_REPLY","orig","",-1)==0){ + exit; +} +... +route[ORIGN_SESSION_AAR_REPLY] +{ + if ($avp(s:aar_return_code) != 1) { + xlog("L_ERR", "IMS: AAR failed Orig\n"); + dlg_terminate("all", "Sorry no QoS available"); + } else { + xlog("L_DBG", "Diameter: Orig AAR success on media authorization\n"); + } +} +... + +5. Statistics + + 5.1. AAR Timeouts (aar_timeouts) + 5.2. Average AAR Response Time (aar_avg_response_time) + +5.1. AAR Timeouts (aar_timeouts) + + The number of timeouts on sending a AAR. i.e. no response to AAR. + +5.2. Average AAR Response Time (aar_avg_response_time) + + The average response time in milliseconds for AAR-AAA transaction. diff --git a/src/modules/mqueue/README b/src/modules/mqueue/README index dbf70893768..10ef5cb07b0 100644 --- a/src/modules/mqueue/README +++ b/src/modules/mqueue/README @@ -45,6 +45,7 @@ Julien Chavanton 3.2. mqueue (string) 3.3. mqueue_name (string) 3.4. mqueue_size (int) + 3.5. mqueue_addmode (int) 4. Functions @@ -66,13 +67,14 @@ Julien Chavanton 1.2. Set mqueue parameter 1.3. Set mqueue_name parameter 1.4. Set mqueue_size parameter - 1.5. mq_add usage - 1.6. mq_fetch usage - 1.7. mq_pv_free usage - 1.8. mq_size usage - 1.9. mqueue.get_size usage - 1.10. mqueue.fetch usage - 1.11. mqueue.get_sizes usage + 1.5. Set mqueue_addmode parameter + 1.6. mq_add usage + 1.7. mq_fetch usage + 1.8. mq_pv_free usage + 1.9. mq_size usage + 1.10. mqueue.get_size usage + 1.11. mqueue.fetch usage + 1.12. mqueue.get_sizes usage Chapter 1. Admin Guide @@ -90,6 +92,7 @@ Chapter 1. Admin Guide 3.2. mqueue (string) 3.3. mqueue_name (string) 3.4. mqueue_size (int) + 3.5. mqueue_addmode (int) 4. Functions @@ -138,6 +141,7 @@ Chapter 1. Admin Guide 3.2. mqueue (string) 3.3. mqueue_name (string) 3.4. mqueue_size (int) + 3.5. mqueue_addmode (int) 3.1. db_url (str) @@ -178,6 +182,13 @@ val character varying(4096) DEFAULT "" NOT NULL shutdown but not read at startup. If set to 3, it is read at sartup but not written at shutdown. Default value is 0 (no db table interaction). + + addmode: how to add new (key,value) pairs. + o 0: Will push all new (key,value) pairs at the end of the + queue. (default) + o 1: Will keep oldest (key,value) pair in the queue, based + on the key. + o 2: Will keep newest (key,value) pair in the queue, based + on the key. The parameter can be set many times, each holding the definition of one queue. @@ -185,7 +196,9 @@ val character varying(4096) DEFAULT "" NOT NULL Example 1.2. Set mqueue parameter ... modparam("mqueue", "mqueue", "name=myq;size=20;") +modparam("mqueue", "mqueue", "name=myq;size=10000;addmode=2") modparam("mqueue", "mqueue", "name=qaz") +modparam("mqueue", "mqueue", "name=qaz;addmode=1") ... 3.3. mqueue_name (string) @@ -223,6 +236,26 @@ modparam("mqueue", "mqueue_name", "my_own_queue") modparam("mqueue", "mqueue_size", 1024) ... +3.5. mqueue_addmode (int) + + Sets the mode to be used when adding a new (key,value) pair in the + mqueue. + * 0 Add all new (key,value) at the end of mqueue + * 1 Unique key, keep oldest (key,value) + * 2 Unique key, keep newest(key,value) + + Default value is “0”. + + Value must be an int. + + The parameter should be set before defining any "mqueue_name". If not + set, the queues defined via "mqueue_name" will have default addmode 0. + + Example 1.5. Set mqueue_addmode parameter +... +modparam("mqueue", "mqueue_addmode", 2) +... + 4. Functions 4.1. mq_add(queue, key, value) @@ -235,7 +268,7 @@ modparam("mqueue", "mqueue_size", 1024) Add a new item (key, value) in the queue. If max size of queue is exceeded, the oldest one is removed. - Example 1.5. mq_add usage + Example 1.6. mq_add usage ... mq_add("myq", "$rU", "call from $fU"); ... @@ -248,7 +281,7 @@ mq_add("myq", "$rU", "call from $fU"); Return: true on success (1); false on failure (-1) or no item fetched (-2). - Example 1.6. mq_fetch usage + Example 1.7. mq_fetch usage ... while(mq_fetch("myq")) { @@ -261,7 +294,7 @@ while(mq_fetch("myq")) Free the item fetched in pseudo-variables. It is optional, a new fetch frees the previous values. - Example 1.7. mq_pv_free usage + Example 1.8. mq_pv_free usage ... mq_pv_free("myq"); ... @@ -273,7 +306,7 @@ mq_pv_free("myq"); If the mqueue is empty, the function returns -1. If the mqueue is not found, the function returns -2. - Example 1.8. mq_size usage + Example 1.9. mq_size usage ... $var(q_size) = mq_size("queue"); xlog("L_INFO", "Size of queue is: $var(q_size)\n"); @@ -303,7 +336,7 @@ xlog("L_INFO", "Size of queue is: $var(q_size)\n"); Parameters: * name - the name of memory queue - Example 1.9. mqueue.get_size usage + Example 1.10. mqueue.get_size usage ... kamcmd mqueue.get_size xyz ... @@ -315,7 +348,7 @@ kamcmd mqueue.get_size xyz Parameters: * name - the name of memory queue - Example 1.10. mqueue.fetch usage + Example 1.11. mqueue.fetch usage ... kamcmd mqueue.fetch xyz ... @@ -326,7 +359,7 @@ kamcmd mqueue.fetch xyz Parameters: none - Example 1.11. mqueue.get_sizes usage + Example 1.12. mqueue.get_sizes usage ... kamcmd mqueue.get_sizes ... diff --git a/src/modules/stirshaken/README b/src/modules/stirshaken/README index 8b137891791..946b5c40be7 100644 --- a/src/modules/stirshaken/README +++ b/src/modules/stirshaken/README @@ -1 +1,558 @@ +Stirshaken Module +Piotr Gregor + + signalwire.com + + +Edited by + +Piotr Gregor + + + + Copyright © 2021 https://www.signalwire.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. as_default_key (str) + 3.2. vs_verify_x509_cert_path (int) + 3.3. vs_ca_dir (str) + 3.4. vs_crl_dir (str) + 3.5. vs_identity_expire_s (int) + 3.6. vs_connect_timeout_s (int) + 3.7. vs_cache_certificates (int) + 3.8. vs_cache_dir (str) + 3.9. vs_cache_expire_s (int) + 3.10. vs_certsubject_pvname (str) + 3.11. vs_pptgrants_pvname (str) + + 4. Functions + + 4.1. stirshaken_check_identity() + 4.2. stirshaken_check_identity_with_key(keyPath) + 4.3. stirshaken_check_identity_with_cert(certPath) + 4.4. stirshaken_add_identity(x5u, attest, origtn_val, + desttn_val, origid) + + 4.5. stirshaken_add_identity_with_key(x5u, attest, + origtn_val, desttn_val, origid, keyPath) + + 5. Installation + + List of Examples + + 1.1. Set as_default_key parameter + 1.2. Set vs_verify_x509_cert_path parameter + 1.3. Set vs_ca_dir parameter + 1.4. Set vs_crl_dir parameter + 1.5. Set vs_identity_expire_s parameter + 1.6. Set vs_connect_timeout_s parameter + 1.7. Set vs_cache_certificates parameter + 1.8. Set vs_cache_dir parameter + 1.9. Set vs_cache_expire_s parameter + 1.10. Set vs_certsubject_pvname parameter + 1.11. Set vs_pptgrants_pvname parameter + 1.12. stirshaken_check_identity usage + 1.13. stirshaken_check_identity_with_key usage + 1.14. stirshaken_check_identity_with_cert usage + 1.15. stirshaken_add_identity with origid usage + 1.16. stirshaken_add_identity with auto generated uuid as origid usage + 1.17. stirshaken_add_identity_with_key usage + 1.18. libstirshaken installation + +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. as_default_key (str) + 3.2. vs_verify_x509_cert_path (int) + 3.3. vs_ca_dir (str) + 3.4. vs_crl_dir (str) + 3.5. vs_identity_expire_s (int) + 3.6. vs_connect_timeout_s (int) + 3.7. vs_cache_certificates (int) + 3.8. vs_cache_dir (str) + 3.9. vs_cache_expire_s (int) + 3.10. vs_certsubject_pvname (str) + 3.11. vs_pptgrants_pvname (str) + + 4. Functions + + 4.1. stirshaken_check_identity() + 4.2. stirshaken_check_identity_with_key(keyPath) + 4.3. stirshaken_check_identity_with_cert(certPath) + 4.4. stirshaken_add_identity(x5u, attest, origtn_val, desttn_val, + origid) + + 4.5. stirshaken_add_identity_with_key(x5u, attest, origtn_val, + desttn_val, origid, keyPath) + + 5. Installation + +1. Overview + + This module implements STIR (Secure Telephony Identity Revisited) and + SHAKEN (Signature-based Handling of Asserted information using toKENs) + (RFC8224, RFC8588), with X509 certificate path check (ATIS + "Signature-based Handling of Asserted information using toKENs + (SHAKEN)", RFC5280 "6. Certification Path Validation"). + + stirshaken module exports the functions to check and to generate + PASSporT, wrapped into SIP Identity header. For call authentication two + functions are available: stirshaken_add_identity(...) and + stirshaken_add_identity_with_key(key). stirshaken_add_identity() uses + default key (through Authentication Service), + stirshaken_add_identity_with_key(..., key) uses key specified as + argument. For call verification three methods are available: + stirshaken_check_identity() (through Verification Service), + stirshaken_check_identity_with_key(key) and + stirshaken_check_identity_with_cert(cert). stirshaken_check_identity() + offers the most comprehensive check as only this method may download + certificate (if needed), cache it, and check it with X509 certificate + path check algorithm. This method is therefore to be used as a default + verification mechanism, while stirshaken_check_identity_with_key(key) + and stirshaken_check_identity_with_cert(cert) are only for + completeness. + +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: + * No dependencies on other Kamailio modules. + +2.2. External Libraries or Applications + + The following libraries or applications must be installed before + running Kamailio with this module loaded: + * libstirshaken - https://github.com/signalwire/libstirshaken. + +3. Parameters + + 3.1. as_default_key (str) + 3.2. vs_verify_x509_cert_path (int) + 3.3. vs_ca_dir (str) + 3.4. vs_crl_dir (str) + 3.5. vs_identity_expire_s (int) + 3.6. vs_connect_timeout_s (int) + 3.7. vs_cache_certificates (int) + 3.8. vs_cache_dir (str) + 3.9. vs_cache_expire_s (int) + 3.10. vs_certsubject_pvname (str) + 3.11. vs_pptgrants_pvname (str) + +3.1. as_default_key (str) + + SSL private key to be used as default. Default key must be set if calls + to stirshaken_add_identity() are executed. When set, module starts + Authentication Service which makes each call to + stirshaken_add_identity() using this key. Default key doesn't need to + be set (Authentication Service doesn't need to be running) for the + stirshaken_add_identity_with_key(..., key) to be available. This param + has no meaning for calls to stirshaken_add_identity_with_key(..., key). + + Default value is "" (not set). + + Example 1.1. Set as_default_key parameter +... +modparam("stirshaken", "as_default_key", "/path/to/key") +... + +3.2. vs_verify_x509_cert_path (int) + + If set, then stirshaken_check_identity() will execute X509 certificate + path check on certificate referenced in PASSporT. This param has no + meaning for calls to stirshaken_check_identity_with_key(key) and + stirshaken_check_identity_with_cert(cert). + + Default value is 1, (turned on). + + Example 1.2. Set vs_verify_x509_cert_path parameter +... +modparam("stirshaken", "vs_verify_x509_cert_path", 1) +... + +3.3. vs_ca_dir (str) + + The path to folder containing CA root certificates with names hashed. + If set then must point to existing directory. This must be set when + enabled X509 certificate path check, otherwise no end entity + certificate will pass that check. This param has no meaning for calls + to stirshaken_check_identity_with_key(key) and + stirshaken_check_identity_with_cert(cert). + + Default value is "" (not set). + + Example 1.3. Set vs_ca_dir parameter +... +modparam("stirshaken", "vs_ca_dir", "/path/to/ca_dir") +... + +3.4. vs_crl_dir (str) + + The path to folder containing CRLs. If set, then must point to existing + directory. This is optional when X509 certificate path check is + enabled, only vs_ca_dir is mandatory. If X509 certificate path check is + enabled, and vs_crl_dir is set, then CRLs are loaded from this + directory, which renders revoked certificates invalid (not trusted). + This param has no meaning for calls to + stirshaken_check_identity_with_key(key) and + stirshaken_check_identity_with_cert(cert). + + Default value is "" (not set). + + Example 1.4. Set vs_crl_dir parameter +... +modparam("stirshaken", "vs_crl_dir", "/path/to/crl_dir") +... + +3.5. vs_identity_expire_s (int) + + This parameter defines a maximum time in seconds for which PASSporT is + considered valid. + + Default value is 60 seconds. + + Example 1.5. Set vs_identity_expire_s parameter +... +modparam("stirshaken", "vs_identity_expire_s", 20) +... + +3.6. vs_connect_timeout_s (int) + + During a call verification with stirshaken_check_identity() a blocking + HTTP(s) call is executed to download certificate referneced in PASSporT + (unless certificate caching is turned on and a valid cert is found in + cache). This parameter defines a maximum time in seconds for this + blocking HTTP(s) connection to be established. After this time had + passed and connection did not succeed (could not resolve host, address + unreachable or other network errors) a call to + stirshaken_check_identity() will return with error. This param has no + meaning for calls to stirshaken_check_identity_with_key(key) and + stirshaken_check_identity_with_cert(cert). + + Default value is 5 seconds. + + Example 1.6. Set vs_connect_timeout_s parameter +... +modparam("stirshaken", "vs_connect_timeout_s", 10) +... + +3.7. vs_cache_certificates (int) + + If set, then certificates caching is turned on. This means that + certificates downloaded during call verification with + stirshaken_check_identity() are cached inside vs_cache_dir, and will be + loaded from that cache as long as they are not there for more than + vs_cache_expire_s seconds (see vs_cache_expire_s). If + vs_cache_certificates is set then vs_cache_dir must be set too and + pointing to existing directory. This param has no meaning for calls to + stirshaken_check_identity_with_key(key) and + stirshaken_check_identity_with_cert(cert). + + Default value is 0 (turned off). + + Example 1.7. Set vs_cache_certificates parameter +... +modparam("stirshaken", "vs_cache_certificates", 1) +... + +3.8. vs_cache_dir (str) + + If vs_cache_certificates is set then vs_cache_dir must be set too and + pointing to existing directory. Cached certificates are saved in this + directory and loaded from there when needed during a call verification + executed with stirshaken_check_identity(), as long as they are not + there for more than vs_cache_expire_s seconds. This param has no + meaning for calls to stirshaken_check_identity_with_key(key) and + stirshaken_check_identity_with_cert(cert). + + Default value is "" (not set). + + Example 1.8. Set vs_cache_dir parameter +... +modparam("stirshaken", "vs_cache_dir", "/tmp/cert_cache") +... + +3.9. vs_cache_expire_s (int) + + If vs_cache_certificates is set then cached certificates are saved in + vs_cache_dir directory and loaded from there when needed during a call + verification executed with stirshaken_check_identity(), as long as they + are not there for more than vs_cache_expire_s seconds. If they are in + cache for more than vs_cache_expire_s seconds, then a blocking HTTP(s) + call is executed to download a new version of (expired) certificate. If + this is successful then old version is removed and new version is saved + in cache. This param has no meaning for calls to + stirshaken_check_identity_with_key(key) and + stirshaken_check_identity_with_cert(cert). + + Default value is 120 seconds. + + Example 1.9. Set vs_cache_expire_s parameter +... +modparam("stirshaken", "vs_cache_expire_s", 15) +... + +3.10. vs_certsubject_pvname (str) + + If vs_certsubject_pvname is set then the Subject of the authenticated + x509 certificate will be written to this pseudo-variable when + stirshaken_check_identity() is executed. If the Identity header cannot + be fully authenticated the pseudo-variable will be set to $null. + + Default value is blank (disabled). + + Example 1.10. Set vs_certsubject_pvname parameter +... +modparam("stirshaken", "vs_certsubject_pvname", "$vn(certsubject)") +... + +3.11. vs_pptgrants_pvname (str) + + If vs_pptgrants_pvname is set then the JSON string of the authenticated + PASSporT's grants will be written to this pseudo-variable when + stirshaken_check_identity() is executed. If the Identity header cannot + be fully authenticated the pseudo-variable will be set to $null. + + Default value is blank (disabled). + + Example 1.11. Set vs_pptgrants_pvname parameter +... +modparam("stirshaken", "vs_pptgrants_pvname", "$vn(grants)") +... + +4. Functions + + 4.1. stirshaken_check_identity() + 4.2. stirshaken_check_identity_with_key(keyPath) + 4.3. stirshaken_check_identity_with_cert(certPath) + 4.4. stirshaken_add_identity(x5u, attest, origtn_val, desttn_val, + origid) + + 4.5. stirshaken_add_identity_with_key(x5u, attest, origtn_val, + desttn_val, origid, keyPath) + +4.1. stirshaken_check_identity() + + Check the validity of the Identity header by decoding PASSporT's + signature with a certificate referenced in it's x5u header and + (optionally) checking that certificate for being trusted by X509 + certificate check with CA root certificates in vs_ca_dir (and + optionally CRLs in vs_crl_dir). PASSporT's iat grant is also checked + for being too fresh or expired against vs_identity_expire_s seconds. + This function executes a call to a callback which may supply + certificates from cache (see vs_cache_certificates param). If + certificate needs to be downloaded this call will block for a maximum + of vs_connect_timeout_s seconds (see vs_connect_timeout_s param); + + This function takes no parameters (only SIP message is passed + implicitly). + + This function can be used from ANY_ROUTE. + + Example 1.12. stirshaken_check_identity usage +... +modparam("stirshaken", "vs_verify_x509_cert_path", 1) +modparam("stirshaken", "vs_ca_dir", "/path/to/ca") +modparam("stirshaken", "vs_cache_certificates", 1) +modparam("stirshaken", "vs_cache_dir", "/path/to/cert_cache") +modparam("stirshaken", "vs_cache_expire_s", 100) + +request_route { + ... + if (1 == stirshaken_check_identity()) { + xlog("Shaken Identity is OK\n"); + } else { + xlog("Shaken Identity is invalid\n"); + } + ... +} +... + +4.2. stirshaken_check_identity_with_key(keyPath) + + Check the validity of the Identity header by decoding PASSporT's + signature with a key read from the location provided. PASSporT's iat + grant is also checked for being too fresh or expired against + vs_identity_expire_s seconds. This method does not involve HTTP(s) + transcations. This method does not execute a call to a callback + (vs_cache_certificates param has no meaning for this method). WARNING: + This method only checks if SIP Identity Header was signed by a key + corresponding to specified public key. This method doesn't attempt to + obtain certificate referenced in PASSporT (but PASSporT should be + checked with key corresponding to that certificate). Therefore it is + possible that this check will be successful, while PASSporT is not + valid (could be signed with key that doesn't match certificate + referenced in x5u header). If you want a complete Shaken check or if + you are not sure what you're doing, then you should execute + w_stirshaken_check_identity() instead (and configure Verification + Service to perform X509 certificate path verification with + stirshaken_vs_verify_x509_cert_path param set to 1). + + The parameters can contain pseudo-variables. + + This function can be used from ANY_ROUTE. + + Example 1.13. stirshaken_check_identity_with_key usage +... +request_route { + ... + if (1 == stirshaken_check_identity_with_key("/path/to/key")) { + xlog("Shaken Identity is OK\n"); + } else { + xlog("Shaken Identity is invalid\n"); + } + ... +} +... + +4.3. stirshaken_check_identity_with_cert(certPath) + + Same as stirshaken_check_identity_with_key(keyPath) but the key is read + from the certificate which is read from the location provided. + + The parameters can contain pseudo-variables. + + This function can be used from ANY_ROUTE. + + Example 1.14. stirshaken_check_identity_with_cert usage +... +request_route { + ... + if (1 == stirshaken_check_identity_with_cert("/path/to/cert")) { + xlog("Shaken Identity is OK\n"); + } else { + xlog("Shaken Identity is invalid\n"); + } + ... +} +... + +4.4. stirshaken_add_identity(x5u, attest, origtn_val, desttn_val, origid) + + Add SIP Identity Header to the call using default private key (see + as_default_key param). Authenticate call with STIR-Shaken. If origID is + empty, a UUID string is generated to fill the field. The origtn_val + represents the origination telephone number; desttn_val, represents the + destination telephone number; x5u is the HTTP(s) URL referencing to the + public key that should be used to verify the signature; attest + represents the attestation level (should be "A", "B" or "C"). + + The parameters can contain pseudo-variables. If origid is empty, an + unique identifier will be generated with libuuid, e.g. + "3f31bd2b-9fc4-4084-b0b0-566506c46292". + + This function can be used from ANY_ROUTE. + + Example 1.15. stirshaken_add_identity with origid usage +... +request_route { + ... + if (1 == stirshaken_add_identity("https://sp.com/sp.pem", "B", " ++44100", "+44200", "origid")) { + xlog("Shaken authentication added (SIP Identity Header c +reated)\n"); + } else { + xlog("Failed\n"); + } + ... +} +... + + Example 1.16. stirshaken_add_identity with auto generated uuid as + origid usage + + If origid is empty, an unique identifier will be generated with + libuuid, e.g. "3f31bd2b-9fc4-4084-b0b0-566506c46292". +... +request_route { + ... + if (1 == stirshaken_add_identity("https://sp.com/sp.pem", "B", " ++44100", "+44200", "")) { + xlog("Shaken authentication added (SIP Identity Header c +reated)\n"); + } else { + xlog("Failed\n"); + } + ... +} +... + +4.5. stirshaken_add_identity_with_key(x5u, attest, origtn_val, desttn_val, +origid, keyPath) + + Same as stirshaken_add_identity() but using the key read from the + location provided as a last parameter. + + The parameters can contain pseudo-variables. If origid is empty, an + unique identifier will be generated with libuuid, e.g. + "3f31bd2b-9fc4-4084-b0b0-566506c46292". + + This function can be used from ANY_ROUTE. + + Example 1.17. stirshaken_add_identity_with_key usage +... +request_route { + ... + if (1 == stirshaken_add_identity_with_key("https://sp.com/sp.pem +", "B", "+44100", "+44200", uuid, "/path/to/key")) { + xlog("Shaken authentication added (SIP Identity Header c +reated)\n"); + } else { + xlog("Failed\n"); + } + ... +} +... + +5. Installation + + The module depends on "libstirshaken", which is an open source C + library from SignalWire. It can be downloaded from + https://github.com/signalwire/libstirshaken. Until the libstirshaken is + packaged in OS distributions, libstirshaken must be compiled and + installed before the stirshaken module can be compiled. + + Installling libstirshaken is easy: + + Example 1.18. libstirshaken installation +... + git clone git@github.com:signalwire/libstirshaken.git + cd libstirshaken + ./bootstrap.sh + ./configure + make + make check + sudo make install +... + + After libstirshaken had been installed, Kamailio's stirshaken module + can then be built with +... + cd /path/to/kamailio/ + make modules modules=src/modules/stirshaken/ +...