Skip to content

Encryption Keys

There are three areas in Domino REST API where encryption keys are needed:

  • HTTPS certificates for Domino REST API ports
  • JSON Web Token (JWT) signing
  • ID vault signing requests

This page documents the creation of those keys. Check the security page for configuration details.

HTTPs certificates for Domino REST API ports

When your server is facing the internet or you can't distribute custom (root) CAs (certificate authorities) to your users, you should consider using a certificate from an official source such as LetsEncrypt. (This documentation does not describe how to do that.) You can run Domino REST API without encryption; however, in a production environment this is not recommended, unless you run on a container service like Kubernetes or OpenShift, where the container handles encryption.

If you create your own CA, you must:

  • Create the private key and root certificate.
  • Create an intermediate key and certificate.
  • Create certificates for your servers.
  • Convert them if necessary, for example for import in Java KeyStore.
  • Make the public key of the root and intermediate certificates available.
  • Import these certificates in all browsers and runtimes used for testing.

Follow the detailed instructions and the follow up.

Again, it's generally better to use LetsEncrypt.

Encryption key for JWT signing

Domino REST API uses JWT for authentication. When you get started with Domino REST API, you probably log in with a Domino username and password. Domino REST API, out of the box, uses an ephemeral symmetric encryption key to sign requests. Since you can't see the key or share it, this configuration is reasonably secure. When you restart Domino REST API, a new key is used.

To use a key that can be deployed to an external identity provider (IdP) or used to send requests to the Domino ID vault service, you must generate a public/private key pair and configure the security settings. Never share the private key.

Use the OpenSSL tool to generate a key. The key is an RSA key:

ssh-keygen -t rsa -b 4096 -m PEM -f private.key
openssl rsa -in private.key -pubout -outform PEM -out public.pem

If you prefer Elliptic-curve keys (smaller, more modern), use this:

openssl ecparam -genkey -name secp521r1 -noout -out privatekey.pem
openssl ec -in privatekey.pem -pubout -out publickey.pem

The parameter -name secp521r1 defines the ES512 encryption algorithm. Don't change the parameter.

Encryption key to sign ID vault requests

The required key is an ES512 elliptic-curve as described above. Keep the private key safe and configure it in security. The public key must be imported into the ID vault. Check the documentation there.

openssl ecparam -genkey -name secp521r1 -noout -out privatekey_ec.pem
openssl pkcs8 -topk8 -nocrypt -in privatekey_ec.pem -out privatekey.pem
openssl ec -in privatekey.pem -pubout -out publickey.pem

Additional information

Check how to use the Management Console for encryption operations to learn more.

You can also check the JWT Multi-Server guide to learn how to set up Domino REST API on multiple Domino servers to use the same JWT keys.