diff --git a/doc/build-contrib.sh b/doc/build-contrib.sh index ce5c4736acc..2a489817443 100755 --- a/doc/build-contrib.sh +++ b/doc/build-contrib.sh @@ -156,6 +156,7 @@ github_handles=( ["Vlad Paiu"]="vladpaiu" ["Vlad Patrascu"]="rvlad-patrascu" ["Walter Doekes"]="wdoekes" + ["Victor Ciurel "]="victor-ciurel" ) # Commits which have been done on behalf of the original authors diff --git a/modules/proto_smpp/doc/proto_smpp.xml b/modules/proto_smpp/doc/proto_smpp.xml new file mode 100644 index 00000000000..c24393f1978 --- /dev/null +++ b/modules/proto_smpp/doc/proto_smpp.xml @@ -0,0 +1,27 @@ + + + + + + +%docentities; + +]> + + + + proto_smpp module + &osipsname; + + + + &admin; + &contrib; + + &docCopyrights; + diff --git a/modules/proto_smpp/doc/proto_smpp_admin.xml b/modules/proto_smpp/doc/proto_smpp_admin.xml new file mode 100644 index 00000000000..f3f273a6a57 --- /dev/null +++ b/modules/proto_smpp/doc/proto_smpp_admin.xml @@ -0,0 +1,479 @@ + + + + &adminguide; + +
+ Overview + + TLS, as defined in SIP RFC 3261, is a mandatory feature for proxies + and can be used to secure the SIP signalling on a hop-by-hop basis + (not end-to-end). TLS works on top of TCP. DTLS, or TLS over UDP is + already defined by IETF and may become available in the future. + +
+ +
+ History + + The TLS support was originally developed by Peter Griffiths and posted + as a patch on SER development mailing list. Thanks to Cesc + Santasusana, several problems were fixed and some improvements were + added. + + + The TLS support was simultaneously added in both projects. In SER, + the support was committed in a separate experimental + CVS tree, as patch to the main CVS tree. In OpenSIPS, the support was + integrated directly into the CVS tree, as a built-in component, and is + part of stable OpenSIPS since release >=1.0.0. + + + Starting with OpenSIPS 2.1, the TLS has been moved to a separate + transport module, that implements the more generic Transport + Interface. + +
+ +
+ Scenario + + By the increased number of providers the SIP world is continuously + growing. More users means more calls and more calls means a high + probability for a user to receive calls from totally unknown people + or, in the worst case, to receive unwanted calls. To prevent this, a + defense mechanism must be adopted by the SIP provider. Since only the + called user is fully able to classify a call as being unwanted, the + SIP server, based on all information regarding the call should notify + the user about the desirability of the call. Information like the + caller domain, the received source or the incoming protocol can be + very useful for a SIP server to establish the nature of the call. + + + As this information is quite limited, is very improbable for a server + to be able detect the unwanted calls - there are many calls that it + cannot predict anything about its status (neutral calls). So, instead + on alerting the called user about unwanted calls, the server can + notify the user about calls that are considered trusted - calls for + which the server is 100% sure there are not unwanted. + + + So, a trust concept must be defined for SIP servers. Which calls + are trusted and which are not? A call is trusted if the caller can + be identify as a trustable user - a user about we have reliable + information. + + + Since all the user from its domain are authenticated (or should be), + a SIP server can consider all the calls generated by its user as + trusted. Now we have to extend the trust concept to the multi-domain + level. A mutual agreement, between several domains, can establish a + trusting relationship. So, a domain (called A) will consider also as + trusted calls all the calls generated by user from a different domain + (called B) and vice-versa. But just an agreement is not enough; since + the authentication information is strictly limited to a domain + (a domain can authenticate only its own user, not the user from other + domains), there is still the problem of checking the authenticity of + the caller - he can impersonate (by a false FROM header) a user from + a domain that is trusted. + + + The answer to this problem is TLS (Transport Layer Security). All + calls via domain A and domain B will be done via TLS. Authentication + in origin domain plus TLS transport between domains will make the + call 100% trusted for the target domain. + + + For such a mechanism to work, the following requirements must be met: + + + + + all UA must have set as outbound proxy their home server. + + + + + all SIP servers must authenticated all the calls generated by + their own users. + + + + all SIP servers must relay the calls generated be their + user to a trusted domain via TLS. + + + + + Based on this, a server can classify as trusted a call for one of + its user only if the call is also generated by one of its users or + is the call is received from a trusted domain ( which is equivalent + with a call received via TLS). Untrusted call will be calls received + from users belonging to untrusted domains or from users from trusted + domains, but whose calls are not routed via their home server + (so, they are not authenticated by there home servers). + + + Once the server is able to tell if the call is trusted or not, the + still open issue is about the mechanism used by server to notify the + called user about the nature of the incoming call. + + + One way to do it is by remotely changing the ringing type of the + called user's phone. This can be done by inserting special header + into the INVITE request. Such feature is supported by now by several + hardphones like CISCO ATA, CISCO 7960 and SNOM. This phones can + change their ringing tone based on the present or content of the + "Alert-Info" SIP header as follows: + + + + CISCO ATA - it has 4 pre-defined + ringing types. The Alert-Info header must look like + Alert-info: Bellcore-drX EOH where X can be + between 1 and 4. Note that 1 is the phone default ringing tone. + + + + CISCO 7960 - it has 2 pre-defined + ringing types and the possibility of uploading new ones. + The Alert-Info header must look like + Alert-info: X EOH where X can be whatever number. + When this header is present, the phones will not change the + ringing tone, but the ringing pattern. Normally, the phone rings + like [ring.........ring..........ring] where [ring] is the + ringing tone; if the header is present, the ringing pattern will + be [ring.ring.........ring.ring........]. So, to be able to hear + some difference between the two patterns (and not only as length), + its strongly recommended to have a highly asymmetric ringing type + (as the pre-defined are not!!). + + + + SNOM - The Alert-Info + header must look like Alert-info: URL EOH" where + URL can be a HTTP URL (for example) from where the phone can + retrieve a ringing tone. + + + +
+ +
+ Dependencies +
+ &osips; Modules + + The following modules must be loaded before this module: + + + + tls_mgm. + + + + +
+
+ Dependencies of external libraries + + &osips; TLS v1.0 support requires the following packages: + + + openssl or + libssl >= 0.9.6 + + + + openssl-dev or + libssl-dev + + + + + + &osips; TLS v1.1/1.2 support requires the following packages: + + + openssl or + libssl >= 1.0.1e + + + + openssl-dev or + libssl-dev + + + + +
+
+ +
+ &osips; Exported parameters + + All these parameters can be used from the opensips.cfg file, + to configure the behavior of &osips;-TLS. + + +
+ <varname>listen</varname>=interface + + Not specific to TLS. Allows to specify the protocol + (udp, tcp, tls), the IP address and the port where the + listening server will be. + + + Set <varname>listen</varname> variable + +... +listen = tls:1.2.3.4:5061 +... + + +
+ +
+ <varname>tls_port</varname> (integer) + + The default port to be used for all TLS related operation. Be + careful as the default port impacts both the SIP listening part + (if no port is defined in the TLS listeners) and the SIP sending + part (if the destination URI has no explicit port). + + + If you want to change only the listening port for TLS, use the port + option in the SIP listener defintion. + + + Default value is 5061. + + + Set <varname>tls_port</varname> variable + +... +modparam("proto_tls", "tls_port", 5062) +... + + +
+ +
+ <varname>tls_crlf_pingpong</varname> (integer) + + Send CRLF pong (\r\n) to incoming CRLFCRLF ping messages over TLS. + By default it is enabled (1). + + + + Default value is 1 (enabled). + + + + Set <varname>tls_crlf_pingpong</varname> parameter + +... +modparam("proto_tls", "tls_crlf_pingpong", 0) +... + + +
+
+ <varname>tls_crlf_drop</varname> (integer) + + Drop CRLF (\r\n) ping messages. When this parameter is enabled, + the TLS layer drops packets that contains a single CRLF message. + If a CRLFCRLF message is received, it is handled according to the + tls_crlf_pingpong parameter. + + + + Default value is 0 (disabled). + + + + Set <varname>tls_crlf_drop</varname> parameter + +... +modparam("proto_tls", "tls_crlf_drop", 1) +... + + +
+ +
+ <varname>tls_max_msg_chunks</varname> (integer) + + The maximum number of chunks that a SIP message is expected to + arrive via TLS. If a packet is received more fragmented than this, + the connection is dropped (either the connection is very + overloaded and this leads to high fragmentation - or we are the + victim of an ongoing attack where the attacker is sending the + traffic very fragmented in order to decrease server performance). + + + + Default value is 4. + + + + Set <varname>tls_max_msg_chunks</varname> parameter + +... +modparam("proto_tls", "tls_max_msg_chunks", 8) +... + + +
+
+ <varname>trace_destination</varname> (string) + + Trace destination as defined in the tracing module. Currently + the only tracing module is proto_hep. + Network events such as connect, accept and connection closed events + shall be traced along with errors that could appear in the process. + For each connection that is created an event containing information + about the client and server certificates, master key and network layer + information shall be sent. + + + WARNING: A tracing module must be + loaded in order for this parameter to work. (for example + proto_hep). + + + + Default value is none(not defined). + + + + Set <varname>trace_destination</varname> parameter + +... +modparam("proto_hep", "trace_destination", "[hep_dest]10.0.0.2;transport=tcp;version=3") + +modparam("proto_tls", "trace_destination", "hep_dest") +... + + +
+ +
+ <varname>trace_on</varname> (int) + + This controls whether tracing for tls is on or not. You still need to define + in order to work, but this value will be + controlled using mi function . + + + Default value is 0(tracing inactive). + + + Set <varname>trace_on</varname> parameter + +... +modparam("proto_tls", "trace_on", 1) +... + + +
+ +
+ <varname>trace_filter_route</varname> (string) + + Define the name of a route in which you can filter which connections will + be trace and which connections won't be. In this route you will have + information regarding source and destination ips and ports for the current + connection. To disable tracing for a specific connection the last call in + this route must be drop, any other exit + mode resulting in tracing the current connection ( of course you still + have to define a and trace must be + on at the time this connection is opened. + + + IMPORTANT + Filtering on ip addresses and ports can be made using + $si and $sp for matching + either the entity that is connecting to &osips; or the entity to which + &osips; is connecting. The name might be misleading ( + $si meaning the source ip if you read the docs) but in reality + it is simply the socket other than the &osips; socket. In order to match + &osips; interface (either the one that accepted the connection or the one + that initiated a connection) $Ri (ip) and + $Rp (port) can be used. + + + + WARNING: IF is + set to 0 or tracing is deactived via the mi command + this route won't be called. + + + Default value is none(no route is set). + + + Set <varname>trace_filter_route</varname> parameter + +... +modparam("proto_tls", "trace_filter_route", "tls_filter") +... +/* all tls connections will go through this route if tracing is activated + * and a trace destination is defined */ +route[tls_filter] { + ... + /* all connections opened from/by ip 1.1.1.1:8000 will be traced + on interface 1.1.1.10:5060(opensips listener) + all the other connections won't be */ + if ( $si == "1.1.1.1" && $sp == 8000 && + $Ri == "1.1.1.10" && $Rp == 5060) + exit; + else + drop; +} +... + + +
+ +
+ + +
+ Exported MI Functions + +
+ + <function moreinfo="none">tls_trace</function> + + + + + + + Name: tls_trace + + + Parameters: + + + trace_mode(optional): set tls tracing on and off. This parameter + can be missing and the command will show the current tracing + status for this module( on or off ); + Possible values: + + on + off + + + + + + + MI FIFO Command Format: + + + opensipsctl fifo tls_trace on + +
+
+