HTTPS for production
The best practice for any REST API access is to secure the connection using TLS, which is often colloquially referred to as SSL. This applies to the Domino REST API as well. In general, you have the following options:
Use a reverse proxy
Terminate the TLS connection at a proxy. When the proxy runs on the same machine, this is a common and accepted practice. Steps using nginx are outlined as reference.
Enable HTTPS using the Domino Certificate Manager
If you are using Domino 14 or later and your certificates are stored in the Domino Certificate Manager, you may be able to enable HTTPS automatically. For more information, see Enable HTTPS using the Domino Certificate Manager.
To learn more about Domino Certificate Manager, see Managing TLS certificates with Certificate Manager.
Use a TLS Certificate
The REST API can directly use TLS and is HTTP 1.1 and HTTP/2 compliant. You would obtain a TLS certificate from your IT security team or your favorite supplier, such as Let's Encrypt, and set the configuration parameters in a JSON file.
Use the following entry to configure TLS for JKS or PFX (set TLSType to the correct type):
{
"TLSFile": "path.to.file",
"TLSPassword": "password-in-clear-protect-this",
"TLSType": "pfx"
}
Use the following to configure TLS for PEM:
{
"TLSFile": "path.to.file",
"PEMCert": "path.to.crt.file",
"TLSType": "pem"
}
Note
TLSfilemust point to private key, while thePEMCertmust point to the certificate chain.- If you won't define a password, you must set the value of
TLSPasswordto"".
-
JKS: Java KeyStore. Only used by Java. Refer to the JKS documentation for details.
-
PEM: defined in RFC 1422, and commonly used in HTTP server
-
PFX: defined in RFC 7292, the RSA provided Public-Key Cryptography Standards
Tip
It's your choice which key you want to use. Main considerations are the assessment of your security team and the ease of acquisition of a specific key format in your organization.
Example of private key and a self-signed certificate using openSSL
Bash commands for:
-
Generating a private key
openssl genpkey -algorithm RSA -out server-key.pem -
Generating a certificate signing request (CSR)
openssl req -new -key server-key.pem -out server.csr -
Self-signing the certificate
openssl x509 -req -days 365 -in server.csr -signkey server-key.pem -out server-cert.pem -
Generating a CA certificate
openssl req -new -x509 -days 365 -key server-key.pem -out ca-cert.pem
The TLS configuration for PEM would look like this:
{
"TLSFile": “server-key.pem”,
"PEMCert": “server-cert.pem”,
"TLSType": "pem"
}
Read the details here: configure certificate.