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 consists in 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).
  • 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.

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 this 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

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 clients applications to effectively authenticate your Appliances, the Common Name of the subject in 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 are all assumed to be in the PEM format. To follow the instructions below, convert them to PEM format if this is not the case. To that end, use for instance the openssl command line tool.

Replacing the server certificate of the Web Console

These instructions apply both to the Web Console in the master and slave Appliances. Use the appropriate server certificate, master.crt or slave.crt, when indicated. The Web Console presents its server certificate to web browsers that connect to it.

The Web Console stores both its server certificate and associated private key concatenated in a single file:

  • /var/nexthink/console/etc/certificate.pem

To replace the default certificate of the Web Console:

  1. Log in to the CLI of the Appliance.
  2. Copy the appropriate certificates to the home directory of the nexthink account in the Appliance by using your favorite SCP tool.
    1. Copy the server certificate and key:
      • The master.crt and master.key files if in the master Appliance.
      • A slave.crt and slave.key files if in a slave Appliance.
    2. If present, copy the bundle of intermediate certificates intermediate.crt.
  3. Stop the Console:
    sudo systemctl stop nxconsole
  4. Make a backup of the default certificate:
    sudo cp /var/nexthink/console/etc/certificate.pem \
    /var/nexthink/console/etc/certificate.pem.default
  5. Concatenate your key and certificate and replace the default:
    • If you are replacing the server certificate of the Web Console in the master Appliance:
      cat master.key master.crt | sudo tee \
      /var/nexthink/console/etc/certificate.pem > /dev/null
    • If you are replacing the server certificate of the Web Console in one of the slave Appliances:
      cat slave.key slave.crt | sudo tee \
      /var/nexthink/console/etc/certificate.pem > /dev/null
  6. If you have a bundle of intermediate certificates:
    1. Copy the intermediate certificates to the configuration folder of the console:
      sudo cp intermediate.crt /var/nexthink/console/etc
    2. Open the configuration file of the Web Console HTTP server:
      sudo vi /var/nexthink/console/etc/lighttpd.conf
    3. Look for the configuration setting ssl.pemfile and add the following line after it:
      ssl.ca-file = "/var/nexthink/console/etc/intermediate.crt"
    4. To save your changes in the configuration file and exit, type:
      :wq
  7. Restart the Console:
    sudo systemctl start nxconsole

Replacing the server certificate of the Portal

The Portal presents its server certificate when receiving connections from the following client applications:

  • A web browser.
  • The Finder.

The Portal stores its server certificate and associated private key in a Java KeyStore located in the master Appliance:

  • /var/nexthink/portal/keystore/keystore.jks

To replace the default certificate of 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. Copy the server certificate master.crt and key master.key.
    3. If present, copy the bundle of intermediate certificates intermediate.crt.
      1. Chain the bundle of intermediate certificates with the root certificate:
        cat intermediate.crt root.crt > ca-chain.crt
  3. Stop the Portal:
    sudo systemctl stop nxportal
  4. Create a PKCS12 keystore with the root certificate, the server certificate, its associated key and, optionally, the bundle of intermediate certificates:
    • If you have no bundle of intermediate certificates, type:
      openssl pkcs12 -export -chain -in master.crt -inkey master.key \
      -out portal.p12 -name portal -passout pass:nexthink \
      -CAfile root.crt -caname root
    • If you do have a bundle of intermediate certificates, type:
      openssl pkcs12 -export -chain -in master.crt -inkey master.key \
      -out portal.p12 -name portal -passout pass:nexthink \
      -CAfile ca-chain.crt -caname chain
  5. Make a backup of the default keystore:
    sudo cp /var/nexthink/portal/keystore/keystore.jks \
    /var/nexthink/portal/keystore/keystore.jks.default
  6. Delete the default certificate from the keystore:
    sudo /usr/java/default/bin/keytool \
    -keystore /var/nexthink/portal/keystore/keystore.jks \
    -delete -storepass nexthink -alias portal
  7. Import the certificate into the keystore:
    sudo /usr/java/default/bin/keytool -importkeystore \
    -deststorepass nexthink \
    -destkeystore /var/nexthink/portal/keystore/keystore.jks \
    -srckeystore portal.p12 -srcstoretype PKCS12 \
    -srcstorepass nexthink -alias portal
  8. Restart the Portal
    sudo systemctl start nxportal

Replacing the server certificates of the Engine

In the slave Appliance, the Engine holds two certificates (and their associated keys) that serve different purposes and can be modified independently:

  • A server certificate to protect the connections established with the Finder, the Portal, and the Web API.
    Server certificate located in:
    • /var/nexthink/engine/common/etc/certificate.pem
    Private key located in:
    • /var/nexthink/engine/common/etc/key.pem
  • A server certificate, generated during the federation of the Engine, to protect the TCP communication channel of the Collectors.
    Server certificate and private key located in:
    • /var/nexthink/nxproxy/keystore

