Add support for certificates in PKCS#12 (P12) key stores (#53810) (#54383)

Kibana now supports the usage of PKCS#12 (P12) key stores and trust stores for certificates and keys.

Author: jportner

docs/development/core/server/kibana-plugin-server.kibanaresponsefactory.md

@@ -10,7 +10,7 @@ Set of helpers used to create `KibanaResponse` to form HTTP response on an incom
 
 ```typescript
 kibanaResponseFactory: {
-    custom: <T extends string | Error | Record<string, any> | Buffer | Stream | {
+    custom: <T extends string | Error | Buffer | Stream | Record<string, any> | {
         message: string | Error;
         attributes?: Record<string, any> | undefined;
     } | undefined>(options: CustomHttpResponseOptions<T>) => KibanaResponse<T>;
@@ -21,9 +21,9 @@ kibanaResponseFactory: {
     conflict: (options?: ErrorHttpResponseOptions) => KibanaResponse<ResponseError>;
     internalError: (options?: ErrorHttpResponseOptions) => KibanaResponse<ResponseError>;
     customError: (options: CustomHttpResponseOptions<ResponseError>) => KibanaResponse<ResponseError>;
-    redirected: (options: RedirectResponseOptions) => KibanaResponse<string | Record<string, any> | Buffer | Stream>;
-    ok: (options?: HttpResponseOptions) => KibanaResponse<string | Record<string, any> | Buffer | Stream>;
-    accepted: (options?: HttpResponseOptions) => KibanaResponse<string | Record<string, any> | Buffer | Stream>;
+    redirected: (options: RedirectResponseOptions) => KibanaResponse<string | Buffer | Stream | Record<string, any>>;
+    ok: (options?: HttpResponseOptions) => KibanaResponse<string | Buffer | Stream | Record<string, any>>;
+    accepted: (options?: HttpResponseOptions) => KibanaResponse<string | Buffer | Stream | Record<string, any>>;
     noContent: (options?: HttpResponseOptions) => KibanaResponse<undefined>;
 }
 ```

docs/settings/security-settings.asciidoc

@@ -45,7 +45,7 @@ if this setting isn't the same for all instances of {kib}.
 
 `xpack.security.secureCookies`::
 Sets the `secure` flag of the session cookie. The default value is `false`. It
-is set to `true` if `server.ssl.certificate` and `server.ssl.key` are set. Set
+is automatically set to `true` if `server.ssl.enabled` is set to `true`. Set
 this to `true` if SSL is configured outside of {kib} (for example, you are
 routing requests through a load balancer or proxy).
 

docs/setup/settings.asciidoc

@@ -82,31 +82,52 @@ Elasticsearch nodes immediately following a connection fault.
 `elasticsearch.sniffOnStart:`:: *Default: false* Attempt to find other
 Elasticsearch nodes on startup.
 
