<?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 "../../../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 want a GUI, try <ulink url="http://tinyca.sm-zone.net/">tinyca (http://tinyca.sm-zone.net/)</ulink>, a very nice and small CA management application. 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 for 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 ctificates 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 CA certificate
-----------------------
1. create CA directory
	mkdir ca
	cd ca
	
2. create 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 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; config. dir


Setting &kamailio; to use the 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)
	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>