Configuring TLS access to an API for the Private Cloud

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

A virtual host on Edge defines the domains and ports on which an API proxy is exposed, and, by extension, the URL that apps use to access an API proxy.

A virtual host also defines whether the API proxy is accessed by using the HTTP protocol, or by the encrypted HTTPS protocol that uses TLS. When configuring a virtual host to use HTTPS and TLS, you create a virtual host on Edge and configure the virtual host to use a keystore and truststore.

Learn more:

Notes:

This Cloud Product Article lists valid SSL ciphers for TLS 1.2: Empirical Analysis of Valid Values for VirtualHost ssl_ciphers for Testing TLS 1.2.
As of Edge for Private Cloud version 4.16.01, you must specify a host alias when creating a virtual host. In releases previous to 4.16.01, the host alias was optional.
The combination of host alias name and port number for the virtual host must be unique for all virtual hosts in the Edge installation.
If you configure a port number (other than 80 or 443), it must be unique and shouldn't have an overlapping port configuration with an existing host.
If your installation uses a load balancer, and the load balancer is responsible for handling encrypted traffic, then you still need to create the virtual host. However, your network configuration will determine whether or not the virtual host has to support TLS between the load balancer and the Router. See Using TLS in a Private Cloud installation for more.

What you need to create a virtual host

Before you create a virtual host, you should have the following information:

The publicly facing domain name of the virtual host. For example, you should know if the publicly facing name is api.myCompany.com, myapi.myCompany.com, etc. That information is used when you create the virtual host and also when you create the DNS record for the virtual host.
For one-way TLS, you need to create a keystore where the keystore contains the following:
- TLS certificate - either a certificate signed by a certificate authority (CA), or a chain of certificates where the last certificate is signed by a CA.
- Private key - Edge supports key sizes up to 2048 bits. A passphrase is optional.
For two-way TLS, you need a keystore and you need a truststore to hold the client's certificate and, optionally, certificate's CA chain. You need the truststore even if the cert is signed by a CA.

See Keystores and Truststores for more information on creating keystores and truststores.

Virtual host configuration for TLS

To create a virtual host, create an XML object that defines the virtual host. The following XML object uses the <SSLInfo> element to define a virtual host for a one-way TLS configuration over HTTPS:

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>apiTLS.myCompany.com</HostAlias>
    </HostAliases>
    <Interfaces/>
    <Port>9006</Port>
    <OCSPStapling>off</OCSPStapling>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <KeyStore>ref://myTestKeystoreRef</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
    </SSLInfo>
</VirtualHost>

Note: Because Edge originally supported SSL, the tag that you use to configure TLS is named <SSLInfo>.

In this example, the <Enabled> element is set to true to enable one-way TLS, and the <KeyStore> and <KeyAlias> elements specify the keystore and key used by the TLS connection.

To enable two-way TLS, set the <ClientAuthEnabled> element to true, and specify a truststore using the <TrustStore> element. The truststore holds the client's certificate and, optionally, certificate's CA chain.

Deciding how to specify the keystore and truststore name in the virtual host

In the virtual host example above, you specified the keystore by using a reference. A reference is a variable that contains the name of the keystore, rather than specifying the keystore name directly.

The advantage to using a reference is that you can change the value of the reference to change the keystore used by the virtual host, usually because the cert in the current keystore is expiring in the near future. Changing the value of the reference does not require you to restart the Edge Router.

Alternatively, you can use a literal keystore name in the virtual host. However, if you ever modify the virtual host to change the keystore name, you have to restart the Edge Routers.

Restrictions in using references to keystores and truststore

You must take into account the following restriction when using references to keystores and truststores:

You can only use keystore and truststore references in virtual hosts if you support SNI and you terminate SSL on the Apigee Routers.
If you have a load balancer in front of the Apigee Routers, and you terminate TLS on the load balancer, then you cannot use keystore and truststore references in virtual hosts.

Modifying an existing virtual host to use references to the keystore and truststore

Apigee strongly recommends that virtual hosts use reference to keystores and truststores. References let you change the keystore and truststore used by the virtual host without having to restart the Edge Routers.

If your virtual hosts are currently configured to use the literal name of the keystore or truststore, you can convert them to use references. To do so, update the virtual host to use references, and then restart the Edge Routers.

Setting the TLS ciphers and protocols for Edge 4.15.07 and earlier

If you are using Edge version 4.15.07 and earlier, then you set the TLS protocol and ciphers used by the virtual host by using the <Ciphers> and <Protocols> child tags of the <SSLInfo> tag. These tags are described in the table below.

