Domino, Proton, IAM, OAuth - Part 3: Certs & Keys

Wednesday, February 20, 2019 at 12:41 PM UTC

This is the most critical part in the whole process. If you make errors here everything will fail in the upcoming steps.

Please download the kyrtool from IBM’s website first and copy the kyrtool file from the linux64 folder to

/opt/ibm/domino/notes/lates/linux

You will need kyrtool to create the certificates.

To use Proton with SSL you need certificates. If you grab the Domino AppDev Pack, there is a tarball that contains the proton executable and some scripts (proton-addin-0.2.2.tgz). 

  • proton
  • setup_proton.sh
  • make_certs.sh
  • make_keyring.sh

Please uncompress this tar somewhere but NOT in the binary folder of Domino like the docs suggest. It’s completely useless to do this. I suggest to use the directory /install we created before. Make sure the notes user (from the Domino setup process) can access this folder. You already did this in part 1.

Copy the proton file to Domino with user root

cp proton /opt/ibm/domino/notes/latest/linux

Make sure the result looks like this:

-rwxr-xr-x  1 root root    33739336 Nov 29 15:25 proton*

We will now take a detailed look at the scripts as they bear the risk to fail everything that will follow. The official docs don’t say anything about the modifications you have to make here

First: forget the setup_proton script. Delete it. It does absolutely nothing but just md5 checking the other two script files and set some access rights. We can leave that alone and do it manually - we have to modify both so that an md5 check would fail anyway.

As you have to run at least the make_keyring script as a non-root user (i.e. the notes user) set the access rights for both make scripts to be open for all. The scripts aren’t needed anymore afterwards so it is completely safe to to so. You can actually remove them afterwards.

chmod 777 make*

What do these scripts really do?

The make_certs script creates sample certificates: a root cert (ca), two application certs (app1 and app2) and a server cert (server).

The make_keyring script creates a self-signed SSL cert in a Domino manner to use for the Proton task. As Proton only will communicate internally it is totally ok to use a self-signed certificate for that. This means you don’t have to use a valid SSL cert e.g. from Letsencrypt.

BOTH scripts need to be modified!

make_certs

Find line 24 and change the canonical name to the one you used for your Domino server, e.g. „/O=Proton/CN=Proton-TestCA“. The key is the O part that should match your Domino org you used during the Domino configuration process. The common name though is not important but to avoid any confusion name it like the example with a suffix of „TestCA“.

Next find the lines 39-41. Also change the O-part to your org name and the CN part to the real Domino server name, e.g.

/O=Proton/CN=Proton. Lastly change the „DNS:“ content to the full qualified hostname of your server machine, e.g. „DNS: domino10.local“.

Hostnames always are important. In this case it’s important to have a valid hostname that will be used in the certificate. Again: the cert will be invalid anyway but for internal communication this is ok.

make_keyring

Find line 18 and replace the two $VARIABLES with real path names. If you installed Domino in the default paths it should look like this:

(set -x ; cd /local/notesdata; /opt/ibm/domino/bin/tools/startup kyrtool $* )

Also find the next two lines that start with „readonly“. You should choose more reasonable names for the two files that will be created other than sample1.* . It’s up to you how you name them but please change the folder from /tmp to /install to have everything together afterwards. The /tmp folder in Ubuntu is emptied at every restart, so be careful what to store here!

readonly keyring=/install/proton.kyr
readonly sthfile=/install/proton.sth

Remember: these two files will go to /local/notesdata and will be used by the Proton task.

Switch to the notes user with

su notes

and provide the password.

Now execute both scripts. Both are executable for user notes. Start with make_certs

./make_certs
./make_keyring

You should see some long outputs containing fingerprints at the end. You absolutely should not see any error messages. I had errors a lot when trying to execute those scripts inside the domino folder as the official docs suggest. Therefore we copied them here and made them executable for user notes.

The result is a bunch of files:

-rw-rw-r--  1 notes notes      1716 Feb 16 20:40  app1.crt
-rw-------  1 notes notes      3247 Feb 16 20:40  app1.key
-rw-rw-r--  1 notes notes      1716 Feb 16 20:40  app2.crt
-rw-------  1 notes notes      3247 Feb 16 20:40  app2.key
-rw-rw-r--  1 notes notes      1850 Feb 16 20:40  ca.crt
-rw-------  1 notes notes      3311 Feb 16 20:40  ca.key
-rw-rw-r--  1 notes notes        17 Feb 16 20:40  ca.seq
-rw-rw-r--  1 notes notes     35391 Feb 16 20:41  proton.kyr
-rw-------  1 notes notes       129 Feb 16 20:41  proton.sth
-rw-rw-r--  1 notes notes      1765 Feb 16 20:40  server.crt
-rw-------  1 notes notes      3243 Feb 16 20:40  server.key

Copy the two proton.* files to /local/notesdata.

cp proton.* /local/notesdata

Copy the app1.crt file to the machine where you use Domino Administrator. We will need at least the app1.crt file for one of the technical accounts we created earlier. You can either do this from the server or from the client machine. I prefer the latter:

