PingDirectory

Understanding key and trust stores

A key store, or keystore, is a type of database for holding certificates.

Key stores come in multiple forms, but the most common include:

  • A file using the Java-specific Java Key Store (JKS) format.

  • A file using the standard PKCS #12 format, as described in RFC 7292.

  • A collection of files that hold certificates and private keys, typically in PEM or DER format.

  • A hardware security module (HSM) that makes the certificate information through an interface like PKCS #11.

The PingDirectory server supports file-based key stores using the Java KeyStore (JKS) and PKCS #12 formats and also hardware security modules that are accessible through PKCS #11. It does not directly support a key store format that is comprised of individual certificate and private key files, but the manage-certificates tool can be used to import these files into a JKS or PKCS #12 key store.

A key store is a collection of entries, each of which is identified by an alias, sometimes called a nickname. Key stores can have three types of entries:

Private key entries

Contain both a certificate chain and a private key. When a server is performing TLS negotiation, it uses a private key entry to obtain the certificate chain to present to the client, and it can use the private key from that same entry for its key agreement processing. Similarly, if a client presents its own certificate chain to the server, then it uses a private key entry for that.

Trusted certificate entries

Contain a single certificate without a private key. As the name implies, these entries are primarily intended to be used in the course of determining whether to trust a certificate chain that has been presented during TLS negotiation.

Secret key entries

Contain just a secret key without any associated certificate. These types of entries are not used for TLS processing, but rather hold symmetric encryption keys or other types of secrets.

The contents of a key store are protected with a password or passphrase, sometimes called a PIN. In some cases, like with JKS key stores, some of the content can be accessible without a password, and a password might only be required when trying to access private keys or secret keys. In other cases, like with PKCS #12 key stores, you might need a password for any interaction with the key store.

Further, private keys can also be protected with an additional password. This is often the same as the key store password, but it can also be different. This could be useful, for example, if a single key store is shared for multiple purposes, and merely having access to the key store isn’t sufficient to have access to all of the data that it contains.

A trust store, or truststore, is another name for a key store that is primarily intended for use in determining whether to trust a certificate chain that has been presented. Trust stores generally contain just trusted certificate entries, but there is no requirement for that to be the case.

Java runtime environments typically include a default trust store, often jre/lib/security/cacerts or lib/security/cacerts, that is pre-populated with several widely trusted certification authority certificates. When presented with a certificate signed by one of these authorities, this default trust store could allow the certificate to be trusted without any additional configuration. When presented with a self-signed certificate, or when presented with a certificate signed by an issuer that is not in this default trust store, such as a private corporate CA, a separate trust store is needed.