Importing and replacing Certificates

Contents

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 viceversa.

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
  • The CA manages the security of the private key of the root certificate
  • Client software trusts your server certificates by default (root certificates are already in their trusted store)
  • You can issue certificates freely
Cons
  • You pay for each issued certificate
  • You must manage the security of the private key of your root certificate
  • Client software does not trust your server certificates by default (you must distribute your root certificates)

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
  • Web Console
  • Portal
  • Engine (Web API / NXQL Editor)
Finder
  • Portal
  • Engine
  • Library (nexthink.com)
Collector (TCP connection)
  • Engine
Portal
  • Engine
  • Active Directory
  • SMTP
Engine
  • Application Library (nexthink.com)
  • Automatic Updates (nexthink.com)
  • Mobile Bridge

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:

  1. Log in to the Web Console of the intended Appliance from a web browser:
    https://<Appliance_address>:99
  2. Select the Appliance tab at the top of the Web Console.
  3. Click Certificates in the left-hand side menu.

The applicable certificates are arranged in a table:

WebConsoleCertificates.png

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 master Appliance (Portal):
    master.crt
  • Server certificates for the slave Appliances (Engines):
    slave.crt

For client applications to effectively authenticate your Appliances, a name in the Subject Alternative Name of the master and slave 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 master and slave Appliances:

  • Private key associated to the server certificate of the master Appliance:
    master.key
  • Private key associated to the server certificate of the slave Appliance:
    slave.key

Although we give one generic name to the files that hold the server certificates of the slave 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 slave Appliances, because each slave 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 master Appliance

The supplied certificate replaces, at the same time, the default server certificates of:

  • The Web Console in the master Appliance
  • The Portal

To replace the server certificates of the Web Console and of the Portal in the master Appliance:

  1. Log in to the Web Console of the master Appliance.
  2. In the Appliance tab, select Certificates from the left-hand side menu.
  3. Under the section Replace certificates:
    1. Placed to the right of the word Certificate, click the button CHOOSE FILE.
    2. Select the file master.crt from the dialog that shows up.
    3. Placed to the right of the words Private key, click the button CHOOSE FILE.
    4. 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.
      1. Click the button CHOOSE FILE that shows up when you tick the previous option.
      2. Select the file intermediate.crt from the dialog that shows up.

ReplaceCertificatesMaster.png

Replacing the server certificates in the slave Appliance

The supplied certificate replaces, at the same time, the default server certificates of:

  • The Web Console in the slave Appliance
  • The Engine
    • The connection with the Finder and the Portal, as well as the Web API (NXQL).
    • Optional: The TCP communication of the Collectors with the Engine.
      • The replacement is optional because the default certificate generated during the federation process is secure enough.
      • Requires to additionally select Use custom certificate under Collector security in the Web Console

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 slave Appliance.
    ReplaceSlaveCertificate.png
  • 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.
    CollectorCADeployment.png

To replace the server certificates of the Web Console and of the Engine in the slave Appliance:

  1. Log in to the Web Console of the slave Appliance.
  2. In the Appliance tab, select Certificates from the left-hand side menu.
  3. Under the section Replace certificates:
    1. Placed to the right of the word Certificate, click the button CHOOSE FILE.
    2. Select the file slave.crt from the dialog that shows up.
    3. Placed to the right of the words Private key, click the button CHOOSE FILE.
    4. 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.
      1. Click the button CHOOSE FILE that shows up when you tick the previous option.
      2. Select the file intermediate.crt from the dialog that shows up.
      ReplaceCertificatesSlave.png
  4. Optional: Enable the replacement of the certificate that secures the TCP connection with the Collectors:
    1. In the Appliance tab, select Collector security from the left-hand side menu.
    2. Tick the option Use custom certificate. This option is only available if you have previously uploaded a custom certificate to the slave Appliance.
    3. Click Save.

If you replaced the certificate that secures the TCP connection between the Collectors and the Engine, 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 slave Appliance and not the Customer Key. The Engine still uses the same Customer Key previously transferred from the master Appliance during the federation process to identify the Collector:

CollectorCAValidation.png

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 master or slave Appliance:

  1. Log in to the CLI of the Appliance.
  2. List the backed up certificates with the following command:
    ll /var/nexthink/console/certificates/backup/
  3. 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 master or a slave Appliance:

  1. 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.crt
    1. Ensure that the file /var/nexthink/console/etc/lighttpd-console.conf contains the line ssl.ca-file="/var/nexthink/console/etc/intermediate.crt".
  2. 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.pem
  3. Restart the Web Console:
    sudo systemctl restart nxconsole

To restore the certificates related to the Portal in a master Appliance:

  1. 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.crt
  2. Restore the private key of the reverse proxy:
    sudo cp -p /var/nexthink/console/certificates/backup/xxxxxxxx-portal-nginx.key /var/nexthink/nxnginx/ssl/nginx.key
  3. Restart the reverse proxy:
    $ sudo systemctl restart nginx

To restore the certificates related to the Engine in a slave Appliance:

  1. 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.crt
    1. Ensure that the file /var/nexthink/engine/01/etc/nxengine.xml contains the following line inside the ssl tag: <certificate_chain_file>/var/nexthink/engine/common/etc/intermediate.crt</certificate_chain_file>
  2. 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.pem
  3. Restore the private key of the Engine:
    sudo cp -p /var/nexthink/console/certificates/backup/xxxxxxxx-engine-key.pem /var/nexthink/engine/common/etc/key.pem
  4. Restart the Engine:
    sudo systemctl restart [email protected]
  5. Optional: Restore the default certificate for the TCP non-traffic connection with the Collectors:
    1. Log in to the Web Console.
    2. In the Appliance tab, select Collector security from the left-hand side menu.
    3. Tick the option Use default certificate. Ensure that you have deployed your Collectors with the root certificate downloaded from the same section Collector security of the Web Console in the master Appliance.
    4. Click Save.

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):

  1. Log in to the Windows 10 device as a user with administrator rights.
  2. Type WinKey+R to open the Run dialog.
  3. Type in certlm.msc and press OK.
  4. Click Yes in the dialog that shows up to allow the program make changes to your computer.
  5. Right-click Trusted Root Certification Authorities and select All Tasks > Import....
  6. The Certificate Import Wizard starts. Click Next.
  7. Click Browse and select the root.crt file.
  8. Click Next.
  9. In the dialog Place all certificates in the following store, click Next to accept the proposed certificate store (Trusted Root Certification Authorities).
  10. 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 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:

  1. Log in to the CLI of the master Appliance.
  2. Copy the appropriate certificates and keys to the home directory of the nexthink account in the master Appliance by using your favorite SCP tool.
    1. Copy the root certificate root.crt.
    2. 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).
  3. Stop the Portal:
    sudo systemctl stop nxportal
  4. Import the root certificate into the keystore:
    sudo sh /var/nexthink/portal/security/import_certificate.sh \
    -alias root_engine -file root.crt \
    -storepass changeit
  5. If 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 changeit
  6. Restart 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:

  1. Log in to the CLI of the master Appliance.
  2. 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:

  1. Log in to the CLI of the master Appliance.
  2. Ask for password modification:
    sudo /usr/java/default/jre/bin/keytool -storepasswd \
    -keystore /usr/java/default/jre/lib/security/cacerts
  3. You 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:

globalconfig.portal.dispatcher.engine-ssl-ignore-certificate-problems=true
globalconfig.ldap.skip-ssl-certificate-validations=false

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:

  1. Log in to the CLI of the slave Appliance.
  2. Copy the root certificate root.crt to the home directory of the nexthink account in the slave Appliance by using your favorite SCP tool.
  3. 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.