scp root@<ipOrHostname>:/install/app1.crt c:\Users\obusse\Desktop

Open the Domino Directory of your server. Open the person document for the app1 user. Edit the document. From the menu choose „Action, Import Internet Certificates“ and choose the app1.crt file. To find it select „All files *.*“ from the list to see it. Accept the next dialog as is and in the second dialog also accept all. You should receive a message that certificates are imported successfully. Save and close the document. If you re-open it, go to the tab „Certificates, Internet Certificates“. You should see the certificate’s name that corresponds to the name you set in the make_cert script.

What did you just do right now?

You created a technical account with a certificate to access Proton with a client certificate. This is just a start and not the practical way of working with Proton later. It’s just for testing. Therefore we leave the app2.crt alone and do not create a second account, but of course you could - it just makes no difference for the next steps. Our goal is to use OAuth to authenticate our Node.js apps later with our Domino server using „real“ user accounts.

Setup Proton

I will skip the anonymous access for Proton in this series. What we want to do is at least using a client certificate for it. Add these lines to the server’s notes.ini:

# use proton with SSL
PROTON_SSL=1
# make proton listen on port 3002
PROTON_LISTEN_PORT=3002
# make proton listen on all addresses
PROTON_LISTEN_ADDRESS=0.0.0.0
# use proton with a client certificate
PROTON_AUTHENTICATION=client_cert
# use this keyfile for SSL
PROTON_KEYFILE=proton.kyr

Remember the kyr-file we created earlier? Here you go.

I recommend to add Proton to the startup task list:

ServerTasks=Update,Replica,Router,AMgr,AdminP,CalConn,Sched,HTTP,LDAP,RnRMgr,Proton

Also, just add these lines to make Proton tell you a bit more about what goes on:

PROTON_TRACE_REQUEST=1
PROTON_TRACE_SESSION=1
PROTON_TRACE_SEARCH=1
PROTON_TRACE_SESSION_CACHE=1

Restart the server.

In the task list (show tasks) you should see

PROTON Listening on 0.0.0.0:3002, SSL-ENABLED

Creating a test app

To test client certificate access you have to create a test Node.js app. This can either be done on a client machine or on the server itself.

In both cases you need 3 of the certification files you created earlier:

  • app1.crt
  • app1.key
  • ca.crt

These files must be part of the Node.js project stored in the root folder or in a folder below the root folder of the application. I recommend to use a folder.

As an easy start just clone this repo, enter the client_cert folder and install all Node.js packages:

git clone https://gitlab.com/obusse/proton_blog.git

Copy domino-domino-db.1.1.0.tgz to the vendor folder.

Copy the app1.crt, app1.key and ca.crt files to the certs folder.

cd client_cert
npm install

You may want to change the hostname in line 24 to your hostname of the Domino machine.

Run the app with

npm start

The expected output is:

Server {
  requestLibrary:
   { server: {},
     database:
      { createDocument: [Function: createSingleDocument],
        explainQuery: [Function: explainQuery],
        bulkCreateDocuments: [Function: createDocuments],
        bulkReadDocuments: [Function: readDocuments],
        bulkReadDocumentsByUnid: [Function: readDocumentsByUnid],
        bulkDeleteDocuments: [Function: deleteDocuments],
        bulkDeleteDocumentsByUnid: [Function: deleteDocumentsByUnid],
        bulkDeleteItems: [Function: deleteItems],
        bulkDeleteItemsByUnid: [Function: deleteItemsByUnid],
        bulkReplaceDocumentsByUnid: [Function: replaceDocumentsByUnid],
        bulkReplaceItems: [Function: replaceItems],
        bulkReplaceItemsByUnid: [Function: replaceItemsByUnid] },
     document:
      { read: [Function: readSingleDocument],
        replaceItems: [Function: replaceSingleDocumentItems],
        replace: [Function: replaceSingleDocument],
        delete: [Function: deleteSingleDocument],
        deleteItems: [Function: deleteSingleDocumentItems] } },
  getHostName: [AsyncFunction],
  getConnection: [AsyncFunction],
  useDatabase: [AsyncFunction] }

Congratulations, you’ve set up your Proton server to use SSL and client certificate access that connects to your server!

Next up is part 4: IAM service






Latest comments to this post

Sven wrote on 11.06.2019, 08:59

Hallo Oliver,

die Testdateien auf deinem verlinkten Gitlab Repo haben leider nicht ganz funktioniert.
Hier fehlt bei der app.js in der serverConfig (Z. 23-28) die Verlinkung der darüber festgelegten
Credentials und das Setzen von secure auf true.

Wäre vielleicht ganz gut, wenn du das bei Gelegenheit anpassen könntest, falls jemand darüberstolpert und
sich wundert, warum das mit TLS nicht funktioniert.

Ansonsten danke soweit für deine Tutorials! :)

 Link to this comment
Lothar wrote on 22.03.2019, 10:59

Hallo Oliver,

du könntest hier evtl. noch den 4. Teil verlinken (ist im Moment nur reiner Text)... Wink

 Link to this comment

Leave a comment right here