Send Docs Feedback

Note: Most user interface tasks can be performed in Edge Classic or the New Edge experience. For an overview, getting started topics, and release notes specific to the New Edge experience, see the docs.

About TLS/SSL

Self-service TLS/SSL Beta: For details, see self-service TLS/SSL Beta release.

TLS (Transport Layer Security, whose predecessor is 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.

Because Edge originally supported SSL, you will see some instances in the Edge UI and in the Edge XML that use the term "SSL". For example, the menu entry in the Edge UI that you use to view certs is called SSL Certificates. The XML tag that you use to configure a virtual host to use TLS is named <SSLInfo>

Edge supports one-way TLS and two-way TLS in both a cloud and an on-premises deployment (see Supported software and supported versions for supported versions of TLS). 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 some important terms and concepts before configuring TLS:

Term

Definition

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.

Self Signed Certificate

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.

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.

Certificate Authority (CA)

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.

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.

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.

CSR

A Certificate Signing Request (CSR) is a file generated on the TLS server based on the private key. The CSR contains the public key and other information like organization's name, location, and domain name. The CA will sign the CSR to create a TLS certificate. You typically generate a CSR when you have an expired cert and want to renew it. 

Note: Apigee does not create the CSR for you. You are responsible for creating the CSR. For more information, see this article: How to create a Private Key and generate a CSR?

Keystore

Contains the TLS certificate and private key used to identify the entity during TLS handshaking.

Truststore

Contains trusted certificates on an 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.

PEM file

Text files which comply with the X.509 format for 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.

PKCS12/PFX file

A binary file format for storing a certificate, any intermediate certificates, and the private key in a single encryptable file. PFX files usually have the extensions .pfx and .p12. PFX files are typically used on Windows machines to import and export certificates and private keys.

Server Name Indication (SNI)

Allows multiple HTTPS targets to be served off the same IP address and port without requiring those targets to use the same certificate.

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 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 makes a request to the Certificate Authority (CA) to authenticates the certificate.
  • 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:

  • 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. The backend server therefore 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 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:

  • 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.

Either the client or server can use a truststore, or both can.

In two-way TLS, Edge can be either the server or the client:

  • 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.  

Server Name Indication (SNI) support

Edge supports the use of Server Name Indication (SNI) from 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.

For Private Cloud installations, Java 1.7 or later is required.

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.

Help or comments?