elasticsearch/docs/reference/rest-api/security/ssl.asciidoc

[role="xpack"]
[[security-api-ssl]]
=== SSL certificate API
++++
<titleabbrev>SSL certificate</titleabbrev>
++++

.New API reference
[sidebar]
--
For the most up-to-date API details, refer to {api-es}/group/endpoint-security[Security APIs].
--

The `certificates` API enables you to retrieve information about the X.509
certificates that are used to encrypt communications in your {es} cluster.

[[security-api-ssl-request]]
==== {api-request-title}

`GET /_ssl/certificates`


[[security-api-ssl-prereqs]]
==== {api-prereq-title}

* If the {security-features} are enabled, you must have `monitor` cluster
privileges to use this API. For more information, see
<<security-privileges>>.

[[security-api-ssl-desc]]
==== {api-description-title}

For more information about how certificates are configured in conjunction with
Transport Layer Security (TLS), see
<<encrypt-internode-communication>>.

The API returns a list that includes certificates from all TLS contexts
including:

* 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.security.transport.ssl.truststore` and
`xpack.security.transport.ssl.certificate_authorities` settings. It also
includes certificates that are used for configuring server identity, such as
`xpack.security.http.ssl.keystore` and
`xpack.security.http.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 {es}.

NOTE: When a PKCS#11 token is configured as the truststore of the JRE, the API
will return all the certificates that are included in the PKCS#11 token
irrespectively to whether these are used in the {es} TLS configuration or not.

If {es} 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.

[[security-api-ssl-response-body]]
==== {api-response-body-title}

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) Indicates whether {es} has access to the private
key for this certificate.
`expiry`:: (string) The ISO formatted date of the certificate's expiry
(not-after) date.
`issuer`:: (string) The Distinguished Name of the certificate's issuer.

[[security-api-ssl-example]]
==== {api-examples-title}

The following example provides information about the certificates on a single
node of {es}:

[source,console]
--------------------------------------------------
GET /_ssl/certificates
--------------------------------------------------

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"
  }
]
----
// NOTCONSOLE