Keystores and Truststores

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

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 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 Apigee free trial cert and key in the Cloud

For all Cloud free trial organizations, Apigee provides a free trial cert and key. Free trial organizations can use this default cert and key to test APIs, and even push APIs to production.

Free trial organizations cannot use their own certs and keys. They have to use the Apigee-supplied cert and key. You can only use your own certs and keys after transitioning to a paid account.

An Edge for the Cloud customer with a paid account can create a virtual hosts in an organization. All virtual hosts are required to support TLS, meaning you must have a cert and key and upload them to a keystore. However, if you have a paid account and do not yet have a TLS cert and key, you can create a virtual host that uses the Apigee free trial cert and key. See Configuring virtual hosts for the Cloud for more.

You cannot use the Apigee-supplied cert in two-way TLS with the backend. To configure two-way TLS with the backend, you have to upload your own certs after transitioning to a paid account.

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: