You're viewing **Apigee Edge** documentation. [Go to the **Apigee X** documentation](http://cloud.google.com/apigee/docs/api-platform/develop/ui-edit-proxy). info This document describes how to create, modify, and delete keystores and truststores for Edge for the Cloud and for Edge for the Private Cloud versions 4.18.01 and later. > [!NOTE] > **Note:** If you are using Edge for Private Cloud version 4.53.00 or later, you need to upload private keys and related certificates using only the PKCS12/PFX format. > [!NOTE] > **Note:** For Edge for the Cloud, you must have a cert signed by a trusted entity, such as Symantec or VeriSign. You cannot use a self-signed cert, or leaf certificates signed by a self-signed CA. For information about TLS, see the [TLS/SSL](https://docs.apigee.com/api-platform/system-administration/ssl). > [!NOTE] > **Note:** Private Cloud version 4.17.09 and earlier do not let you create keystores and truststore in the Edge UI. To create keystores and truststores for a Private Cloud deployment of Edge version 4.17.09 and earlier, see [Create > keystores and truststores for the Private Cloud 4.17.09 and earlier](https://docs.apigee.com/api-platform/system-administration/create-keystores-and-truststores-private-cloud). > [!CAUTION] > **Caution:** When an API proxy in Apigee Edge for Public or Private Cloud connects to a target endpoint or target server, Apigee does not by default perform hostname validation for the certificate presented by the target endpoint or target server. To enforce hostname validation, you have the option of applying a configuration at the individual proxy level or setting a flag to enable enforcement for your entire organization. For more information these configuration changes, see [Security Bulletin: GCP-2024-006](https://cloud.google.com/apigee/docs/security-bulletins/security-bulletins). ## About keystores/truststores and virtual hosts for Edge Cloud The process of creating keystores/truststores for Edge Cloud requires that you follow all of the rules about using virtual hosts. For example, with virtual hosts in the Cloud: - Virtual hosts must use TLS. - Virtual hosts can only use port 443. - You must use a signed TLS cert. Unsigned certs are not allowed for use with virtual hosts in the Cloud. - The domain name specified by the TLS cert must match the host alias of the virtual host. **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) - [Configuring Virtual Hosts FAQ](https://docs.apigee.com/api-platform/fundamentals/faq-configuring-virtual-hosts-edge-cloud) - [About virtual hosts](https://docs.apigee.com/api-platform/fundamentals/virtual-hosts) ## Implementing keystores and truststores in Edge To configure functionality that relies on public key infrastructure, such as TLS, you need to create keystores and truststores that contain the necessary keys and digital certificates. In Edge, keystores and truststores are both represented by a **keystore** entity that contain one or more **aliases**. That is, there is no implementation difference between a keystore and a truststore on Edge. The difference between keystores and truststore is derived from the kinds of entries that they contain and how they are used in TLS handshaking: - keystore - a **keystore** entity that contains one or more **aliases**, where each alias contains a cert/key pair. - truststore - a **keystore** entity that contains one or more **aliases**, where each alias contains a cert only. When configuring TLS for a virtual host or target endpoint, keystores and truststores provide different roles in the TLS handshaking process. When configuring a virtual host or target endpoint, you specify keystores and truststores separately in the `` tag, as shown below for a virtual host: ```rust apiTLS.myCompany.com 9006 true false ref://keystoreref myKeyAlias ``` In this example, you specify the name of the keystore and alias used by the virtual host for its TLS keystore. You use a [reference](https://docs.apigee.com/api-platform/system-administration/working-references) to specify the keystore name so that you can change it later when the cert expires. The alias contains a cert/key pair used to identify the virtual host to a TLS client accessing the virtual host. In this example, there is no truststore required. If a truststore is required, for example for a 2-way TLS configuration, use the `` tag to specify the truststore: ```rust apiTLS.myCompany.com 9006 true true ref://keystoreref myKeyAlias ref://truststoreref ``` In this example, the `` tag references a keystore only, it does not specify a specific alias. Each alias in the keystore contains a cert, or a cert chain, that is used as part of the TLS handshaking process. ## Supported certificate formats | Format | API and UI upload supported | Northbound supported | Validated | |---|---|---|---| | PEM | Yes | Yes | Yes | | \* PKCS12 | Yes | Yes | Yes Note: Apigee internally converts PKCS12 to PEM. | | \* DER | No | No | Yes | | \* PKCS7 | No | No | No | \* We recommend using PEM if possible. ### Using PKCS12 keystores with Edge for Private Cloud 4.53.00 or later If you are using Edge for Private Cloud 4.53.00 or later, you should use only a PKCS12 keystore to upload keys and related certificates to Apigee. For assistance with converting your existing keys and certificates to the PKCS12/PFX format, refer to [Converting certificates to supported format](https://docs.apigee.com/how-to-guides/converting-certificates-to-supported-format#packaging-pem-key-and-certificate-files-into-pkcs12pfx). ## About implementing an alias **Note**: Apigee converts uploaded PKCS12 keys and certificates to PEM format. We recommend using PEM format files only, if possible. On Edge, a **keystore** contains one or more **aliases**, where each alias contains: - TLS certificate as a PEM or PKCS12/PFX file - either a certificate signed by a certificate authority (CA), a file containing a chain of certificates where the last certificate is signed by a CA, or a self-signed cert. - Private key as a PEM or PKCS12/PFX file. Edge supports key sizes up to 2048 bits. A passphrase is optional. On Edge, a **truststore** contains one or more **aliases**, where each alias contains a: - TLS certificate as a PEM file - either a certificate signed by a certificate authority (CA), a chain of certificates where the last certificate is signed by a CA, or a self-signed cert. Edge provides a UI and API that you use to create keystores, create aliases, upload cert/key pairs, and update certs. The UI and API that you use to create a truststore are the same as you use to create a keystore. The difference is that when you create a truststore, you create aliases that contain only a cert. ### About the format of the cert and key files You can represent certs and keys as PEM files or as PKCS12/PFX files. PEM files comply with the X.509 format. 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`. However, many .crt files and .key files are already in the PEM format. If these files are text files, and are enclosed in: ```rust ---BEGIN CERTIFICATE--- ---END CERTIFICATE--- ``` or: ```rust ---BEGIN ENCRYPTED PRIVATE KEY--- ---END ENCRYPTED PRIVATE KEY--- ``` Then the files are compatible with the PEM format and you can use them in a keystore or truststore without converting them to a PEM file. ### About cert chains If a cert is part of a chain, you handle it differently based on whether the cert is used in a keystore or in a truststore: - **Keystore** - If a cert is part of a chain, then you must create a single file containing all the certs in the chain. The certs have to be in order and the last cert must be a root certificate or an intermediate cert signed by a root certificate. - **Truststore** - If a cert is part of a chain, then you must either create a single file containing all the certs and upload that file to an alias, or upload all certs in the chain separately to the truststore using a different alias for each cert. If you upload them as a single cert, the certs have to be in order and the last cert must be a root certificate or an intermediate cert signed by a root certificate. - If you create a single file that contains multiple certs, you must insert an empty line between each cert. For example, you can combine all of the certs into a single PEM file. The certs have to be in order and the last cert must be a root certificate or an intermediate cert signed by a root certificate: ```rust ---BEGIN CERTIFICATE--- (Your Primary TLS certificate) ---END CERTIFICATE--- ---BEGIN CERTIFICATE--- (Intermediate certificate) ---END CERTIFICATE--- ---BEGIN CERTIFICATE--- (Root certificate or intermediate certificate signed by a root certificate) ---END CERTIFICATE--- ``` If your certs are represented as PKCS12/PFX files, you can use the `openssl` command to create a PKCS12/PFX file from chain of certs, as shown below: ``` openssl pkcs12 -export -out certificate.pfx -inkey privateKey.key -in certificate.crt -certfile CACert.crt ``` When working with cert chains in a truststore, you do not always have to upload all the certs in the chain. For example, you upload a client certificate, `client_cert_1`, and the client certificate issuer's certificate, `ca_cert`. During two-way TLS authentication, client authentication succeeds when the server sends `client_cert_1` to the client as part of the TLS handshaking process. Alternatively, you have a second cert, `client_cert_2`, signed by the same cert, `ca_cert`. However, you do not upload `client_cert_2` to the truststore. The truststore still contains only `client_cert_1` and `ca_cert`. When the server passes `client_cert_2` as part of TLS handshaking, the request succeeds. This is because Edge allows TLS verification to succeed when `client_cert_2` does not exist in the truststore but was signed by the a cert that exists in the truststore. If you remove the CA certificate, `ca_cert`, from the truststore then TLS verification fails. ### FIPS considerations If you are using Edge for Private Cloud 4.53.00 or later on a FIPS-enabled operating system, you should use only a PKCS12 keystore to upload keys and related certificates to Apigee. ## Explore the TLS Keystores page Access the TLS Keystores page, as described below. ### Edge To access the TLS Keystores page using the Edge UI: 1. Sign in to as an **organization administrator**. 2. Select your organization. 3. Select **Admin \> Environment \> TLS Keystores**. ### Classic Edge (Private Cloud) > [!NOTE] > **Note:** The Classic Edge UI is available with Edge for Private Cloud only. To access the TLS Keystores page using the Classic Edge UI: 1. Sign in to `http://ms-ip:9000` as an **organization administrator** , where ms-ip is the IP address or DNS name of the Management Server node. 2. Select your organization. 3. Select **Admin \> Environment Configuration \> TLS Keystores**. The TLS Keystores page is displayed: ![](https://docs.apigee.com/static/api-platform/images/tls-keystores.png) As highlighted in the previous figure, the TLS Keystores page enables you to: - Select an environment - [Create a keystore and alias](https://docs.apigee.com/api-platform/system-administration/creating-keystores-and-truststore-cloud-using-edge-ui#create-a-keystore-truststore-and-alias) - [Test](https://docs.apigee.com/api-platform/system-administration/creating-keystores-and-truststore-cloud-using-edge-ui#test-a-keystore-or-truststore) and [delete](https://docs.apigee.com/api-platform/system-administration/creating-keystores-and-truststore-cloud-using-edge-ui#delete-a-keystore-truststore-or-alias) keystores - [](https://docs.apigee.com/api-platform/system-administration/creating-keystores-and-truststore-cloud-using-edge-ui#view-an-alias)[View](https://docs.apigee.com/api-platform/system-administration/creating-keystores-and-truststore-cloud-using-edge-ui#view-an-alias) and [delete](https://docs.apigee.com/api-platform/system-administration/creating-keystores-and-truststore-cloud-using-edge-ui#delete-a-keystore-truststore-or-alias) aliases > [!NOTE] > **Note:** The steps in the topics that follow are specific to the Edge UI. The Classic Edge UI steps are similar to those described. ## View an alias To view an alias: 1. [Access the TLS Keystores page](https://docs.apigee.com/api-platform/system-administration/creating-keystores-and-truststore-cloud-using-edge-ui#explore). 2. Select the Environment (typically `prod` or `test`). 3. Click the row associated with the alias that you want to view. Details for the alias cert and key are displayed. ![](https://docs.apigee.com/static/api-platform/images/cert_pop_up_v1.png) You can see all information about the alias, including the expiration date. 4. Manage the cert using the buttons at the top of the page to: - Download the cert as a PEM file. - Generate a CSR. If you have an expired cert and want to renew it, you can download a Certificate Signing Request (CSR). You then send the CSR to your CA to obtain a new cert. - Update a certificate. **Caution** : If you update a certificate that is currently being used by a virtual host or target server/target endpoint then you must contact [Apigee Edge Support](https://docs.apigee.com/api-platform/troubleshoot/support) to restart the Routers and Message Processors. The recommended way to update a cert is to: 1. Create a new keystore or truststore. 2. Add the new cert to the new keystore or truststore. 3. Update the [reference](https://docs.apigee.com/api-platform/system-administration/working-references) in the virtual host or target server/target endpoint to the keystore or truststore. See [Update a TLS certificate for the Cloud](https://docs.apigee.com/api-platform/system-administration/update-tls-certificate-cloud) for more. 4. Delete the alias. **Note**: If you delete an alias, and it is currently being used by a virtual host or target endpoint, then the virtual host or target endpoint will fail. ## Create a keystore/truststore and alias You can create a keystore for use as either a TLS keystore or a TLS truststore. A keystore is specific to an environment in your organization, for example the test or prod environment. Therefore, if you want to test the keystore in a test environment before deploying it to your production environment, you must create it in both environments. To create a keystore in an environment, you only need to specify the keystore name. After you create a named keystore in an environment, you can then create aliases and upload a cert/key pair (keystore) or upload a cert only (truststore) to the alias. To create a keystore: 1. [Access the TLS Keystores page](https://docs.apigee.com/api-platform/system-administration/creating-keystores-and-truststore-cloud-using-edge-ui#explore). 2. Select the Environment (typically `prod` or `test`). 3. Click **+ Keystore**. 4. Specify the keystore name. The name can only contain alphanumeric characters. 5. Click **Add Keystore**. The new keystore appears in the list. 6. Use one of the following procedures to add an alias. See also [Supported certificate file formats](https://docs.apigee.com/api-platform/system-administration/supportedcertificateformats). - [Creating an alias from a cert (truststore only)](https://docs.apigee.com/api-platform/system-administration/creating-keystores-and-truststore-cloud-using-edge-ui#creating-an-alias-from-a-cert-truststore-only) - [Creating an alias from a JAR file (keystore only)](https://docs.apigee.com/api-platform/system-administration/creating-keystores-and-truststore-cloud-using-edge-ui#creating-an-alias-from-a-jar-file-keystore-only) - [Create an alias](https://docs.apigee.com/api-platform/system-administration/creating-keystores-and-truststore-cloud-using-edge-ui#creating-an-alias-from-a-cert-and-key-keystore-only) [from a cert and key (keystore only)](https://docs.apigee.com/api-platform/system-administration/creating-keystores-and-truststore-cloud-using-edge-ui#creating-an-alias-from-a-cert-and-key-keystore-only) - [Create an alias from a PKCS12/PFX file (keystore only)](https://docs.apigee.com/api-platform/system-administration/creating-keystores-and-truststore-cloud-using-edge-ui#creating-an-alias-from-a-pkcs12-pfx-file-keystore-only) - [Creating an alias from a self-signed certificate (keystore only)](https://docs.apigee.com/api-platform/system-administration/creating-keystores-and-truststore-cloud-using-edge-ui#creating-an-alias-from-a-self-signed-certificate-keystore-only) ### Creating an alias from a cert (truststore only) To create an alias from a cert: 1. [Access the TLS Keystores page](https://docs.apigee.com/api-platform/system-administration/creating-keystores-and-truststore-cloud-using-edge-ui#explore). 2. Position the cursor over the keystore in to display the action menu and click **+**. 3. Specify the **Alias Name**. 4. Under Certificate details, select **Certificate Only** in the Type drop-down. 5. Click **Choose File** next to **Certificate File** , navigate to the PEM file containing the cert, and click **Open**. 6. By default, the API checks to make sure the certificate hasn't expired. Optionally select **Allow Expired Certificate** to skip validation. 7. Select **Save** to upload the cert and create the alias. ### Creating an alias from a JAR file (keystore only) To create an alias from a JAR file: 1. [Access the TLS Keystores page](https://docs.apigee.com/api-platform/system-administration/creating-keystores-and-truststore-cloud-using-edge-ui#explore). 2. Position the cursor over the keystore in to display the action menu and click **+**. 3. Specify the **Alias Name**. 4. Under Certificate details, select **JAR File** in the Type drop-down. 5. Click **Choose File** next to **JAR File** , navigate to the JAR file containing the cert and key, and click **Open**. 6. If the key has a password, specify the **Password**. if the key has no password, leave this field blank. 7. By default, the API checks to make sure the certificate hasn't expired. Optionally select **Allow Expired Certificate** to skip validation. 8. Select **Save** to upload the key and cert and create the alias. ### Creating an alias from a cert and key (keystore only) To create an alias from a cert and key: 1. [Access the TLS Keystores page](https://docs.apigee.com/api-platform/system-administration/creating-keystores-and-truststore-cloud-using-edge-ui#explore). 2. Position the cursor over the keystore in to display the action menu and click **+**. 3. Specify the **Alias Name**. 4. Under Certificate details, select **Certificate and Key** in the Type drop-down. 5. Click **Choose File** next to **Certificate File** , navigate to the PEM file containing the cert, and click **Open**. 6. If the key has a password, specify the **Key Password**. if the key has no password, leave this field blank. 7. Click **Choose File** next to **Key File** , navigate to the PEM file containing the key, and click **Open**. 8. By default, the API checks to make sure the certificate hasn't expired. Optionally select **Allow Expired Certificate** to skip validation. 9. Select **Save** to upload the key and cert and create the alias. ### Creating an alias from a PKCS12/PFX file (keystore only) To create an alias from a PKCS12 file containing the cert and key: 1. [Access the TLS Keystores page](https://docs.apigee.com/api-platform/system-administration/creating-keystores-and-truststore-cloud-using-edge-ui#explore). 2. Position the cursor over the keystore in to display the action menu and click **+**. 3. Specify the **Alias Name**. 4. Under Certificate details, select **PKCS12/PFX** in the Type drop-down. 5. Click **Choose File** next to **PKCS12/PFX** , navigate to the file containing the key and cert, and click **Open**. 6. If the key has a password, specify the **Password** for the PKCS12/PFX file. if the key has no password, leave this field blank. 7. By default, the API checks to make sure the certificate hasn't expired. Optionally select **Allow Expired Certificate** to skip validation. 8. Select **Save** to upload the file and create the alias. ### Creating an alias from a self-signed certificate (keystore only) To create an alias that uses a self-signed certificate, you fill in a form with the necessary information required to create the cert. Edge then creates the cert and a private key pair and uploads them to the alias. To create an alias from a self-signed cert: 1. [Access the TLS Keystores page](https://docs.apigee.com/api-platform/system-administration/creating-keystores-and-truststore-cloud-using-edge-ui#explore). 2. Position the cursor over the keystore in to display the action menu and click **+**. 3. Specify the **Alias Name**. 4. Under Certificate details, select **Self-Signed Certificate** in the Type drop-down. 5. Fill in the form by using the table below. 6. Select **Save** to create the cert and private key pair and to upload them to the alias. In the generated certificate, you will see the following additional fields: - **Issuer** The entity that signed and issued the certificate. For a self-signed certificate, this is the CN you specified when you created the cert. - **Validity** The certificate validity period represented as two dates: the date on which the certificate validity period begins and the date on which the certificate validity period ends. Both can be encoded as UTCTime or GeneralizedTime values. The following table describes the form fields: | Form Field | Description | Default | Required | |---|---|---|---| | Alias Name | Alias name. Maximum length is 128 characters. | N/A | Yes | | Key Size | Size of the key, in bits. Default and maximum value is 2048 bits. | 2048 | No | | Signature Algorithm | Signature algorithm to generate private key. Valid values are "SHA512withRSA", "SHA384withRSA" and "SHA256withRSA" (default). | SHA256withRSA | No | | Certificate validity in days | Validity duration of certificate, in days. Accepts positive non zero value. | 365 | No | | Common Name | Common Name (CN) of the organization identifies the fully qualified domain name(s) associated with the certificate. It is typically composed by a host and a domain name. For example, api.enterprise.apigee.com, www.apigee.com, etc. Max length is 64 characters. Depending on the [certificate type](https://support.dnsimple.com/articles/ssl-certificates-types/), the CN can be one or more hostnames belonging to the same domain (e.g. example.com, www.example.com), a wildcard name (e.g. \*.example.com) or a list of domains. Do not include any protocol (http:// or https://), port number, or resource path. The certificate is valid only if the request hostname matches at least one of the certificate common names. | N/A | Yes | | Email | Email address. Maximum length is 255 characters. | N/A | No | | Org Unit Name | Organization team name. Maximum length is 64 characters. | N/A | No | | Org Name | Organization name. Maximum length is 64 characters. | N/A | No | | Locality | City/Town name. Maximum length is 128 characters. | N/A | No | | State/Province | State/Province name. Maximum length is 128 characters. | N/A | No | | Country | Two letter country code. Example, IN for India, US for United States of America. | N/A | No | | Alternative Names | List of alternative host names. Allows additional identities to be bound to the subject of the certificate. Defined options include an Internet electronic mail address, a DNS name, an IP address, and a uniform resource identifier (URI). Max of 255 characters for each value. You can separate names by comma, or by pressing the Enter key after each name. | N/A | No | ## Test a keystore or truststore You can test your truststore and keystore in the Edge UI to verify that they are configured properly. The Test Ui validates a TLS request from Edge to a backend service. The backend service can be configured to support one-way or two-way TLS. To test one-way TLS: 1. [Access the TLS Keystores page](https://docs.apigee.com/api-platform/system-administration/creating-keystores-and-truststore-cloud-using-edge-ui#explore). 2. Select the Environment (typically `prod` or `test`). 3. Position your cursor over the TLS keystore you want to test to display the actions menu and click **Test** . The following dialog box appears showing the name of the truststore: ![](https://docs.apigee.com/static/api-platform/images/test_1_way-tls.png) 4. Enter the hostname of the backend service. 5. Enter the TLS port number (typically 443). 6. Optionally specify any Protocols or Ciphers. 7. Select **Test**. To test two-way TLS: 1. For the desired truststore, select the **Test** button. 2. In the dialog box, select **Two Way** for the **SSL Test Type** . The following dialog box appears: ![](https://docs.apigee.com/static/api-platform/images/test_2_way-tls.png) 3. Specify the name of the keystore used in two-way TLS. 4. Specify the alias name in the keystore containing the cert and key. 5. Enter the hostname of the backend service. 6. Enter the TLS port number (typically 443). 7. Optionally specify any Protocols or Ciphers. 8. Select **Test**. ## Add a cert to a truststore for two-way TLS When using two-way TLS for **inbound connections**, meaning an API request into Edge, the truststore contains a cert or CA chain for each client allowed to make requests to Edge. When you initially configure the truststore, you can add all the certs for the known clients. However, over time, you might want to add additional certs to the truststore as you add new clients. To add new certs to a truststore used for two-way TLS: 1. Ensure that you are using a reference to the truststore in the virtual host. 2. Upload a new cert to the truststore as described above in [Creating an alias from a cert (truststore only)](https://docs.apigee.com/api-platform/system-administration/creating-keystores-and-truststore-cloud-using-edge-ui#creating-an-alias-from-a-cert-truststore-only). 3. Update the truststore reference to set it to the **same** value. This update causes Edge to reload the truststore and the new cert. See [Modifying a reference](https://docs.apigee.com/api-platform/system-administration/working-references#modifyingareference) for more. ## Delete a keystore/truststore or alias You must use caution when deleting a keystore/truststore or alias. If you delete a keystore, truststore, or alias that is being used by a virtual host, target endpoint, or target server, all API calls through the virtual host or target endpoint/target server will fail. Typically, the process you use to delete a keystore/truststore or alias is: 1. Create a new keystore/truststore or alias as described above. 2. For **inbound connections**, meaning an API request into Edge, update the virtual host configuration to reference the new keystore and key alias. 3. For **outbound connections** , meaning from Apigee to a backend server: 1. Update the TargetEndpoint configuration for any API proxies that referenced the old keystore and key alias to reference the new keystore and key alias. If your TargetEndpoint references a TargetServer, update the TargetServer definition to reference the new keystore and key alias. 2. If the keystore and truststore are referenced directly from the TargetEndpoint definition, then you must redeploy the proxy. If the TargetEndpoint references a TargetServer definition, and the TargetServer definition references the keystore and truststore, then no proxy redeployment is necessary. 4. Confirm that your API proxies are functioning correctly. 5. Delete the keystore/truststore or alias. ### Delete a keystore You can delete a keystore or truststore by positioning your cursor over the keystore or trustore in the list to display the actions menu and clicking ![](https://docs.apigee.com/static/api-platform/images/delete-icon-black.png). If you delete a keystore or truststore that is being used by a virtual host or target endpoint/target server, all API calls through the virtual host or target endpoint/target server will fail. **Caution**: You should not delete a keystore until you have converted your virtual hosts and target endpoints/target servers to use a new keystore. ### Delete an alias You can delete an alias bby positioning your cursor over the alias in the list to display the actions menu and clicking ![](https://docs.apigee.com/static/api-platform/images/delete-icon-black.png). If you delete an alias that is being used by a virtual host or target endpoint/target server, all API calls through the virtual host or target endpoint/target server will fail. **Caution**: You should not delete an alias until you have converted your virtual hosts and target endpoints/target servers to use a new keystore and alias.