During the installation of the Control Room in a cluster setup, you can upload custom certificates with a trusted Certificate Authority (CA) instead of using the default certificate provided by the product for enhanced security.

Ensure you review the following guidelines and recommendations before you upload custom certificates:
  • Ensure that the certificates have an appropriate validity (duration) so that the installation does not fail.
  • Review the following naming conventions for the custom certificate files in Linux:
    File Expected file naming Expected file format
    Root (CA certificate) root-ca-cert.pem .pem
    Certificate/Key (nodes-administrative) elasticsearch-cert.pem .pem
    elasticsearch-key.pem
    Certificate/Key (nodes-intercommunication) elasticsearch-node-cert.pem .pem
    elasticsearch-node-key.pem
    • The elasticsearch-cert.pem is for administrative purposes, we recommend that you use the firstnode hostname.
      Note:
      • If you have an intermediate certificate, you can rename it to root-ca-cert.pem to use it as the root certificate. The system will then recognize this intermediate certificate as the root after performing a certificate chain validation up to it.
      • The .zip file must contain the certificate, key, and root CA certificate files.
      • The elasticsearch-node-cert.pem is used to secure inter-node communication. It must include the host names of the second or third node, ensuring encrypted and trusted communication between cluster members.
      • Ensure that the following certificates are signed by root/intermediate CA certificate:
        • elasticsearch-cert.pem
        • elasticsearch-node-cert.pem
    • Ensure that the following certificates are signed by root/intermediate CA certificate:
      • elasticsearch-cert.pem

        Applicable for both Windows and Linux.

      • elasticsearch-node-cert.pem

        Applicable only for Linux.

        Note:
        • Two unique CA signed certificates must be generated:
          • One for node admin.
          • One for node intercommunication
        • Both certificates must have unique common name. Same common name cannot be used for these certificates.
        • Transport layer TLS certificates need to be configured as both the client (TLS Web Client Authentication) and server (TLS Web Server Authentication) in the certificate’s Extended Key Usage section because the nodes using the TLS certificates assume the responsibility of serving and receiving the communication requests internally. The certificates should have extended key usage with both server and client authentication. For example while generating the certificates it must include extendedKeyUsage = serverAuth, clientAuth using a config file.
  • Ensure the certificates in the .zip file follow the below guidelines so that they can be easily accessed and processed by the Control Room.
    • Ensure certificates are not encrypted (no password protection)
    • Include only the five required certificate files
    • Folder structure should not contain any sub folders inside the .zip file.

      For example: OpenSearch CA for Linux

  • The certificate must have a common name (CN). We recommend using the hostname as CN.

Debugging common custom certificate upload errors

Custom certificate retrieval might fail due to the following reasons. For detailed information, check msi logs in the temp folder. Example: C:\Users\<Username>\AppData\Local\Temp.
Error code Possible reason Mitigation
java.security.cert.CertificateExpiredException Certificate is invalid error. Ensure the certificate has not expired, and check for any mismatches in the certificate details. Re-upload the certificate after correcting any issues.
java.Lang.RuntimeException: ERROR required certificate does not exist The .zip folder structure is incorrect or the certificate is missing certificate error. Ensure that the certificates are correctly placed in the .zip folder.
ERROR: java.lang.RuntimeException: Elasticsearch root certificate is not a CA The root CA does not match with node certificate. Verify that the certificate is a valid CA certificate. Correct any issues and re-upload the certificate.