Document exporting certificates from PKCS#12 keystores (#1403)

* Document exporting certificates from PKCS#12 keystores

* Reference the bundle file name containing the CA cert/key (elastic-stack-ca.p12)

* Adjust position of the PKCS12 conversion example and alter section title

* Add `-nokeys` to CA cert export command

* Adjust private CA wording.

Co-authored-by: Quentin Pradet <[email protected]>

docs/command_line_reference.rst

@@ -674,7 +674,7 @@ Enable it with ``use_ssl:true``.
 **TLS/SSL Certificate Verification**
 
 Server certificate verification is controlled with the ``verify_certs`` boolean. The default value is `true`. To disable use ``verify_certs:false``.
-If ``verify_certs:true``, Rally will attempt to verify the certificate provided by Elasticsearch. If they are private certificates, you will also need to supply the private CA certificate using ``ca_certs:'/path/to/cacert.pem'``.
+If ``verify_certs:true``, Rally will attempt to verify the certificate provided by Elasticsearch. If this certificate is signed by a private certificate authority (CA), you will also need to supply that CA in PEM format using ``ca_certs:'/path/to/cacert.pem'``.
 
 You can also optionally present client certificates, e.g. if Elasticsearch has been configured with ``xpack.security.http.ssl.client_authentication: required`` (see also `Elasticsearch HTTP TLS/SSL settings <https://www.elastic.co/guide/en/elasticsearch/reference/current/security-settings.html#http-tls-ssl-settings>`_).
 Client certificates can be presented regardless of the ``verify_certs`` setting, but it's strongly recommended to always verify the server certificates.
@@ -685,6 +685,28 @@ Client certificates can be presented regardless of the ``verify_certs`` setting,
 * Enable SSL, verify server certificates using private CA: ``--client-options="use_ssl:true,verify_certs:true,ca_certs:'/path/to/cacert.pem'"``
 * Enable SSL, verify server certificates using private CA, present client certificates: ``--client-options="use_ssl:true,verify_certs:true,ca_certs:'/path/to/cacert.pem',client_cert:'/path/to/client_cert.pem',client_key:'/path/to/client_key.pem'"``
 
+**Converting PKCS#12 Files to PEM Format**
+
+Rally supports PEM format for CA and client certificates. Certificates in PKCS#12 formatted keystores will need to be exported to PEM format in order for Rally to use them. The ``openssl`` command can be used to export certificates from a PKCS#12 keystore. In the following example, PKCS#12 file ``elastic-stack-ca.p12`` is generated by the Elasticsearch ``elasticsearch-certutil ca`` command and contains only the CA certificate and private key.
+
+* Export CA certificate:
+
+ ::
+
+   openssl pkcs12 -in elastic-stack-ca.p12 -nokeys -out cacert.pem
+
+* Export a node private key for client authentication:
+
+ ::
+
+   openssl pkcs12 -in elastic-certificates.p12 -nocerts -nodes -out client_key.pem
+
+* Export the node certificate for client authentication:
+
+ ::
+
+   openssl pkcs12 -in elastic-certificates.p12 -nokeys -clcerts -out client_cert.pem
+
 **Static Responses**
 
 Define a JSON file containing a list of objects with the following properties: