-
Notifications
You must be signed in to change notification settings - Fork 565
/
README
1295 lines (1005 loc) · 44.7 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
TLS module
Peter Griffiths
unknown
Klaus Darilion
enum.at
Edited by
Klaus Darilion
Edited by
Bogdan-Andrei Iancu
Edited by
Cesc Santasusana
Edited by
Klaus Darilion
Edited by
Christian Lahme
Edited by
Ionut-Razvan Ionita
Copyright © 2005 Voice Sistem SRL
Copyright © 2005 Cesc Santasusana
Copyright © 2006 enum.at
Copyright © 2013 Secusmart GmbH
Copyright © 2015 OpenSIPS Solutions
__________________________________________________________
Table of Contents
1. Admin Guide
1.1. Overview
1.2. History
1.3. Scenario
1.4. Dependencies of external libraries
1.5. TLS setup
1.5.1. Creating CA root certificate
1.5.2. Creating a server/client certificate
1.5.3. Setting OpenSIPS to use the certificate
1.5.4. TLS OpenSIPS authentication behavior
1.6. Exported Functions
1.6.1. is_peer_verified
1.7. OpenSIPS Exported parameters
1.7.1. listen=interface
1.7.2. tls_port (integer)
1.7.3. tls_method [(string):](string)
1.7.4. certificate [(string):](string)
1.7.5. private_key [(string):](string)
1.7.6. ca_list [(string):]((string)
1.7.7. ca_dir [(string):](string)
1.7.8. ciphers_list [(string):](string)
1.7.9. dh_params [(string):](string)
1.7.10. ec_curve[(string):](string)
1.7.11. verify_cert [(string):](string) and
require_cert[(string):](string)
1.7.12. tls_handshake_timeout (integer) and
tls_send_timeout (integer)
1.7.13. client_domain_avp (integer)
1.7.14. server_domain, client_domain (string)
1.8. Pseudo-Variables
1.8.1. $tls_version
1.8.2. $tls_description
1.8.3. $tls_cipher_info
1.8.4. $tls_cipher_bits
1.8.5. $tls_[peer|my]_version
1.8.6. $tls_[peer|my]_serial
1.8.7. $tls_[peer|my]_[subject|issuer]
1.8.8. $tls_[peer|my]_[subject|issuer]_cn
1.8.9. $tls_[peer|my]_[subject|issuer]_locality
1.8.10. $tls_[peer|my]_[subject|issuer]_country
1.8.11. $tls_[peer|my]_[subject|issuer]_state
1.8.12. $tls_[peer|my]_[subject|issuer]_organization
1.8.13. $tls_[peer|my]_[subject|issuer]_unit
1.8.14. $tls_[peer|my]_san_email
1.8.15. $tls_[peer|my]_san_hostname
1.8.16. $tls_[peer|my]_san_uri
1.8.17. $tls_[peer|my]_san_ip
1.8.18. $tls_peer_verified
1.8.19. $tls_peer_revoked
1.8.20. $tls_peer_expired
1.8.21. $tls_peer_selfsigned
1.8.22. $tls_peer_notBefore
1.8.23. $tls_peer_notAfter
1.9. OpenSIPS with TLS - script example
1.10. Debug TLS connections
2. Frequently Asked Questions
List of Examples
1.1. is_peer_verified usage
1.2. Set listen variable
1.3. Set tls_port variable
1.4. Set tls_method variable
1.5. Set certificate variable
1.6. Set private_key variable
1.7. Set ca_list variable
1.8. Set ca_dir variable
1.9. Set ciphers_list variable
1.10. Set dh_params variable
1.11. Set verify_cert & require_cert variable
1.12. Set tls_handshake_timeout & tls_send_timeout variable
1.13. Set tls_client_domain_avp variable
1.14. Usage of tls_client_domain and tls_server_domain block
1.15. Example of $tls_[peer|my]_[subject|issuer]
1.16. Script with TLS support
1.17. Example of TLS logging
Chapter 1. Admin Guide
1.1. 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. This module also implements TLS
related functions to use in the routing script, and exports
pseudo variables with certificate and TLS parameters.
1.2. 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.
1.3. 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.
A script example which implements this scenario can be found in
Section 1.9, “OpenSIPS with TLS - script example”.
1.4. Dependencies of external libraries
OpenSIPS TLS v1.0 support requires the following packages:
* openssl or libssl >= 0.9.6
* openssl-dev or libssl-dev
OpenSIPS TLS v1.1/1.2 support requires the following packages:
* openssl or libssl >= 1.0.1e
* openssl-dev or libssl-dev
1.5. TLS setup
TLS provides for strong authentication mechanism, as well as
encryption following authentication. Of course, null encryption
can be used, as well as weak authentication mechanisms (for
example, anonymous, that is, no authentication).
How does verification work? Verification is the process by
which the authentication data provided by the peers is checked.
This data consists usually of a peer certificate, plus a chain
of trusted certification authorities. If for whatever reason,
either of the peers thinks that the handshake is not valid, the
ssl connection is not established. The reasons could be many:
untrusted server certificate, too-weak algorithm, invalid
client cert, no client authentication, ...
This paragraph describe how to generate all the needed keys and
certificates for establishing TLS connection with SER. The
described TLS setup is based on the assumption that we run our
own certificate authority (CA) and we want to connect via TLS
several OpenSIPS servers (SIP domain).
Warning
In this setup the private key is not encrypted. The client and
server keys must not be encrypted (or else OpenSIPS will ask
you for a password on startup or will fail to load the
certificates), but you should use a password at least for your
CA private key.
1.5.1. Creating CA root certificate
This part must be done only once, disregarding the number of
how many interconnected OpenSIPS's we want to have.
Using “opensipsctl tls rootCA”, you may create a local root CA.
The script will produce the private key (which will be used to
sign client/server certificates) and the self-signed
certificate authority.
1.5.2. Creating a server/client certificate
This part must be done for each OpenSIPS server interconnected
into your TLS enabled network: build a certificate request and
sign it with a root CA (yourself or from third party).
For this purpose you may use the “opensipsctl tls userCERT”
The output of the script will be a directory containing all
needed TLS files for configuring the OpenSIPS proxy (private
key, signed certificate and CA list)
1.5.3. Setting OpenSIPS to use the certificate
Append to the CA list file all the CA root certificates ( this
list must contain all CA root certificates to be accepted by
your server):
If you use the “opensipsctl tls userCERT”, it will create an
one element CA list with the CA used to sign the certificate.
To add more CAs to your list, just do:
* cat add_cacert.pem >> calist.pem
Now copy intended OpenSIPS certificate, private key and ca list
file (basically the whole content of the opensipsX directory)
to your intended machine in some directory (which will be
further refer by path “path”).
There are some OpenSIPS TLS specific parameter that must be set
up in OpenSIPS configuration file to use the certificate:
* set up opensips.cfg to use the certificate :
modparam("proto_tls", "certificate", "/path/cert.pem"
* set up opensips to use the private key :
modparam("proto_tls", "private_key", "/path/privkey.pem"
* set up opensips to use the CA list (optional - make sens
only if verify_cert is turned on)
modparam("proto_tls", "ca_list", "/path/calist.pem"
1.5.4. TLS OpenSIPS authentication behavior
The "verify_cert" and "require_cert" are OpenSIPS-names for the
OpenSSL defined flags:
* SSL_VERIFY_PEER is verify_cert
* SSL_VERIFY_FAIL_IF_NO_PEER_CERT is require_cert
(require_cert is only used if verify_cert=1)
If your OpenSIPS is acting as a server (incoming TLS
connections), it will always send its server-side certificate
to the client. If verify_cert is disabled (set to 0), your
OpenSIPS will not request the client a client-certificate. This
means that the client is not authenticated. If verify_cert=1,
your OpenSIPS (the server) sends a client-certificate request
to the client. But the client is free to not provide any. In
this case, require_cert comes into play:
* require_cert=0(client side) - the verification process will
succeed if the client does not provide a certificate, or if
it provides one, it verifies correctly against the server's
list of trusted certification authorities.
* require_cert=1(client side) - the verification process will
only succeed if the client provides a certificate and this
verifies correctly against the server's list of trusted
CAs.
If your OpenSIPS is acting as a client (outgoing TLS
connections), it will always receive a certificate from the
peer. If verify_cert(server side) is disabled (set to 0), your
OpenSIPS will not verifiy the certificate and allows TLS
connections to servers which do not present a valid
certificate. If verify_cert=1(server side), your OpenSIPS (the
client) verifies the server certificate and will close the TLS
connection if the server certificate is not valid.
For more details see page man verify(1).
1.6. Exported Functions
1.6.1. is_peer_verified
Returns 1 if the message is received via TLS and the peer was
verified during TLS connection handshake, otherwise it returns
-1
This function can be used from REQUEST_ROUTE.
Example 1.1. is_peer_verified usage
...
if (is_peer_verified()) {
xlog("L_INFO","request from verified TLS peer\n");
} else {
xlog("L_INFO","request not verified\n");
}
...
1.7. OpenSIPS Exported parameters
All these parameters can be used from the opensips.cfg file, to
configure the behavior of OpenSIPS-TLS.
1.7.1. listen=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.
Example 1.2. Set listen variable
...
listen = tls:1.2.3.4:5061
...
1.7.2. tls_port (integer)
Sets the default TLS listening port.
Default value is 5061.
Example 1.3. Set tls_port variable
...
modparam("proto_tls", "tls_port", 5062)
...
1.7.3. tls_method [(string):](string)
Sets the TLS protocol. The first parameter, if set, represents
the id of the domain. TLS method which can be:
* TLSv1_2 - means OpenSIPS will accept only TLSv1.2
connections (rfc3261 conformant).
* TLSv1 - means OpenSIPS will accept only TLSv1 connections
(rfc3261 conformant).
* SSLv3 - means OpenSIPS will accept only SSLv3 connections
* SSLv2 - means OpenSIPS will accept only SSLv2 connections
(almost all old clients support this).
* SSLv23 - means OpenSIPS will accept any of the above
methods, but the initial SSL hello must be v2 (in the
initial hello all the supported protocols are advertised
enabling switching to a higher and more secure version).
The initial v2 hello means it will not accept connections
from SSLv3 or TLSv1 only clients.
Default value is SSLv23.
Warning
Best is to use SSLv23, for extended compatibility. Using any of
the other will restrict the version to just that one version.
In fact, SSLv2 is disabled in the source code; to use it, you
need to edit tls/tls_init.c
If you want RFC3261 conformance and all your clients support
TLSv1 (or you are planning to use encrypted "tunnels" only
between different OpenSIPS proxies) use TLSv1. If you want to
support older clients use SSLv23 (in fact most of the
applications with SSL support use the SSLv23 method).
Example 1.4. Set tls_method variable
...
modparam("proto_tls", "tls_method", "TLSv1")
modparam("proto_tls", "tls_method", "dom:TLSv1")
...
1.7.4. certificate [(string):](string)
Public certificate file for OpenSIPS. It will be used as
server-side certificate for incoming TLS connections, and as a
client-side certificate for outgoing TLS connections. The first
parameter, if set, represents the id of the domain.
See previous chapter Section 1.5.3, “Setting OpenSIPS to use
the certificate” for more information.
Default value is "CFG_DIR/cert.pem".
Example 1.5. Set certificate variable
...
modparam("proto_tls", "certificate", "/mycerts/certs/opensips_server_cer
t.pem")
modparam("proto_tls", "certificate", "dom:/mycerts/certs/opensips_server
_cert.pem")
...
1.7.5. private_key [(string):](string)
Private key of the above certificate. I must be kept in a safe
place with tight permissions! The first parameter, if set,
represents the id of the domain.
See previous chapter Section 1.5.3, “Setting OpenSIPS to use
the certificate” for more information.
Default value is "CFG_DIR/cert.pem".
Example 1.6. Set private_key variable
...
modparam("proto_tls", "private_key", "/mycerts/private/prik.pem")
modparam("proto_tls", "private_key", "dom:/mycerts/private/prik.pem")
...
1.7.6. ca_list [(string):]((string)
List of trusted CAs. The file contains the certificates
accepted, one after the other. It MUST be a file, not a folder.
The first parameter, if set, represents the id of the domain.
See previous chapter Section 1.5.3, “Setting OpenSIPS to use
the certificate” for more information.
Default value is "".
Example 1.7. Set ca_list variable
...
modparam("proto_tls", "ca_list", "/mycerts/certs/ca_list.pem")
modparam("proto_tls", "ca_list", "dom:/mycerts/certs/ca_list.pem")
...
1.7.7. ca_dir [(string):](string)
Directory storing trusted CAs. The path contains the
certificates accepted, each as hash which is linked to
certificate file. The first parameter, if set, represents the
id of the domain.
See previous chapter Section 1.5.3, “Setting OpenSIPS to use
the certificate” for more information.
Default value is "".
Example 1.8. Set ca_dir variable
...
modparam("proto_tls", "ca_dir", "/mycerts/certs")
modparam("proto_tls", "ca_dir", "dom:/mycerts/certs")
...
1.7.8. ciphers_list [(string):](string)
You can specify the list of algorithms for authentication and
encryption that you allow. The first parameter, if set,
represents the id of the domain. To obtain a list of ciphers
and then choose, use the openssl application:
* openssl ciphers 'ALL:eNULL:!LOW:!EXPORT'
Warning
Do not use the NULL algorithms (no encryption) ... only for
testing!!!
It defaults to the OpenSSL default ciphers.
Example 1.9. Set ciphers_list variable
...
modparam("proto_tls", "ciphers_list", "NULL")
modparam("proto_tls", "ciphers_list", "dom:NULL")
...
1.7.9. dh_params [(string):](string)
You can specify a file which contains Diffie-Hellman parameters
as a PEM-file. This is needed if you would like to specify
ciphers including Diffie-Hellman mode. The first parameter, if
set, represents the id of the domain.
It defaults to not set a dh param file.
Example 1.10. Set dh_params variable
...
modparam("proto_tls", "dh_params", "/etc/pki/CA/dh1024.pem")
modparam("proto_tls", "dh_params", "dom:/etc/pki/CA/dh1024.pem")
...
1.7.10. ec_curve[(string):](string)
You can specify an elliptic curve which should be used for
ciphers which demand an elliptic curve. The first parameter, if
set, represents the id of the domain.
It's usable only if TLS v1.1/1.2 support was compiled. A list
of curves which can be used you can get by
openssl ecparam -list_curve
It defaults to not set a elliptic curve.
1.7.11. verify_cert [(string):](string) and
require_cert[(string):](string)
Technically, verify_cert activates SSL_VERIFY_PEER in the
ssl_context. 'require_cert' does the same with
SSL_VERIFY_FAIL_IF_NO_PEER_CERT, which is only possible if
SSL_VERIFY_PEER is also turned on. Since version 2.1, these
parameters act have been reduced to only one. They act both on
client side and server side if no domain specified, elseway
they act on a specific domain, depending on the first
parameter.
These two parameters are used for incoming TLS connections,
where OpenSIPS acts as server.
See previous chapter Section 1.5.4, “TLS OpenSIPS
authentication behavior” for more information.
It's usable only if TLS support was compiled.
Default value for both is 1.
Example 1.11. Set verify_cert & require_cert variable
...
# turn on the strictest and strongest authentication possible
modparam("proto_tls", "require_cert", "1")
modparam("proto_tls", "require_cert", "1:1")
modparam("proto_tls", "verify_cert", "0")
modparam("proto_tls", "verify_cert", "1:1")
...
1.7.12. tls_handshake_timeout (integer) and tls_send_timeout
(integer)
Timeouts ... advanced users only
Default value for both is 30.
Example 1.12. Set tls_handshake_timeout & tls_send_timeout
variable
...
modparam("proto_tls", "tls_handshake_timeout", 119) # number
of seconds
modparam("proto_tls", "tls_send_timeout", 121) # number
of seconds
...
1.7.13. client_domain_avp (integer)
This sets the interger AVP used for name based TLS server
domains (please see tls_client_domain for more details).
Setting the value to 0 disables name based TLS client domains.
It's usable only if TLS support was compiled.
Default value is 0.
Example 1.13. Set tls_client_domain_avp variable
...
modparam("proto_tls", "tls_client_domain_avp", "400") # only i
nteger named AVPs are supported
...
1.7.14. server_domain, client_domain (string)
If you only run one domain, the main one is enough. If you are
running several TLS servers (that is, you have more than one
listen=tls:ip:port entry in the config file), you can specify
some parameters for each of them separately (not all the
above).
The wording 'TLS domain' means that this TLS connection will
have different parameters than another TLS connection (from
another TLS domain). Thus, TLS domains must are not directly
related to different SIP domains, although they are often used
in common. Depending on the direction of the TLS handshake, a
TLS domain is called 'client domain' (=outgouing TLS
connection) or 'server domain' (= incoming TLS connection).
For example, TLS domains can be used in virtual hosting
scenarios with TLS. OpenSIPS offers SIP service for multiple
domains, e.g. atlanta.com and biloxi.com. Altough both domains
will be hosted a single SIP proxy, the SIP proxy needs 2
certificates: One for atlanta.com and one for biloxi.com. For
incoming TLS connections, the SIP proxy has to present the
respective certificate during the TLS handshake. As the SIP
proxy does not have received a SIP message yet (this is done
after the TLS handshake), the SIP proxy can not retrieve the
target domain (which will be usually retrieved from the domain
in the request URI). Thus, distinction for these domains must
be done by using multiple sockets. The socket on which the TLS
connection is received, identifies the respective domain. Thus
the SIP proxy is able to present the proper certificate.
For outgoing TLS connections, the SIP proxy usually has to
provide a client certificate. In this scenario, socket based
distinction is not possible as there is no dedicated outgoing
socket. Thus, the certificate selection (selection of the
proper TLS client domain) will be name based. For this purpose,
TLS client domains can be associated with a name (e.g. the
domain can be used as name). If the SIP proxy establishes a new
outgoing TLS connection, it checks for the TLS client domain
AVP (parameter tls_client_domain_avp). If this AVP is set (e.g.
in OpenSIPS.cfg), OpenSIPS searches for a TLS client domain
with the same name and uses the certificates defined in the
respective tls_client_domain section.
TLS client domains can also be socket based. If name based
domains are disabled or no name based AVP is found, OpenSIPS
searches for socket based TLS client domains. In this case the
mapping between to the TLS client domain is done based on the
destination socket of the underlying outgoing TCP connection.
Note: If there is already an existing TLS connection to the
remote target, it will be reused wether the TLS client domain
AVP matches or not.
NOTE: Make sure to also configure OpenSIPS to listen on the
specified IP:port.
NOTE: Except tls_handshake_timeout and tls_send_timeout all TLS
parameters can be set per TLS domain. If a parameter is not
explicit set, the default value will be used.
It's usable only if TLS support was compiled.
Example 1.14. Usage of tls_client_domain and tls_server_domain
block
...
listen=tls:IP_2:port2
listen=tls:IP_3:port3
...
# set the TLS client domain AVP
modparam("proto_tls", "tls_client_domain_avp", "400")
...
# 'atlanta' server domain
modparam("proto_tls", "server_domain", "1=IP_2:port2")
modparam("proto_tls", "certificate", "1:/certs/atlanta.com/cert.pem")
modparam("proto_tls", "private_key", "1:/certs/atlanta.com/privkey.pem")
modparam("proto_tls", "ca_list", "1:/certs/wellknownCAs")
modparam("proto_tls", "tls_method", "1:tlsv1")
modparam("proto_tls", "verify_cert", "1:1")
modparam("proto_tls", "require_cert", "1:1")
#'biloxy' server domain
modparam("proto_tls", "server_domain", "2=IP_3:port3")
modparam("proto_tls", "certificate", "2:/certs/biloxy.com/cert.pem")
modparam("proto_tls", "private_key", "2:/certs/biloxy.com/privkey.pem")
modparam("proto_tls", "ca_list", "2:/certs/wellknownCAs")
modparam("proto_tls", "tls_method", "2:tlsv1")
modparam("proto_tls", "verify_cert", "2:1")
modparam("proto_tls", "require_cert", "2:1")
# 'atlanta' client domain
modparam("proto_tls", "client_domain", "3=IP_2:port2")
modparam("proto_tls", "certificate", "3:/certs/atlanta.com/cert.pem")
modparam("proto_tls", "private_key", "3:/certs/atlanta.com/privkey.pem")
modparam("proto_tls", "ca_list", "3:/certs/wellknownCAs")
modparam("proto_tls", "tls_method", "3:tlsv1")
modparam("proto_tls", "verify_cert", "3:1")
modparam("proto_tls", "require_cert", "3:1")
#'biloxy' client domain
modparam("proto_tls", "client_domain", "4=IP_3:port3")
modparam("proto_tls", "certificate", "4:/certs/biloxy.com/cert.pem")
modparam("proto_tls", "private_key", "4:/certs/biloxy.com/privkey.pem")
modparam("proto_tls", "ca_list", "4:/certs/wellknownCAs")
modparam("proto_tls", "tls_method", "4:tlsv1")
modparam("proto_tls", "verify_cert", "4:1")
modparam("proto_tls", "require_cert", "4:1")
# socket based TLS server domains (for TLS based downstream from GW prov
ider)
modparam("proto_tls", "client_domain", "5=IP_5:port5")
modparam("proto_tls", "certificate", "5:/certs/atlanta.com/cert.pem")
modparam("proto_tls", "private_key", "5:/certs/atlanta.com/privkey.pem")
modparam("proto_tls", "ca_list", "5:/certs/wellknownCAs")
modparam("proto_tls", "tls_method", "5:tlsv1")
modparam("proto_tls", "verify_cert", "5:0")
# socket based TLS client domains (for TLS based upstream to GW provider
)
# GW IP: 1.2.3.4, GW port: 6677
modparam("proto_tls", "client_domain", "6=1.2.3.4:6677")
modparam("proto_tls", "certificate", "6:/certs/biloxy.com/cert.pem")
modparam("proto_tls", "private_key", "6:/certs/biloxy.com/privkey.pem")
modparam("proto_tls", "ca_list", "6:/certs/wellknownCAs")
modparam("proto_tls", "tls_method", "6:tlsv1")
modparam("proto_tls", "verify_cert", "6:0")
...
route{
...
# calls to other SIP domains
# set the proper SSL context (certificate) for local hosted domains
avp_write("$fd","$avp(fd)");
t_relay(); # uses NAPTR and SRV lookups
exit;
...
# calls to the PSTN GW
t_relay("tls:1.2.3.4:6677");
exit;
...
1.8. Pseudo-Variables
This module exports the follong pseudo-variables:
Some pseudo variables are available for both, the peer'S
certificate and the local certificate. Further, some parameters
can be read from the “Subject” field or the “Issuer” field.
1.8.1. $tls_version
$tls_version - the TLS/SSL version which is used on the TLS
connection from which the message was received. String type.
1.8.2. $tls_description
$tls_description - the TLS/SSL description of the TLS
connection from which the message was received. String type.
1.8.3. $tls_cipher_info
$tls_cipher_info - the TLS/SSL cipher which is used on the TLS
connection from which the message was received. String type.
1.8.4. $tls_cipher_bits
$tls_cipher_bits - the number of cipher bits which are used on
the TLS connection from which the message was received. String
and Integer type.
1.8.5. $tls_[peer|my]_version
$tls_[peer|my]_version - the version of the certificate. String
type.
1.8.6. $tls_[peer|my]_serial
$tls_[peer|my]_serial - the serial number of the certificate.
String and Integer type.
1.8.7. $tls_[peer|my]_[subject|issuer]
$tls_[peer|my]_[subject|issuer] - ASCII dump of the fields in
the issuer/subject section of the certificate. String type.
Example 1.15. Example of $tls_[peer|my]_[subject|issuer]
/C=AT/ST=Vienna/L=Vienna/O=enum.at/CN=enum.at
1.8.8. $tls_[peer|my]_[subject|issuer]_cn
$tls_[peer|my]_[subject|issuer]_cn - commonName in the
issuer/subject section of the certificate. String type.
1.8.9. $tls_[peer|my]_[subject|issuer]_locality
$tls_[peer|my]_[subject|issuer]_locality - localityName in the
issuer/subject section of the certificate. String type.
1.8.10. $tls_[peer|my]_[subject|issuer]_country
$tls_[peer|my]_[subject|issuer]_country - countryName in the
issuer/subject section of the certificate. String type.
1.8.11. $tls_[peer|my]_[subject|issuer]_state
$tls_[peer|my]_[subject|issuer]_state - stateOrProvinceName in
the issuer/subject section of the certificate. String type.
1.8.12. $tls_[peer|my]_[subject|issuer]_organization
$tls_[peer|my]_[subject|issuer]_organization - organizationName
in the issuer/subject section of the certificate. String type.
1.8.13. $tls_[peer|my]_[subject|issuer]_unit
$tls_[peer|my]_[subject|issuer]_unit - organizationalUnitName
in the issuer/subject section of the certificate. String type.
1.8.14. $tls_[peer|my]_san_email
$tls_[peer|my]_san_email - email address in the “subject
alternative name” extension. String type.
1.8.15. $tls_[peer|my]_san_hostname
$tls_[peer|my]_san_hostname - hostname (DNS) in the “subject
alternative name” extension. String type.
1.8.16. $tls_[peer|my]_san_uri
$tls_[peer|my]_san_uri - URI in the “subject alternative name”
extension. String type.
1.8.17. $tls_[peer|my]_san_ip
$tls_[peer|my]_san_ip - ip address in the “subject alternative
name” extension. String type.
1.8.18. $tls_peer_verified
$tls_peer_verified - Returns 1 if the peer's certificate was
successful verified. Otherwise it returns 0. String and Integer
type.
1.8.19. $tls_peer_revoked
$tls_peer_revoked - Returns 1 if the peer's certificate was
revoked. Otherwise it returns 0. String and Integer type.
1.8.20. $tls_peer_expired
$tls_peer_expired - Returns 1 if the peer's certificate is
expired. Otherwise it returns 0. String and Integer type.
1.8.21. $tls_peer_selfsigned
$tls_peer_selfsigned - Returns 1 if the peer's certificate is
selfsigned. Otherwise it returns 0. String and Integer type.
1.8.22. $tls_peer_notBefore
$tls_peer_notBefore - Returns the notBefore validity date of
the peer's certificate. String type.
1.8.23. $tls_peer_notAfter
$tls_peer_notAfter - Returns the notAfter validity date of the
peer's certificate. String type.
1.9. OpenSIPS with TLS - script example
IMPORTANT: The TLS support is based on TCP, and for allowing
OpenSIPS to use TCP, it must be started in multi-process mode.
So, there is a must to have the "fork" parameter set to "yes":
NOTE: Since the TLS engine is quite memory consuming, increase
the used memory by the run time parameter "-m" (see OpenSIPS -h
for more details).
* fork = yes
Example 1.16. Script with TLS support
# ----------- global configuration parameters ------------------------
debug=3
fork=yes
log_stderror=no
check_via=no
dns=no
rev_dns=no
listen=_your_serv_IP_
port=5060
children=4
fifo="/tmp/opensips_fifo"
# ------------------ module loading ----------------------------------
#TLS specific settings
loadmodule "proto_tls.so"
modparam("proto_tls", "certificate", "/path/opensipsX_cert.pem")
modparam("proto_tls", "private_key", "/path/privkey.pem")
modparam("proto_tls", "ca_list", "/path/calist.pem")
modparam("proto_tls", "ca_list", "/path/calist.pem")
modparam("proto_tls", "require_cert", "1")
modparam("proto_tls", "verify_cert", "1")
alias=_DNS_ALIAS_
loadmodule "modules/sl/sl.so"
loadmodule "modules/rr/rr.so"
loadmodule "modules/maxfwd/maxfwd.so"
loadmodule "modules/mysql/mysql.so"
loadmodule "modules/usrloc/usrloc.so"
loadmodule "modules/registrar/registrar.so"
loadmodule "modules/tm/tm.so"
loadmodule "modules/auth/auth.so"
loadmodule "modules/auth_db/auth_db.so"
loadmodule "modules/textops/textops.so"
loadmodule "modules/uri_db/uri_db.so"
# ----------------- setting module-specific parameters ---------------
# -- auth_db params --
modparam("auth_db", "db_url", "sql_url")
modparam("auth_db", "password_column", "password")
modparam("auth_db", "calculate_ha1", 1)
# -- registrar params --
# no multiple registrations
modparam("registrar", "append_branches", 0)
# ------------------------- request routing logic -------------------
# main routing logic