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:
where
customKey is the location of the private server key file extracted in Step 12
customCert—location of one of the following:
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:
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. 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
|
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. 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 |