Gregg Eldred

As I have been getting quite a few referrers looking for SMTP TLS on Domino or Domino TLS, a friend has graciously provided this primer on enabling TLS with Domino.

This post now fully peer reviewed and correct

For the purposes of illustration here, I have used 192.168.0.1 to mean the public IP address of your Domino SMTP/mail router server, domino.company.example to mean your Domino server's fully qualified host name and keyfile.kyr to mean the keyring file used for TLS.

Using SMTP TLS (Transport Layer Security) on Domino is very simple. I have broken down the process into 5 steps:

1. DNS set up
   
2. Firewall config
   
3. Keyring file creation
   
4. Domino server configuration
   
5. Testing

1. DNS Set Up

Before you start, you will need correct forward and reverse pointing for your Domino server. domino.company.example should have a host A record in public DNS pointing to 192.168.0.1 and 192.168.0.1 should have a PTR record pointing to domino.company.example.

When an SSL certificate is issued it will be issued bearing the fully qualified host name of your server and you will need to take steps to prove to the CA that the server is yours to secure. These steps include having correct DNS pointing and may well include others such as providing details of your company registration. Some CAs will verify your claim to secure domino.company.example by correlating the domain name registration with your company name and Dun & Bradstreet reference for example.

If you can't set up correct DNS for whatever reason, give up now and address that issue first.

2. Firewall Config

SMTP TLS uses TCP port 465. In addition to the other ports you have open at the firewall, you will need to open TCP/465 inbound to and outbound from domino.company.example.

If you have one of those firewalls that interferes with SMTP (example: Pix fixup), turn that off now (not the firewall, just the fixup or equivalent). Fixup and like firewall tomfoolery will prevent the use of EHLO by any SMTP client that connects. No EHLO, no TLS.

3. Keyring File Creation

If you already have an SSL certificate for domino.company.example (for HTTPS for example), you can skip this part.

To use TLS, you will need an SSL certificate on a keyring file. This keyring file is exactly the same as one used for other web security duties such as secure web access and is obtained the same way.

Open the Server Certificate Admin database on your server (typically certsrv.nsf) or create one from the template if none exists. Click Create Keyring File.

Here, Common Name means the fully qualified host name of your Domino server. Organisation should match whatever details exist in your domain registration. State should be the two letter abbreviation for your state if in the US, otherwise your region, province or whatever. British readers take note: Country is GB for Great Britain, NOT UK!

Click " Create Key Ring".

This will create two files, keyfile.kyr and keyfile.sth in the Domino root data directory. keyfile.kyr is the key ring and keyfile.sth is the stash file which holds the keyring password, hashed.

Now click Create Certificate request.

Click the Create Certificate request button:

You will need to copy and paste the entire certificate request from this screen into either an email to your certificate authority or their web form if they have one. If you are looking for an authority to use, I still recommend Digi-Sign.

Depending on how efficient your chosen CA is you should shortly receive back a certificate to be installed on the keyring. They may also send one or more trusted roots. If they do, you will need to install those on the keyring first.

To install trusted roots, click "Install Trusted Root Certificate into Keyring":

Here, File Name is the full path to the trusted root certificate file you have been sent and which you have dropped into the local file system temporarily. Repeat this step for all trusted roots you have been sent.

Now you can install your new certificate. Click "Install Certificate Into Keyring"

Here, File Name is the full path to the certificate for domino.company.example which you have dropped into the local file system temporarily.

That's it. You're done. You now have a keyring file containing an SSL certificate valid for domino.company.example and you can go ahead and modify server settings to use it.

4. Domino Server Configuration

Edit the Server Config document for domino.company.example. On the Router/SMTP / Advanced / Commands and Extensions tab, ensure that SSL negotiated over TCP/IP port: is set to Enabled. (Housekeeping tip: disable all the extensions you don't need while you're there.)

Now edit the server document for domino.company.example.

Pay close attention now! Even if your server uses Internet Site documents, you must temporarily set "Load Internet configurations from Server\Internet Sites documents:" on the "Basics" tab to Disabled. There is no need to save the server document in this state, but only by disabling Internet Site documents will you expose this part of the server document form on the Ports/Internet Ports tab. Select the Ports/Internet Ports tab now.

