Keystores and Truststores

To configure functionality that relies on public key infrastructure (TLS) you need to create keystores and truststores that provide the necessary keys and digital certificates.

Learn more:

About keystores and truststores

Keystores and truststores define repositories of security certificates used for TLS encryption. The main difference between the two is where they are used in the TLS handshaking process:

  • A keystore contains a TLS certificate and private key used to identify the entity during TLS handshaking.

    In one-way TLS, when a client connects to the TLS endpoint on the server, the server's keystore presents the server's certificate (public cert) to the client. The client then validates that certificate with a Certificate Authority (CA), such as Symantec or VeriSign.

    In two-way TLS, both the client and the server maintain a keystore with their own cert and private key used for mutual authentication.
  • A truststore contains certificates used to verify certificates received as part of TLS handshaking.

    In one-way TLS, a truststore is not required if the cert is signed by a valid CA. If the certificate received by a TLS client is signed by a valid CA, then the client makes a request to the CA to authenticate the certificate. A TLS client typically uses a truststore to validate self-signed certificates received from the TLS server, or certificates that are not signed by a trusted CA. In this scenario, the client populates its truststore with certificates that it trusts. Then, when the client receives a server certificate, the incoming certificate is validated against the certificates in its truststore.

    For example, a TLS client connects to a TLS server where the server uses a self-signed certificate. Because it is a self-signed certificate, the client cannot validate it with a CA. Instead, the client preloads the server's self-signed certificate into its truststore. Then, when the client attempts to connect to the server, the client uses the its truststore to validate the certificate received from the server.

    For two-way TLS, both the TLS client and the TLS server can use a truststore. A truststore is required when performing two-way TLS when Edge acts as the TLS server.

Certificates can be issued by a certificate authority (CA), or they can be self-signed by the private key that you generate. If you have access to a CA, follow instructions provided by your CA for generating keys and issuing certificates. If you do not have access to a CA, you can generate a self-signed certificate using one of the many publicly available free tools, such as openssl.

Using the default Apigee keystore and cert in a free trial organization in the Cloud

For all Cloud free trial organizations, Apigee creates a default keystore and alias. You should see a keystore named freetrial that contains an alias named freetrial. This alias contains the default certificate that Apigee provides for free trial accounts.

Free trial organizations can use this default keystore and alias to test APIs, and even push APIs to production.

After you transition to a paid account,you can:

  • Create your own keystores
  • Create your own truststores
  • Upload your own certs and keys
  • Configure your APIs to use your keystores/truststore/certs/keys

Differences between Cloud and Private Cloud

The Cloud version of Edge and Private Cloud versions 4.18.01 and later have expanded capabilities for working with keystores and truststores that are not available in Private Cloud version 4.17.09 and earlier. For example, you can:

  • Use the Edge UI to create keystores and truststores
  • Use a new set of APIs to manage keystores and truststores

When working with keystores and truststores, make sure you use the correct section of the documentation:

Send feedback about...

Apigee Docs