Clarify how certificate fingerprints work for Fleet Server

reference/fleet/agent-command-reference.md

@@ -263,10 +263,10 @@ For more information about custom certificates, refer to [Configure SSL/TLS for
 :   Start a {{fleet-server}} process when {{agent}} is started, and connect to the specified {{es}} URL.
 
 `--fleet-server-es-ca <string>` {applies_to}`serverless: unavailable`
-:   Path to certificate authority to use to communicate with {{es}}.
+:   Path to certificate authority file to use to communicate with {{es}}. This is an alternative to using `--fleet-server-es-ca-trusted-fingerprint`.
 
 `--fleet-server-es-ca-trusted-fingerprint <string>` {applies_to}`serverless: unavailable`
-:   The SHA-256 fingerprint (hash) of the certificate authority used to self-sign {{es}} certificates. This fingerprint will be used to verify self-signed certificates presented by {{fleet-server}} and any inputs started by {{agent}} for communication. This flag is required when using self-signed certificates with {{es}}.
+:   The SHA-256 fingerprint (hash) of a certificate authority that is present in the certificate chain sent by {{es}} during the TLS handshake. If this certificate is found in the chain, it will be added to the trusted CAs. This is an alternative to using `--fleet-server-es-ca` to provide a CA certificate file. For more information, refer to [Using certificate fingerprints](/reference/fleet/certificate-fingerprints.md).
 
 `--fleet-server-es-cert` {applies_to}`serverless: unavailable`
 :   The path to the client certificate that {{fleet-server}} will use when connecting to {{es}}.
@@ -741,10 +741,10 @@ For more information about custom certificates, refer to [Configure SSL/TLS for
 :   Start a {{fleet-server}} process when {{agent}} is started, and connect to the specified {{es}} URL.
 
 `--fleet-server-es-ca <string>` {applies_to}`serverless: unavailable`
-:   Path to certificate authority to use to communicate with {{es}}.
+:   Path to certificate authority file to use to communicate with {{es}}. This is an alternative to using `--fleet-server-es-ca-trusted-fingerprint`.
 
 `--fleet-server-es-ca-trusted-fingerprint <string>` {applies_to}`serverless: unavailable`
-:   The SHA-256 fingerprint (hash) of the certificate authority used to self-sign {{es}} certificates. This fingerprint will be used to verify self-signed certificates presented by {{fleet-server}} and any inputs started by {{agent}} for communication. This flag is required when using self-signed certificates with {{es}}.
+:   The SHA-256 fingerprint (hash) of a certificate authority that is present in the certificate chain sent by {{es}} during the TLS handshake. If this certificate is found in the chain, it will be added to the trusted CAs. This is an alternative to using `--fleet-server-es-ca` to provide a CA certificate file. For more information, refer to [Using certificate fingerprints](/reference/fleet/certificate-fingerprints.md).
 
 `--fleet-server-es-cert` {applies_to}`serverless: unavailable`
 :   The path to the client certificate that {{fleet-server}} will use when connecting to {{es}}.

reference/fleet/agent-environment-variables.md

@@ -65,7 +65,7 @@ Settings used to bootstrap {{fleet-server}} on this {{agent}}. At least one {{fl
 | --- | --- |
 | $$$env-bootstrap-fleet-fleet-server-enable$$$<br>`FLEET_SERVER_ENABLE`<br> | (int) Set to `1` to bootstrap {{fleet-server}} on this {{agent}}. When set to `1`, this automatically forces {{fleet}} enrollment as well.<br><br>**Default:** none<br> |
 | $$$env-bootstrap-fleet-fleet-server-elasticsearch-host$$$<br>`FLEET_SERVER_ELASTICSEARCH_HOST`<br> | (string) The {{es}} host for {{fleet-server}} to communicate with. Overrides `ELASTICSEARCH_HOST` when set.<br><br>**Default:** `http://elasticsearch:9200`<br> |
-| $$$env-bootstrap-fleet-fleet-server-elasticsearch-ca$$$<br>`FLEET_SERVER_ELASTICSEARCH_CA`<br> | (string) The path to a certificate authority. Overrides `ELASTICSEARCH_CA` when set.<br><br>By default, {{agent}} uses the list of trusted certificate authorities (CA) from the operating system where it is running. If the certificate authority that signed your node certificates is not in the host system’s trusted certificate authorities list, use this config to add the path to the `.pem` file that contains your CA’s certificate.<br><br>**Default:** `""`<br> |
+| $$$env-bootstrap-fleet-fleet-server-elasticsearch-ca$$$<br>`FLEET_SERVER_ELASTICSEARCH_CA`<br> | (string) The path to a certificate authority file used to communicate with {{es}}. Overrides `ELASTICSEARCH_CA` when set. This is an alternative to using `FLEET_SERVER_ELASTICSEARCH_CA_TRUSTED_FINGERPRINT`. <br><br>By default, {{agent}} uses the list of trusted certificate authorities (CA) from the operating system where it is running. If the certificate authority that signed your node certificates is not in the host system’s trusted certificate authorities list, use this config to add the path to the `.pem` file that contains your CA's certificate.<br><br>**Default:** `""`<br> |
 | $$$env-bootstrap-fleet-fleet-server-es-cert$$$<br>`FLEET_SERVER_ES_CERT`<br> | (string) The path to the mutual TLS client certificate that {{fleet-server}} will use to connect to {{es}}.<br><br>**Default:** `""`<br> |
 | $$$env-bootstrap-fleet-fleet-server-es-cert-key$$$<br>`FLEET_SERVER_ES_CERT_KEY`<br> | (string) The path to the mutual TLS private key that {{fleet-server}} will use to connect to {{es}}.<br><br>**Default:** `""`<br> |
 | $$$env-bootstrap-fleet-fleet-server-insecure-http$$$<br>`FLEET_SERVER_INSECURE_HTTP`<br> | (bool) When `true`, {{fleet-server}} is exposed over insecure or unverified HTTP. Setting this to `true` is not recommended.<br><br>**Default:** `false`<br> |
@@ -79,7 +79,7 @@ Settings used to bootstrap {{fleet-server}} on this {{agent}}. At least one {{fl
 | $$$env-bootstrap-fleet-fleet-server-cert-key$$$<br>`FLEET_SERVER_CERT_KEY`<br> | (string) The path to the private key for the certificate used for HTTPS.<br><br>**Default:** none<br> |
 | $$$env-bootstrap-fleet-fleet-server-cert-key-passphrase$$$<br>`FLEET_SERVER_CERT_KEY_PASSPHRASE`<br> | (string) The path to the private key passphrase for an encrypted private key file.<br><br>**Default:** none<br> |
 | $$$env-bootstrap-fleet-fleet-server-client-auth$$$<br>`FLEET_SERVER_CLIENT_AUTH`<br> | (string) One of `none`, `optional`, or `required`. {{fleet-server}}'s client authentication option for client mTLS connections. If `optional` or `required` is specified, client certificates are verified using CAs.<br><br>**Default:** `none`<br> |
-| $$$env-bootstrap-fleet-fleet-server-es-ca-trusted-fingerprint$$$<br>`FLEET_SERVER_ELASTICSEARCH_CA_TRUSTED_FINGERPRINT`<br> | (string) The SHA-256 fingerprint (hash) of the certificate authority used to self-sign {{es}} certificates. This fingerprint is used to verify self-signed certificates presented by {{fleet-server}} and any inputs started by {{agent}} for communication. This flag is required when using self-signed certificates with {{es}}.<br><br>**Default:** `""`<br> |
+| $$$env-bootstrap-fleet-fleet-server-es-ca-trusted-fingerprint$$$<br>`FLEET_SERVER_ELASTICSEARCH_CA_TRUSTED_FINGERPRINT`<br> | (string) The SHA-256 fingerprint (hash) of a certificate authority that is present in the certificate chain sent by {{es}} during the TLS handshake. If this certificate is found in the chain, it will be added to the trusted CAs.<br><br>This is an alternative to using `FLEET_SERVER_ELASTICSEARCH_CA`. For more information, refer to [Using certificate fingerprints](/reference/fleet/certificate-fingerprints.md).<br><br>**Default:** `""`<br> |
 | $$$env-bootstrap-fleet-fleet-daemon-timeout$$$<br>`FLEET_DAEMON_TIMEOUT`<br> | (duration) Set to indicate how long {{fleet-server}} will wait during the bootstrap process for {{agent}}.<br> |
 | $$$env-bootstrap-fleet-fleet-server-timeout$$$<br>`FLEET_SERVER_TIMEOUT`<br> | (duration) Set to indicate how long {{agent}} will wait for {{fleet-server}} to check in as healthy.<br> |
 

reference/fleet/certificate-fingerprints.md

@@ -0,0 +1,213 @@
+---
+navigation_title: Certificate fingerprints
+description: Use certificate fingerprints to secure Elastic Agent connections to Fleet Server and Elasticsearch without CA certificate files.
+applies_to:
+  stack: ga
+  serverless: ga
+products:
+  - id: fleet
+  - id: elastic-agent
+---
+
+# Using certificate fingerprints [certificate-fingerprints]
+
+Certificate fingerprints provide an alternative to using certificate authority (CA) files when securing connections between {{agent}}, {{fleet-server}}, and {{es}}.
+
+:::{note}
+:applies_to: { serverless: ga, ess: ga }
+In {{ech}} deployments and {{serverless-short}} projects, you don't need to set certificate authorities or certificate fingerprints because Elastic always uses trusted certificates.
+:::
+
+## How certificate fingerprints work [how-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.
+
+::::{important}
+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 [fingerprint-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 [fingerprint-requirements-1]
+
+The certificate must be included in the certificate file that the server presents during the TLS handshake. For {{es}}, 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 [fingerprint-requirements-2]
+
+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 [fingerprint-requirements-3]
+
+The fingerprint must be a HEX-encoded SHA-256 hash with colons removed.
+
+## Choosing which certificate to use [choosing-certificate]
+
+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 {{es}} configuration:
+
+```yaml
+xpack.security.http.ssl.certificate: certs/server-intermediate2-intermediate1.pem
+xpack.security.http.ssl.certificate_authorities: ["certs/root-ca.pem"]
+```
+
+:::{note}
+This example shows {{es}} 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 [generate-fingerprint]
+
+Use this command to generate the SHA-256 fingerprint for the CA certificate:
+
+:::::{tab-set}
+::::{tab-item} Linux
+:sync: linux
+
+```bash
+openssl x509 -fingerprint -sha256 -noout -in ca.crt | \
+  awk -F"=" '{print $2}' | \
+  sed 's/://g'
+```
+::::
+
+::::{tab-item} macOS
+:sync: macos
+
+```bash
+openssl x509 -fingerprint -sha256 -noout -in ca.crt | \
+  awk -F"=" '{print $2}' | \
+  sed 's/://g'
+```
+::::
+
+::::{tab-item} Windows
+:sync: windows
+
+In PowerShell, run:
+
+```powershell
+(openssl x509 -fingerprint -sha256 -noout -in ca.crt) -replace '.*=', '' -replace ':', ''
+```
+
+:::{note}
+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 [fingerprint-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 \ <1>
+  --fleet-server-port=8220
+```
+
+1. Replace `INTERMEDIATE_CA1_FINGERPRINT` with the fingerprint value of the intermediate CA certificate.
+
+### Fleet UI configuration
+
+1. In {{kib}}, go to **{{fleet}} > Settings**.
+2. Under **Outputs**, edit your {{es}} output.
+3. In the **Elasticsearch CA trusted fingerprint** field, enter any CA certificate's fingerprint that's present in the certificate chain sent by {{es}}.
+
+::::{note}
+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-server}}s](/reference/fleet/secure-connections.md)
+* [Rotate SSL/TLS CA certificates](/reference/fleet/certificates-rotation.md)
+* [{{agent}} SSL configuration options](/reference/fleet/elastic-agent-ssl-configuration.md)

reference/fleet/certificates-rotation.md

@@ -190,9 +190,9 @@ To rotate a CA certificate on {{es}} for connections from {{agent}}:
 
 1. In {{fleet}} open the **Settings** tab.
 2. In the **Outputs** section, click the edit button for the {{es}} output that requires a certificate rotation.
-3. In the **Elasticsearch CA trusted fingerprint** field, add the new trusted fingerprint to use. This is the SHA-256 fingerprint (hash) of the certificate authority used to self-sign {{es}} certificates. This fingerprint will be used to verify self-signed certificates presented by {{es}}.
+3. In the **Elasticsearch CA trusted fingerprint** field, add the new trusted fingerprint to use. This is the SHA-256 fingerprint (hash) of a certificate authority that's present in the certificate chain {{es}} sends during the TLS handshake.
 
-    If this certificate is present in the chain during the handshake, it will be added to the `certificate_authorities` list and the handshake will continue normally.
+    When a certificate matching this fingerprint is found in the chain during the handshake, it will be added to the `certificate_authorities` list and the handshake will continue normally. For more information, refer to [Using certificate fingerprints](/reference/fleet/certificate-fingerprints.md).
 
     :::{image} images/certificate-rotation-agent-es.png
     :alt: Screen capture of the Edit Output UI: Elasticsearch CA trusted fingerprint

reference/fleet/elastic-agent-ssl-configuration.md

@@ -180,7 +180,7 @@ $$$client-ssl-options$$$
     **Default:** `full`
 
 `ssl.ca_trusted_fingerprint` $$$ssl.ca_trusted_fingerprint$$$
-:   (string) A HEX encoded SHA-256 of a CA certificate. If this certificate is present in the chain during the handshake, it will be added to the `certificate_authorities` list and the handshake will continue normally.
+:   (string) A HEX-encoded SHA-256 of a CA certificate that's present in the certificate chain the server sends during the TLS handshake. If this certificate is found in the chain, it'll be added to the `certificate_authorities` list and the handshake will continue normally.
 
     Example:
 

reference/fleet/es-output-settings.md

@@ -33,7 +33,7 @@ Specify these settings to send data over a secure connection to {{es}}. In the {
     Refer to the [{{fleet-server}}](/reference/fleet/fleet-server.md) documentation for default ports and other configuration details.
 
 **{{es}} CA trusted fingerprint** $$$es-trusted-fingerprint-yaml-setting$$$
-:   HEX encoded SHA-256 of a CA certificate. If this certificate is present in the chain during the handshake, it will be added to the `certificate_authorities` list and the handshake will continue normally. To learn more about trusted fingerprints, refer to the [{{es}} security documentation](/deploy-manage/deploy/self-managed/installing-elasticsearch.md).
+:   HEX-encoded SHA-256 of a CA certificate that's present in the certificate chain {{es}} sends during the TLS handshake. If this certificate is found in the chain, it'll be added to the `certificate_authorities` list and the handshake will continue normally. For more information, refer to [Using certificate fingerprints](/reference/fleet/certificate-fingerprints.md).
 
 **Proxy** $$$es-agent-proxy-output$$$
 :   Select a proxy URL for {{agent}} to connect to {{es}}. To learn about proxy configuration, refer to [Using a proxy server with {{agent}} and {{fleet}}](/reference/fleet/fleet-agent-proxy-support.md).