From a4fad02d9a8977cb434077a312f2a4369ada9dfe Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Wed, 17 Jan 2018 08:14:02 -0800 Subject: [PATCH] [DOCS] Added SSL certificates API (elastic/x-pack-elasticsearch#3136) Original commit: elastic/x-pack-elasticsearch@62cb574fcf2a1ecd762d6d05b38c68acba306aea --- docs/build.gradle | 1 + docs/en/rest-api/security.asciidoc | 10 ++- docs/en/rest-api/security/ssl.asciidoc | 111 +++++++++++++++++++++++++ 3 files changed, 118 insertions(+), 4 deletions(-) create mode 100644 docs/en/rest-api/security/ssl.asciidoc diff --git a/docs/build.gradle b/docs/build.gradle index 11880216ddf..f6835aa0c8a 100644 --- a/docs/build.gradle +++ b/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', diff --git a/docs/en/rest-api/security.asciidoc b/docs/en/rest-api/security.asciidoc index d80c7c78528..227e343192a 100644 --- a/docs/en/rest-api/security.asciidoc +++ b/docs/en/rest-api/security.asciidoc @@ -4,17 +4,19 @@ * <> * <> -* <> +* <> * <> * <> -* <> +* <> * <> +* <> 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[] diff --git a/docs/en/rest-api/security/ssl.asciidoc b/docs/en/rest-api/security/ssl.asciidoc new file mode 100644 index 00000000000..f7a40c6d876 --- /dev/null +++ b/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" + } +] +----