To generate custom TLS certificate files for the NSP

Purpose

Perform this procedure to generate a set of TLS key and certificate files to provide as security artifacts in an NSP deployment.

The locations of the custom TLS files that the procedure generates are the required inputs to the ‘nspdeployerctl secret’ prompts when you create or update the custom TLS secret, as shown below:

  • tls.key=customKey

  • tls.cert=customCert

  • ca.crt=customCaCert

where

customKey is the location of the private server key file extracted in Step 9

customCert—location of one of the following:

  • server.pem file obtained in Step 7

  • server-chained.pem obtained in Step 10, if using intermediate CA

customCaCert—location of CA.pem key file obtained in Step 7

In addition, the CA key file location must be specified as shown below in the tls section of the NSP cluster configuration file:

customCaCert—location of CA.pem key file obtained in Step 7

Using the Java keytool utility

The procedure uses the Java keytool utility, which is included in each Java Development Kit, or JDK, and Java Runtime Environment, or JRE. The keytool utility is described on the Oracle website.

You can run the keytool command from any directory on an NSP deployer host or cluster VM. If the NSP is not yet deployed, ensure that the keytool utility on the station that you use is from the supported Java version specified in the NSP Planning Guide.

Note: The keytool utility that you use must be from the Java version that the NSP uses.

Note: You require root user privileges to run the keytool command.

Steps

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.

Generate TLS certificate
 

Log in as the root user on the station that hosts the keytool utility.


Open a console window.


Generate a keystore file that contains the certificate.

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: A custom certificate is unique to an NSP cluster; in a DR deployment, each cluster requires a unique, cluster-specific SAN entry.

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 internal advertised address of the NSP cluster. The address to include is one of the following in the platformingressApplicationsingressController section of the config.yml file on the local NSP deployer host:

In the internalAddresses subsection, if configured, otherwise, in the clientAddresses subsection:

  • if configured, the advertised value

  • otherwise, the virtualIp value

If mTLS is used between the NSP and NFM-P in such a deployment, you do not need to include the internal NSP address in the SAN field.


Record the alias and password values that you specify.


Export certificate
 

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


Generate and submit CSR
 

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.


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
 

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


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 

As required, perform the required NFM-P TLS configuration described in “NSP component TLS configuration” in the NSP System Administrator Guide.


15 

Close the console window.

End of steps