Using certificate fingerprints

Certificate fingerprints provide an alternative to using certificate authority (CA) files when securing connections between Elastic Agent, Fleet Server, and Elasticsearch.

Certificate fingerprints and CA certificate files establish trust in different ways during the TLS handshake. Fingerprints require the CA certificate to be in the presented chain, whereas using CA files works even when the server doesn't send the root CA.

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, including the newly added one.

When using ssl.certificate_authorities in the 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.

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

• The certificate must be in the server's presented chain
• The certificate must be a CA certificate
• The fingerprint must be correctly formatted

The certificate must be included in the certificate file that the server presents during the TLS handshake. For Elasticsearch, this is the file specified in the xpack.security.http.ssl.certificate setting. For Fleet Server, this is the certificate specified in its configuration.

Certificates that exist only in the server's certificate authorities file cannot be used for fingerprints because they are not sent during the TLS handshake.

For a practical example of how this works with a real certificate chain, refer to Choosing which certificate to use.

The certificate must have CA:TRUE in its X509v3 Basic Constraints. Server 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.

Before generating a fingerprint, you need to identify which certificate from your certificate chain to use. You must use a CA certificate from the certificate file the server presents during the TLS handshake, not from the server's certificate authorities file.

Consider this certificate chain as an example:

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

Let's assume that this chain is split across two certificate files in the Elasticsearch configuration:

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

The certificate file presented during the TLS handshake (server-intermediate2-intermediate1.pem) contains:

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

The certificate authorities file (root-ca.pem) contains:

• Root CA certificate

Based on this server configuration, the following table shows which certificates can be used for fingerprints and why:

Key takeaway: You need to use a CA certificate from the certificate file that the server presents during the TLS handshake. You cannot use the root CA if it's only in the server's certificate authorities file, nor can you use the server certificate itself.

Use this command to generate the SHA-256 fingerprint for the CA certificate:

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

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

(openssl x509 -fingerprint -sha256 -noout -in ca.crt) -replace '.*=', '' -replace ':', ''
		

This outputs a string like:

A1B2C3D4E5F6789012345678901234567890123456789012345678901234ABCD
		

Use this value in the fingerprint configuration fields.

Using the certificate chain example where Intermediate CA 1 is in the server's certificate file, you can install a Fleet Server with the fingerprint:

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. Replace INTERMEDIATE_CA1_FINGERPRINT with the fingerprint value of the intermediate CA certificate.

1. In Kibana, go to Fleet > Settings.
2. Under Outputs, edit your Elasticsearch output.
3. In the Elasticsearch CA trusted fingerprint field, enter any CA certificate's fingerprint that's present in the certificate chain sent by Elasticsearch.

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