To generate custom TLS certificate files for the NSP

Purpose

A TLS keystore and truststore are security artifacts that are required in order to enable TLS in an NSP system. This procedure describes how to manually generate a set of files that contain custom TLS artifacts for use in an NSP deployment.

Note: After you redeploy an NSP cluster that uses a custom TLS certificate and has deleteOnUndeploy set to false in the nsp-config.yml file, you must reset the OpenSearch security configuration, as described in To reset the OpenSearch security configuration.

The locations of the custom TLS files that the procedure generates are specified in the tls section of the nsp-config.yml file, as shown below:

    tls

      customKey: private_server_key_location

      customCert: public_server_key_location

      customCaCert: public_CA_key_location

When you configure the NSP deployment, you must set the file locations in the tls section using the following values:

customKey—location of server private key file from Step 9

customCert—location of server.pem file from Step 7, or server-chained.pem from Step 10, if using intermediate CA

customCaCert—location of CA.pem file from Step 7

Note: An NSP keystore must be in JKS, or Java Key Store format.

Note: The NSP TLS artifacts are an OpenSSL RSA key and certificate. The NFM-P artifacts are JKS keystore and truststore files.

If you use self-signed TLS certificates, you must do one of the following:

  • Submit separate NSP and NFMP CSRs with the appropriate artifacts

  • Convert the CSR-signed artifacts to the appropriate format.

The Java keytool utility is included in each Java Development Kit, or JDK, and Java Runtime Environment, or JRE.

The keytool utility that you use must be from the Java version that the NSP uses. After an NSP component installation, the keytool utility is defined in the server PATH variable, so can be run from any location on an NSP cluster VM. If the NSP is not yet installed, ensure that the keytool utility on an alternative station that you use is from the supported Java version specified in the NSP Planning Guide.

Note: You require root user privileges.

Note: The Bash shell is the supported command shell for RHEL CLI operations.

Note: A leading # character in a command line represents the root user prompt, and is not to be included in a typed command.

Steps
Generate TLS certificate
 
1 

Log in as the root user on the NSP or NFM-P VM, or alternative station, as required.

2 

Open a console window.

3 

Use the Java keytool utility on the station to generate a keystore file. See the Oracle website for keytool information, if required.

Note: If the NSP includes one or more NSP analytics servers, each analytics server must be represented in the certificate, as shown in this step.

Note: A file path in the keystore_file value, or in the name of any file generated in a subsequent step, must not include /opt/nsp/os. If you do not include a path, the file is generated in the current working directory, which must not be below /opt/nsp/os.

Note: You must enclose a password that contains a special character in single quotation marks; for example:

-keypass 'Mypa$$word' -storepass 'Mypa$$word'

# keytool -genkeypair -alias alias -keyalg RSA -keypass password -storepass password -keystore keystore_file -validity days -dname "CN=server_name, OU=org_unit, O=org_name, L=locality, S=state, C=country" -ext bc=ca:true -ext san=DNS:DNS_name↵

where

alias is a case-insensitive alias that is required for subsequent keytool operations

password is the password for the key and keystore

Note: The keypass and storepass passwords must be identical.

keystore_file is the name of the keystore file to generate

days is the number of days for which the certificate is to be valid

server_name is the common name or hostname of the server

org_unit is a department or division name

org_name is a company name

locality is a city name

state is a state or region name

country is a country code, for example, US

DNS_name is the DNS-resolvable server hostname or FQDN

Note: Multiple server SAN entries are separated using semicolons; for example:

san=DNS:DNS_name_1;DNS:DNS_name_2

Note: In an NSP deployment that includes NFM-P, uses separate client and internal interfaces, and does not use mTLS, the SAN field must also include the NSP internalAdvertisedAddress value from the NSP configuration. The value is not to be confused with the advertisedAddress value in the configuration. If mTLS is used between the NSP and NFM-P in such a deployment, the SAN field does not require the inclusion of the internalAdvertisedAddress value.

4 

