<?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">


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

	<title>Quick Certificate Howto</title>
			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.
			Assumptions: we run our own CA.
			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.

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


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
		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")