About TLS support

You can configure Proton to allow domino-db applications Anonymous-only access to databases on the server. In this case, maximum access is governed by the 'Maximum Internet name and password' setting specified on the database ACL. Network traffic to and from Proton can be either encrypted or unencrypted.

To configure Proton for this use case, set the Client authentication setting to Anonymous and the Enable SSL/TLS connections setting to enabled or disabled. If enabled, be sure to also set the Keyring File setting.

Client certificate authentication

A more typical use case is to allow client applications using domino-db to have the rights of a real identity on the Domino server. Access to databases on the server is governed by each database ACL for every identity using domino-db.

To do this, set the Client authentication setting to Client Certificate.

When you enable this setting, the following additional steps are required:

The client application must supply a client certificate, signed by an authority that Proton trusts, when making domino-db requests to the Proton server on Domino. The Common Name (CN) in the client certificate must have a name that can found in the Domino directory. Proton performs a lookup in the Domino directory to find the Person document using the Common Name (CN) from the client certificate. For information on using sample scripts to create client certificates, see Creating certificates and keyfiles
The Domino administrator must create a Person document in the Domino directory to use as the ID for the client application and then import the client certificate into the document. For more information, see Preparing the Person document for an application.

Preparing the Person document for an application

The Domino administrator must create a Person document in the Domino directory that identifies each client application using domino db and to control the level of access in databases using the database ACL.

The Person document may be created manually or by registering a new user in the Domino directory. These are the requirements for the application's Person document:

The Short name/UserID in the Person document should match the Common Name in the client certificate. This allows Proton to locate the Person document from the client client certificate.
The client certificate must be imported into Person document. Proton uses this to verify the client certificate presented by a client application.

The following image shows how to verify that a Person document has an imported certificate:

There are two methods to import a client certificate into a Person document:
1. Using the Notes Client
2. Using Proton

Import client certificate using the Notes Client

Follow these steps to import a client certificate into a Person document using the Notes Client.

Locate and Open the Person document for the application
Click on the Edit Person button
Select the Actions menu and then Import Internet Certificates
Specify the File containing the Internet Certificates
Specify the certificate file format
Accept the certificate
Close Person document without saving changes
Open Person document, and verify client certificate is shown under the Certificates and Internet Certificates tabs.

Import client certificate using Proton

This method for loading the certificate into the directory allows you to verify that the client application using the certificate is mapped to the correct Person document in the directory. You only provide the file name with the client certificate. Proton matches the certificate to a user in the Domino directory using the common name in the certificate, and is the same lookup that Proton uses when the application sends a request via domino-db.

Use the load proton --importcert certfilename.crt command. For example:

> load proton --importcert testapp1.crt
06/10/2020 01:15:10 PM  PROTON_CMD: import_certificate: testapp1.crt
06/10/2020 01:15:10 PM  PROTON_CMD: Certificate::init: subject: CN=TestApp1/OU=Applications/O=Develop
06/10/2020 01:15:10 PM  PROTON_CMD: Updating note 0x1D96 for 'TestApp1'

Creating certificates and keyfiles

The AppDev Pack kit includes sample scripts to:

Create your own private certificate authority. Note that a private certificate authority is not automatically trusted by others; additional steps are needed to establish this trust.
Create one, or more, client key/certificates signed by your private certificate authority. These keys may be used to authenticate domino-db applications, including the IAM functional id.
Create a Domino keyfile with a server certificate and key, suitable for use by the Proton addin task.

You may use these scripts to create your own TLS key infrastructure to get started, but ultimately, you should consult with your organization's security expert before using these keys in a production environment.

The kit includes Linux and Windows versions of the scripts. They produce the same type of keys and certificates.

The setup guide shows how to create the same type of keys and certificates using raw OpenSSL commands.

Using the scripts on Linux

There are two sample scripts provided with the install kit that show how to create a certificate authority, client and server keys and the keyring. Consult with your organization's security expert before using these scripts.

make_certs.sh: creates a certificate authority and a few sample certificates and keys using the openssl command line utility. Client applications using the domino-db module will need their own certificate and key when Proton is enabled for SSL connections.
make_keyring.sh: shows how to use the Domino KYRTool to create a keyring file that Proton can use for TLS connections. The script uses the sample server key and certificate created by make_certs.sh.

Note: You should modify the provided scripts to match your environment. This includes the number and types of certificates, names stored in the certificates, passwords, and file names.

This is a sample session using a Linux shell:

Step 1 - create a new directory and initialize with the scripts

The example scripts do not manipulate files outside of the current directory. To start, create a new directory and move the scripts into the directory. You will make changes to the scripts in this directory to match the needs of your configuration.

$ mkdir $HOME/mycerts
$ cd $HOME/mycerts
$ cp xxxxx/make_certs.sh make_certs.sh
$ cp xxxxx/make_keyring.sh make_keyring.sh

Step 2 - customize your make_certs.sh script

The script included in the kit is an example. You will want to customize it for your environment. The most common changes to make are:

The name and password of your Certificate Authority
The password for new keys
The names of new keys

You can run the script multiple times and it will not overwrite existing files. You can run the script one time, then later add a new key and run the script again to create the new key. Existing keys aren't touched.

Here are an example set of changes you can make to the script. Lines modified are marked at the start of the line with the ! symbol.

  # CUSTOMIZE: Set the parameters below.

  # The subject name of the root certificate.
! ROOT_SUBJECT="/O=MyRootCA/CN=MyRootCA"
  # The number of days the root certificate will be valid.
! ROOT_VALIDITY=3650
  # The password to create and access the root certificate.
! ROOT_PASSWORD=pass:this-is-a-secret-password-3487
  # Number of days leaf certificate(s) will be valid.
  LEAF_VALIDITY=365
  # The password to create and access the leaf certificate(s).
! LEAF_PASSWORD=pass:another-secret-password-1324

  create_root

  # CUSTOMIZE: Change the list of certificates to create and their attributes.
  # Parameters to create_leaf: "file-name" "subject-name" "optional-subject-alternate-names"
! create_leaf server1 "/O=MyOrg/CN=proton-server-1" "DNS:domino1.myco.example.com"
! create_leaf server2 "/O=MyOrg/CN=proton-server-2" "DNS:domino2.myco.example.com"
! create_leaf iamapp "/O=MyOrg/CN=iamclientforproton" ""
! create_leaf finapp "/O=MyOrg/OU=Apps/CN=finapp" ""
! create_leaf salesapp "/O=MyOrg/OU=Apps/CN=salesapp" ""
! create_leaf hrapp "/O=MyOrg/OU=Apps/CN=hrapp" ""
! create_leaf storeapp "/O=MyOrg/OU=Apps/CN=storeapp" ""

Step 3 - execute the make_certs.sh script for the first time

When you execute the make_certs.sh script for the first time:

the script will create the self-signed certificate for your Certificate Authority. These are the ca.* files.
the script will create the keys and certificates as indicated.
at the end, it will report details about all the certificates (*.crt) it finds in the directory.

$ ./make_certs.sh

...
Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number:
            a8:93:59:f2:d8:04:30:6e
    Signature Algorithm: sha256WithRSAEncryption
        Issuer: O=MyRootCA, CN=MyRootCA
        Validity
            Not Before: Jun 12 18:23:49 2020 GMT
            Not After : Jun 12 18:23:49 2021 GMT
        Subject: O=MyOrg, CN=proton-server-1
        X509v3 extensions:
            X509v3 Subject Alternative Name:
                DNS:domino1.myco.example.com

...
Certificate:
    Data:
        Version: 1 (0x0)
        Serial Number:
            a8:93:59:f2:d8:04:30:73
    Signature Algorithm: sha256WithRSAEncryption
        Issuer: O=MyRootCA, CN=MyRootCA
        Validity
            Not Before: Jun 12 18:23:54 2020 GMT
            Not After : Jun 12 18:23:54 2021 GMT
        Subject: O=MyOrg, OU=Apps, CN=storeapp