For example:

    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <KeyStore>myTestKeystore</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
        <SSLInfo>
            <Enabled>true</Enabled>
            <ClientAuthEnabled>false</ClientAuthEnabled>
            <KeyStore>myTestKeystore</KeyStore>
            <KeyAlias>myKeyAlias</KeyAlias>
            <Ciphers>
                <Cipher>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</Cipher>
                <Cipher>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256</Cipher>
            </Ciphers>
            <Protocols>
                <Protocol>TLSv1.2</Protocol>
            </Protocols>
        </SSLInfo>
   </SSLInfo>

The <Cipher> tag uses the Java and JSSE name of the cipher. For example, for Java 8 see http://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#ciphersuites.

Specifying the TLS ciphers and protocols for Edge 4.16.01 to 4.16.09

In Edge 4.16.01 through 4.16.09, you set the default ciphers and protocols for virtual hosts globally on the Router. These defaults then apply to all virtual hosts.

Use tokens to specify the default protocols and ciphers:

To specify the default protocols, use the token conf_load_balancing_load.balancing.driver.server.ssl.protocols
To specify the default ciphers for the Router, use the token conf_load_balancing_load.balancing.driver.server.ssl.ciphers

The default value of the conf_load_balancing_load.balancing.driver.server.ssl.protocols token is:

conf_load_balancing_load.balancing.driver.server.ssl.protocols=TLSv1 TLSv1.1 TLSv1.2

This setting specifies that the Router supports TLS versions 1.0, 1.1, and 1.2. Specify a space delimited list of values to the token.

The default value of the conf_load_balancing_load.balancing.driver.server.ssl.ciphers token is:

conf_load_balancing_load.balancing.driver.server.ssl.ciphers=HIGH:!aNULL:!MD5:!DH+3DES:!RSA+3DES

This setting specifies:

Key length of 128 bits or more required (HIGH).
Exclude ciphers with no authentication (!aNULL)
Exclude cipher suites using MD5 (!MD5)
Exclude cipher suites using DH (including anonymous DH, ephemeral DH and fixed DH) AND triple DES (!DH+3DES)
Exclude cipher suites using RSA key exchange AND triple DES (!RSA+3DES)

For information on the syntax and values allowed by this token, see OpenSSL ciphers. Note that this token uses the OpenSSL cipher names, such as AES128-SHA256, and not the Java/JSSE cipher names, such as TLS_RSA_WITH_AES_128_CBC_SHA256.

To set the token for the Router:

Edit the /opt/apigee/customer/application/router.properties file. If that file does not exist, create it.

Set the conf_load_balancing_load.balancing.driver.server.ssl.ciphers token. For example, to specify TLSv1.2 only and exclude cipher suites using pre-shared keys, add!PSK:

conf_load_balancing_load.balancing.driver.server.ssl.protocols=TLSv1.2
conf_load_balancing_load.balancing.driver.server.ssl.ciphers=HIGH:!aNULL:!MD5:!DH+3DES:!RSA+3DES:!PSK

Ensure that the router.properties file is owned by apigee:

chown apigee:apigee /opt/apigee/customer/application/router.properties

Restart the Edge Router:

/opt/apigee/apigee-service/bin/apigee-service edge-router restart

Check the value of the token:

/opt/apigee/apigee-service/bin/apigee-service edge-router configure -search conf_load_balancing_load.balancing.driver.server.ssl.ciphers

Setting TLS virtual host parameters for Edge version 4.17.01 and later

If you are using Edge version 4.17.01 and later, then you can set some TLS properties for an individual virtual host, such as TLS protocol and cipher, by using the <Properties> child tag of the <VirtualHost> tag. These tags are described at Virtual host property reference.

For example:

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>apiTLS.myCompany.com</HostAlias>
    </HostAliases>
    <Interfaces/>
    <Port>9006</Port>
    <OCSPStapling>off</OCSPStapling>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <KeyStore>ref://myTestKeystoreRef</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
    </SSLInfo>
    <Properties>
        <Property name="proxy_read_timeout">50</Property>
        <Property name="keepalive_timeout">300</Property>
        <Property name="proxy_request_buffering">off</Property>
        <Property name="proxy_buffering">off</Property>
        <Property name="ssl_protocols">TLSv1.2 TLSv1.1</Property>
        <Property name="ssl_ciphers">HIGH:!aNULL:!MD5:!DH+3DES:!kEDH</Property>
    </Properties>
