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:
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