-`elasticsearch.ssl.alwaysPresentCertificate:`:: *Default: false* Controls
-whether to always present the certificate specified by
-`elasticsearch.ssl.certificate` when requested. This applies to all requests to
-Elasticsearch, including requests that are proxied for end-users. Setting this
-to `true` when Elasticsearch is using certificates to authenticate users can
-lead to proxied requests for end-users being executed as the identity tied to
-the configured certificate.
-
-`elasticsearch.ssl.certificate:` and `elasticsearch.ssl.key:`:: Optional
-settings that provide the paths to the PEM-format SSL certificate and key files.
-These files are used to verify the identity of Kibana to Elasticsearch and are
-required when `xpack.ssl.verification_mode` in Elasticsearch is set to either
-`certificate` or `full`.
-
-`elasticsearch.ssl.certificateAuthorities:`:: Optional setting that enables you
-to specify a list of paths to the PEM file for the certificate authority for
-your Elasticsearch instance.
-
-`elasticsearch.ssl.keyPassphrase:`:: The passphrase that will be used to decrypt
-the private key. This value is optional as the key may not be encrypted.
-
-`elasticsearch.ssl.verificationMode:`:: *Default: full* Controls the
-verification of certificates presented by Elasticsearch. Valid values are `none`,
-`certificate`, and `full`. `full` performs hostname verification, and
-`certificate` does not.
+`elasticsearch.ssl.alwaysPresentCertificate:`:: *Default: false* Controls whether to always present the certificate specified by
+`elasticsearch.ssl.certificate` or `elasticsearch.ssl.keystore.path` when requested. This setting applies to all requests to Elasticsearch,
+including requests that are proxied for end users. Setting this to `true` when Elasticsearch is using certificates to authenticate users can
+lead to proxied requests for end users being executed as the identity tied to the configured certificate.
+
+`elasticsearch.ssl.certificate:` and `elasticsearch.ssl.key:`:: Paths to a PEM-encoded X.509 certificate and its private key, respectively.
+When `xpack.security.http.ssl.client_authentication` in Elasticsearch is set to `required` or `optional`, the certificate and key are used
+to prove Kibana's identity when it makes an outbound request to your Elasticsearch cluster.
++
+--
+NOTE: These settings cannot be used in conjunction with `elasticsearch.ssl.keystore.path`.
+--
+
+`elasticsearch.ssl.certificateAuthorities:`:: Paths to one or more PEM-encoded X.509 certificates. These certificates may consist of a root
+certificate authority (CA), and one or more intermediate CAs, which make up a trusted certificate chain for Kibana. This chain is used to
+establish trust when Kibana creates an SSL connection with your Elasticsearch cluster. In addition to this setting, trusted certificates may
+be specified via `elasticsearch.ssl.keystore.path` and/or `elasticsearch.ssl.truststore.path`.
+
+`elasticsearch.ssl.keyPassphrase:`:: The passphrase that will be used to decrypt the private key that is specified via
+`elasticsearch.ssl.key`. This value is optional, as the key may not be encrypted.
+
+`elasticsearch.ssl.keystore.path:`:: Path to a PKCS #12 file that contains an X.509 certificate with its private key. When
+`xpack.security.http.ssl.client_authentication` in Elasticsearch is set to `required` or `optional`, the certificate and key are used to
+prove Kibana's identity when it makes an outbound request to your Elasticsearch cluster. If the file contains any additional certificates,
+those will be used as a trusted certificate chain for your Elasticsearch cluster. This chain is used to establish trust when Kibana creates
+an SSL connection with your Elasticsearch cluster. In addition to this setting, trusted certificates may be specified via
+`elasticsearch.ssl.certificateAuthorities` and/or `elasticsearch.ssl.truststore.path`.
++
+--
+NOTE: This setting cannot be used in conjunction with `elasticsearch.ssl.certificate` or `elasticsearch.ssl.key`.
+--
+
+`elasticsearch.ssl.keystore.password:`:: The password that will be used to decrypt the key store and its private key. If your key store has
+no password, leave this unset. If your key store has an empty password, set this to `""`.
+
+`elasticsearch.ssl.truststore.path:`:: Path to a PKCS #12 trust store that contains one or more X.509 certificates. This may consist of a
+root certificate authority (CA) and one or more intermediate CAs, which make up a trusted certificate chain for your Elasticsearch cluster.
+This chain is used to establish trust when Kibana creates an SSL connection with your Elasticsearch cluster. In addition to this setting,
+trusted certificates may be specified via `elasticsearch.ssl.certificateAuthorities` and/or `elasticsearch.ssl.keystore.path`.
+
+`elasticsearch.ssl.truststore.password:`:: The password that will be used to decrypt the trust store. If your trust store has no password,
+leave this unset. If your trust store has an empty password, set this to `""`.
+
+`elasticsearch.ssl.verificationMode:`:: *Default: full* Controls the verification of certificates presented by Elasticsearch. Valid values
+are `none`, `certificate`, and `full`. `full` performs hostname verification and `certificate` does not. This setting is used only when
+traffic to Elasticsearch is encrypted, which is specified by using the HTTPS protocol in `elasticsearch.hosts`.
 
 `elasticsearch.startupTimeout:`:: *Default: 5000* Time in milliseconds to wait
 for Elasticsearch at Kibana startup before retrying.