</VirtualHost>

For information on the syntax and values allowed by the ssl_ciphers token, see OpenSSL ciphers. Note that this token uses the OpenSSL cipher names, such as AES128-SHA256, and not the Java/JSSE cipher names, such as TLS_RSA_WITH_AES_128_CBC_SHA256.

Creating a virtual host that uses HTTPS

This example specifies the keystore to the virtual host by using a reference. Using a reference allows you to change the keystore without having to restart Routers.

Use the following procedure to create the virtual host:

Create and configure a keystore named myTestKeystore by using the procedure described here: Keystores and Truststores. Ensure that the keystore uses an alias name of myKeyAlias for the cert and private key.

Use the following POST API call to create the reference named keystoreref to the keystore you created above:

curl -X POST  -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references \
  -d '<ResourceReference name="keystoreref">
    <Refers>myTestKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
  </ResourceReference>'
  -u email:password

The reference specifies the name of the keystore and the reference type as KeyStore.

Use the following GET API call to view the reference:

curl -X GET https://api.enterprise.apigee.com/v1/o/[org_name}/e/{env_name}/references/keystoreref -u uname:password

Create the virtual host by using the Create a Virtual Host API, where <ms-IP> is the IP address or domain name of the Management Server node.

Make sure to specify the correct keystore reference and key alias:
```
curl -X POST -H "Content-Type:application/xml" \
  http://<ms-IP>:8080/v1/o/{org_name}/environments/{env_name}/virtualhosts \
  -d '<VirtualHost  name="newTLSTrustStore2">
    <HostAliases>
      <HostAlias>apiTLS.myCompany.com</HostAlias>
    </HostAliases>
    <Interfaces/>
    <Port>9005</Port>
    <OCSPStapling>off</OCSPStapling>
    <SSLInfo>
      <Enabled>true</Enabled>
      <ClientAuthEnabled>false</ClientAuthEnabled>
      <KeyStore>ref://keystoreref</KeyStore>
      <KeyAlias>myKeyAlias</KeyAlias>
    </SSLInfo>
  </VirtualHost>' \
  -u email:password
```
Note: If you are performing two-way TLS with the client, then set <ClientAuthEnabled> to true and specify the truststore using the <TrustStore> element. The client must be configured correctly for two-way TLS, meaning Edge has a truststore containing the client's cert and certificate chain. Create the truststore by using the procedure described here: Keystores and Truststores.
Create a DNS record for the virtual host that matches the host alias.
If you have any existing API proxies, add the virtual host to the <HTTPConnection> element in the ProxyEndpoint. The virtual host is added automatically to all new API proxies.

See Updating an API proxy after creating a virtual host in About virtual hosts.

Warning: All virtual hosts are automatically added to all new API proxies. Therefore, if you create a new API proxy that should not be accessible over a particular virtual host, then you must edit the API proxy to remove that virtual host from its ProxyEndpoint.

After updating an API proxy to use the virtual host, and creating the DNS record for the host alias, you can access the API proxy as shown below:

https://apiTLS.myCompany.com/v1/{project-base-path}/{resource-path}

For example:

https://apiTLS.myCompany.com/v1/weather/forecastrss?w=12797282

Creating and modifying references to a keystore or truststore

You can optionally configure the virtual host to use a reference to the keystore or truststore instead. The advantage to using a reference is that you can update the reference to point to a different keystore or truststore to update the TLS cert without having to restart a Router.

For example, shown below is a virtual host that uses a reference to the keystore:

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>apiTLS.myCompany.com</HostAlias>
    </HostAliases>
    <Interfaces/>
    <Port>9006</Port>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <KeyStore>ref://keystoreref</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
    </SSLInfo>
</VirtualHost>

Use the following POST API call to create the reference named keystoreref:

curl -X POST  -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references \
  -d '<ResourceReference name="keystoreref">
    <Refers>myTestKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
  </ResourceReference>'
  -u email:password

The reference specifies the name of the keystore and its type.

Use the following GET API call to view the reference:

curl -X GET https://api.enterprise.apigee.com/v1/o/[org_name}/e/{env_name}/references/keystoreref -u uname:password

To later change the reference to point to a different keystore, ensuring that the alias has the same name, use the following PUT call:

curl -X PUT -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references/keystoreref \
  -d '<ResourceReference name="keystoreref">
    <Refers>myNewKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
  </ResourceReference>'
  -u email:password