Record the alias and password values that you specify.

5 

Enter the following to export the certificate from the keystore to a certificate file:

Note: You must enclose a password that contains a special character in single quotation marks; for example:

-storepass 'Mypa$$word'

# keytool -export -alias alias -keystore keystore_file -storepass password -file certificate_file ↵

where

alias is the alias specified during keystore creation

keystore_file is the source keystore file, for example, /opt/samserver.keystore

password is the keystore password

certificate_file is the name of the certificate file to generate

6 

Generate a certificate signing request, or CSR.

  1. Enter the following:

    # path/keytool -certreq -alias alias -keystore keystore_file -file CSR_file -storetype JKS -ext san=DNS:DNS_name -ext ExtendedKeyUsage=serverAuth,clientAuth ↵

    where

    alias is the keystore alias

    keystore_file is the keystore file generated in Step 3

    CSR_file is the name of the CSR file to generate

    DNS_name is the DNS-resolvable server hostname or FQDN

    Note: Multiple server SAN entries are separated using semicolons; for example,

    san=DNS:DNS_name_1;DNS:DNS_name_2

    The following prompt is displayed:

    Enter keystore password:

  2. Enter the keystore password. The following prompt is displayed:

    Enter key password for alias

  3. Enter the key password. The utility generates a CSR file.

7 

Send the CSR file to a CA for authentication. The CA returns the following certificate files that contain a trusted root certificate in a hierarchical certificate chain.

  • server.pem—public server key

  • CA.pem—public CA key

Generate NSP cluster TLS artifacts
 
8 

Enter the following to convert the keystore to PKCS12 format:

# keytool -importkeystore -noprompt -srckeystore keystore_file -destkeystore file_name.pkcs12 -deststoretype PKCS12 -deststorepass storepass -destkeypass keypass -srcstorepass storepass -srckeypass keypass -alias alias ↵

where

alias is the keystore alias

keystore_file is the keystore file generated in Step 3

file_name is the name of the new keystore file in PKCS12 format

keypass is the keystore password

storepass is the truststore password

9 

Enter the following to extract the private key from the PKCS12 keystore to a file:

# openssl pkcs12 -in file_name.pkcs12 -passin pass:keypass -nodes -nocerts -descert -out private_key.key ↵

where

file_name is the name of the keystore file in PKCS12 format

private_key is the name to assign to the private key file

10 

If you are using an intermediate CA, enter the following to generate the chained server .pem file:

# cat server.pem ca-chained.pem > server-chained.pem ↵

Note: The certificate order is important; the server certificate must be first in the chain of certificates in the file in order for the NSP installer to read the certificates correctly.

11 

If the NSP deployment does not include the NFM-P, go to Step 15.

Generate NFM-P TLS artifacts
 
12 

Enter the following to import the certificate to a truststore file.

Note: If the certificate is signed by a CA, you must import the entire CA chain of certificates to the truststore file; see the CA documentation for information about importing trusted certificates.

Note: You must enclose a password that contains a special character in single quotation marks; for example:

-storepass 'Mypa$$word'

# path/keytool -import -trustcacerts -alias alias -file certificate_file -keystore truststore_file -storepass password ↵

where

alias is the keystore alias

certificate_file is the self-signed or CA certificate file

truststore_file is the truststore file that is to hold the certificate

password is the truststore password

13 

Enter the following to import the certificate to a keystore file

Note: You must import the entire CA chain of certificates to the keystore file; see the CA documentation for information about importing trusted certificates.

Note: You must enclose a password that contains a special character in single quotation marks; for example:

-storepass 'Mypa$$word'

# path/keytool -import -trustcacerts -alias alias -file certificate_file -keystore keystore_file -storepass password ↵

where

alias is the keystore alias

certificate_file is the CA certificate file

keystore_file is the keystore file that is to hold the certificate

password is the keystore password

14 

Perform the required TLS configuration described in NFM-P TLS configuration.

15 

Close the console window.

End of steps