mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
415 lines
19 KiB
415 lines
19 KiB
[NOTE: this file is obsolete, use README instead]
|
|
|
|
|
|
free-TLS core module
|
|
|
|
Created By: Peter Griffiths
|
|
Mantainer: Cesc Santasusana
|
|
|
|
Edited by
|
|
|
|
Cesc Santasusana
|
|
|
|
Copyright © 2005 Cesc Santasusana
|
|
_________________________________________________________
|
|
|
|
TABLE OF CONTENTS
|
|
1. CHAPTER 1. USER'S GUIDE 2
|
|
1.1. OVERVIEW 2
|
|
1.2. DEPENDENCIES 2
|
|
1.2.1. SER Core and patches 2
|
|
1.2.2. SER Modules 2
|
|
1.2.3. External Libraries or Applications 2
|
|
1.3. HOW TO INSTALL 3
|
|
1.3.1. File Structure
|
|
1.3.2. Patches
|
|
1.3.3. Test Configuration in tls/etc
|
|
1.3.4. Tools to create certificates in tls/tools
|
|
1.4. HOW TO COMPILE 3
|
|
1.5. CONFIG FILE PARAMETERS 3
|
|
1.5.1. disable_tls 4
|
|
1.5.2. listen 4
|
|
1.5.3. tls_certificate 4
|
|
1.5.4. tls_private_key 4
|
|
1.5.5. tls_ca_list 4
|
|
1.5.6. tls_ciphers_list 4
|
|
1.5.7. tls_method 4
|
|
1.5.8. tls_verify and tls_require_certificate 4
|
|
1.5.9. tls_handshake_timeout and tls_send_timeout 5
|
|
1.5.10. tls_domain[IP_2:port2] 5
|
|
1.6. SSL/TLS AUTHENTICATION: CLIENT AND SERVER 5
|
|
1.7. EXPORTED FUNCTIONS 6
|
|
2. CHAPTER 2. DEVELOPER'S GUIDE 6
|
|
2.1. TLS_CONFIG 6
|
|
2.2. TLS_INIT 6
|
|
2.2.1. default ssl context 6
|
|
2.2.2. init_tls(void) 6
|
|
2.2.3. destroy_tls(void) 6
|
|
2.2.4. tls_init(struct socket_info *) 7
|
|
2.2.5. ser_malloc, ser_realloc, ser_free 7
|
|
2.3. TLS_SERVER 7
|
|
2.3.1. SSL data per connection 7
|
|
2.3.2. tls_print_errstack(void) 7
|
|
2.3.3. tls_tcpconn_init( struct tcp_connection *, int) 7
|
|
2.3.4. tls_tcpconn_clean( struct tcp_connection *) 7
|
|
2.3.5. tls_close( struct tcp_connection *, int ) 7
|
|
2.3.6. tls_blocking_write( struct tcp_connection, int, const char, size_t ) 7
|
|
2.3.7. tls_read( struct tcp_connection *) 8
|
|
2.3.8. tls_fix_read_conn( struct tcp_connection ) 8
|
|
2.4. TLS_DOMAIN 8
|
|
2.4.1. tls_domains 8
|
|
2.4.2. tls_find_domain( struct ip_addr *, unsigned short) 8
|
|
2.4.3. tls_new_domain( struct ip_addr *, unsigned *) 8
|
|
2.4.4. tls_free_domains(void) 8
|
|
3. CHAPTER 3. FREQUENTLY ASKED QUESTIONS 8
|
|
3.1. WHERE CAN I FIND MORE ABOUT SER? 8
|
|
3.2. WHERE CAN I POST A QUESTION ABOUT THIS MODULE? 8
|
|
3.3. HOW CAN I REPORT A BUG? 9
|
|
3.4. WHAT IS THE DIFFERENCE WITH OpenSER-TLS?
|
|
3.5. I AM NOT HAPPY WITH THIS README ... NOW WHAT?
|
|
|
|
_________________________________________________________
|
|
|
|
1. CHAPTER 1. USER'S GUIDE
|
|
1.1. OVERVIEW
|
|
TLS is an optional part of the core, not a module.
|
|
TLS, as defined in SIP RFC, 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).
|
|
_________________________________________________________
|
|
|
|
1.2. DEPENDENCIES
|
|
1.2.1. SER Core and patches
|
|
Core must be compiled with TCP support and the patched cfg.y and cfg.lex, and some
|
|
modification in Makefile.defs.
|
|
The Makefile.defs file is where the library and include paths are set (where to locate Openssl)
|
|
Read more on this below on the "external libraries" dependencies.
|
|
The cfg.XXX patch provide configuration features from the ser.cfg file, usefull and necessary.
|
|
This core module has been compiled successfully with ser branch rel_0_9_0 (updated
|
|
as of June 2005, ser-0.9.3). It should compile in HEAD too without problem.
|
|
It has been tested for functionality (successfully) with rel_0_9_0 (ser-0.9.0).
|
|
Report on success/failure stories to the mantainer. Tks!
|
|
_________________________________________________________
|
|
|
|
1.2.2. SER Modules
|
|
No dependencies on SER modules
|
|
_________________________________________________________
|
|
|
|
1.2.3. External Libraries or Applications
|
|
The following libraries or applications must be installed before running SER with this module loaded:
|
|
* OpenSSL v0.9.7 or higher (OpenSSL v0.9.6 also compiles, though not recommended).
|
|
Out of OpenSSL, you need:
|
|
* libssl
|
|
* libcrypto
|
|
* openssl/*.h
|
|
Locate this, usually in:
|
|
/usr/local/lib (for libraries)
|
|
/usr/local/ssl/include/openssl (for header files)
|
|
Depending on your distro, these paths may vary. In this case, you need to modify Makefile.defs file in
|
|
$SERROOT. At the bottom of the file, look for
|
|
ifneq ($(TLS),)
|
|
LIBS+= -L$SOMEPATH/lib -lssl -lcrypto
|
|
DEFS+= -I$SOMEPATH/ssl/include
|
|
endif
|
|
Change the LIBS entry to include the folder where the libssl and libcrypto files are.
|
|
Change the DEFS entry to include the folder where the openssl/ folder is.
|
|
NOTE: RedHat ships by default with a very strange setup of the paths, as well as not usual compilation of
|
|
the libraries, which resumes in ... trouble. Look for solutions in Google, or locally compile OpenSSL
|
|
sources on your system.
|
|
________________________________________________________
|
|
1.3. HOW TO INSTALL
|
|
1.3.1. File Structure
|
|
This is the file structure that needs to be created:
|
|
$SER_ROOT/tls/tls_config.h and .c
|
|
$SER_ROOT/tls/tls_init.h and .c
|
|
$SER_ROOT/tls/tls_server.h and .c
|
|
$SER_ROOT/tls/tls_domain.h and .c
|
|
|
|
The files that (may) need to be patched or modified
|
|
$SER_ROOT/Makefile.defs
|
|
$SER_ROOT/cfg.y
|
|
$SER_ROOT/cfg.lex
|
|
NOTE: patches can be found in the tls/patches. See above for Makefile.defs tweaking to locate OpenSSL.
|
|
|
|
1.3.2. Patches
|
|
In the experimental/tls/patches folder, there are the following files:
|
|
- cfg.lex.patch and cfg.y.patch, to be used to patch the corresponding
|
|
files in $SERROOT.
|
|
> cp cfg.XXX.patch $SERROOT/
|
|
> cd $SERROOT
|
|
> patch -p0 < cfg.XXX.patch
|
|
- cfg.y and cfg.lex: these are the full files, taken from the cvs rel_0_9_0 and patched
|
|
with the above patches (for lazy people :D ).
|
|
Use the patches if you have modified your cfg.y or cfg.lex files or if it is a different
|
|
branch. Use the full files if you don't want to patch the files, or have the standard
|
|
cvs rel_0_9_0 branch files.
|
|
|
|
1.3.3. Test configuration
|
|
In the folder tls/etc you can find a sample config file, along with test certificates ready to use.
|
|
Note that in the tls/etc/tls.ser.cfg, the path to certificates and private keys are set to
|
|
/usr/local/etc/ser/certs and /usr/local/etc/ser/private
|
|
(change according to your local configuration)
|
|
|
|
1.3.4. Tools to create certificates
|
|
In the folder tls/tools there are script and configuration files to be used with openssl application
|
|
to create certificate (root CA and user certs).
|
|
Read the README.tls.tools file there for more info.
|
|
________________________________________________________
|
|
|
|
1.4. HOW TO COMPILE
|
|
Easy ;) Add the TLS=1 flag when compiling, for example:
|
|
> make TLS=1 install
|
|
If you have problems compiling the TLS code, such as header files not found, or linking problems related
|
|
to SSL_* functions, check the paths in Makefile.defs (at the bottom, the DEFS+= and LIB+=, and check if
|
|
the openssl/ folder is there, and if the libssl.so and libcrypto.so files are in the specified folders).
|
|
________________________________________________________
|
|
|
|
1.5. CONFIG FILE PARAMETERS
|
|
All these parameters can be used from the ser.cfg file, to configure the behavior of SER-tls.
|
|
________________________________________________________
|
|
1.5.1. disable_tls
|
|
Disables TLS (no server is created on the listen addresses, no outgoing connections can be set up).
|
|
It only exhists if TLS=1 is used at compile time.
|
|
Default_value: disable_tls=0
|
|
________________________________________________________
|
|
1.5.2. listen
|
|
Not specific to TLS. Allows to specify the protocol (udp, tcp, tls), the IP address and the port
|
|
where the listening server will be.
|
|
listen=tls:IP:port
|
|
________________________________________________________
|
|
1.5.3. tls_certificate
|
|
NOTE: To be able to use most of this configuration parameters, you need to have patched cfg.y and cfg.lex
|
|
(and recompile :D )
|
|
Public certificate file for SER. It will be used as server-side certificate for incoming TLS
|
|
connections, and as a client-side certificate for outgoing TLS connections.
|
|
default: "CFG_DIR/cert.pem"
|
|
example: tls_certificate="/mycerts/certs/ser_server_cert.pem"
|
|
________________________________________________________
|
|
1.5.4. tls_private_key
|
|
Private key of the above certificate ... keep it in a safe place with tight permissions!
|
|
default: CFG_DIR/cert.pem
|
|
example: tls_private_key="/mycerts/private/prik.pem"
|
|
________________________________________________________
|
|
1.5.5. tls_ca_list
|
|
List of trusted CAs. The file contains the certificates accepted, one after the other ( cat x >>
|
|
ca.list). It MUST be a file, not a folder (for now).
|
|
default: "" (no ca_list)
|
|
example: tls_ca_list="/mycerts/certs/ca_list.pem"
|
|
________________________________________________________
|
|
1.5.6. tls_ciphers_list
|
|
We can specify the list of algorithms for authentication and encryption that we allow.
|
|
To obtain a list of ciphers and then choose, use the openssl application:
|
|
> openssl ciphers 'ALL:eNULL:!LOW:!EXPORT'
|
|
Do not use the NULL algorithms ... only for testing!!!
|
|
Default: no change, use the default ciphers choosen by OpenSSL.
|
|
Example: tls_ciphers_list="NULL-SHA:NULL-MD5:AES256-SHA:AES128-SHA"
|
|
________________________________________________________
|
|
1.5.7. tls_method
|
|
Protocol version to use. 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_init.c
|
|
Default: sslv23
|
|
tls_method= [sslv2 | sslv23 | sslv3 | tlsv1]
|
|
________________________________________________________
|
|
1.5.8. tls_verify and tls_require_certificate
|
|
This two variables highly effect the final security of your deployment. READ carefully!
|
|
Technically, tls_verify activates SSL_VERIFY_PEER in the ssl_context.
|
|
tls_require_certificate does the same with SSL_VERIFY_FAIL_IF_NO_PEER_CERT, which is
|
|
only possible if SSL_VERIFY_PEER is also turned on.
|
|
See the "how does verification work" for more info
|
|
default is 0 for both.
|
|
Example: tls_verify = 1
|
|
tls_require_certificate = 1
|
|
(this example turns on the strictest and strongest authentication possible)
|
|
________________________________________________________
|
|
1.5.9. tls_handshake_timeout and tls_send_timeout
|
|
Timeouts ... advanced users only.
|
|
default is 120 seconds for both.
|
|
Example: tls_handshake_timeout=119 [number of seconds]
|
|
Example: tls_send_timeout=121 [number of seconds]
|
|
________________________________________________________
|
|
1.5.10. tls_domain[IP_2:port2]
|
|
Note: domains are only possible if cfg.y and cfg.lex are patched.
|
|
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).
|
|
tls_domain[IP_2:port2] {
|
|
#specify parameters for a domain in particular, otherwise,
|
|
#it will use the default. These are the possible parameters to
|
|
#change for each domain
|
|
tls_certificate="new_cert"
|
|
tls_private_key="new_cert_key"
|
|
tls_ca_list="other ca"
|
|
tls_method="tlsv1"
|
|
}
|
|
tls_domain[IP_3:port3] {
|
|
...
|
|
}
|
|
NOTE: For now, tls_ciphers_list cannot be specified on a per domain basis. When I have the time
|
|
to thoroughly test tls_domains, I will add this.
|
|
_________________________________________________________
|
|
|
|
1.6. SSL/TLS AUTHENTICATION: CLIENT AND SERVER
|
|
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 certficate, too-weak algorithm, invalid client cert, no client
|
|
authentication, ...
|
|
The "tls_verify" and "tls_require_certificate" are SER-names for the
|
|
OpenSSL defined flags:
|
|
- SSL_VERIFY_PEER is tls_verify) and
|
|
- SSL_VERIFY_FAIL_IF_NO_PEER_CERT is tls_require_certificate (tls_require_certificate is only used
|
|
if tls_verify=1)
|
|
|
|
If we are acting as a server, we always send our server-side certificate to the client.
|
|
- If tls_verify=0, we do not request the client a client-certificate. This means that the client is not
|
|
authenticated.
|
|
- If tls_verify=1, we (the server) send a client-certificate request to the client. But the client is free
|
|
to not provide any. In this case, tls_require_certificate comes into play:
|
|
_ if tls_require_cert=0, the verification process will succedd 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.
|
|
_ if tls_require_cert=1, the verification process will only succeed
|
|
if the client provides a certificate and this verifies correctly
|
|
against the server's list of trusted CAs.
|
|
_________________________________________________________
|
|
|
|
1.7. EXPORTED FUNCTIONS
|
|
Functions are accessible by including the appropriate tls/tls_xxx.h file.
|
|
|
|
_________________________________________________________
|
|
|
|
2. CHAPTER 2. DEVELOPER'S GUIDE
|
|
________________________________________________________
|
|
2.1. TLS_CONFIG
|
|
It contains configuration variables for ser's tls (timeouts, file paths, etc).
|
|
________________________________________________________
|
|
2.2. TLS_INIT
|
|
Initialization related functions and parameters.
|
|
________________________________________________________
|
|
2.2.1. default ssl context
|
|
extern SSL_CTX *default_ctx;
|
|
It is the common context for all tls sockets. If domains are used, each has its own.
|
|
________________________________________________________
|
|
2.2.2. init_tls(void)
|
|
Called once to initialize the tls subsystem, from the main().
|
|
int init_tls(void);
|
|
________________________________________________________
|
|
2.2.3. destroy_tls(void)
|
|
Called once, just before cleanup.
|
|
void destroy_tls(void);
|
|
________________________________________________________
|
|
2.2.4. tls_init(struct socket_info *)
|
|
Called once for each tls socket created.
|
|
int tls_init(struct socket_info *si);
|
|
________________________________________________________
|
|
2.2.5. ser_malloc, ser_realloc, ser_free
|
|
Wrapper functions around the shm_* functions. OpenSSL uses non-shared memory to create its objects,
|
|
thus it would not work in SER. By creating these wrappers and configuring OpenSSL to use them instead
|
|
of its default memory functions, we have all OpenSSL objects in shared memory, ready to use.
|
|
________________________________________________________
|
|
2.3. TLS_SERVER
|
|
________________________________________________________
|
|
2.3.1. SSL data per connection
|
|
Each TLS connection, incoming or outgoing, creates an SSL * object, where configuration inherited from
|
|
the SSL_CTX * and particular info on that socket are stored. This SSL * structure is kept in SER as long as
|
|
the connection is alive, as part of the struct tcp_connection * object:
|
|
struct tcp_connection *c;
|
|
SSL *ssl;
|
|
//create somehow SSL object
|
|
c->extra_data = (void *) ssl;
|
|
ssl = (SSL *) c->extra_data;
|
|
________________________________________________________
|
|
2.3.2. tls_print_errstack(void)
|
|
/*
|
|
* dump ssl error stack
|
|
*/
|
|
void tls_print_errstack(void);
|
|
________________________________________________________
|
|
2.3.3. tls_tcpconn_init( struct tcp_connection *, int)
|
|
/*
|
|
* Called when new tcp connection is accepted
|
|
*/
|
|
int tls_tcpconn_init(struct tcp_connection *c, int sock);
|
|
________________________________________________________
|
|
2.3.4. tls_tcpconn_clean( struct tcp_connection *)
|
|
/*
|
|
* clean the extra data upon connection shut down
|
|
*/
|
|
void tls_tcpconn_clean(struct tcp_connection *c);
|
|
________________________________________________________
|
|
2.3.5. tls_close( struct tcp_connection *, int )
|
|
/*
|
|
* shut down the TLS connection
|
|
*/
|
|
void tls_close(struct tcp_connection *c, int fd);
|
|
________________________________________________________
|
|
2.3.6. tls_blocking_write( struct tcp_connection, int, const char, size_t )
|
|
size_t tls_blocking_write(struct tcp_connection *c, int fd,
|
|
const char *buf, size_t len);
|
|
________________________________________________________
|
|
2.3.7. tls_read( struct tcp_connection *)
|
|
size_t tls_read(struct tcp_connection *c);
|
|
________________________________________________________
|
|
2.3.8. tls_fix_read_conn( struct tcp_connection )
|
|
int tls_fix_read_conn(struct tcp_connection *c);
|
|
________________________________________________________
|
|
2.4. TLS_DOMAIN
|
|
________________________________________________________
|
|
2.4.1. tls_domains
|
|
extern struct tls_domain *tls_domains;
|
|
|
|
________________________________________________________
|
|
2.4.2. tls_find_domain( struct ip_addr *, unsigned short)
|
|
/*
|
|
* find domain with given ip and port
|
|
*/
|
|
struct tls_domain *tls_find_domain(struct ip_addr *ip,
|
|
unsigned short port);
|
|
________________________________________________________
|
|
2.4.3. tls_new_domain( struct ip_addr *, unsigned *)
|
|
/*
|
|
* create a new domain
|
|
*/
|
|
int tls_new_domain(struct ip_addr *ip, unsigned short port);
|
|
|
|
________________________________________________________
|
|
2.4.4. tls_free_domains(void)
|
|
/*
|
|
* clean up
|
|
*/
|
|
void tls_free_domains(void);
|
|
|
|
________________________________________________________
|
|
CHAPTER 3. FREQUENTLY ASKED QUESTIONS
|
|
|
|
________________________________________________________
|
|
3.1. WHERE CAN I FIND MORE ABOUT SER?
|
|
Take a look at http://iptel.org/ser and http://www.openser.org
|
|
________________________________________________________
|
|
3.2. WHERE CAN I POST A QUESTION ABOUT THIS MODULE?
|
|
In the webpages above there is access to mailing list. Use the users list for normal user support, use the dev
|
|
list for development questions (bugs, fixes, etc).
|
|
________________________________________________________
|
|
3.3. HOW CAN I REPORT A BUG?
|
|
At the dev lists on the above webpages, and also at:
|
|
http://bugs.sip-router.org
|
|
________________________________________________________
|
|
3.4. WHAT IS THE DIFFERENCE WITH OpenSER-TLS?
|
|
None. At least for now. The initial commit in both repositories
|
|
(experimental tree for SER, HEAD for OpenSER) come from the same source:
|
|
an extended version of that released sometime late in 2004 by Peter Griffiths
|
|
and modified by Cesc Santasusana.
|
|
________________________________________________________
|
|
3.5. I AM NOT HAPPY WITH THIS README ... NOW WHAT?
|
|
Three things:
|
|
1 - Complain to the maintainer.
|
|
2 - Contribute yourself with your acquired knowledge. It is welcome.
|
|
3 - Take a look at OpenSER tutorials for TLS: http://openser.org/docs/tls.html
|
|
|