NXLog Documentation

Certificates

NXLog Manager uses X.509 certificates for various security purposes and has a built-in PKI system to manage them.

Listing Certificates

To list the available certificates, click CERTIFICATES under the ADMIN menu. A list similar to the following appears.

List of certificates

The table contains the following information.

Name

The certificate subject name.

Type

The type is either CA or CERT.

Activation

The time and date after which the certificate is valid.

Expiration

The time and date before which the certificate is valid.

Status

This status is either VALID, REVOKED, or EXPIRED.

Private Key

This field indicates whether the private key pair of the certificate is available or not.

The certificate list shows entries in a hierarchical (tree) structure. Certificates (and sub-CAs) will be rooted under the CA which was used to sign it.

If the PKI system does not have any certificates, you will need to create a CA first.

Creating a CA

The certificate authority is used to issue and sign certificates and, subsequently, to verify the associated trust relationships. To be able to create certificates, a CA is required. To create a CA cert, click Add new CA on the certificate list page. The certificate creator dialog is displayed.

Creating a CA

Some field values are pre-filled if certificate settings are already configured. After clicking Create, the new CA appears.

Creating a Certificate

Creating a certificate

Some field values are pre-filled if the certificate settings are already configured. Fill in the name (certificate subject) and expiry and select the certificate purpose. It is possible to customize the certificate purpose flags, but this is not required if the certificate is only used within NXLog Manager with NXLog. After clicking Create, the new certificate appears, displaying information similar to the following screenshot.

Viewing certificate details

Exporting certificates

To export a certificate, click Export on a certificate’s general information page or below the certificate list after selecting one certificate. The following options appear.

Exporting a certificate

In order to support external certificate tools and PKI systems, certificates can be exported in different formats. The NXLog agents use PEM formatted X.509 certificates.

To export selected certificates from the list in PKCS#12 key store format, click on the export PKCS#12 button from the certificates page. It will ask for an optional password to protect the PKCS#12 key store:

PKCS#12 Password

Importing certificates

In order to support external certificate tools and PKI systems, certificates can be imported in different formats.

Importing a certificate

Revoking and Deleting Certificates

It is not possible to delete a certificate unless it is revoked. If the PKI system does not contain the certificate of an NXLog agent and the presented certificate is authenticated, the connection will be accepted.

If the PKI system does contain the certificate of an NXLog agent and the certificate is found to be revoked, the connection will be refused.

Deleting certificates is not recommended.

Connecting agents with expired certificates

Agents with expired certificates should be connected for renewing certificates only!

NXLog Manager notifies about certificate expiration under the AGENTS menu.

Notification about certificate expiration

After a certificate has expired, the agent status changes for Offline with the corresponding notification.

Agent with expired certificate

To enable NXLog Manager to connect agents with expired certificates, under ADMIN > SETTINGS > Agent manager select Trust connections with expired certificates.

Trusting connections with expired certificates

If an agent with an expired certificate is connected to NXLog Manager, it is displayed as an Untrusted agent.

Connected agent

Renewing a Certificate

This operation will issue a new certificate. It can be used to replace an existing certificate which has already expired, will shortly expire, or is revoked.

Generally, it is not a good idea to have multiple valid certificates with the same subject. If a certificate has been superseded by a new one (e.g. already pushed to the agent), make sure to revoke the former.

Certificates Encryption

By default, NXLog-Manager encrypts the private keys of certificates in the database, to prevent stealing them if the database is hacked. This is 2-phase encryption with predefined algorithms:

  • The first time the 'admin' user logs-in, NXLog-Manager generates a random encryption key with predefined length. This key is only kept in application memory space and certificate keys will be encrypted with it.

  • NXLog-Manager then encrypts this key with the authorized user password and saves it in the user settings in the database. When NXLog-Manager is restarted, the authorized user with a key must login to decrypt this key with the password to make it available for encryption/decryption of certificate keys.

An authorized user is eligible for this key when it has the role of ROLE_ADMINISTRATOR or ROLE_CERTIFICATE. By default an 'admin' user has ROLE_ADMINISTRATOR.
When a new authorized user is added, the encryption key must also be encrypted with the new user’s password and saved in the database. Currently, this can only happen if the user logs in to the same application session for which this key is already available (an authorized user with a stored key has logged in to unlock the key). In the future, there will be enhancements in NXLog Manager to skip the log-in step for new authorized users.

There is an option Do not encrypt agent manager’s private key in Agent Manager. With this option active, when the NXLog Manager has to be restarted for some reason it is not necessary for the administrator to log in to decrypt their keys so the manager can (re)start.

Reset Certificates and Encryption Key

If the encryption key cannot be decrypted due to some configuration problem or defect, NXLog Manager offers a recover option to reset all the certificates with encrypted keys and reset the encryption key for them. When the encryption key is not available after log in with authorized user, a dialog similar to this one is displayed:

Encryption key not available

If reset certificates and encryption key is the last resort and there is no other option, this action can be done from this dialog. This will update the certificates for the connected agents with renewed certificates. It is a good outcome if there are as many agents as possible connected and the manager should be already running with non-encrypted keys.

All offline agents during this operation must be updated locally with the new certificates. They will not be able to connect to the manager when it is running with new certificates for authentication.

There will be notifications for each change/failure in the UI and also in the logs.