To generate custom TLS certificates

Purpose

Perform this procedure to generate a set of TLS key and certificate files to provide as security artifacts in an NSP and NFM-P 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 12

customCert—location of one of the following:

  • server.pem file obtained in Step 5

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

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

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 5

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.

To generate custom TLS certificates for NSP

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.

 
1 

Log in as the root user on the station.


2 

Open a console window.


3 

Generate the private key.

# openssl genrsa -out private_server_key 2048 ↵

where private_server_key is the name of the private TLS key to generate.


4 

Generate a certificate signing request, or CSR.

# openssl req -new -key private_server_key -out CSR_file -config ssl.conf ↵

where

private_server_key is the private TLS key generated in Step 3

CSR_file is the name of the CSR file to generate

ssl.conf should have the following:

[ req ]

default_bits = 2048

prompt = no

distinguished_name = dn

req_extensions = req_ext

[ dn ]

CN = common_name

OU = org_unit

O = organization

L = locality

ST = province or state

C = country

[ req_ext ]

basicConstraints = CA:false

keyUsage = digitalSignature, keyEncipherment

extendedKeyUsage = serverAuth, clientAuth

subjectAltName = @alt_names

[ alt_names ]

DNS.1 = DNS_1

DNS.2 = DNS_2

IP.1 = IP_1

IP.2 = IP_2

Note: SAN entries for the certificate are in the alt-names field of ssl.conf.

Note: A custom certificate is unique to an NSP cluster; in a DR deployment, each cluster requires a unique, cluster-specific SAN entry.

Note: In an NSP deployment that includes NFM-P, uses separate client and internal interfaces, and has the Kafka internal mTLS parameter disabled in nsp-config.yml, the NSP TLS certificate SAN field must also include the internal advertised address of the NSP cluster. In the nsp-config.yml file on the local NSP deployer host:

  • The Kafka internal mTLS parameter is in the nsp—deployment—modules—nspos—kafka—internalClientAuth section.

  • The address to include is in the platform—ingressApplications—ingressController section.

If NSP and NFM-P use separate client and internal interfaces and the Kafka internal mTLS parameter is enabled, the NSP TLS certificate SAN field does not require the internal advertised address of NSP cluster.


5 

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

Note: The TLS certificate file type needs to be PEM certificate (base64 format) to integrate with NSP. Ensure that certificate files are converted to PEM format as needed.


6 

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.


Apply the new TLS artifacts
 
7 

Enter the following on the deployer node:

# ./nspdeployerctl secret -s nginx-nb-tls-nsp -n nsp-psa-restricted -f tls.key=customKey -f tls.crt=customCert -f ca.crt=customCaCert update ↵

where

customKey is the full path of the private server key

customCert is the full path of the server public certificate

customCaCert is the full path of the CA public certificate

Messages like the following are displayed as the server secret is updated:

secret/nginx-nb-tls-nsp patched

The following files may contain sensitive information. They are no longer required by NSP and may be removed.

  customKey

  customCert

  customCaCert


8 

If you are using a DR deployment, repeat this procedure on the secondary NSP cluster.


9 

Close the console window.


10 

If your deployment includes NFM-P, perform To generate and apply NFMP TLS certificates using keystore and truststore files.

End of steps

To generate and apply NFMP TLS certificates using keystore and truststore files

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
 
1 

Log in as the root user on the station.


2 

Open a console window.


3 

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'

Note: You can enter a DNS or IP address as the SAN server entry.

Enter one of the following commands:

# 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:false -ext san=IP:IP_address,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

IP_address is the server IP address

DNS_name is the hostname or FQDN; the hostname or FQDN must be resolvable by DNS


Export certificate
 
4 

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 keystore file generated in Step 3

password is the keystore password in Step 3

certificate_file is the name of the certificate file to generate


Generate and submit CSR
 
5 

Generate a certificate signing request, or CSR.

Note: You can enter a DNS or IP address as the SAN server entry

  1. Enter one of the following:

    # path/keytool -certreq -alias alias -keystore keystore_file -file CSR_file -storetype JKS -ext san=IP:IP_address,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

    IP_address is the server IP address used in Step 3

    DNS_name is the hostname or FQDN; the hostname or FQDN must be resolvable by DNS used in Step 3

    The following prompt is displayed:

    Enter keystore password:

  2. Enter the keystore password.

    The utility generates a CSR file.


6 

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

Note: The TLS certificate file type needs to be PEM certificate (base64 format) to integrate with NSP. Ensure that certificate files are converted to PEM format as needed.


7 

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.


Import TLS certificates into NFM-P keystore and truststore files
 
8 

Import the root CA certificate into keystore,

# keytool -import -trustcacerts -alias alias -file ca-chained.pem -keystore keystore_file -storepass password ↵

where

alias is the alias for the root certificate

keystore_file is the keystore file generated in Step 3

password is the keystore password in Step 3


9 

Import the certificate chain into keystore,

# keytool -import -trustcacerts -alias alias -file server-chained.pem -keystore keystore_file -storepass password ↵

where

alias is the keystore alias in Step 3

keystore_file is the keystore file generated in Step 3

password is the keystore password in Step 3


10 

Import the root CA certificate into truststore.

# keytool -import -trustcacerts -alias alias -file ca-chained.pem -keystore truststore_file -storepass password ↵

where

alias is the alias for the root certificate in ca-chained.pem.

truststore_file is the truststore file

password is the truststore password


11 

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 in Step 3

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


12 

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


13 

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


Apply updated keystore and truststore files to NFM-P configuration
 
14 

Enter the following:

# samconfig -m main ↵

The following is displayed:

Start processing command line inputs...

<main>


15 

Configure the keystore and truststore files.

Enter the following:

<main>configure tls ↵

<main configure tls> keystore-file /path/keystore_file ↵

<main configure tls> keystore-pass keystore_password ↵

<main configure tls> truststore-file /path/truststore_file ↵

<main configure tls> truststore-pass truststore_password ↵

<main configure tls> alias alias ↵

<main configure tls> exit ↵

where

path is the location of the keystore_file or truststore_file

keystore_file and keystore_password are from Step 9

truststore_file and truststore_password are from Step 10

alias is from Step 3


16 

Enter the following:

<main> apply ↵

The configuration is applied.


17 

Enter the following:

<main> exit ↵

The samconfig utility closes.


18 

Close the console window.

End of steps