kamailio/modules/tls/README.TLS

[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