You're viewing **Apigee Edge** documentation. [Go to the **Apigee X** documentation](http://cloud.google.com/apigee/docs/api-platform/system-administration/options-configuring-tls). 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*. > [!NOTE] > **Private Cloud:** This document describes how to create a virtual host for an on-premises deployment of Edge. To create a virtual host for a cloud deployment of Edge, see [Using > TLS in a cloud-based Edge installation](https://docs.apigee.com/api-platform/system-administration/configuring-ssl-cloud-based-edge-installation). **Learn more:** - [About TLS/SSL](https://docs.apigee.com/api-platform/system-administration/about-ssl) - [Using TLS with Edge](https://docs.apigee.com/api-platform/system-administration/using-ssl-edge) - [About virtual hosts](https://docs.apigee.com/api-platform/fundamentals/virtual-hosts) - [Configuring virtual hosts for the Private Cloud](https://docs.apigee.com/api-platform/fundamentals/configuring-virtual-hosts-private-cloud) - [Virtual host property reference](https://docs.apigee.com/api-platform/fundamentals/virtual-host-property-reference) - [Keystores and Truststores](https://docs.apigee.com/api-platform/system-administration/keystores-and-truststores) > [!NOTE] > **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](https://www.googlecloudcommunity.com/gc/Cloud-Product-Articles/Empirical-Analysis-of-Valid-Values-for-VirtualHost-ssl-ciphers/ta-p/75888). > - 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](https://docs.apigee.com/api-platform/system-administration/configuring-ssl-premises-edge-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](https://docs.apigee.com/api-platform/system-administration/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 `` element to define a virtual host for a one-way TLS configuration over HTTPS: ``` apiTLS.myCompany.com 9006 off true false ref://myTestKeystoreRef myKeyAlias ``` > [!NOTE] > **Note:** Because Edge originally supported SSL, the tag that you use to configure TLS is named ``. In this example, the `` element is set to true to enable one-way TLS, and the `` and \<`KeyAlias>` elements specify the keystore and key used by the TLS connection. To enable two-way TLS, set the `` element to `true`, and specify a truststore using the `` 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. > [!NOTE] > **Note:** You can only use a reference to the keystore and truststore; you cannot use a reference to the alias. When you change the reference to a keystore, ensure that the alias name of the cert in the new keystore is the same as in the old keystore. 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 `` and `` child tags of the `` tag. These tags are described in the table below. For example: ``` true false myTestKeystore myKeyAlias true false myTestKeystore myKeyAlias TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 TLSv1.2 ``` The `` 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](https://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. > [!NOTE] > **Note:** You cannot override these value for specific virtual hosts. All virtual hosts use the same values for protocol and cipher. 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](https://www.openssl.org/docs/man1.1.1/man1/ciphers.html). 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: 1. Edit the `/opt/apigee/customer/application/router.properties` file. If that file does not exist, create it. 2. 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 ``` 3. Ensure that the `router.properties` file is owned by apigee: ``` chown apigee:apigee /opt/apigee/customer/application/router.properties ``` 4. Restart the Edge Router: ``` /opt/apigee/apigee-service/bin/apigee-service edge-router restart ``` 5. 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 `` child tag of the `` tag. These tags are described at [Virtual host property reference](https://docs.apigee.com/api-platform/fundamentals/virtual-host-property-reference). > [!NOTE] > **Note:** You can still use tokens to set the default ciphers and protocols for virtual hosts globally on the Router, as described in the previous section for Edge 4.16.01 through 4.16.09. This section describes new properties added in 4.17.01 that let you override those defaults for an individual virtual host. For example: ``` apiTLS.myCompany.com 9006 off true false ref://myTestKeystoreRef myKeyAlias 50 300 off off TLSv1.2 TLSv1.1 HIGH:!aNULL:!MD5:!DH+3DES:!kEDH ``` For information on the syntax and values allowed by the `ssl_ciphers` token, see [OpenSSL ciphers](https://www.openssl.org/docs/man1.1.1/man1/ciphers.html). 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: 1. Create and configure a keystore named **myTestKeystore** by using the procedure described here: [Keystores and Truststores](https://docs.apigee.com/api-platform/system-administration/keystores-and-truststores). Ensure that the keystore uses an alias name of **myKeyAlias** for the cert and private key. 2. 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 ' myTestKeystore KeyStore ' -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 ``` 3. Create the virtual host by using the [Create a Virtual Host](https://docs.apigee.com/management/apis/post/organizations/{org_name}/environments/{env_name}/virtualhosts) API, where `` 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://:8080/v1/o/{org_name}/environments/{env_name}/virtualhosts \ -d ' apiTLS.myCompany.com 9005 off true false ref://keystoreref myKeyAlias ' \ -u email:password ``` > [!NOTE] > **Note:** If you are performing two-way TLS with the client, then set `` to `true` and specify the truststore using the `` 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](https://docs.apigee.com/api-platform/system-administration/keystores-and-truststores). 4. Create a DNS record for the virtual host that matches the host alias. 5. If you have any existing API proxies, add the virtual host to the `` 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](https://docs.apigee.com/api-platform/fundamentals/virtual-hosts). > [!WARNING] > **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. > [!NOTE] > **Note:** You can only use a reference to the keystore and truststore; you cannot use a reference to the alias. When you change the reference to a keystore, ensure that the alias name of the cert is the same as in the old keystore. > [!NOTE] > **Note:** If your virtual host currently uses literal keystore or truststore names, you can convert the virtual hosts to use references. However, after you update the virtual hosts to use references, you must restart the Edge Routers, one at a time. For example, shown below is a virtual host that uses a reference to the keystore: ``` apiTLS.myCompany.com 9006 true false ref://keystoreref myKeyAlias ``` 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 ' myTestKeystore KeyStore ' -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 ' myNewKeystore KeyStore ' -u email:password ```