@@ -330,11 +351,19 @@ are rewritten by your reverse proxy.
 `server.socketTimeout:`:: *Default: "120000"* The number of milliseconds to wait before closing an
 inactive socket.
 
-`server.ssl.certificate:` and `server.ssl.key:`:: Paths to the PEM-format SSL
-certificate and SSL key files, respectively.
+`server.ssl.certificate:` and `server.ssl.key:`:: Paths to a PEM-encoded X.509 certificate and its private key, respectively. These are used
+when enabling SSL for inbound requests from web browsers to the Kibana server.
++
+--
+NOTE: These settings cannot be used in conjunction with `server.ssl.keystore.path`.
+--
 
-`server.ssl.certificateAuthorities:`:: List of paths to PEM encoded certificate
-files that should be trusted.
+`server.ssl.certificateAuthorities:`:: Paths to one or more PEM-encoded X.509 certificates. These certificates may consist of a root
+certificate authority (CA) and one or more intermediate CAs, which make up a trusted certificate chain for Kibana. This chain is used when a
+web browser creates an SSL connection with the Kibana server; the certificate chain is sent to the browser along with the end-entity
+certificate to establish trust. This chain is also used to determine whether client certificates should be trusted when PKI authentication
+is enabled. In addition to this setting, trusted certificates may be specified via `server.ssl.keystore.path` and/or
+`server.ssl.truststore.path`.
 
 `server.ssl.cipherSuites:`::
 *Default: ECDHE-RSA-AES128-GCM-SHA256, ECDHE-ECDSA-AES128-GCM-SHA256, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-ECDSA-AES256-GCM-SHA384, DHE-RSA-AES128-GCM-SHA256, ECDHE-RSA-AES128-SHA256, DHE-RSA-AES128-SHA256, ECDHE-RSA-AES256-SHA384, DHE-RSA-AES256-SHA384, ECDHE-RSA-AES256-SHA256, DHE-RSA-AES256-SHA256, HIGH,!aNULL, !eNULL, !EXPORT, !DES, !RC4, !MD5, !PSK, !SRP, !CAMELLIA*.
@@ -345,12 +374,36 @@ https://www.openssl.org/docs/man1.0.2/apps/ciphers.html#CIPHER-LIST-FORMAT[OpenS
 connections. Valid values are `required`, `optional`, and `none`. `required` forces a client to present a certificate, while `optional`
 requests a client certificate but the client is not required to present one.
 
