Major update:

Add examples.
Always use .pem extension.
Document use of symlinks.
Document virtual hosting handling.

2 files changed, 68 insertions, 24 deletions

diff --git a/doc/Certificates.txt b/doc/Certificates.txt
index d4a278e..c8b1f7b 100644
--- a/doc/Certificates.txt
+++ b/doc/Certificates.txt
@@ -1,25 +1,66 @@
 Public Key Infrastructure (PKI)
 ===============================
 
+General
+-------
+
+Certificates are not (yet) widely used in Debian, so a typical packaging
+error is to purge certificates on package removal (without checking if
+the certificate was actially created by that package).
+
+A workaround is generous use of symlinks, so that buggy packages only
+remove the symlink.
+
+(Please send a bugreport to the Debian Bug Tracking System if you come
+across such a buggy package!)
+
 Hosts
 -----
-Host certificates can be either self-signed or signed by a CA. The
-private key can be either embedded into the same file as the certificate 
-or in a separate file.
+Host certificates can be either self-signed or signed by a CA. The key
+can be either embedded into the same file as the certificate or in a
+separate file. The simplest form is a self-signed certificate with
+null-password embedded key.
 
-The simplest form is a self-signed certificate with null-password 
-embedded key.
+Some services (like SMTP TLS in server mode) requires certificate and
+key in separate files.
 
-Beware that passwords for host certificates usually means you will need
-to manually start the services.
+Beware that adding password to host certificates may require you to
+manually start the services. Depending on the startup scripts it might
+even HANG THE STARTUP PROCESS OF THE SYSTEM!
 
 Self-signed host certificates contain both certificate and key in same
-file. The file is placed in /etc/ssl/certs/ named by the service it
-provides appended ".pem".
-
-CA signed host certificates have separate public (certificate) and
-private (key) parts. The certificate is located as with self-signed
-ones, and keys are placed in /etc/ssl/private/ named similarly.
+file. CA signed host certificates have separate public (certificate) and
+private (key) files.
+
+The CN field of the certificate must be the hostname as accessed from
+clients. This means virtual hosting requires separate certificates for
+each hostname. Most daemons cannot handle multiple certificates, and
+thus do not support SSL/TLS virtual hosting.
+
+The certificate is placed in /etc/ssl/certs/ named by the hostname
+appended ".pem". If several certificates are used for same host then
+secondary certificates are additionally appended their (primary) service
+like this: "<hostname_<service>.pem".
+
+The key (if separate) is placed in /etc/ssl/private/ named similarly.
+
+Host certificate is symlinked from "/etc/ssl/certs/<service>.pem" for
+each service depending on the key, and the key (if separate) symlinked
+likewise from "/etc/ssl/private/<service>.pem".
+
+Example:
+/etc/ssl/certs/mail.jones.dk.pem
+/etc/ssl/certs/ldap.jones.dk.pem
+/etc/ssl/certs/imapd.pem -> mail.jones.dk.pem
+/etc/ssl/certs/ipop3d.pem -> mail.jones.dk.pem
+/etc/ssl/certs/postfix.pem -> mail.jones.dk.pem
+/etc/ssl/certs/slapd.pem -> ldap.jones.dk.pem
+/etc/ssl/private/mail.jones.dk.pem
+/etc/ssl/private/ldap.jones.dk.pem
+/etc/ssl/private/imapd.pem -> mail.jones.dk.pem
+/etc/ssl/private/ipop3d.pem -> mail.jones.dk.pem
+/etc/ssl/private/postfix.pem -> mail.jones.dk.pem
+/etc/ssl/private/slapd.pem -> ldap.jones.dk.pem
 
 The script /usr/share/local/localmksslcerts can be used to make
 self-signed certificates with embedded keys.
@@ -31,14 +72,18 @@ Certificate Authority
 CA Certificates are divided in a public certificate and a private key.
 
 The CA certificate is placed in /etc/ssl/certs/ and named loosely by the
-CN of the organisation using digits [a-zA-Z0-9_-], appended "_CA.crt".
-
-Example: IT_guide_dr_Jones_CA.pem
+CN of the organisation using digits [a-zA-Z0-9_-], appended "_CA.pem".
 
 CA key is located in /etc/ssl/private/ equally named.
 
-Certificate is symlinked to "/etc/ssl/certs/cacert.pem" for easy
-locating by scripts.
+CA certificate is symlinked from "/etc/ssl/certs/cacert.pem" and the key
+symlinked from "/etc/ssl/private/cakey.pem" to ease locating by scripts.
+
+Example:
+/etc/ssl/certs/IT_guide_dr_Jones_CA.pem and
+/etc/ssl/certs/cacert.pem -> IT_guide_dr_Jones_CA.pem
+/etc/ssl/private/IT_guide_dr_Jones_CA.pem
+/etc/ssl/private/cakey.pem -> IT_guide_dr_Jones_CA.pem
 
 More info here: http://tirian.magd.ox.ac.uk/~nick/openssl-certs/ca.shtml
 
@@ -55,4 +100,4 @@ http://www.cise.ufl.edu/help/secure-access/ssl-mail-setup.shtml
 The script is at /usr/share/local/mycert, adapted to Debian GNU/Linux.
 
 -- 
-$Id: Certificates.txt,v 1.3 2002-12-31 02:31:21 jonas Exp $
+$Id: Certificates.txt,v 1.4 2003-01-02 00:57:54 jonas Exp $
diff --git a/doc/Email.txt b/doc/Email.txt
index e633e01..446f3c3 100644
--- a/doc/Email.txt
+++ b/doc/Email.txt
@@ -61,17 +61,16 @@ for the existense of that directory - when enabled in the hint file
 
 Mail User Agents (MUA)
 ----------------------
-/usr/local/bin/spine and /usr/local/bin/xmutt fires up your favourite
+/usr/local/bin/xpine and /usr/local/bin/xmutt fires up your favourite
 low-tech MUA even in a hi-tech environment :-)
 
 If debugging StartTLS and SASL avoid using Evolution: It leaves a small
-daemon running and not releaing SASL from memory (which might be causing
-some of the frustrations about getting SASL to work). Run the command
-`lsof | grep sasl` to make sure.
+daemon running possibly not freeing SASL from memory. Use the command
+`lsof | grep sasl` to check if SASL is in use (is there a better way?).
 
 ------------
 Here's a brief overview of interaction between mail agents and daemons:
 http://lists.samba.org/pipermail/linux/1999-September/003605.html
 
 -- 
-$Id: Email.txt,v 1.3 2002-12-31 02:31:21 jonas Exp $
+$Id: Email.txt,v 1.4 2003-01-02 00:57:54 jonas Exp $