Every other type of Internet site has individual settings for SSL on an Internet Site document BUT outbound mail routing via SMTP does not. This is where you tell your server what keyring to use for outbound SMTP TLS. Enter the name of your new keyring file there, then go back to the Basics tab and re-enable Internet Sites if you need to.

Now you can go back to the Ports/Internet Ports tab. You will see that the SSL settings portion of the form has now been hidden. Set Mail (SMTP Inbound) and Mail (SMTP Outbound) like this:

Save the server document.

If you are not using Internet Site documents, you're done. Otherwise open your inbound SMTP Site document and configure the security tab like so:

Make sure the correct keyring file name is there. If you plan to use authentication, you can enable the Name & Password options. Otherwise leave them off.

Now you're done.

5. Testing

Restart the router and SMTP tasks.

To verify that inbound SMTP TLS is working you can set a notes.ini variable SSL_Trace_Keyfileread=1. This will log keyfile reads to the console.

Telnet into port 25 of domino.example.com. Type EHLO whatever after the greeting. You should see something like this:

220 domino.company.example ready at Thu, 25 Feb 2010 12:14:35 +0000
ehlo whatever
250-domino.company.example Hello whatever ([10.0.100.11]), pleased to meet you
250-TLS
250-STARTTLS
250 SIZE

The exact make-up of this may vary but you should see at least 250-TLS and 250-STARTTLS.

Now enter STARTTLS. You should see something like this at the Domino console:

02/25/2010 12:14:55.77 [078C:0029-0988] ReadKeyfile> Recovering password from stash file
02/25/2010 12:14:56.07 [078C:0029-0988] ReadKeyfile> Password is password
02/25/2010 12:14:56.07 [078C:0029-0988] ReadKeyfile> Reading keyfile c:\lotus\domino\data\keyfile.kyr
02/25/2010 12:14:56.09 [078C:0029-0988] ReadKeyfile> Looking for trusted roots
02/25/2010 12:14:56.19 [078C:0029-0988] ReadKeyfile> Found trusted roots
02/25/2010 12:14:56.19 [078C:0029-0988] ReadKeyfile> Exit status = 0
02/25/2010 12:14:56.19 [078C:0029-0988] ReadKeyfile> Recovering password from stash file
02/25/2010 12:14:56.19 [078C:0029-0988] ReadKeyfile> Password is password
02/25/2010 12:14:56.19 [078C:0029-0988] ReadKeyfile> Reading keyfile c:\lotus\domino\data\keyfile.kyr
02/25/2010 12:14:56.19 [078C:0029-0988] ReadKeyfile> Looking for cert chain
02/25/2010 12:14:56.23 [078C:0029-0988] ReadKeyfile> Got cert chain
02/25/2010 12:14:56.23 [078C:0029-0988] ReadKeyfile> Exit status = 0
02/25/2010 12:14:56.23 [078C:0029-0988] ReadKeyfile> Recovering password from stash file
02/25/2010 12:14:56.23 [078C:0029-0988] ReadKeyfile> Password is password
02/25/2010 12:14:56.23 [078C:0029-0988] ReadKeyfile> Reading keyfile c:\lotus\domino\data\keyfile.kyr
02/25/2010 12:14:56.23 [078C:0029-0988] ReadKeyfile> Looking for private key
02/25/2010 12:14:56.23 [078C:0029-0988] ReadKeyfile> Decoding keys
02/25/2010 12:14:56.27 [078C:0029-0988] ReadKeyfile> Keys decoded
02/25/2010 12:14:56.27 [078C:0029-0988] ReadKeyfile> Exit status = 0

Things to look out for: Correct keyring file is being used. Password is found. Exit status is 0.

Testing outbound is less straightforward. You need to wait until the Domino server encounters an external host which offers TLS. When one does, your server will attempt to negotiate a secure channel and you will see a similar SSL keyfile read debug trace at the Domino console.

Remember to set notes.ini SSL_Trace_Keyfileread=0 when you have finished.

Finished. That wasn't difficult or expensive and it does offer some real security benefit where the supposed security benefits of many other common practices around Internet mail are wholly illusory.

Technorati Tag: Show-n-Tell Thursday SnTT