tls: removed deprecated readme file [skip ci]

src/modules/tls/README.TLS

@@ -1,414 +0,0 @@
-[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, useful 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
-