[DOCS] Added SSL certificates API (elastic/x-pack-elasticsearch#3136)

Original commit: elastic/x-pack-elasticsearch@62cb574fcf

docs/build.gradle

@@ -19,6 +19,7 @@ buildRestTests.expectedUnconvertedCandidates = [
         'en/ml/functions/time.asciidoc',
         'en/ml/aggregations.asciidoc',
         'en/ml/customurl.asciidoc',
+        'en/rest-api/security/ssl.asciidoc',
         'en/rest-api/security/users.asciidoc',
         'en/rest-api/security/tokens.asciidoc',
         'en/rest-api/watcher/put-watch.asciidoc',

docs/en/rest-api/security.asciidoc

@@ -4,17 +4,19 @@
 
 * <<security-api-authenticate>>
 * <<security-api-clear-cache>>
-* <<security-api-users>>
+* <<security-api-privileges>>
 * <<security-api-roles>>
 * <<security-api-role-mapping>>
-* <<security-api-privileges>>
+* <<security-api-ssl>>
 * <<security-api-tokens>>
+* <<security-api-users>>
 
 include::security/authenticate.asciidoc[]
 include::security/change-password.asciidoc[]
 include::security/clear-cache.asciidoc[]
-include::security/users.asciidoc[]
+include::security/privileges.asciidoc[]
 include::security/roles.asciidoc[]
 include::security/role-mapping.asciidoc[]
-include::security/privileges.asciidoc[]
+include::security/ssl.asciidoc[]
 include::security/tokens.asciidoc[]
+include::security/users.asciidoc[]

docs/en/rest-api/security/ssl.asciidoc

@@ -0,0 +1,111 @@
+[role="xpack"]
+[[security-api-ssl]]
+=== SSL Certificate API
+
+The `certificates` API enables you to retrieve information about the X.509
+certificates that are used to encrypt communications in your {es} cluster.
+
+==== Request
+
+`GET /_xpack/ssl/certificates`
+
+
+==== Description
+
+For more information about how certificates are configured in conjunction with
+Transport Layer Security (TLS), see
+{xpack-ref}/ssl-tls.html[Setting up SSL/TLS on a cluster].
+
+The API returns a list that includes certificates from all TLS contexts
+including:
+
+* {xpack} default TLS settings
+* Settings for transport and HTTP interfaces
+* TLS settings that are used within authentication realms
+* TLS settings for remote monitoring exporters
+
+The list includes certificates that are used for configuring trust, such as
+those configured in the `xpack.ssl.truststore` and
+`xpack.ssl.certificate_authorities` settings. It also includes certificates that
+that are used for configuring server identity, such as `xpack.ssl.keystore` and
+`xpack.ssl.certificate` settings.
+
+The list does not include certificates that are sourced from the default SSL
+context of the Java Runtime Environment (JRE), even if those certificates are in
+use within {xpack}.
+
+If {xpack} is configured to use a keystore or truststore, the API output
+includes all certificates in that store, even though some of the certificates
+might not be in active use within the cluster.
+
+
+==== Results
+
+The response is an array of objects, with each object representing a
+single certificate. The fields in each object are:
+
+`path`:: (string) The path to the certificate, as configured in the
+`elasticsearch.yml` file.
+`format`:: (string) The format of the file. One of: `jks`, `PKCS12`, `PEM`.
+`alias`:: (string) If the path refers to a container file (a jks keystore, or a
+  PKCS#12 file), the alias of the certificate. Otherwise, null.
+`subject_dn`:: (string) The Distinguished Name of the certificate's subject.
+`serial_number`:: (string) The hexadecimal representation of the certificate's
+serial number.
+`has_private_key`:: (boolean) If {xpack} has access to the private key for this
+certificate, this field has a value of `true`.
+`expiry`:: (string) The ISO formatted date of the certificate's expiry
+(not-after) date.
+
+==== Authorization
+
+If {security} is enabled, you must have `monitor` cluster privileges to use this
+API. For more information, see
+{xpack-ref}/security-privileges.html[Security Privileges].
+
+
+==== Examples
+
+The following example provides information about the certificates on a single
+node of {es}:
+
+[source,js]
+--------------------------------------------------
+GET /_xpack/ssl/certificates
+--------------------------------------------------
+// CONSOLE
+// TEST[skip:todo]
+
+The API returns the following results:
+[source,js]
+----
+[
+  {
+    "path": "certs/elastic-certificates.p12",
+    "format": "PKCS12",
+    "alias": "instance",
+    "subject_dn": "CN=Elastic Certificate Tool Autogenerated CA",
+    "serial_number": "a20f0ee901e8f69dc633ff633e5cd5437cdb4137",
+    "has_private_key": false,
+    "expiry": "2021-01-15T20:42:49.000Z"
+  },
+  {
+    "path": "certs/elastic-certificates.p12",
+    "format": "PKCS12",
+    "alias": "ca",
+    "subject_dn": "CN=Elastic Certificate Tool Autogenerated CA",
+    "serial_number": "a20f0ee901e8f69dc633ff633e5cd5437cdb4137",
+    "has_private_key": false,
+    "expiry": "2021-01-15T20:42:49.000Z"
+  },
+  {
+    "path": "certs/elastic-certificates.p12",
+    "format": "PKCS12",
+    "alias": "instance",
+    "subject_dn": "CN=instance",
+    "serial_number": "fc1905e1494dc5230218d079c47a617088f84ce0",
+    "has_private_key": true,
+    "expiry": "2021-01-15T20:44:32.000Z"
+  }
+]
+----