You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
kamailio/modules/tls/doc/certs_howto.xml

155 lines
5.3 KiB

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