[sr-dev] git:master: tls: doc - CRL howto and expected default ca section

Module: sip-router Branch: master Commit: 3f48edc9726e2402756ec1e307698c482db471bf URL: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=3f48edc… Author: Andrei Pelinescu-Onciul &lt;andrei(a)iptel.org&gt; Committer: Andrei Pelinescu-Onciul &lt;andrei(a)iptel.org&gt; Date: Thu Sep 9 22:08:29 2010 +0200 tls: doc - CRL howto and expected default ca section - note about the expected default_ca section paths in openssl.cnf (dir = ./demoCA a.s.o), needed for the example/howto to work. - added a section about revoking a certificate --- modules/tls/README | 63 +++++++++++++++++++++++++++++++++++---- modules/tls/doc/certs_howto.xml | 62 +++++++++++++++++++++++++++++++++++--- 2 files changed, 114 insertions(+), 11 deletions(-) diff --git a/modules/tls/README b/modules/tls/README index 8d5cb83..24fe818 100644 --- a/modules/tls/README +++ b/modules/tls/README @@ -223,6 +223,43 @@ make -C modules/tls extra_defs="-DTLS_WR_DEBUG -DTLS_RD_DEBUG" keys), so make sure the corresponding files are readable only by trusted people. You should use a password for your CA private key. +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 ser1_cert_req.pem -out ser1_cert.p +em + + Creating CA certificate ----------------------- 1. create CA dir @@ -235,6 +272,7 @@ Creating CA certificate 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 @@ -249,7 +287,8 @@ Creating a server/client certificate ------------------------------------ 1. create a certificate request (and its private key in privkey.pem) openssl req -out ser1_cert_req.pem -new -nodes - WARNING: the organization name should be the same as in the ca certificate. + WARNING: the organization name should be the same as in the ca certifica +te. 2. sign it with the ca certificate openssl ca -in ser1_cert_req.pem -out ser1_cert.pem @@ -265,8 +304,7 @@ Setting sip-router to use the certificate 2. copy your sip-router certificate, private key and ca list file to your intended machine (preferably in your sip-router configuration directory, - this is the - default place sip-router searches for) + this is the default place sip-router searches for). 3. set up sip-router.cfg to use the certificate if your ser certificate name is different from cert.pem or it is not @@ -275,9 +313,8 @@ Setting sip-router to use the certificate 4. set up sip-router 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 sip-router.c -fg: + (or the certificate name is not the default cert.pem), add to your + sip-router.cfg: modparam("tls", "private_key", "/path/private_key_file") 5. set up sip-router to use the ca list (optional) @@ -289,6 +326,20 @@ fg: 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 ser config. dir + +4. set up sip-router to use the CRL: + modparam("tls", "crl", "path/my_crl.pem") + 1.9. Parameters Revision History diff --git a/modules/tls/doc/certs_howto.xml b/modules/tls/doc/certs_howto.xml index a5cdae1..f75461a 100644 --- a/modules/tls/doc/certs_howto.xml +++ b/modules/tls/doc/certs_howto.xml @@ -24,6 +24,41 @@ </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 ser1_cert_req.pem -out ser1_cert.pem + Creating CA certificate ----------------------- @@ -37,6 +72,7 @@ Creating CA certificate 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 @@ -50,7 +86,7 @@ Creating a server/client certificate ------------------------------------ 1. create a certificate request (and its private key in privkey.pem) openssl req -out ser1_cert_req.pem -new -nodes - WARNING: the organization name should be the same as in the ca certificate. + WARNING: the organization name should be the same as in the ca certificate. 2. sign it with the ca certificate openssl ca -in ser1_cert_req.pem -out ser1_cert.pem @@ -65,8 +101,8 @@ Setting sip-router to use the certificate cat cacert.pem >>calist.pem 2. copy your sip-router certificate, private key and ca list file to your - intended machine (preferably in your sip-router configuration directory, this is the - default place sip-router searches for) + intended machine (preferably in your sip-router configuration directory, + this is the default place sip-router searches for). 3. set up sip-router.cfg to use the certificate if your ser certificate name is different from cert.pem or it is not @@ -74,8 +110,9 @@ Setting sip-router to use the certificate modparam("tls", "certificate", "/path/cert_file_name") 4. set up sip-router 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 sip-router.cfg: + 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 + sip-router.cfg: modparam("tls", "private_key", "/path/private_key_file") 5. set up sip-router to use the ca list (optional) @@ -87,6 +124,21 @@ Setting sip-router to use the certificate 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 ser config. dir + +4. set up sip-router to use the CRL: + modparam("tls", "crl", "path/my_crl.pem") + + </programlisting> </para>