Although the two default server certificates are different and work independently, you can use a single certificate to replace both.

To replace the default Engine certificate that protects the connections the Finder, the Portal, and the Web API:

  1. Log in to the CLI of the slave Appliance.
  2. Copy the server certificate slave.crt and key slave.key to the home directory of the nexthink account in the slave Appliance by using your favorite SCP tool.
  3. Stop the Engine:
    sudo systemctl stop [email protected]
  4. Make a backup of the default certificate and key:
    sudo mv /var/nexthink/engine/common/etc/certificate.pem \
    /var/nexthink/engine/common/etc/certificate.pem.default
    sudo mv /var/nexthink/engine/common/etc/key.pem \
    /var/nexthink/engine/common/etc/key.pem.default
  5. Set owner and permissions of the server certificate and key files:
    sudo chown nxengine:nxengine slave.crt
    sudo chown nxengine:nxengine slave.key
    sudo chmod 444 slave.crt
    sudo chmod 400 slave.key
  6. Copy your server certificate and key files to common configuration folder of the Engine:
    sudo cp -p slave.crt \
    /var/nexthink/engine/common/etc/certificate.pem
    sudo cp -p slave.key /var/nexthink/engine/common/etc/key.pem
  7. Restart the Engine:
    sudo systemctl start [email protected]

Note that the Engine supports only the installation of the server certificate for protecting the connections with the Finder, the Portal, or the Web API, but not the possible bundle of intermediate certificates. As a workaround, install the intermediate certificates in the client, if necessary.

In turn, the protection of the TCP communication channel of Collectors with the Engine does support the installation of intermediate certificates. In this case, the default server certificate is generated when you federate the slave Appliance. The certificate is signed by the private key of the ad hoc PKI that the federation process creates in the master Appliance, which thus acts as a CA. For the Collector to be able to verify the authenticity of the server certificate, you usually specify the root certificate of the master Appliance when you install the Collector (or generate the Collector installer).

It is safe to rely on the default PKI to protect the TCP communications with the Collectors. If you decide nevertheless to replace the default certificate in the Engine for this purpose:

  • Leave empty the root certificate field when installing the Collector (or generating the Collector installer).
    Distribute instead the root certificate to the Trusted Root Certification Authorities store of the Windows devices where the Collector is being installed.
  • Replace the default certificate after federating the slave Appliance.
    If you replace the default certificate before federating the slave Appliance, your server certificate will be overwritten during the federation process.

To replace the default Engine certificate that protects the TCP communication with the Collectors:

  1. Log in to the CLI of the slave Appliance that hosts a particular Engine.
  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. Copy the server certificate slave.crt and key slave.key.
    3. If present, copy the bundle of intermediate certificates intermediate.crt.
      1. Chain the bundle of intermediate certificates with the root certificate:
        cat intermediate.crt root.crt > ca-chain.crt
  3. Create a PKCS12 keystore with the root certificate, the server certificate, its associated key and, optionally, the bundle of intermediate certificates (to use another name or password for the certificate, change the configuration file detailed below):
    • If you have no bundle of intermediate certificates, type:
      openssl pkcs12 -export -chain -in slave.crt -inkey slave.key \
      -out slave.p12 -name nxproxy -passout pass:nexthink \
      -CAfile root.crt -caname root
    • If you do have a bundle of intermediate certificates, type:
      openssl pkcs12 -export -chain -in slave.crt -inkey slave.key \
      -out slave.p12 -name nxproxy -passout pass:nexthink \
      -CAfile ca-chain.crt -caname chain
  4. Make a backup of the default keystore:
    sudo mv /var/nexthink/nxproxy/keystore/keystore.jks \
    /var/nexthink/nxproxy/keystore/keystore.jks.default
  5. Create a new Java KeyStore:
    keytool -importkeystore -deststorepass nexthink \
    -destkeypass nexthink -destkeystore keystore.jks \
    -srckeystore slave.p12 -srcstoretype PKCS12 \
    -srcstorepass nexthink -noprompt
  6. Set the owner and permissions of the keystore:
    sudo chown nxproxy:nexthink keystore.jks
    sudo chmod 660 keystore.jks
  7. Copy the keystore file to the appropriate configuration folder:
    sudo cp -p keystore.jks /var/nexthink/nxproxy/keystore
  8. Restart the proxy service in the Engine:
    sudo systemctl restart nxproxy

To use a different name or password for the certificate, as well as a different path for the keystore, edit the configuration file:

  • /var/nexthink/nxproxy/nxproxy.conf

And modify the following lines accordingly:

nxproxy {
  jetty {
    ssl-key-store-path = "keystore/keystore.jks"
    ssl-key-store-password = "nexthink"
    ssl-key-manager-password = "nexthink"
    certificate-alias = "nxproxy"
  }
}

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 (as it is currently the case of the Engine).
  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_engine -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.