...
$ ls
ca.crt  finapp.crt  hrapp.key   make_certs.sh  server1.crt  server2.key
ca.key  finapp.key  iamapp.crt  salesapp.crt   server1.key  storeapp.crt
ca.seq  hrapp.crt   iamapp.key  salesapp.key   server2.crt  storeapp.key

Step 4 - create additional certificates

You can execute the make_certs.sh script multiple times. It will not overwrite existing certificates. Therefore you can add additional certificates to the script and run it again to create them.

Step 5 - customize your make_keyring.sh script

The make_keyring.sh script included in the kit is an example. You will want to customize it for your environment. The most common changes to make are:

The file name for the keyfile
The password for the keyfile
The server key and certificate to import

Each Domino server must have its own keyfile with only its private key contents. Therefore, you must update and run the script separately for each Domino server.

Here are an example set of changes you can make to the script. Lines modified are marked at the start of the line with the ! symbol.

  # CUSTOMIZE: Set the parameters below.

  # The Domino server data directory
  export NOTESDATA=${NOTESDATA-/local/notesdata}
  # The Domino server binaries directory
  export NOTESBIN=${NOTESBIN-/opt/hcl/domino/bin/tools}
  # The root certificate file name
  ROOTCA_CRT=ca.crt
  # The server private key file
! SERVER_KEY=server2.key
  # The server certificate file
! SERVER_CRT=server2.crt
  # The output KYRFILE name
! KYRFILE=$NOTESDATA/server2keys.kyr
  # The output STHFILE name
! STHFILE=$NOTESDATA/server2keys.sth
  # The password to the KYRFILE
  KYRPASS=1234567890

Step 6 - create the keyfile

Execute the make_keyring.sh script to create a new keyfile for the Domino server. If the keyfile already exists the script will not overwrite it.

$ ./make_keyring.sh
...

$ ls /notesdata/server2*
/notesdata/server2keys.kyr  /notesdata/server2keys.sth

Using the scripts on Windows

Prerequisites

The following scripts require a Windows distribution of OpenSSL. You can find a reference to a Windows package here.

Sample Scripts

make_certs.cmd: creates a certificate authority and a few sample certificates and keys using the openssl command line utility. Client applications using the domino-db module will need their own certificate and key when Proton is enabled for SSL connections.
make_keyring.cmd: shows how to use the Domino KYRTool to create a keyring file that Proton can use for TLS connections. The script uses the sample server key and certificate created by make_certs.cmd.

Note: You should modify the provided scripts to match your environment. This includes the number and types of certificates, names stored in the certificates, passwords, and file names.

This is a sample session using the Windows Command Prompt:

Step 1 - create a new directory and initialize with the scripts

> mkdir \certs
> cd \certs
> copy xxxx\make_certs.cmd .
> copy xxxx\make_keyring.cmd .

Step 2 - customize your make_certs.cmd script

The script included in the kit is an example. You will want to customize it for your environment. The most common changes to make are:

The name and password of your Certificate Authority
The password for new keys
The names of new keys

Here are an example set of changes you can make to the script. Lines modified are marked at the start of the line with the ! symbol.

  @REM CUSTOMIZE: Change the parameters here

  @REM The subject name of the root certificate.
! SET ROOT_SUBJECT=/O=MyRootCA/CN=MyRootCA
  @REM The number of days the root certificate will be valid.
! SET ROOT_VALIDITY=3650
  @REM The password to create and access the root certificate.
! SET ROOT_PASSWORD=pass:this-is-a-secret-password-2384
  @REM Number of days leaf certificate(s) will be valid.
  SET LEAF_VALIDITY=365
  @REM The password to create and access the leaf certificate(s).
! SET LEAF_PASSWORD=pass:another-secret-password-23748034

  call :create_root || goto :cleanup

  @REM CUSTOMIZE: Change the list of certificates to create and their attributes.
  @REM Parameters to create_leaf: "file-name" "subject-name" "optional-subject-alternate-names"
