Domino KYRTool and SSL / TLS under Notes 9.01 FP3 IF3 – Positive Impressions



Native SSL / TLS with Domino – Looking Good

Last year IBM got into a bit of a pickle when the Poodle Exploits hit and there was no support for SSLV3 in domino. At the time we moved to putting Apache Proxy Servers in front off all of our web facing servers.

I needed to deploy a new XWorks server for a customer or our “Knowledge Directory” product and we wanted to do some LDAP integration. As the Apache Proxy servers only do HTTP traffic and not LDAP or SMTP I though that I would try the native Domino SSL / TLS functionality again.

My impressions were pretty good. I was able to take an existing Apache SSL certificate and change it into a Domino KYR format certificate without too much hassle. It did take time ( about 2 hours ) but the next time around it would only take 30 minutes.

The KYRtool is a command line tool but following my experiences of doing it for the Apache servers last year it was no more difficult than that platform.

There is a very good Wiki article from IBM.

The Gotchas were as follows

=> when working on your PC you need the 32 bit KYRtool utility even if your PC is 64 bit. Otherwise you get an error

=> when using OpenSSL you need the 64 bit Visual C++ 2008 Redistributables if you have a 64 bit machine ( doh )

=> you need to run openssl as administrator otherwise you get the “error unable to write ‘random state'”

=> if you move the kyr file you MUST also move the .sth file as this contains the password for the kyr file – otherwise you get the error “Access to data denied”

=> You can disable SSLV3 using DISABLE_SSLV3=1 in the notes.ini settings ( please use the configuration document 🙂 )

My Command Lines

The wiki article is very good and you should refer there but my commands ( I already had a certificate ) were :

cd c:\ssl

“C:\Program Files (x86)\IBM\Notes\kyrtool.exe” =”C:\Program Files (x86)\IBM\Notes\notes.ini” create -k “C:\SSL\keyring.kyr” -p somepassowrd

type focul_net_2015.crt gsalphasha2g2r1.cer Root-R1.crt > server3.txt

“C:\Program Files (x86)\IBM\Notes\kyrtool.exe” =”C:\Program Files (x86)\IBM\Notes\notes.ini” verify “C:\SSL\server3.txt”

“C:\Program Files (x86)\IBM\Notes\kyrtool.exe” =”C:\Program Files (x86)\IBM\Notes\notes.ini” import all -k “C:\SSL\keyring.kyr” -i “C:\SSL\server3.txt”

“C:\Program Files (x86)\IBM\Notes\kyrtool.exe” =”C:\Program Files (x86)\IBM\Notes\notes.ini” show keys -k c:\SSL\keyring.kyr

Configuring Mandrill to work with Domino for SMTP routing


Mandrill is a cloud service which is used to ensure that transactional emails such as password resets get through to end users without falling foul of spam filters. We have had to move to using this with our SaaS XPage apps as it seems to be increasingly difficult to get the Microsoft to play nice when they seem to arbitrarily block our traffic ( there may be some good reason for this that we could address but they don’t seem willing to be helpful and tell us what is tripping the SPAM flags ).

There are two big gotchas that you need to work around when setting up Mandrill integration.

1) SMTP Relay Settings.

You can send emails via Mandrill using modern web APIs or by simply directing your outbound SMTP traffic to the Mandrill servers. We choose to use the second option as we didn’t want to change our coding as this point.

When you sign up to Mandrill you will be given a username and the option to generate some API keys which act as passwords.

The Madrill site also helps you to set the DKIM and SPF settings for your domain. This functionality is very good and detects common mistakes and makes suggestions about how to fix them.

As I described in an earlier blog post there is an issue with the SMTP relay configuration in Domino. Although mandrill advise this address actually redirects to a regional server such as You need to add this specific regional server to your Domino config – read the article

2) Mandrill ( and Gmail ) do not like the doc.principal field.

The doc.principal field is commonly used to programatically set the replyto address. When you are offering a SaaS service this becomes quite important as you cannot use the users own email address or you will definitely fall foul of the anti-spam police. Fortunately there is an alternative in the form of doc.INetFrom. The downside is that inetFrom does not work with native Notes mail but that is not an issue in this case.

Be careful though in that you MUST NOT try to use both doc.principal and doc.InetFrom as this will fail for some reason.

There is a  good API report option which will show you that this is the problem. I had to get help from Mandrill ( via twitter ) and they explained that the from attribute has to be set on both the envelope and in the data of the SMTP email. You can see from the example below that Domino is setting the Sender attribute but not the From Attribute.


Once you have stripped out the doc.principals and added doc.InetFrom you get this which does have have a from attribute in the data although interestingly not as an attribute in the API – but it works.



Madrill Itself

I must admit to being impressed with mandrill. I had a look at Sendgrid when Mandrill didn’t work but it was nowhere near as impressive in terms of reports, troubleshooting or options. The pricing options on Mandrill look good too although to be able to request support you need to pay or beg via twitter. Once I had raised a ticket the response was swift.

This was their response

Hi Sean,

Thanks for writing in. It appears that right now your system is not supplying a “From:” header in the DATA portion of your SMTP message. The MAIL FROM header is part of the SMTP envelope, and is different than the “From:” address in the actual message data. The address used in the MAIL FROM header can be used to generate a “Sender:” header, but it isn’t used to generate a “From:” header since in SMTP that can be different than the envelope-from AKA “Sender:” header. You’ll want to make sure that your system is generating both a “From:” and a “To:” message header in theDATA portion of your message in order for the message to be able to be sent through Mandrill.

Please feel free to write back if you have any further questions.


Solved : Quirk with Domino and Relay Hosts which redirect

This took me 4 hours to suss out so I hope that this helps someone else.

If you set up a Relay Host in IBM Domino and are using authentication and it doesn’t work then read on.

The first sign of an issue is that the emails just stay in the

Enable SMTPCLIENTDEBUG=1   ( yes I know it says client but it works on the server )

tell router quit

load router

looking in the log you will now see a trace that says

SMTPClient: Attempting to Connect: Host
SMTPClient: Connection successful
SMTPClient: ReceiveResponse: 250-AUTH PLAIN LOGIN
SMTPClient: SMTP Authentication is required by local server. Username: -blank-

The -blank- bit is the problem because you have defined the user name in the configuration document but it is obviously not being used.


I can tell you that the issue is NOT encryption, is NOT ports, is NOT domino versions.

The problem IS that in this case the settings specify but this is actually redirected to

Changing the configured server address to causes the correct username and password to be used.

I am still having issues with Mandrill not being compatible with Domino in a subsequent step but I will blog about that if I can resolve that issue too.

A shout out to George E Marshall who provided the missing piece via a user forum 🙂