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

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

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>