doc(tls): updated with TLS dir rules

docs/plugins/tls.md

@@ -4,9 +4,11 @@ This plugin enables the use of TLS (via `STARTTLS`) in Haraka.
 
 For this plugin to work you must have SSL certificates installed correctly.
 
+Haraka has [SNI](https://en.wikipedia.org/wiki/Server_Name_Indication) support. When the remote MUA/MTA presents a servername during the TLS handshake and a TLS certificate with that Common Name matches, that certificate will be presented. If no match is found, the default certificate (see Certificate Files) is presented.
+
 ## Certificate Files
 
-Defaults are shown and can be overridden in `config/tls.ini`.
+Defaults settings are shown and can be overridden in `config/tls.ini`.
 
 ```ini
 key=tls_key.pem
@@ -16,20 +18,37 @@ dhparam=dhparams.pem
 
 ## Certificate Directory
 
-If the directory `config/tls` exists, each file within the directory is expected to be a PEM encoded TLS bundle. Generate the PEM bundles in The Usual Way[TM] by concatenating the key, certificate, and CA/chain certs in that order. Example:
+If the directory `config/tls` exists, files within the directory are PEM encoded TLS files in one of two formats: bundles or Wild Wild West.
+
+### Certificate bundles
+
+Generate PEM bundles in The Usual Way[TM] by concatenating the key, certificate, and CA/chain certs in that order. Example:
 
 ```sh
-cat example.com.key example.com.crt ca.crt > config/tls/example.com.pem
+cat example.com.key example.com.crt ca-int.crt > haraka/config/tls/example.com.pem
 ```
 
-An example [acme.sh](https://acme.sh) deployment [script](https://github.com/msimerson/Mail-Toaster-6/blob/master/provision/letsencrypt.sh) demonstrates how to install [Let's Encrypt](https://letsencrypt.org) certificates to the Haraka `config/tls`directory.
+An example [acme.sh](https://acme.sh) deployment [script](https://github.com/msimerson/Mail-Toaster-6/blob/master/provision/letsencrypt.sh) installs [Let's Encrypt](https://letsencrypt.org) certificate bundles to the Haraka `config/tls`directory.
+
+### Wild Wild West
+
+You can drop PEM encoded TLS certificates and keys into files in `config/tls`. The certificate loader is recursive, so TLS files can be in subdirs like `config/tls/mx1.example.com`. The certificate names are parsed from the 1st cert in each file and indexed by the certs Common Name(s). Subject Alternate Names are supported. The file name containing the certificates does *not* matter. Additional certificates within each file are presumed to be CA chain (intermediate) certificates.
+
+If the TLS key is stored in the same file as the matching certificate, then the name of the file does not matter. If the TLS key is alone in a file, the file MUST be named with the keys Common Name. The file extension (.pem or .key are common) does not matter.  If the key is used for multiple CNs, the key must be stored in a file name matching each CNs name. Examples of working TLS key/cert file pairs for the Common Name mx1.example.com:
 
-Haraka has [SNI](https://en.wikipedia.org/wiki/Server_Name_Indication) support. When the remote MUA/MTA presents a servername during the TLS handshake and a TLS certificate with that Common Name matches, that certificate will be presented. If no match is found, the default certificate (see Certificate Files above) is presented.
+1. certificate bundle (see above), key & cert in same file
+    - config/tls/mx1.example.com.pem (recommended)
+    - config/tls/any-unique-name.pem (CN is extracted from 1st cert)
+2. files in TLS dir
+    - config/tls/mx1.example.com.crt
+    - config/tls/mx1.example.com.key
+3. files in subdir
+    - config/tls/example.com/mx1.cert
+    - config/tls/example.com/mx1.example.com.key
 
 ## Purchased Certificate
 
-If you have a purchased certificate, append any intermediate/chained/ca-cert
-files to the certificate in this order:
+For purchased certificate, append any intermediate/chained/ca-cert files to the certificate in this order:
 
 1. The CA signed SSL cert
 2. Any intermediate certificates
@@ -39,8 +58,7 @@ See also [Setting Up TLS](https://github.com/haraka/Haraka/wiki/Setting-up-TLS-w
 
 ## Self Issued (unsigned) Certificate
 
-Create a certificate and key file in the config directory with the following
-command:
+Create a certificate and key file in the config directory with the following command:
 
     openssl req -x509 -nodes -days 2190 -newkey rsa:2048 \
             -keyout config/tls_key.pem -out config/tls_cert.pem