Enabling TLS Encryption

NuoDB Admin supports TLS encryption for all processes in the domain. NuoDB Admin (nuoadmin) is responsible for propagating certificates to database processes. To enable TLS encryption for all processes, it is necessary to configure NuoDB Admin with a set of certificates and also configure NuoDB Command (nuocmd) clients to be able to communicate with NuoDB Admin.

By default, TLS is enabled when NuoDB is installed.

The current setting of TLS support can be checked and modified using the nuoadmin service management script, see Managing TLS Security

If TLS support is enabled, the following steps are necessary to configure TLS encryption:

  1. Provision trusted certificates for all NuoDB Admin Processes (APs).

  2. Provision key pair certificates for all NuoDB APs.

  3. Provision key pair certificates for all NuoDB Command clients.

Once TLS Encryption has been configured, you must provide the required client key and associated Client Authority (CA) certificate when running nuocmd commands. For more information on NuoDB Command and other command line tools, see Command Line Tools.

Once TLS encryption has been configured, you may connect to a NuoDB database using TLS encryption. For more information, see Connect to a database Using TLS and LDAP.

Trust Models

NuoDB recommends using one of the following two models in which certificates can be provisioned to enable TLS encryption.

  • Shared Admin Key

  • Unique Admin Key

Shared Admin Key

This trust model uses the same key pair certificate for all NuoDB Admin and NuoDB Command clients, which is then used as the trusted certificate for all processes. This model has several disadvantages, the most significant of which is the fact that the key is exposed to clients.

To avoid exposing a key to clients, it is possible to provision a separate key pair certificate for NuoDB Command clients, and include that among the set of trusted certificates for the APs. This allows the APs to communicate securely with each other (since they have the same certificate, which they all trust) and to communicate securely with NuoDB Command clients. This model still has the disadvantage of every AP being provisioned with the same key pair certificate, which means if that a certificate has to be replaced (for example, because it has expired), then every AP has to have its trusted certificates and key pair certificate also replaced.

For instructions on enabling TLS using a Shared Admin Key, see Generating Keystores and Truststores: Shared Admin Key.

Unique Admin Key

This model provisions a unique key pair certificate for each AP, each signed by a Certificate Authority (CA) trusted by all entities (APs and client).

For instructions on enabling TLS using a Unique Admin Key, see Generating Keystores and Truststores: Unique Admin Key.

Keystore and Truststore Formats

For all of the subcommands described in Using NuoDB Command to Generate TLS Keys and Certificates, the supported keystore and truststore formats are PKCS12 and JKS. These are industry-standard formats for X509 certificate data, and either of these formats can be used for a NuoDB AP’s keystore, which contains its key pair certificate, and truststore, which contains the set of certificates trusted by the AP.

To specify values for keystore and truststore properties, update nuoadmin.conf. For more information on nuoadmin.conf, see Configuration Files.

NuoDB Command (nuocmd) uses PEM-encoded keys and certificates as described in RFC7468. The PEM file containing the client’s key and certificate is specified using either the --client-key argument or the NUOCMD_CLIENT_KEY environment variable. This is analogous to the keystore for an AP. The PEM file used to verify the certificate presented by the AP (--api-server) is specified using the --verify-server argument or the NUOCMD_VERIFY_SERVER environment variable. This is analogous to the truststore for an AP.

Using NuoDB Command to Generate TLS Keys and Certificates

You may create your own key pair certificates using methods approved by your IT department. Alternatively, you may use NuoDB Command to create and install TLS authentication keys. The NuoDB Command key and certificate creation commands use the keytool utility from the Java SE Runtime Environment (a requirement for running NuoDB). For more information see the Java keytool documentation.

The following table describes NuoDB Command subcommands required for generating key pairs and certificates are described in the following table:

Subcommand Description

create keypair

Generates a key pair and self-signed certificate, which is stored in a keystore.

import certificate

Imports a certificate from a keystore into a truststore.

sign certificate

Generates a signed certificate for an existing key pair using another key pair certificate. Both the subject and issuer keys and certificates are stored in keystores.

show certificate

Outputs the PEM-encoded certificate and (optionally) outputs private key data for a key pair certificate.

For more information on NuoDB Command and other command line tools, see Command Line Tools.

NuoDB recommends that you review permissions for key pair certificates after you create them.
The default expiry date for a key pair is one year. For information on rotating key pair certificates before their expiry, see Rotating Key Pair Certificates.

Using NuoDB Command create keypair Options

The following options are available when using the create keypair command:

Option Description

--keystore

Specifies the keystore to store the generated key-pair into, which will be created if it does not exist.

--store-type

Specifies the type of the keystore; derived from the --keystore value if not specified. (JKS or PKCS12)

--alias

Specifies the alias to store the key pair as; derived from the --keystore value if not specified.

--store-password

Specifies the password for the keystore.

--key-password

Specifies the password for the key-pair; defaults to --store-password value if not specified.

--dname

Specifies the distinguished name of the certificate.

--sub-altnames

Specifies the list of subjectAltNames for the certificate; must be prefixed by type, for example dns:hostname.

--resolve-san

Specifies whether to resolve subjectAltName using DNS, for example dns:hostname.

--algorithm

Specifies the key algorithm. RSA, DSA, or EC. The default is RSA.

--validity

Specifies the validity of the certificate in days. The default is 365.

--start-date

Specifies the start date of the certificate.

--ca

Specifies whether the generated certificate should be used as a certificate authority.

The --ca option is specified so that NuoDB APs can act as a Certificate Authority. This allows NuoDB APs to generate and sign certificates for database processes, which is useful in environments where the database processes are not on the same physical hosts as the APs (for example OpenShift). The --ca option is available for both the Shared Admin Key and Unique Admin key trust models.

Using NuoDB Command import certificate Options

The following options are available when using the create keypair command:

Option Description

--keystore

Specifies the keystore to store the generated key-pair into, which will be created if it does not exist.

--alias

Specifies the alias to store the key pair as; derived from the --keystore value if not specified.

--truststore

Specifies the the keystore containing trusted certificates.

--truststore-type

Specifies the type of the truststore; is derived from --truststore value if not specified. (JKS or PKCS12)

--truststore-password

Specifies the password for the truststore.

--nuokey-cmd

Specifies the the path to the nuokeymgr executable (default: /opt/nuodb-3.4.2/etc/nuokeymgr).

Using NuoDB Command sign certificate Options

The following options are available when using the sign certificate command:

Option Description

--keystore

Specifies the keystore to store the generated key-pair into, which will be created if it does not exist.

--store-type

Specifies the type of the keystore; derived from the --keystore value if not specified. (JKS or PKCS12)

--alias

Specifies the alias of the certificate; is derived from --keystore value if not specified.

--ca-keystore

Specifies the keystore containing the root CA certificate.

--ca-store-type

Specifies the type of the CA keystore; is derived from --ca-keystore value if not specified. (JKS or PKCS12)

--ca-alias

Specifies the alias of the CA certificate; is derived from --ca-keystore value if not specified

--ca-store-password

Specifies the password for the CA keystore.

--update

Updates the keystore with the signed certificate; if not specified, the certificate chain is written to standard output.

Using NuoDB Command show certificate Options

The following options are available when using the show certificate command:

Option Description

--keystore

Specifies the keystore to store the generated key-pair into, which will be created if it does not exist.

--cert-only

Specifies whether to export only the certificate.