Importing and replacing certificates
Overview
To protect sensitive information against eavesdropping, all the communications between client applications (e.g. web browsers) and Nexthink components, as well as most of the communications between pairs of Nexthink components themselves, are encrypted. The majority of these communications are protected by combining the Transport Layer Security (TLS) protocol with a Public Key Infrastructure (PKI) scheme based on the X.509 standard, which uses digital certificates. A few others, most notably the transmission of device data from the Collector to the Engine, use different protection mechanisms.
This article focuses on the communications that are protected by TLS and a PKI scheme. More specifically, the article details how to replace the default digital certificates in the product by your own set of certificates when needed.
Understanding how TLS and PKI works
Although the reader is assumed to be familiar with the technologies behind TLS and PKI, let us briefly review them here for applying them later to the configuration of Nexthink. This review of how TLS and PKI work does not pretend to be exhaustive. It covers only the basic concepts and the most common cases that are considered relevant to the configuration of the Nexthink product. For an authoritative document on TLS, refer to the RFC 5246. For an authoritative document on PKI, refer to the ITU-T standard X.509. Find as well other sources of information about PKI and TLS on well-respected Internet sites, such as the Certificate Authorities Council or the support pages of the main web hosting and security companies.
A PKI is built around digital certificates. Certificates are just computer files that, in a typical client-server model, help clients ensure the authenticity of the server and protect the privacy of the communication. To that end, certificates rely on a pair of cryptographic keys that are mathematically linked: a private key, which identifies the server and must never be disclosed, and a public key, which is included unencrypted in the certificate itself and, therefore, is disclosed to everyone that gets the certificate. Content that is encrypted using the private key can only be decrypted using the public key and vice versa.
According to the TLS protocol, a client that wishes to connect to a server receives the certificate from the server. Once the identity of the server has been established by means of its certificate (see below), the client and the server negotiate the parameters of the secure connection. Thanks to the mathematical properties of their public and private keys, client and server are able to privately agree on the encryption algorithms to be used during the session and exchange randomly generated new keys for these algorithms. Some of the encryption algorithms that TLS negotiates may get old and become less secure with time, as the computation power of modern computers increases or vulnerabilities are found. To define the lists of allowed encryption algorithms for each server component in Nexthink, see the article on the Security Settings in the Appliance.
To understand how a client authenticates a server through its certificate, let us discuss first how server certificates are issued. An entity that issues certificates is called a Certificate Authority (CA). A CA owns a public and a private key with the properties described above. When a CA issues a new certificate to a particular subject, the CA signs the certificate with its own private key (signing is encrypting a hash of the certificate text), thus generating a digital signature that is attached to the certificate. A digital certificate holds thus the following important information:
Issuer: the name of the entity that issues the certificate (the CA, in our case).
Subject: the name of the entity to which the certificate is granted (when applied to the Nexthink product, this is usually the DNS name of a server component).
It is possible to issue a certificate for multiple subjects (DNS names) at the same time.
Public key: the public key of the subject entity.
Digital signature: the binary result of signing the certificate with the private key of the issuer.
To protect a server component in Nexthink, request a CA to generate a certificate that uses the DNS name of the server component as subject and binds it to the public key of the server with a digital signature. This is the certificate that you will use to replace the default server certificates in Nexthink. To that end, generate a Certificate Signing Request (CSR) with your server component information and send it to a CA. You need this step even if you are your own CA. Usually, CAs provide you with tools to generate CSRs for them. Alternatively, use OpenSSL to generate your CSRs. Remember to specify the subjects (DNS names) for the certificate in the field Subject Alternative Name (SAN) of your CSR, instead of the now deprecated Common Name (CN) field. To generate your own CSR with OpenSSL, follow the instructions in the CAcert site, for example.
A certificate that a CA issues to identify itself is called a root certificate. A root certificate thus has the same Issuer and Subject. Because the Issuer and the Subject are the same, the root certificate is said to be self-signed: it holds the public key of the CA and it was signed with the private key of the CA. If a client trusts a CA, the client may use the root certificate of the CA to authenticate any server certificate issued by the same CA. Indeed, by using the public key of the CA in the root certificate, the client can decrypt the contents of the digital signature in the server certificate (remember that the CA signed the certificate by using its private key); thus verifying the authenticity of the server. Since clients rely on root certificates for validation, root certificates must be distributed to clients in a trustworthy way (not through a simple connection). For instance, the root certificates of publicly-trusted CAs are typically distributed embedded in the operating system, the web browser, or other trust stores of specific applications. Users must therefore assume that the root certificates included in their client software are correct; that is, users must either trust the publisher of the client software or not use the software.
Usually, CAs add several layers of security and they do not sign server certificates using the private key of the root certificate, but the private key of an intermediate certificate. This intermediate certificate is itself signed by either the private key of the root certificate or by the private key of another intermediate certificate. Intermediate certificates thus form a chain of trust from your server certificate up to the root certificate of the CA, which is the trust anchor. When using server certificates that were generated in this way, install in your server component not only the server certificate, but the whole bundle of intermediate certificates that let a client follow the full chain of validation until it reaches the root certificate. Alternatively, install in the client the intermediate certificates besides the root certificate of the CA.
When talking about CAs, people usually refer to publicly-trusted institutions, but you can generate your own certificates and become your own CA as well. The certificates generated by an individual or organization without requesting them to a publicly-trusted CA are said to be self-issued. Using certificates issued by publicly-trusted CAs have some advantages over the use of self-issued certificates though. See the comparison table below:
Type of certificate | Issued by a trusted CA | Self-issued |
Pros |
|
|
Cons |
|
|
For the purposes of this article, you do not need to know the full TLS protocol nor the mathematics of public key cryptography. There are just a couple of things that you must absolutely keep in mind when dealing with digital certificates in Nexthink:
Server certificates enable clients to authenticate and communicate securely with a server.
The issuer of your server certificates can be either a publicly recognized CA or your own organization (self-issued certificates).
The client must trust the issuer of the server certificate to accept the connection.
For example, in the case of a web browser acting as a client, if the browser is not able to authenticate the server that hosts a web site because it does not know the issuer of the server certificate (i.e. it does not have the root certificate of the issuing CA in its trusted store), you usually get a warning message informing you that the connection to that web site is not secure. Most web browsers let advanced users add an exception and proceed with the connection, clearly stating nonetheless that the identity of the server cannot be confirmed and that it might be impersonated.
Secure connections in Nexthink requiring certificates
In Nexthink, the components in the Appliance (the Web Console, the Portal, and the Engine) usually play the server role in the client-server model of communication. Each one of these components uses a server certificate to provide client applications with the means to establish a secure connection. Nevertheless, the Engine and the Portal may also play the client role in some cases. For their part, the Finder and the Collector always behave as clients.
For each component, find below the table of all the connections that require certificates:
Client | Server |
Web Browser |
|
Finder |
|
Collector (TCP connection) |
|
Portal |
|
Engine |
|
Viewing the certificates in the Appliance from the Web Console
To quickly view the digital certificates of the server components that are in place in a particular Nexthink Appliance:
Log in to the Web Console of the intended Appliance from a web browser:
https://:99Select the APPLIANCE tab at the top of the Web Console.
Click Certificates in the left-hand side menu.
The applicable certificates are arranged in a table:
Replacing the certificates of the server components
In this section, learn how to replace the certificates in the server components of Nexthink that the different client applications may use to authenticate them. Let us suppose that you have obtained the following set of certificates from a publicly-trusted CA or that you have generated them yourself:
Root certificate of the CA:
root.crt
Optional bundle of intermediate certificates (provided by the CA when the server certificates are not directly signed by the private key associated to the root certificate, which is customary):
intermediate.crt
Server certificate for the primary Appliance (Portal):
master.crt
Server certificates for the secondary Appliances (Engines):
slave.crt
For client applications to effectively authenticate your Appliances, a name in the Subject Alternative Name of the primary and secondary certificates must match the external DNS names of the Appliances hosting the Portal and the Engines, respectively. If you also need certificate validation internally between Appliances (namely, for the connections from the Portal to the Engines), configure your corporate DNS so that the internal DNS names of the Appliances match their external names. In that way, you will not need to issue server certificates with multiple subjects.
In addition, you must own the private keys associated to the server certificates of the primary and secondary Appliances:
Private key associated to the server certificate of the primary Appliance:
master.key
Private key associated to the server certificate of the secondary Appliance:
slave.key
Although we give one generic name to the files that hold the server certificates of the secondary Appliances (slave.crt) and their associated keys (slave.key), note that you will usually need a different server certificate and private key for each one of your secondary Appliances, because each secondary Appliance is identified as a different subject in the certificate (they have a different DNS name). The exception to this rule is if you use multiple-subject certificates.
The certificates and cryptographic keys described here are all assumed to be in PEM format, which is basically a Base64 (text) encoding of the binary DER format. Note that the extension of the certificate file (.crt, .cer, .pem) is not relevant, but the actual content of the file is determinant. To follow the instructions below, convert the certificate files to PEM format if this is not already the case. For instance, to convert a root certificate in DER format to PEM with the help of the openssl command line tool, type in:
openssl x509 -inform DER -outform PEM -in root.der -out root.crt
If you obtained your PEM certificate files from a Windows system, Nexthink strongly recommends you to convert them to Unix text format to avoid problems when chaining certificates. Once you have copied the certificate files generated in Windows to the appliance, run the following command on each one of them (substitute win-cert.crt and unix-cert.crt for the appropriate names):
tr -d '\r' < win-cert.crt > unix-cert.crt
Replacing the server certificates in the primary Appliance
The supplied certificate replaces, at the same time, the default server certificates of:
The Web Console in the primary Appliance
The Portal (which includes the Collector communication with the Portal for rule-based assignment, when using TCP port 443).
If Collectors communicate with the Portal through a custom TCP port, the default certificate that protects this channel is generated during the federation of the Appliances and it is secure enough. Optionally replace this certificate separately.
To replace the server certificates of the Web Console and of the Portal in the primary Appliance:
Log in to the Web Console of the primary Appliance.
In the APPLIANCE tab, select Certificates from the left-hand side menu.
Under the section Certificates, find the list of installed certificates for the Web Console and the Portal (including Collector communication, when using TCP port 443).
Click the button REPLACE CERTIFICATES below the list of certificates. A dialog shows up:
Placed to the right of the word Certificate, click the button CHOOSE FILE.
Select the file master.crt from the dialog that shows up.
Placed to the right of the words Private key, click the button CHOOSE FILE.
Select the file master.key from the dialog that shows up.
Optional: Tick Use an intermediate or chain certificate if you have a bundle of intermediate certificates.
Click the button CHOOSE FILE that shows up when you tick the previous option.
Select the file intermediate.crt from the dialog that shows up.
Click the button Replace certificates for Portal, Collector communication (port 443) and Web Console.
If you installed Nexthink in a single Appliance, the dialog to replace the certificates in the primary Appliance also include the secondary (Engine) Appliance:
Optionally replace the certificate for Collector communication, when using a custom TCP port (not the default TCP 443):
Log in to the Web Console of the primary Appliance.
In the APPLIANCE tab, select Certificates from the left-hand side menu.
Under the section Certificates used for the Collector custom TCP port, find the installed certificate for the communication of the Collector when using a custom TCP port.
Click the button REPLACE CERTIFICATE below the certificate. A dialog shows up.
Placed to the right of the word Certificate, click the button CHOOSE FILE.
Select the file master.crt from the dialog that shows up.
Placed to the right of the words Private key, click the button CHOOSE FILE.
Select the file master.key from the dialog that shows up.
Optional: Tick Use an intermediate or chain certificate if you have a bundle of intermediate certificates.
Click the button CHOOSE FILE that shows up when you tick the previous option.
Select the file intermediate.crt from the dialog that shows up.
Click the button Replace the certificate for the Collector communication on custom TCP port.
Replacing the server certificates in the secondary Appliance
The supplied certificate replaces, at the same time, the default server certificates of:
The Web Console in the secondary Appliance
The Engine
The connection with the Finder and the Portal, as well as the Web API (NXQL).
The Collector communication when using the default TCP port 443.
If Collectors communicate with the Engine through a custom TCP port, the default certificate that protects this channel is generated during the federation of the Appliances and it is secure enough. To replace it, follow the same procedure as shown above for the primary Appliance, but from the Web Console of each secondary Appliance.
If you intend to replace the certificate that secures the TCP communication of the Collectors with the Engine:
Replace the default certificates after federating the secondary Appliance.
Leave empty the root certificate field when installing the Collector (or generating the Collector installer). Distribute instead the root certificate (root.crt) to the Trusted Root Certification Authorities certificate store of the Windows devices where the Collector is being installed. This step may not be necessary if the root certificate is from a publicly trusted CA and, therefore, already included in the Windows store.
To replace the server certificates of the Web Console and of the Engine in the secondary Appliance:
Log in to the Web Console of the secondary Appliance.
In the APPLIANCE tab, select Certificates from the left-hand side menu.
Under the section Certificates, find the list of installed certificates for the Web Console and the Engine (including Finder and Web API) and the Collector communication when using the default TCP port 443.
Click the button REPLACE CERTIFICATES below the list of certificates. A dialog shows up:
Under the section Replace certificates:
Placed to the right of the word Certificate, click the button CHOOSE FILE.
Select the file slave.crt from the dialog that shows up.
Placed to the right of the words Private key, click the button CHOOSE FILE.
Select the file slave.key from the dialog that shows up.
Optional: Tick Use an intermediate or chain certificate if you have a bundle of intermediate certificates.
Click the button CHOOSE FILE that shows up when you tick the previous option.
Select the file intermediate.crt from the dialog that shows up.
Click the button Replace certificates for Engine, Collector communication (port 443) and Web Console .
If you replaced the certificate that secures the TCP connection between the Collectors and Engine (which is mandatory for Collector on TCP port 443), leave empty the root certificate field when installing the Collector. The Collector uses then the Trusted Root Certification Authorities certificate store to validate its TCP connection with the Engine. Note that you replace only the certificates in the secondary Appliance and not the Customer Key. The Engine still uses the same Customer Key previously transferred from the primary Appliance during the federation process to identify the Collector:
Restoring the default certificates
If the replacement of the default certificates fails or presents any issue (for instance, if the uploaded certificates are not trusted by the devices in which the Collector is installed), it is possible to sort back to the default (or previous) certificates, which are automatically backed up in the Appliances.
To list the backed up certificates of a primary or secondary Appliance:
Log in to the CLI of the Appliance.
List the backed up certificates with the following command:
ll /var/nexthink/console/certificates/backup/Choose the set of certificates from the list that you want to restore. The saved certificates are sorted by date and component name.
To restore the server certificate of the Web Console in a primary or a secondary Appliance:
Optional: If you used a chain of intermediate certificates, copy it to the configuration folder of the Web Console:
sudo cp -p /var/nexthink/console/certificates/backup/xxxxxxxx-console-intermediate.crt /var/nexthink/console/etc/intermediate.crtEnsure that the file /var/nexthink/console/etc/lighttpd-console.conf contains the line ssl.ca-file="/var/nexthink/console/etc/intermediate.crt".
Restore the server certificate of the Web Console:
sudo cp -p /var/nexthink/console/certificates/backup/xxxxxxxx-console-certificate.pem /var/nexthink/console/etc/certificate.pemRestart the Web Console:
sudo systemctl restart nxconsole
To restore the certificates related to the Portal in a primary Appliance:
Restore the server certificate of the reverse proxy:
sudo cp -p /var/nexthink/console/certificates/backup/xxxxxxxx-portal-nginx.crt /var/nexthink/nxnginx/ssl/nginx.crtRestore the private key of the reverse proxy:
sudo cp -p /var/nexthink/console/certificates/backup/xxxxxxxx-portal-nginx.key /var/nexthink/nxnginx/ssl/nginx.keyRestart the reverse proxy:
$ sudo systemctl restart nginx
To restore the certificates related to the Engine in a secondary Appliance:
Optional: If you used a chain of intermediate certificates, copy it to the configuration folder of the Engine:
sudo cp -p /var/nexthink/console/certificates/backup/xxxxxxxx-engine-intermediate.crt /var/nexthink/engine/common/etc/intermediate.crtEnsure that the file /var/nexthink/engine/01/etc/nxengine.xml contains the following line inside the ssl tag:
/var/nexthink/engine/common/etc/intermediate.crt
Restore the server certificate of the Engine:
sudo cp -p /var/nexthink/console/certificates/backup/xxxxxxxx-engine-certificate.pem /var/nexthink/engine/common/etc/certificate.pemRestore the private key of the Engine:
sudo cp -p /var/nexthink/console/certificates/backup/xxxxxxxx-engine-key.pem /var/nexthink/engine/common/etc/key.pemRestart the Engine:
sudo systemctl restart nxengine@1
Optional: Restore the default certificate for the custom TCP connection with the Collectors in both the primary and secondary Appliances.
Log in to the Web Console.
In the APPLIANCE tab, select Certificates from the left-hand side menu.
Under the section Certificates used for the Collector custom TCP port, click the button RESET TO DEFAULT CERTIFICATE at the bottom:
Importing CA certificates into client components
When behaving as client applications, Nexthink components need access to the root certificate of the CA that signed the server certificates to be able to authenticate the server components. Learn here how to import the root certificate and, in some cases, the bundle of intermediate certificates. Therefore, we assume that you have access to the following files:
Root certificate of the CA:
root.crt
Optional bundle of intermediate certificates (provided by the CA when the server certificates are not directly signed by the private key associated to the root certificate, which is customary):
intermediate.crt
Importing CA certificates into Windows for the Collector and the Finder
To validate servers, the Finder looks for root certificates in the Windows Trusted Root Certification Authorities store. For its part, the Collector resorts to the same certificate store when the Root CA certificate field is left empty during its installation; that is, when you do not use the default ad hoc PKI of federation. The store includes by default the root certificates of all the CAs trusted by Microsoft. If you got your server certificates from a publicly-trusted CA, its root certificate is most probably already in the list. If you acted as your own CA to generate your server certificates (that is, if you self-issued the server certificates), add the root certificate to the store.
To add the root certificate to the Trusted Root Certification Authorities store (Windows 10):
Log in to the Windows 10 device as a user with administrator rights.
Download the certificate file root.crt to the device.
Type WinKey+R to open the Run dialog.
Type in certlm.msc and press OK.
Click Yes in the dialog that shows up to allow the program make changes to your computer.
Right-click Trusted Root Certification Authorities and select All Tasks > Import....
The Certificate Import Wizard starts. Click Next.
Click Browse and select the root.crt file.
Click Next.
In the dialog Place all certificates in the following store, click Next to accept the proposed certificate store (Trusted Root Certification Authorities).
Verify the certificate to be imported and click Finish.
After importing the root certificate, the Finder is able to connect to the Portal without prompting any certificate error and Collectors installed with an unspecified root certificate can use the TCP channel to communicate with the Engine. If the server certificate in the Engine was signed using the key of an intermediate certificate, the connection of the Finder with the Engine will however issue the message
The security certificate of Nexthink Engine could not be validated
This situation happens because the Engine does not currently manage intermediate certificates for its connections with the Finder, the Portal, and the Web API. To solve this, either repeat the previous procedure and import the file intermediate.crt into the Intermediate Certification Authorities store or ignore the message and validation altogether by clicking Continue anyway in the dialog.
Importing CA certificates into macOS for the Collector
Similarly to the Windows Collector, if you replaced the default PKI certificates generated during federation and you left empty the Root CA field when installing the Collector, the Mac Collector will look for a valid root certificate in the Keychains store.
If your server certificates were signed by a publicly-trusted CA, the root certificate is most probably already present in the Keychains. Otherwise, add the root certificate to the list of trusted certificates as follows:
Log in to the macOS device as a user with administrator rights.
Download the certificate file root.crt to the device.
Run the app Finder > Applications > Utilities > Keychain Access.
Select System on the left-hand side panel, under Keychains.
Drag the file root.crt and drop it on to the list of keychain items on the right-hand side of the window. A dialog shows up asking for your password to modify the keychain.
Type in your password.
Click Modify keychain. The root certificate appears as a new item with a red cross (X) on the left, meaning that it is still untrusted.
Double-click the new item with the red X that represents the imported root certificate. A dialog to modify the certificate settings shows up.
Click Trust to expand the section.
In the first entry of the list When using this certificate, select Always trust. All other entries change automatically to the same setting.
Close the dialog. Again the system asks for your password to validate the modification.
Type in your password.
Click Update Settings. The red X disappears from the list item.
Exit Keychain Access.
This process can be automated via MDM.
Importing CA certificates for the Portal
When behaving as a client component, the Portal uses the default keystore of the JDK installed in the Appliance to validate the server certificates that it receives:
/usr/java/default/jre/lib/security/cacerts
If your server components use certificates signed by a generally trusted Certification Authority (CA), you do not need to import the certificates into the Portal, because they will already reside in the keystore. On the other hand, if you are securing the connection of the Portal to your server components with self-issued certificates, import the CA certificates into the Portal with the help of a utility written for this purpose.
For instance, to import the CA certificates that were used to generate the server certificate of the Engine into the Portal:
Log in to the CLI of the primary Appliance.
Copy the appropriate certificates and keys to the home directory of the Nexthink account in the primary Appliance by using your favorite SCP tool.
Copy the root certificate
root.crt.If necessary, copy the bundle of intermediate certificates intermediate.crt. Installing intermediate certificates is usually not mandatory, but you may need to install it if the server component is not able to provide them (the Engine can do it since V6.10).
Stop the Portal:
sudo systemctl stop nxportalImport the root certificate into the keystore:
sudo sh /var/nexthink/portal/security/import_certificate.sh \-alias root_engine -file root.crt \-storepass changeitIf necessary, import the bundle of intermediate certificates into the keystore:
sudo sh /var/nexthink/portal/security/import_certificate.sh \-alias inter -file intermediate.crt \-storepass changeitRestart the Portal
sudo systemctl start nxportal
The Engine presents the same server certificate to the Portal as to other client applications. Since the subject of this server certificate must be set to the external DNS name of the Engine, but the Portal connects to the Engine through it internal name, you either need to have the same internal and external DNS name for the Engine or a multiple-subject certificate.
The -alias option lets you identify the certificates that you import. For different certificates, you must choose an alias that is unique within the same keystore (root_engine and inter_engine in our example). Trying to import another certificate with the same alias results in an error. To reuse an alias, delete the previous certificate from the keystore:
Log in to the CLI of the primary Appliance.
Delete the certificate identified by the alias:
sudo /usr/java/default/jre/bin/keytool \-delete -alias root_engine \-storepass changeit \-keystore /usr/java/default/jre/lib/security/cacerts
Note that the default password for the JDK keystore is changeit (argument to the option -storepass). To actually change the password of the keystore:
Log in to the CLI of the primary Appliance.
Ask for password modification:
sudo /usr/java/default/jre/bin/keytool -storepasswd \-keystore /usr/java/default/jre/lib/security/cacertsYou are prompted to type in the current password for the keystore and to type in twice the new password.
The Portal may be instructed to ignore certificate problems when communicating with server components. By default, the Portal ignores certificate errors when connecting to the Engine, but not when connecting to the mail or the LDAP servers.
For the Engine and the LDAP server components, there is an entry in the configuration file of the Portal (/var/nexthink/portal/conf/portal.conf) that controls certificate validation. To enforce validation, set the value of each entry to false. Find below the entries which correspond to the Engine and the LDAP server, with their default values:
Importing CA certificates for the Engine
When behaving as a client component, the Engine uses the CA certificates listed in the following file to validate the server certificates that it receives:
/var/nexthink/engine/common/etc/ca-bundle.crt
To add a new CA root certificate to this file, just append the certificate file to it:
Log in to the CLI of the secondary Appliance.
Copy the root certificate root.crt to the home directory of the Nexthink account in the secondary Appliance by using your favorite SCP tool.
Append the root certificate to the bundle of certificates from publicly-trusted CAs:
cat root.crt | sudo tee -a \ /var/nexthink/engine/common/etc/ca-bundle.crt > /dev/null
The operations described in this article should only be performed by a Nexthink Engineer or a Nexthink Certified Partner.
If you need help or assistance, please contact your Nexthink Certified Partner.
RELATED TASKS
Last updated
