You're viewing Apigee Edge documentation.
Go to the
Apigee X documentation. info
Transport Layer Security (TLS), whose predecessor is Secure Sockets Layer (SSL), is the standard security technology
for establishing an encrypted link between a web server and a web client, such as a browser or an
app. An encrypted link ensures that all data passing between the server and the client remains
private. To use TLS, a client makes a secure request to the server by using the encrypted
HTTPS protocol, instead of the unencrypted HTTP protocol.
Edge supports one-way TLS and two-way TLS in both a cloud and an on-premises deployment (for supported versions of TLS see Supported software and supported versions). One-way TLS enables the TLS client to verify the identity of the TLS server. For example, an app running on an Android phone (client) can verify the identity of Edge APIs (server).
Apigee also supports a stronger form of authentication using two-way, or client, TLS. You typically implement two-way TLS to enhance security end-to-end and protect your data from client attacks such as client spoofing or man-in-the middle attacks. In two-way TLS, the client verifies the identity of the server followed by the server verifying the identity of the client.
TLS terminology
You should be familiar with the following important terms and concepts before configuring TLS:
|
Term |
Definition |
|---|---|
|
CA |
Certificate Authority. A trusted entity, such as Symantec or VeriSign, used to issue certs and to validate the authenticity of a cert. One type of cert, called a self-signed cert, does not require a CA. |
|
Certificate chain |
Often you will not have a certificate signed by your CA's root private key. Instead, you have your cert along with one or more intermediate certs that form a chain. The last intermediate cert in the chain is typically signed by the CA's root private key. |
|
CSR |
Certificate Signing Request. A CSR is a file generated on the TLS server based on the private key. The CSR contains the public key and other information such as the organization's name, location, and domain name. The CA signs the CSR to create a TLS certificate. You typically generate a CSR when you have an expired cert and want to renew it. |
| DER |
Distinguished Encoding Rules. The DER format is a binary form of a certificate instead
of the ASCII PEM format. It sometimes has a file extension of .der but it often has a
file extension of .cer. The only way to tell the difference between a DER .cer file and
a PEM .cer file is to open the file in a text editor and look for the |
| Key alias |
A key alias uniquely identifies a keystore entry (TLS certificate and corresponding private key) in the keystore.
In Apigee Edge |
|
Keystore |
A keystore is a repository which contains one or more TLS certificates and a corresponding private key which is used to identify the entity during a TLS handshake between a Client and Server. On the northbound connection, the Router acts as the server and its certificate is stored in the keystore in Apigee Edge. On the southbound connection, the Message Processor acts as the client and the backend server acts as the server. The client certificate and its private key are stored in the keystore in Apigee Edge. |
| P7B |
The PKCS #7 or P7B format is usually stored in Base64 ASCII format and has a file
extension of .p7b or .p7c. P7B certificates contain |
|
PEM |
The Privacy Enhanced Mail (PEM) format is a text-based ASCII format that is a Base64
encoding of the binary Distinguished Encoding Rules (DER) format. PEM certificates
can be opened in any Text Editor and the actual certificate content is delimited
between the
It complies with the X.509 format for storing a certificate, certificate chain, or private key. If your cert or private key is not defined by a PEM file, you can convert it to a PEM file by using utilities such as OpenSSL. |
| PKCS #12/PFX | The PKCS #12 or PFX format is a binary format for storing the server certificate, any intermediate certificates, and the private key in one encryptable file. PFX files usually have extensions such as .pfx and .p12. PFX files are typically used on Windows machines to import and export certificates and private keys. |
|
Private key |
Used on the TLS server to decrypt data. Only the TLS server has the private key—it is not shared with TLS clients. |
|
Public key |
Used to encrypt data sent from a TLS client to a TLS server. The public key is included in the cert. All TLS clients have a copy of the server's public key. |
| References | References provide a level of indirection for keystores; therefore, keystore changes do not require a virtual host update as long as the same reference and key alias are maintained. This empowers you to self-serve these changes and reduce the dependencies with the Apigee Support team. |
|
Self-signed certificate |
A certificate that is not signed by a trusted CA. The issuer and the subject are identical; they are signed with the private key matching the public key they contain. |
|
SNI |
Server Name Indication. Allows multiple HTTPS targets to be served off the same IP address and port without requiring those targets to use the same certificate. |
|
TLS certificate |
A digital file that identifies an entity in a TLS transaction. A certificate, or cert, can be used to identify the TLS server and TLS client, depending on the TLS configuration. |
|
Truststore |
Contains trusted certificates on a TLS client used to validate a TLS server's certificate presented to the client. These certificates are typically self-signed certificates or certificates that are not signed by a trusted CA. On the northbound connection, the client application’s certificates are stored in the truststore in Apigee Edge. This is required only if you have configured a two-way TLS between the client and Apigee. On the southbound connection, the backend server’s certificates are stored in the truststore in Apigee Edge. This is required if you would like to verify the backend’s certificate in Apigee Edge in one-way or two-way TLS communication between Apigee Edge and the backend server. Apigee Edge does not have a separate truststore object. Therefore, the truststores are created as a keystore object, but referenced as truststore wherever it is used (for example, in virtual host, target endpoints, target servers, etc.). |
| Virtual host |
Virtual host represents the Apigee API endpoint for client applications. It is an entity which aids in hosting multiple domain names ( with separate handling of each name) on a single server (or pool of servers). This allows one server to share its resources, such as memory and processor cycles, without requiring all services provided to use the same host name. A virtual host can serve either HTTP or HTTPS (SSL-enabled) traffic. An SSL-enabled virtual host can be configured in one-way or two-way TLS mode. It is configured with the following:
|
One-way TLS/SSL
The following figure shows TLS/SSL handshaking for one-way authentication between a TLS client and TLS server:
In a one-way TLS configuration, the handshake is as follows:
- The client issues a session request to the server.
- The server responds with a certificate, which contains its public key. This certificate comes from the server's keystore, which also contains the server's private key. The private key is never sent to the client.
- For a signed cert, the client uses a truststore containing server certificates and public keys to validate that the certificate chain is signed by a trusted Certificate Authority (CA).
- The client and server exchange several more messages to validate keys.
- The client begins TLS data transfer with the server.
The following figure shows TLS/SSL handshaking using an optional truststore on the client:
If the TLS server uses a self-signed certificate or a certificate that is not signed by a trusted CA, then you create a truststore on the client. The client populates its truststore with server certificates and public keys that it trusts. When the client receives a certificate, the incoming certificate is then validated against the certificates in its truststore.
In one-way TLS, Edge can be either the server or the client as follows:
-
Edge as the TLS server
Edge is the server hosting the TLS endpoint, where the TLS endpoint corresponds to an API proxy deployed to a virtual host. The client is an app attempting to access the API proxy. In this scenario, Edge has the keystore containing the certificate and private key.
-
Edge as the TLS client
Edge acts as the client that accesses a backend service. In this case, the backend service corresponds to the server hosting a TLS endpoint. Therefore the backend server has a keystore that contains its certificate and private key.
Two-way TLS
The following figure shows the TLS/SSL handshaking for two-way TLS authentication between a client and server:
In two-way TLS the handshake is as follows:
- The client and server both have their own keystores. The client's keystore contains its cert and private key, and the server's keystore contains its cert and private key.
- The TLS server presents its certificate to the TLS client to authenticate itself. The client then verifies the identity of the server prior to sending its cert to the server.
- The TLS client presents its certificate to the TLS server to authenticate itself to the server.
The following figure shows TLS handshaking using an optional truststore:
In this scenario the handshake is as follows:
- If the TLS server uses a self-signed certificate or a certificate that is not signed by a trusted CA, then you create a truststore on the client. The client has a copy of the server's cert in its truststore. During TLS handshaking, the client compares the cert in its truststore to the cert send from the server to verify the identity of the server.
- If the TLS client uses a self-signed certificate or a certificate that is not signed by a trusted CA, then you create a truststore on the server.The server has a copy of the client's cert in its truststore. During TLS handshaking, the server compares the cert in its truststore to the cert send from the client to verify the identity of the client.
The client or server or both can use a truststore.
In two-way TLS, Edge can be either the server or the client as follows:
-
Edge as the server
Edge is the server hosting the TLS endpoint, where the TLS endpoint corresponds to an API proxy. The client is an app attempting to access the API proxy. In this scenario, Edge has a keystore containing the certificate and private key, and requires a truststore containing the client's cert and CA chain.
-
Edge as the client
Edge acts as a client that accesses a backend service. In this case, the backend service corresponds to the server hosting the TLS endpoint. The backend server therefore has a keystore that contains its certificate and private key.
Edge must also define a keystore that contains the certificate needed to validate itself to the backend service, and optionally a truststore containing the cert from the backend server if the server uses a self-signed certificate or a certificate that is not signed by a trusted CA.
The important thing to remember is that Edge is flexible enough to support two-way TLS regardless of how you decide to configure it.
SNI support
Edge supports the use of Server Name Indication (SNI) from API proxies to Edge, where Edge acts as the TLS server, and from Edge to target endpoints, where Edge acts as the TLS client, in both Cloud and Private Cloud installations.
With SNI, which is an extension of TLS/SSL, multiple HTTPS targets can be served off the same IP address and port without requiring those targets to use the same certificate.
For information on enabling SNI for an on-premises installation, see Using SNI with Edge.
Northbound and southbound
In Apigee, northbound refers to the API endpoint used by client applications to invoke the API Proxy. Typically the Router is the entry point in Apigee Edge and it handles the incoming requests to Apigee Edge. Therefore in Apigee, the endpoint used for communication between the client application and Apigee Edge (Router) is referred to as northbound.
In Apigee, southbound refers to the target endpoint Apigee uses to communicate with the backend server. Therefore in Apigee, the endpoint used for communication between the Apigee Edge (Message Processor) and the backend server is referred to as southbound. The Message Processor is a component of Apigee Edge that proxies API requests to backend target servers.
The following figure illustrates northbound and southbound connections for Apigee Edge:
