Using certificate fingerprints

Certificate fingerprints provide an alternative to using certificate authority (CA) files when securing connections between Elastic Agent, Fleet Server, and Elasticsearch. This guide explains how certificate fingerprints work and how to avoid common configuration errors.

Certificate fingerprints and CA certificate files establish trust in different ways during the TLS handshake. Understanding this difference is essential to avoid connection failures.

When using ca_trusted_fingerprint in the configuration or the --fleet-server-es-ca-trusted-fingerprint CLI option:

1. The server presents its certificate chain during the TLS handshake.
2. Before validating the server certificate, the client examines each certificate in the presented chain.
3. If the client finds a CA certificate whose fingerprint matches the configured fingerprint, it adds that certificate to the in-memory list of trusted CAs.
4. The TLS handshake continues with normal certificate validation using all configured CAs plus the newly added one.

When using ssl.certificate_authorities in configuration or the --fleet-server-es-ca CLI option:

1. The server presents its certificate chain during the TLS handshake.
2. The client uses the CA certificate file to validate the chain.
3. The root CA does not need to be in the server's presented chain because the client already has it locally.

This is the critical difference: CA files work even when the root CA is not sent by the server, but fingerprints require the CA certificate to be in the presented chain.

For a certificate fingerprint to work correctly, the certificate and fingerprint must meet these requirements:

The certificate must be included in the server's xpack.security.http.ssl.certificate setting (for Elasticsearch) or equivalent TLS certificate configuration.

For example, if your Elasticsearch configuration is:

xpack.security.http.ssl.certificate: certs/server-intermediate2-intermediate1.pem
		

The server-intermediate2-intermediate1.pem file contains three certificates:

• Server certificate
• Intermediate CA 2
• Intermediate CA 1

You can use fingerprints for Intermediate CA 1 or Intermediate CA 2, but not for a root CA that's not in this file.

The certificate must have CA:TRUE in its X509v3 Basic Constraints. Server certificates (leaf certificates) cannot be used with the fingerprint method.

To check if a certificate is a CA certificate, use:

openssl x509 -noout -text -in certificate.crt
		

Look for this section in the output:

X509v3 extensions:
    X509v3 Basic Constraints: critical
        CA:TRUE
		

If CA:TRUE is present, the certificate can be used with the fingerprint method.

The fingerprint must be a HEX-encoded SHA-256 hash with colons removed.

To generate the SHA-256 fingerprint for a CA certificate:

openssl x509 -fingerprint -sha256 -noout -in ca.crt | \
  awk -F"=" '{print $2}' | \
  sed 's/://g'
		

This outputs a string like:

A1B2C3D4E5F6789012345678901234567890123456789012345678901234ABCD
		

Use this value in fingerprint configuration fields.

Consider this certificate chain:

Root CA → Intermediate CA 1 → Intermediate CA 2 → Server Certificate
		

Elasticsearch configuration:

xpack.security.http.ssl.certificate: certs/server-intermediate2-intermediate1.pem
xpack.security.http.ssl.certificate_authorities: ["certs/root-ca.pem"]
		

The server-intermediate2-intermediate1.pem file contains:

• Server certificate
• Intermediate CA 2 certificate
• Intermediate CA 1 certificate

The root-ca.pem file contains:

• Root CA certificate

Use the fingerprint of an intermediate CA that's in the presented chain:

sudo ./elastic-agent install \
  --url=https://fleet-server:8220 \
  --fleet-server-es=https://elasticsearch:9200 \
  --fleet-server-service-token=SERVICE_TOKEN \
  --fleet-server-policy=fleet-server-policy \
  --fleet-server-es-ca-trusted-fingerprint=INTERMEDIATE_CA1_FINGERPRINT \
  --fleet-server-port=8220
		

1. In Kibana, go to Fleet > Settings.
2. Under Outputs, edit your Elasticsearch output.
3. In the Elasticsearch CA trusted fingerprint field, enter the fingerprint of an intermediate CA that's in the server's certificate chain.

This is the most common error when using certificate fingerprints incorrectly.

Cause: The certificate whose fingerprint you configured is not present in the certificate chain sent by the server during the TLS handshake.

Solutions:

1. Verify the certificate is in the server's chain:

   Check which certificates the server presents:

   openssl s_client -connect elasticsearch:9200 -showcerts
   		

   Compare the output with your xpack.security.http.ssl.certificate configuration.

2. Use a different certificate fingerprint:

   If the root CA is not in the chain, generate the fingerprint for an intermediate CA that is in the chain.

3. Verify the certificate is a CA:

   openssl x509 -noout -text -in certificate.crt | grep "CA:"
   		

   Should show CA:TRUE.

4. Switch to using CA certificate files:

   If you cannot include the necessary CA in the server's certificate chain, use ssl.certificate_authorities with a CA file instead:

   ssl.certificate_authorities: ["/path/to/root-ca.crt"]
   		

Cause: The server's certificate chain configuration changed, and the CA certificate is no longer included in the presented chain.

Solution: Check the server's TLS configuration and either:

• Add the CA back to the certificate chain, or
• Generate a fingerprint for a CA that is in the new chain, or
• Switch to using CA certificate files

If you're wondering why the same setup works with a root CA file but not with a root CA fingerprint:

With a CA file, the client can validate intermediate certificates signed by the root CA even when the root CA is not sent by the server. The client already has the root CA locally.

With a fingerprint, the client must find the certificate in the presented chain before it can add it to trusted CAs. If it's not in the chain, it cannot be found and trusted.

• Configure SSL/TLS for self-managed Fleet Servers
• Rotate SSL/TLS CA certificates
• Elastic Agent SSL configuration options