--- title: Using certificate fingerprints description: Use certificate fingerprints to secure Elastic Agent connections to Fleet Server and Elasticsearch without CA certificate files. url: https://www.elastic.co/elastic/docs-builder/docs/3016/reference/fleet/certificate-fingerprints products: - Elastic Agent - Fleet applies_to: - Elastic Cloud Serverless: Generally available - Elastic Stack: Generally available --- # Using certificate fingerprints Certificate fingerprints provide an alternative to using certificate authority (CA) files when securing connections between Elastic Agent, Fleet Server, and Elasticsearch. In Elastic Cloud Hosted deployments and Serverless projects, you don't need to set certificate authorities or certificate fingerprints because Elastic always uses trusted certificates. ## How certificate fingerprints work 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. ### Fingerprint method 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. The certificate whose fingerprint you configure must be present in the certificate chain the server sends during the TLS handshake. If the certificate is not in the chain, the fingerprint cannot be matched, and the connection will fail with a `certificate signed by unknown authority` error. ### CA certificate method 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. ## Requirements 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](#fingerprint-requirements-1) - [The certificate must be a CA certificate](#fingerprint-requirements-2) - [The fingerprint must be correctly formatted](#fingerprint-requirements-3) ### The certificate must be in the server's presented chain 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](#choosing-certificate). ### The certificate must be a CA certificate 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: ```bash openssl x509 -noout -text -in certificate.crt ``` Look for this section in the output: ```text 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 correctly formatted The fingerprint must be a HEX-encoded SHA-256 hash with colons removed. ## Choosing which certificate to use 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. ### Understanding your certificate chain Consider this certificate chain as an example: ```text 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: ```yaml xpack.security.http.ssl.certificate: certs/server-intermediate2-intermediate1.pem xpack.security.http.ssl.certificate_authorities: ["certs/root-ca.pem"] ``` This example shows Elasticsearch configuration settings. If you're connecting to Fleet Server, the configuration will use different setting names, but the principle is the same. 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: | Fingerprint of | Result | Reason | |--------------------|-------------|------------------------------------------------------------------------------------| | Root CA | ❌ **Fails** | Not in the server's presented certificate file (not sent during the TLS handshake) | | Intermediate CA 1 | ✅ **Works** | In the server's presented certificate file and has `CA:TRUE` | | Intermediate CA 2 | ✅ **Works** | In the server's presented certificate file and has `CA:TRUE` | | Server certificate | ❌ **Fails** | Not a CA certificate (`CA:FALSE`) | **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. ## Generate a certificate fingerprint Use this command to generate the SHA-256 fingerprint for the CA certificate: ```bash openssl x509 -fingerprint -sha256 -noout -in ca.crt | \ awk -F"=" '{print $2}' | \ sed 's/://g' ``` ```bash openssl x509 -fingerprint -sha256 -noout -in ca.crt | \ awk -F"=" '{print $2}' | \ sed 's/://g' ``` In PowerShell, run: ```powershell (openssl x509 -fingerprint -sha256 -noout -in ca.crt) -replace '.*=', '' -replace ':', '' ``` This requires OpenSSL for Windows to be installed. This outputs a string like: ```text A1B2C3D4E5F6789012345678901234567890123456789012345678901234ABCD ``` Use this value in the fingerprint configuration fields. ## Configuration examples ### CLI configuration for Fleet Server Using the [certificate chain example](#choosing-certificate) where Intermediate CA 1 is in the server's certificate file, you can install a Fleet Server with the fingerprint: ```bash 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 ``` ### Fleet UI configuration 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. Refer to [Choosing which certificate to use](#choosing-certificate) to determine which certificate from your chain is appropriate for the fingerprint. ## Related topics - [Configure SSL/TLS for self-managed Fleet Servers](https://www.elastic.co/elastic/docs-builder/docs/3016/reference/fleet/secure-connections) - [Rotate SSL/TLS CA certificates](https://www.elastic.co/elastic/docs-builder/docs/3016/reference/fleet/certificates-rotation) - [Elastic Agent SSL configuration options](https://www.elastic.co/elastic/docs-builder/docs/3016/reference/fleet/elastic-agent-ssl-configuration)