-`server.ssl.enabled:`:: *Default: "false"* Enables SSL for outgoing requests
-from the Kibana server to the browser. When set to `true`,
-`server.ssl.certificate` and `server.ssl.key` are required.
+`server.ssl.enabled:`:: *Default: "false"* Enables SSL for inbound requests from the browser to the Kibana server. When set to `true`, a
+certificate and private key must be provided. These can be specified via `server.ssl.keystore.path` or the combination of
+`server.ssl.certificate` and `server.ssl.key`.
+
+`server.ssl.keyPassphrase:`:: The passphrase that will be used to decrypt the private key that is specified via `server.ssl.key`. This value
+is optional, as the key may not be encrypted.
+
+`server.ssl.keystore.path:`:: Path to a PKCS #12 file that contains an X.509 certificate with its private key. These are used when enabling
+SSL for inbound requests from web browsers to the Kibana server. If the file contains any additional certificates, those will be used as a
+trusted certificate chain for Kibana. This chain is used when a web browser creates an SSL connection with the Kibana server; the
+certificate chain is sent to the browser along with the end-entity certificate to establish trust. This chain is also used to determine
+whether client certificates should be trusted when PKI authentication is enabled. In addition to this setting, trusted certificates may be
+specified via `server.ssl.certificateAuthorities` and/or `server.ssl.truststore.path`.
++
+--
+NOTE: This setting cannot be used in conjunction with `server.ssl.certificate` or `server.ssl.key`.
+--
+
+`server.ssl.keystore.password:`:: The password that will be used to decrypt the key store and its private key. If your key store has no
+password, leave this unset. If your key store has an empty password, set this to `""`.
+
+`server.ssl.truststore.path:`:: Path to a PKCS #12 trust store that contains one or more X.509 certificates. These certificates may consist
+of a root certificate authority (CA) and one or more intermediate CAs, which make up a trusted certificate chain for Kibana. This chain is
+used when a web browser creates an SSL connection with the Kibana server; the certificate chain is sent to the browser along with the
+end-entity certificate to establish trust. This chain is also used to determine whether client certificates should be trusted when PKI
+authentication is enabled. In addition to this setting, trusted certificates may be specified via `server.ssl.certificateAuthorities` and/or
+`server.ssl.keystore.path`.
 
-`server.ssl.keyPassphrase:`:: The passphrase that will be used to decrypt the
-private key. This value is optional as the key may not be encrypted.
+`server.ssl.truststore.password:`:: The password that will be used to decrypt the trust store. If your trust store has no password, leave
+this unset. If your trust store has an empty password, set this to `""`.
 
 `server.ssl.redirectHttpFromPort:`:: Kibana will bind to this port and redirect
 all http requests to https over the port configured as `server.port`.

docs/user/monitoring/monitoring-kibana.asciidoc

@@ -96,7 +96,8 @@ used when {kib} sends monitoring data to the production cluster.
 .. Configure {kib} to encrypt communications between the {kib} server and the
 production cluster. This set up involves generating a server certificate and
 setting `server.ssl.*` and `elasticsearch.ssl.certificateAuthorities` settings
-in the `kibana.yml` file on the {kib} server. For example:
+in the `kibana.yml` file on the {kib} server. For example, using a PEM-formatted
+certificate and private key:
 +
 --
 [source,yaml]
@@ -105,14 +106,19 @@ server.ssl.key: /path/to/your/server.key
 server.ssl.certificate: /path/to/your/server.crt
 --------------------------------------------------------------------------------
 
-If you are using your own certificate authority to sign certificates, specify
-the location of the PEM file in the `kibana.yml` file:
+If you are using your own certificate authority (CA) to sign certificates,
+specify the location of the PEM file in the `kibana.yml` file:
 
 [source,yaml]
 --------------------------------------------------------------------------------
 elasticsearch.ssl.certificateAuthorities: /path/to/your/cacert.pem
 --------------------------------------------------------------------------------
 
+NOTE: Alternatively, the PKCS #12 format can be used for the Kibana certificate
+and key, along with any included CA certificates, by setting
+`server.ssl.keystore.path`. If your CA certificate chain is in a separate trust
+store, you can also use `server.ssl.truststore.path`.
+
 For more information, see <<using-kibana-with-security>>.
 --
 

docs/user/security/authentication/index.asciidoc

@@ -67,6 +67,9 @@ server.ssl.clientAuthentication: required
 xpack.security.authc.providers: [pki]
 --------------------------------------------------------------------------------
 
+NOTE: Trusted CAs can also be specified in a PKCS #12 keystore bundled with your Kibana server certificate/key using
+`server.ssl.keystore.path` or in a separate trust store using `server.ssl.truststore.path`.
+
 PKI support in {kib} is designed to be the primary (or sole) authentication method for users of that {kib} instance. However, you can configure both PKI and Basic authentication for the same {kib} instance:
 
 [source,yaml]