[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"
  }
]
----