! call :create_leaf server1 "/O=MyOrg/CN=proton-server-1" "DNS:domino1.myco.example.com" || exit /B 1
! call :create_leaf server2 "/O=MyOrg/CN=proton-server-2" "DNS:domino2.myco.example.com" || exit /B 1
! call :create_leaf iamapp "/O=MyOrg/CN=iamclientforproton" "" || exit /B 1
! call :create_leaf finapp "/O=MyOrg/OU=Apps/CN=finapp" "" || exit /B 1
! call :create_leaf salesapp "/O=MyOrg/OU=Apps/CN=salesapp" "" || exit /B 1
! call :create_leaf hrapp "/O=MyOrg/OU=Apps/CN=hrapp" "" || exit /B 1
! call :create_leaf storeapp "/O=MyOrg/OU=Apps/CN=storeapp" "" || exit /B 1

Step 3 - execute the make_certs.cmd script for the first time

When you execute the make_certs.cmd script for the first time:

the script will create the self-signed certificate for your Certificate Authority. These are the ca.* files.
the script will create the keys and certificates as indicated.
at the end, it will report details about all the certificates (*.crt) it finds in the directory.

Note: make_certs.cmd will pause at each step in the process of running the script.

c:\certs>.\make_certs.cmd

...
Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number:
            21:cd:33:6c:f9:98:02:b1:e9:be:59:3e:36:3e:1c:0b:0f:a3:f7:21
        Signature Algorithm: sha256WithRSAEncryption
        Issuer: O = MyRootCA, CN = MyRootCA
        Validity
            Not Before: Jun 15 13:22:30 2020 GMT
            Not After : Jun 15 13:22:30 2021 GMT
        Subject: O = MyOrg, CN = proton-server-1
        X509v3 extensions:
            X509v3 Subject Alternative Name:
                DNS:domino1.myco.example.com

...
Certificate:
    Data:
        Version: 1 (0x0)
        Serial Number:
            21:cd:33:6c:f9:98:02:b1:e9:be:59:3e:36:3e:1c:0b:0f:a3:f7:25
        Signature Algorithm: sha256WithRSAEncryption
        Issuer: O = MyRootCA, CN = MyRootCA
        Validity
            Not Before: Jun 15 13:22:48 2020 GMT
            Not After : Jun 15 13:22:48 2021 GMT
        Subject: O = MyOrg, OU=Apps, CN = storeapp

...
c:\certs>dir
...
06/15/2020  09:22 AM             1,884 ca.crt
06/15/2020  09:20 AM             3,365 ca.key
06/15/2020  09:22 AM                42 ca.seq
06/15/2020  09:22 AM             1,756 finapp.crt
06/15/2020  09:22 AM             3,294 finapp.key
06/15/2020  09:22 AM             1,752 hrapp.crt
06/15/2020  09:22 AM             3,294 hrapp.key
06/15/2020  09:22 AM             1,772 iamapp.crt
06/15/2020  09:22 AM             3,294 iamapp.key
06/15/2020  09:20 AM             5,076 make_certs.cmd
06/15/2020  07:10 AM             2,520 make_keyring.cmd
06/15/2020  09:22 AM             1,756 salesapp.crt
06/15/2020  09:22 AM             3,294 salesapp.key
06/15/2020  09:22 AM             1,830 server1.crt
06/15/2020  09:22 AM             3,294 server1.key
06/15/2020  09:22 AM             1,830 server2.crt
06/15/2020  09:22 AM             3,294 server2.key
06/15/2020  09:22 AM             1,756 storeapp.crt
06/15/2020  09:22 AM             3,298 storeapp.key
              19 File(s)         48,401 bytes

Step 4 - create additional certificates

You can execute the make_certs.cmd script multiple times. It will not overwrite existing certificates. Therefore you can add additional certificates to the script and run it again to create them.

Step 5 - customize your make_keyring.cmd script

The make_keyring.cmd script included in the kit is an example. You will want to customize it for your environment. The most common changes to make are:

The file name for the keyfile
The password for the keyfile
The server key and certificate to import

Each Domino server must have its own keyfile with only its private key contents. Therefore, you must update and run the script separately for each Domino server.

Here are an example set of changes you can make to the script. Lines modified are marked at the start of the line with the ! symbol.

  REM CUSTOMIZE: Change the parameters here

  REM The location of the Domino program directory.
  set NOTESBIN=C:\Program Files\HCL\Domino

  REM The location of the Domino data directory.
  set NOTESDATA=C:\Program Files\HCL\Domino\Data

  REM The full path to the Notes.ini for the Domino server
  set NOTES_INI=%NOTESDATA%\notes.ini

  REM The filename of the keyfile to create
! set KYR_FILE=%NOTESDATA%\server2keys.kyr

  REM The passsword to create and access the key file.
! set KYR_PASS=strong-password-123

  REM The file name for the (proton) server certificate in PEM format.
! set SERVER_CERT=server2.crt

  REM The file name for the private key to the (proton) server, in PEM format,
  REM without a password.
! set SERVER_KEY=server2.key

  REM The file name with the certificate that signed the server's certificate,
  REM in PEM format.
  set CA_CERT=ca.crt

Step 6 - create the keyfile

Execute the make_keyring.cmd script to create a new keyfile for the Domino server. If the keyfile already exists the script will not overwrite it.

Note: make_keyring.cmd will pause at each step in the process of running the script.

c:\certs>.\make_keyring.cmd
...

c:\certs>dir "\Program Files\HCL\Domino\Data\server2keys.*"
...
06/15/2020  01:52 PM            35,427 server2keys.kyr
06/15/2020  01:52 PM               129 server2keys.sth
               2 File(s)         35,556 bytes

Next Steps

Using the above scripts, after you have made changes for your environment, you will produce the following files:

ca.crt, ca.crt, ca.seq -- These files represent your certificate authority (CA). Store them, and the password, in a safe location. You will need these same files again when you create additional certificates using this same certificate authority. If you loose the CA files you can recreate them, but then you must also recreate all other certificates signed by the lost CA.
server2keys.kyr and server2keys.sth -- These files represent the keyfile. They must be deployed on the Domino server running Proton, typically in the data directory. You will need to set the .kyr file path into the Keyring file setting. The .kyr contains the server's identity, certificate chain, and additional trusted roots that Proton needs to authenticate clients, and servers (e.g. the IAM introspection service).

Note if the IAM service uses certificates signed by a different CA, then these certificates must also be imported into the keyfile.
*.crt and *.key files -- Additional certificates and private keys, in PEM format, with the attributes you defined in make_certs.*. These are the key differences between certificates and keys when used by clients vs servers.
- Client keys/certificates:
  - Do not need Subject Alternate Names (SAN).
  - Must have a CN attribute that exists in the Domino directory. The entry in the Directory with the matching name, must have a copy of the same certificate (See client certificate authentication).
  - In some cases, the key must be deployed with a password. Specifically for the IAM service. The keys created by the make_certs scripts do not have a password. Use this openssl command to add a password to a private key:
```
openssl rsa -aes256 -in app1.key -out app1.encrypted.key
```
- Server keys/certificates for Proton:
  - Must have valid Subject Altername Names (SAN), which is the way that clients use to connect to the server.
  - Must be installed on the server in the form of a Domino keyfile. In this case the .crt and .key files are intermediate files needed to build the keyfile.

Domino AppDev Pack

1.0.14

Proton Administration

Configure Domino keyring

Configure Proton Test Utility

Configure IAM Service

Configure Act-As-User

Configuration Test

Client certificate authentication

Preparing the Person document for an application

Import client certificate using the Notes Client

Import client certificate using Proton

Creating certificates and keyfiles

Using the scripts on Linux

Step 1 - create a new directory and initialize with the scripts

Step 2 - customize your make_certs.sh script

Step 3 - execute the make_certs.sh script for the first time

Step 4 - create additional certificates

Step 5 - customize your make_keyring.sh script

Step 6 - create the keyfile

Using the scripts on Windows

Prerequisites

Sample Scripts

Step 1 - create a new directory and initialize with the scripts

Step 2 - customize your make_certs.cmd script

Step 3 - execute the make_certs.cmd script for the first time

Step 4 - create additional certificates

Step 5 - customize your make_keyring.cmd script

Step 6 - create the keyfile

Next Steps