Certificates Overview

The certificates tab is divided into four sections:

  • Let's Encrypt Cert Wizard
  • Certificates List
  • Upload Certificate File
  • Server Management Certificate

These sections are to help you manage certificates in Heimdall.

Let's Encrypt Cert Wizard

Let's Encrypt Cert Wizard section provides a way to simply generate Let's encrypt requests and then the final certificate from this.

Prerequisites

In the certificate tab in Let's Encrypt Cert Wizard section, there are three fields that need to be set to create an order of the Let's Encrypt certificate:

  • Challenge type (DNS is default)
  • Certificate alias
  • Domain

Challenge

Challenges are used to prove ownership of a domain. There are two available challenges DNS and HTTP:

  • DNS: You prove to the CA that you are able to control the DNS records of the domain to be authorized, by creating a TXT record with a signed content.
  • HTTP: You prove to the CA that you are able to control the website content of the domain to be authorized, by making a file with a signed content available at a given path.

Certificate alias

A certificate alias is a name, used in other places, which is going to be assigned to the generated certificate in the Keystore and Virtual Databases.

Domain

A domain is a subject of the generated certificate.

Flow

In case to generate new Let's Encrypt certificate you must:

  1. Set up all fields and click "Order" button. Let's Encrypt API will request order certificate.
  2. Make a challenge returned by Let's Encrypt API. You will find instructions in message field.
  3. Click "Verify" button. If you did your challenge properly, Let's Encrypt API will generate new Let's Encrypt certificate and will place it in the Keystore and Virtual Databases with given certificate alias.

Be careful !!!
If a certificate alias already exists in Heimdall, the existing certificate will be overridden with a new Let's Encrypt Certificate.

Create order

After you set up all fields and click the "Order" button:

  1. Let's Encrypt API creates your unique account in Let's Encrypt CA if you don't have one.
  2. Send to Let's Encrypt CA request to create certificate order for the given domain name.
  3. Let's Encrypt API returns you a message on how you can prove your ownership, based on the selected challenge type.

Verify order

After you do your challenge and click "Verify" button:

  1. Let's Encrypt API send request to Let's Encrypt CA in case to verify your ownership.
  2. If verification went properly, API will request for certificate.
  3. Generated certificated is being uploaded to Keystore with given alias. If certificate with given alias already exists it will override existing certificate.

Extra information

You can test API by selecting the checkbox "Use Let's Encrypt test API"

Certificates List

There is a list of uploaded certificates shown by the aliases.

You can check the details of each certificate, such as:

  • Issuer - The entity or organization that grants or issues the certificate. They are responsible for verifying the qualifications, credentials, or completion of specific requirements that make the recipient eligible for the certificate.
  • Subject - The individual or entity to whom the certificate is issued. They are the recipient or beneficiary of the certificate.
  • Public Key Info - The public key information such as: Algorithm - The specific cryptographic method or algorithm used to generate the key pair associated with the certificate, such as RSA, DSA, or ECDSA. Exponent - A component of the public key that is used in encryption and digital signature verification. It is a positive integer associated with the algorithm used. Key Size - The length or size of the cryptographic key, typically measured in bits. A larger key size generally implies increased security against certain types of attacks. Modulus - A mathematical term representing the modulus value used in the cryptographic algorithm. It is part of the public key and plays a crucial role in encryption and signature verification.
  • Miscellaneous - Additional information such as serial number, signature algorithm, version.
  • Validity - The period of time, where the certificate is valid.
  • Fingerprints - A unique identifier generated from the certificate's contents using a specific hash algorithm.

You can remove all unused certificates (which are not used by any vdb) by clicking the "Delete Unused Certificates" button.

CA Certificates List

There is a list of uploaded CA certificates shown by the aliases in the same way as above certificates.

Under the details for each CA certificate there is a button to delete a given certificate. Remember! Before deleting the CA certificate, make sure that all proxies are enabled so that the certificate will also be removed from the proxy cacerts file if it is on a different machine than the central manager.

Upload Certificate File

Upload Certificate File section provides a way to upload your own certificate into Heimdall.

There are 3 fields in upload certificate file interface:

  • Combined pem file (A file that contains private key and certificate in pem format with appropriate headers).
  • Force update checkbox (If certificate with given alias already exists, force flag must be checked to override existing certificate in Keystore and Virtual Databases).
  • Alias (Alias in keystore where certificate will be kept. By default, it's "global_use_certificate" alias).

You can also upload a CA certificate, which will be saved on the central manager side and transferred to all proxies. In both cases it will be saved in the cacerts file with the default password and in the default location appropriate for Java where the central manager/proxy is running.

If you want to upload a CA certificate, just select "CA Certificate" checkbox. The pem file should contain only the certificate - public key.

The ca certs aliases are also stored in the ca_certs_aliases.json file in the config directory.

Server Management Certificate

Server management Certificate section provides a way to see your current server management certificate, and also to change your server management certificate with it.

Flow:

  1. Choose certificate that you to want use for server management.
  2. Click "Commit" button to assign new certificate to the server management.

To start using the new certificate, you must restart the Heimdall.