<?xml version="1.0" encoding='ISO-8859-1'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [

<!-- Include general documentation entities -->
<!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
%docentities;

]>

<section id="tls.certs_howto" xmlns:xi="http://www.w3.org/2001/XInclude">
    <sectioninfo>
    </sectioninfo>

	<title>Quick Certificate Howto</title>
		<para>
			There are various ways to create, sign certificates and manage small CAs (Certificate Authorities).
			If you are in a hurry and everything you have are the installed OpenSSL libraries and utilities, read on.
		</para>
		<para>
			Assumptions: we run our own CA.
		</para>
		<para>
			Warning: in this example no key is encrypted. The client and server private keys must not be encrypted
			(&kamailio; doesn't support encrypted keys), so make sure the corresponding files are readable only by
			trusted people. You should use a password to protect your CA private key.
		</para>
		<para>
		<programlisting>
Assumptions
------------

The default openssl configuration (usually /etc/ssl/openssl.cnf)
default_ca section is the one distributed with openssl and uses the default
directories:

...

default_ca      = CA_default            # The default ca section

[ CA_default ]

dir             = ./demoCA              # Where everything is kept
certs           = $dir/certs            # Where the issued certs are kept
crl_dir         = $dir/crl              # Where the issued crl are kept
database        = $dir/index.txt        # database index file.
#unique_subject = no                    # Set to 'no' to allow creation of
                                        # several certificates with same subject.
new_certs_dir   = $dir/newcerts         # default place for new certs.

certificate     = $dir/cacert.pem       # The CA certificate
serial          = $dir/serial           # The current serial number
crlnumber       = $dir/crlnumber        # the current CRL number
crl             = $dir/crl.pem          # The current CRL
private_key     = $dir/private/cakey.pem# The private key
RANDFILE        = $dir/private/.rand    # private random number file

...

If this is not the case create a new OpenSSL config file that uses the above
paths for the default CA and add to all the openssl commands:
 -config filename. E.g.:
	openssl ca -config my_openssl.cnf -in kamailio1_cert_req.pem -out kamailio1_cert.pem


Creating the CA certificate
---------------------------
1. Create the CA directory
	mkdir ca
	cd ca
	
2. Create the CA directory structure and files  (see ca(1))
	mkdir demoCA 		#default CA name, edit /etc/ssl/openssl.cnf
	mkdir  demoCA/private
	mkdir demoCA/newcerts
	touch demoCA/index.txt
	echo 01 >demoCA/serial
	echo 01 >demoCA/crlnumber
	
2. Create CA private key
	openssl genrsa -out demoCA/private/cakey.pem 2048
	chmod 600 demoCA/private/cakey.pem
	
3. Create CA self-signed certificate
	openssl req -out demoCA/cacert.pem   -x509 -new -key demoCA/private/cakey.pem


Creating a server/client TLS certificate
----------------------------------------
1. Create a certificate request (and its private key in privkey.pem)

	openssl req -out kamailio1_cert_req.pem -new -nodes

	WARNING: the organization name should be the same as in the CA certificate.
	
2. Sign it with the CA certificate
	openssl ca -in kamailio1_cert_req.pem -out kamailio1_cert.pem
	
3. Copy kamailio1_cert.pem to your &kamailio; configuration dir


Setting &kamailio; to use the TLS certificate
---------------------------------------------
1. Create the CA list file:
	for each of your CA certificates that you intend to use do:
		cat cacert.pem >>calist.pem
	
2. Copy your &kamailio; certificate, private key and ca list file to your 
	intended machine (preferably in your &kamailio; configuration directory,
	 this is the default place &kamailio; searches for).
	
3. Set up &kamailio;.cfg to use the certificate
	if your &kamailio; certificate name is different from cert.pem or it is not
	placed in &kamailio; cfg. directory, add to your kamailio.cfg:
		modparam("tls", "certificate", "/path/cert_file_name")
	
4. Set up &kamailio; to use the private key
	if your private key is not contained in the same file as the certificate
	(or the certificate name is not the default cert.pem), add to your
	 &kamailio;.cfg:
		modparam("tls", "private_key", "/path/private_key_file")
	
5. Set up &kamailio; to use the CA list (optional)
   The CA list is not used for your server certificate - it's used to approve other servers
   and clients connecting to your server with a client certificate or for approving
   a certificate used by a server your server connects to.
	add to your &kamailio;.cfg:
		modparam("tls", "ca_list", "/path/ca_list_file")
	
6. Set up TLS authentication options:
		modparam("tls", "verify_certificate", 1)
		modparam("tls", "require_certificate", 1) 
	(for more information see the module parameters documentation)


Revoking a certificate and using a CRL
--------------------------------------
1. Revoking a certificate:
	openssl ca -revoke bad_cert.pem
	
2. Generate/update the certificate revocation list:
	openssl ca -gencrl -out my_crl.pem
	
3. Copy my_crl.pem to your &kamailio; config. dir
	
4. Set up &kamailio; to use the CRL:
		modparam("tls", "crl", "path/my_crl.pem")


		</programlisting>
		</para>


</section>
