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.
- About TLS/SSL
- Using TLS with Edge
- About virtual hosts
- Creating keystores and truststore using the Edge UI
- Creating keystores and truststore using the Edge management API
- Create keystores and truststores for the Private Cloud version 4.17.09 and earlier
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 freetrial cert and key 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
Free trial organizations can use this default keystore and alias to test APIs, and even push
APIs to production.
Free trial organizations cannot use their own certs. They have to use the default keystore and Apigee-supplied cert. You can only use your own certs 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 freetrial 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: