Quick Start Guide
The steps in this guide require AppDev Pack 1.0.9 and Domino 12, or later versions.
Introduction
This quide describes how to use Proton setup commands to do the following tasks:
Set up a new Proton server.
Set up a person or functional ID for Proton access.
ProtonMicroCA
The Proton setup commands create SSL/TLS private keys and certificates issued by the ProtonMicroCA. The first Proton setup command you use creates the ProtonMicroCA. The Certificate Store (certstore.nsf) stores the private key and certificate for the ProtonMicroCA.
Note: The Proton setup commands are not intended to provide full-featured certificate authority management functions. They provide the minimum functions needed to quickly and securely configure Proton and its client applications. If you need fine-grained control over your certificate authority or need anything more than very basic workflow you should look at setting up your certificates manually.
ProtonMicroCA and the Certificate Store (certstore.nsf)
The Domino server must have a Certificate Store (certstore.nsf). If you have
not already created the Certificate Store on your Domino 12 server, create the
database using the load certmgr command. For example:
> load certmgr
06/18/2021 08:49:57 AM CertMgr: Configuring domain wide CertMgr server ..
06/18/2021 08:49:57 AM CertMgr: Certificate Manager started
There is no need to continue running the certmgr task after it has created
the Certificate Store (certstore.nsf). It's only purpose is to create the
database. You may shut it down using the tell certmgr q command. For
example:
> tell certmgr q
06/18/2021 08:49:57 AM CertMgr: Shutdown
If you intend to use the same ProtonMicroCA on multiple Domino servers then be sure to replicate the Certificate Store (certstore.nsf) between the servers.
Set up a new Proton server
This section describes how to use the Proton setupserver command which:
Creates adpconfig.nsf on the Domino server, if needed.
Creates the Proton server keyfile
protonserver.kyrwith a private key and certificate signed by the ProtonMicroCA.Creates the Proton server document in adpconfig.nsf with default options for a secure deployment using the new keyfile.
You invoke the setupserver command from the Domino server console using this
format:
> load proton --setupserver {ipaddress-or-hostname}:{portnumber}
where:
{ipaddress-or-hostname}is the address or hostname that clients use to connect to the Proton server add-in task. The server certificate encodes this address or hostname as theSubject Alternate Nameand clients must use this address or hostname to connect to the server.{portnumber}is the port number where Proton will listen for connections from client applications.
Example
The following setupserver command shows how to configure Proton on the
Domino server using an ip address.
> load proton --setupserver 10.134.104.25:3003
These are the typical log messages generated from the setupserver command:
adpconfig.nsfdid not already exist on the server and it was created.- ProtonMicroCA did not already exist and it was created.
- The key file
protonserver.kyris created with a certificate signed by the ProtonMicroCA. - The Proton configuration document is created in
adpconfig.nsf. - Server setup is complete.
06/18/2021 08:51:19 AM PROTON_SETUP: Database 'adpconfig.nsf' does not exist. Creating new from 'adpconfig.ntf'
06/18/2021 08:51:20 AM PROTON_SETUP: Created new 'adpconfig.nsf' database.
06/18/2021 08:51:20 AM PROTON_SETUP: Created Proton uCA 'ProtonMicroCA'
06/18/2021 08:51:21 AM PROTON_SETUP: Created server certificate signed by 'ProtonMicroCA'
06/18/2021 08:51:21 AM PROTON_SETUP: Created Proton keyfile 'C:\Domino\Data\protonserver.kyr'
06/18/2021 08:51:21 AM PROTON_SETUP: Created new configuration document for 'spn3/spn3'
06/18/2021 08:51:21 AM PROTON_SETUP: Completed server setup for 'spn3/spn3' on '10.134.104.25:3003'
At this point you can start the Proton add-in task to listen on the
port specified at the setupserver command.
Note: The listen address reported is 0.0.0.0 which indicates that Proton listens on all addresses available on the Domino server. This is intentional in case there is a NAT between Proton and the clients using it. You can change this through the Proton configuration document.
> load proton
06/18/2021 08:52:41 AM PROTON: Build 0.10.1-37
06/18/2021 08:52:41 AM PROTON: Server initializing
06/18/2021 08:52:43 AM JVM: Java Virtual Machine initialized.
06/18/2021 08:52:43 AM PROTON: Listening on 0.0.0.0:3003, SSL-ENABLED
06/18/2021 08:52:43 AM PROTON: Server initialized
To view all the configuration settings created by the
setupserver command, use the `tell proton showconfig' command.
> tell proton showconfig
Proton: Version : "0.10.1-37"
Proton: Configuration : "'CN=spn3/O=spn3' loaded from note 2294"
Proton: Enabled : True
Proton: Valid : True
Proton: SSL : True
Proton: Keyfile : "C:\Domino\Data\protonserver.kyr"
Proton: Listen Address : "0.0.0.0"
Proton: Listen Port : 3003
Proton: Allow Anonymous : False
Proton: Allow Client Cert : True
Proton: Allow Act-as-User : False
Proton: IAM Client Config : ""
Proton: Wait time for ID : 10 seconds
Proton: Max Note Count : 200 per request
Proton: Session Cache TTL : 300 seconds
Proton: Session Cache Size : 5000 entries
Proton: Allow Write Attachments : True
Proton: Min Attachment Chunk : 4 KB
Proton: Max Attachment Chunk : 32 KB
Proton: Max Write Attachment Size : 0 MB
Proton: Allow Agent Run : True
Proton: JVM Min Heap : ""
Proton: JVM Max Heap : ""
Proton: Enable Rate Limits : True
Proton: Max Applications : 500
Proton: Max Bad Requests : 50
Proton: Max Bad Requests Time : 60 seconds
Proton: Abuse jail time : 120 seconds
Proton: Enable Rich Text Streaming : True
Proton: Min Rich Text Chunk : 4 KB
Proton: Max Rich Text Chunk : 32 KB
Proton: Max Rich Text Size : 1024 MB
Proton: Allow Admin Operations : False
Run kyrtool as follows at the Domino server console to show the certificate
chain created by setupserver. It shows the server certificate (Certificate
#0) along with its certifier (Certificate #1).
This command does not show the server's Subject Alternate Name (SAN), but one does exist.
> load kyrtool show certs -k protonserver.kyr
Using keyring path 'protonserver.kyr'
Certificate #0
Subject: CN=10.134.104.25/O=Proton
Issuer: CN=Proton Certificate Authority/O=Proton
Not Before: 06/17/2021 08:51:21 AM
Not After: 06/19/2022 08:51:21 AM
Public Key Alg: rsaEncryption
Fingerprint: mKGGuoe7NL6XYMysezBppe5nJxQlqwCLya2cmmgt0+s=
Key length: 4096 bits
Signature Alg: sha256WithRSAEncryption
-----BEGIN CERTIFICATE-----
... (certificate details omitted) ...
-----END CERTIFICATE-----
Certificate #1
Subject: CN=Proton Certificate Authority/O=Proton
Issuer: CN=Proton Certificate Authority/O=Proton
Not Before: 06/17/2021 08:51:20 AM
Not After: 06/17/2031 08:51:20 AM
Public Key Alg: rsaEncryption
Fingerprint: HbUQm5pWhBVmcjHtuthgyZeZ/zwd1146VD+diW1K9vI=
Key length: 4096 bits
Signature Alg: sha256WithRSAEncryption
-----BEGIN CERTIFICATE-----
... (certificate details omitted) ...
-----END CERTIFICATE-----
Run kyrtool as follows at the Domino server console to show the trusted
roots in the server keyfile. Proton trusts and authenticates client
certificates issued by the ProtonMicroCA.
> load kyrtool show roots -k protonserver.kyr
Using keyring path 'protonserver.kyr'
Trust Anchors:
Anchor 0 (name)
CN=Proton Certificate Authority/O=Proton
Anchor 0 (cert)
Subject: CN=Proton Certificate Authority/O=Proton
Issuer: CN=Proton Certificate Authority/O=Proton
Not Before: 06/17/2021 08:51:20 AM
Not After: 06/17/2031 08:51:20 AM
Public Key Alg: rsaEncryption
Fingerprint: HbUQm5pWhBVmcjHtuthgyZeZ/zwd1146VD+diW1K9vI=
Key length: 4096 bits
Signature Alg: sha256WithRSAEncryption
Set up a person or functional ID for Proton access
This section describes how to use the Proton setupclient command which:
Creates the client key and certificate for a person or functional ID in the Domino directory. The certificate is signed by the ProtonMicroCA.
Updates the Person document in the Domino directory to add the new client certificate. Proton uses this certificate to authenticate the client.
Sends an encrypted mail message with the private key and certificates needed to create a secure and authenticated connection to Proton running on the Domino server.
You invoke the setupclient command from the Domino server console using this
format:
> load proton --setupclient "{name}" --sendto "{name}"
where:
{name}is the name of the person to configure (User Name, Full Name, Short Name, etc) that results in exactly one match in the Domino directory.The
--sendtooption and its{name}parameter are optional and will redirect the mail message with the client key and certificate to another person in the directory. If you don't use the--sendtooption the mail message is sent to the same person.
The person or functional ID must be a registered user in the Domino directory. Depending on the use of the
--sendtooption, the user that receives the mail message must be configured to receive encrypted mail on the Domino server.
The setupclient commands sends an encrypted mail message to the Domino user
or if it's a functional ID, to another Domino user that controls the
functional ID. The mail message contains the following attachments:
| Attachment | Description |
|---|---|
clientkey.pem | the user's private key |
clientcrt.pem | the user's certificate, signed by the ProtonMicroCA |
rootcrt.pem | the root certificate, or in other words, the ProtonMicroCA certificate |
Applications using the domino-db client libraries and other authorized Proton clients need these files to make SSL/TLS connections to the Proton server.
The application or user with using these PEM files will be able to authenticate to Domino through the Proton add-in task and perform actions on the Domino server as allowed for the user in database ACLs, readers fields, etc.
Note: For a more secure deployment, create special-purpose user IDs on the Domino server that are assigned the minimum access required for Proton use. For example, if an ID requires read-only access to a database through Proton but greater access through Notes, create an ID for Proton use that allows only read access.
Example
The following setupclient command shows how to configure a Domino user for
access to the Proton server.
> load proton --setupclient "john lakeman"
These are the typical log messages generated from the setupclient command:
- client name is found in the Domino directory showing fullname and shortname
- using the ProtonMicroCA to create the client certificate
- adding the client certificate to the Person document in the domino directory
- encrypted mail message is deposited for delivery and the router has delivered the mesage.
06/18/2021 09:14:21 AM PROTON_SETUP: Found: John Lakeman/spn3 (JLakeman)
06/18/2021 09:14:22 AM PROTON_SETUP: Using existing Proton uCA 'ProtonMicroCA'
06/18/2021 09:14:22 AM PROTON_SETUP: Created client certificate signed by 'ProtonMicroCA'
06/18/2021 09:14:22 AM PROTON_SETUP: Added certificate for 'John Lakeman/spn3' in directory
06/18/2021 09:14:22 AM PROTON_SETUP: Completed client setup for 'John Lakeman/spn3'
06/18/2021 09:14:22 AM Router: Message 0048BA23 delivered to John Lakeman/spn3
The following setupclient command shows how to configure a Domino user with
a functional ID that does not have mail access. This example uses the
--sendto option to send the mail message with the key and certificates to a
different Domino user, such as the administrator of the functional ID.
> load proton --setupclient "dapp3" --sendto "cora miller"
06/18/2021 09:53:34 AM PROTON_SETUP: Found: demo app3/spn3 (dapp3)
06/18/2021 09:53:34 AM PROTON_SETUP: Using existing Proton uCA 'ProtonMicroCA'
06/18/2021 09:53:37 AM PROTON_SETUP: Created client certificate signed by 'ProtonMicroCA'
06/18/2021 09:53:37 AM PROTON_SETUP: Found: Cora Miller/spn3 (CMiller)
06/18/2021 09:53:37 AM PROTON_SETUP: Added certificate for 'demo app3/spn3' in directory
06/18/2021 09:53:37 AM PROTON_SETUP: Completed client setup for 'demo app3/spn3'
06/18/2021 09:53:37 AM Router: Message 004C51FB delivered to Cora Miller/spn3