You're viewing **Apigee Edge** documentation. [Go to the **Apigee X** documentation](http://cloud.google.com/apigee/docs). info This document describes how to create, modify, and delete keystores and truststores for Edge for the Private Cloud version 4.17.09 and earlier. > [!NOTE] > **Private Cloud:** To create keystores and truststores for Private Cloud versions 4.18.01 and later, see [Creating > keystores and truststore using the Edge UI](https://docs.apigee.com/api-platform/system-administration/creating-keystores-and-truststore-cloud-using-edge-ui) or [Creating keystores and truststore using the Edge management API](https://docs.apigee.com/api-platform/system-administration/creating-keystores-and-truststore-cloud-using-edge-management-api). ## About keystores and truststores Keystores and truststores define repositories of security certificates used for TLS encryption. The main difference between the two is where they are used in the TLS handshaking process: - A **keystore** contains a TLS certificate and private key used to identify the entity during TLS handshaking. In one-way TLS, when a client connects to the TLS endpoint on the server, the server's keystore presents the server's certificate (public cert) to the client. The client then validates that certificate with a Certificate Authority (CA), such as Symantec or VeriSign. In two-way TLS, both the client and the server maintain a keystore with their own cert and private key used for mutual authentication. - A **truststore** contains certificates used to verify certificates received as part of TLS handshaking. In one-way TLS, a truststore is not required if the cert is signed by a valid CA. If the certificate received by a TLS client is signed by a valid CA, then the client makes a request to the CA to authenticate the certificate. A TLS client typically uses a truststore to validate self-signed certificates received from the TLS server, or certificates that are not signed by a trusted CA. In this scenario, the client populates its truststore with certificates that it trusts. Then, when the client receives a server certificate, the incoming certificate is validated against the certificates in its truststore. For example, a TLS client connects to a TLS server where the server uses a self-signed certificate. Because it is a self-signed certificate, the client cannot validate it with a CA. Instead, the client preloads the server's self-signed certificate into its truststore. Then, when the client attempts to connect to the server, the client uses its truststore to validate the certificate received from the server. For two-way TLS, both the TLS client and the TLS server can use a truststore. A truststore is required when performing two-way TLS when Edge acts as the TLS server. > [!NOTE] > **Note:** See [About TLS/SSL](https://docs.apigee.com/api-platform/system-administration/about-ssl) for diagrams showing the use of keystores and truststores in TLS handshaking. Certificates can be issued by a certificate authority (CA), or they can be self-signed by the private key that you generate. If you have access to a CA, follow instructions provided by your CA for generating keys and issuing certificates. If you do not have access to a CA, you can generate a self-signed certificate using one of the many publicly available free tools, such as openssl. ### Implementing a keystore and truststore on Edge On Edge, a keystore contains one or more JAR files, where the JAR file 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. - Private key as a PEM file. Edge supports key sizes up to 2048 bits. A passphrase is optional. A truststore is similar to a keystore except that it contains only certs as a PEM file, but no private keys. If the cert is part of a chain, then the keystore/truststore must contain all certs in the chain, either as individual PEM files or as a single file. If you use a single file, then the certs must be in order where the first cert in the file is the certificate used for TLS followed by the chain of certs, in order, to the CA certificate. You must insert an empty line between each cert in the file. Edge provides an API that you use to create keystores and truststores. The actual APIs are the same. The difference is that when you create a keystore, you pass a JAR file that contains the cert and private key. When you create a truststore, you pass only the cert as a PEM file. ### About the format of the cert and key files The examples in this document show the TLS cert and key defined as PEM files, which 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. If you have a certificate chain, and want to use that chain in a keystore or truststore, then you can combine all of the certs into a single PEM file with a new line between each 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: ```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--- ``` ## Get details about an existing keystore Check your environment for any existing keystores by using the [List Keystores and Truststores](https://docs.apigee.com/management/apis/get/organizations/{org_name}/environments/{env_name}/keystores) API: ``` curl -X GET \ https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores \ -u email:password ``` For cloud customers, a default keystore is provided for free trial organizations in both the test and prod environments. You should see the following results for this call for both environments: ```rust [ "freetrial" ] ``` You can use this default keystore to test your APIs, and push your APIs to production, but you typically create your own keystore, with your own cert and key, before you deploy to production. For Private Cloud customers, the returned array is empty until you create your first keystore. Check the contents of the keystore by using the [Get a Keystore or Truststore](https://docs.apigee.com/management/apis/get/organizations/{org_name}/environments/{env_name}/keystores/{keystore_name}) API. For a cloud customer, you should see a single server TLS certificate--the default certificate that Apigee Edge provides for free trial accounts. ``` curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/freetrial \ -u email:password ``` The response should appear as: ```rust { "certs" : [ "wildcard.apigee.net.crt" ], "keys" : [ "freetrial" ], "name" : "freetrial" } ``` You can also view this information in the Edge management UI: 1. Login to the Edge management UI at (cloud) or `http://:9000` (on-premises), where `` is the IP address of the Management Server node. 2. In the Edge management UI menu, select **Admin \> TLS Certificates**. ## Get TLS certificate details You can use the [Get Cert Details from a Keystore or Truststore](https://docs.apigee.com/management/apis/get/organizations/{org_name}/environments/{env_name}/keystores/{keystore_name}/certs/{cert_name}) API to view details about TLS certificates in the keystore, such as expiration date and issuer. First, obtain the name of the certificate in which you are interested. This example fetches information for the keystore called "freetrial". ``` curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/freetrial \ -u email:password ``` Sample response: ```rust { "certs" : [ "wildcard.apigee.net.crt" ], "keys" : [ "freetrial" ], "name" : "freetrial" } ``` Then, use the value of the certs property to get the certificate details: ``` curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/freetrial/certs/wildcard.apigee.net.crt \ -u email:password ``` Sample response: ```rust { "certInfo" : [ { "expiryDate" : "Wed, 23 Apr 2014 20:50:02 UTC", "isValid" : "Yes", "issuer" : "CN=Go Daddy Secure Certificate Authority - G2, OU=http://certs.godaddy.com/repository/, O="GoDaddy.com, Inc.", L=Scottsdale, ST=Arizona, C=US", "subject" : CN=*.example.apigee.net, OU=Domain Control Validated", "subjectAlternativeNames" : ["*.example.apigee.net","*.example.apigee.net" ], "validFrom" : "Tue, 15 Apr 2014 09:17:03 UTC", "version" : 3 } ], "name" : "example.apigee.net.crt" } ``` You can also view this information in the Edge management UI: 1. Login to the Edge management UI at (cloud) or `http://:9000` (on-premises), where `` is the IP address of the Management Server node. 2. In the Edge management UI menu, select **Admin \> TLS Certificates**. In the Edge UI, you can specify how far in advance Edge indicates that a certificate is going to expire. By default, the UI highlights any certificates scheduled to expire in the next 10 days. ## Create a keystore > [!NOTE] > **Note:** A keystore should only contain a single cert/key pair. Do not upload more than one cert/key pair to the keystore. 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. Creating a keystore is a two-step process: 1. Create a JAR file containing your cert and private key. 2. Create the keystore and upload the JAR File. ### Create a JAR file containing your cert and private key Create a JAR file with your private key, certificate, and a manifest. The JAR file must contain the following files and directories: ```rust /META-INF/descriptor.properties myCert.pem myKey.pem ``` > [!NOTE] > **Note:** A keystore JAR can contain only one certificate. If you have a certificate chain, all certs in the chain must be appended into a single PEM file, where the last certificate is signed by a CA, and each cert is separated by a new line. The certs must be appended to the PEM file in the correct order, meaning: > > ```rust > cert -> intermediate cert(1) -> intermediate cert(2) -> ... -> root > ``` In the directory containing your key pair and certificate, create a directory called `/META-INF`. Then, create a file called `descriptor.properties` in `/META-INF` with the following contents: ```rust certFile={myCertificate}.pem keyFile={myKey}.pem ``` Generate the JAR file containing your key pair and certificate: ``` jar -cf myKeystore.jar myCert.pem myKey.pem ``` Add descriptor.properties to your JAR file: ``` jar -uf myKeystore.jar META-INF/descriptor.properties ``` ### Create the keystore and upload the JAR file To create a keystore in an environment, you only need to specify the keystore name to the [Create a Keystore or Truststore](https://docs.apigee.com/management/apis/post/organizations/{org_name}/environments/{env_name}/keystores) API. The name can only contain alphanumeric characters: ``` curl -X POST -H "Content-Type: text/xml" \ https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores \ -d '' -u email:password ``` Sample response: ```rust { "certs" : [ ], "keys" : [ ], "name" : "myKeystore" } ``` After you create a named keystore in an environment, you can upload your JAR files that contain a cert and private key by using the [Upload a JAR file to a Keystore](https://docs.apigee.com/management/apis/post/organizations/{org_name}/environments/{env_name}/keystores/{keystore_name}/keys) API: ``` curl -X POST -H "Content-Type: multipart/form-data" \ -F file="@myKeystore.jar" -F password={key_pass} \ "https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/{myKeystore}/keys?alias={key_alias}" \ -u email:password ``` where the `-F` option specifies the path to the JAR file. In this call, you specify two query parameters: - `alias` - Identifies the certificate and key in the key store. When you create a virtual host, you reference the certificate and key by its alias name. - `password` - The password for the private key. Omit this parameter if the private key has no password. Verify that your keystore uploaded properly: ``` curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/myKeystore \ -u email:password ``` Sample response: ```rust { "certs" : [ "myCertificate" ], "keys" : [ "myKey" ], "name" : "myKeystore" } ``` ## Create a truststore The APIs that you use to create a truststore are the same as used to create a keystore. The only difference is that you pass the cert file as a PEM file instead of a JAR file. > [!NOTE] > **Note:** You must create a truststore on Edge as part of configuring two-way TLS between a TLS client and Edge, where Edge acts as the TLS server. When you configure the truststore on Edge, upload the cert that you received from the client. During TLS handshaking, Edge uses the cert in its truststore to validate the cert that it receives from the client. If the cert is part of a chain, then you must either upload all certs in the chain separately to the truststore, or create a single file containing all the certs, Include a new line between each cert in the file. The final certificate is typically signed by the certificate issuer. For example, in the truststore, 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 `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. Create an empty truststore in the environment by using [Create a Keystore or Truststore](https://docs.apigee.com/management/apis/post/organizations/{org_name}/environments/{env_name}/keystores), the same API that you use to create a keystore: ``` curl -X POST -H "Content-Type: text/xml" -d \ '' \ https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores \ -u email:password ``` Upload the certificate as a PEM file to the truststore by using the [Upload a Certificate to a Truststore](https://docs.apigee.com/management/apis/post/organizations/{org_name}/environments/{env_name}/keystores/{keystore_name}/certs) API: ``` curl -X POST -H "Content-Type: multipart/form-data" -F file="@trust.pem" \ https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/myTruststore/certs?alias=myTruststore \ -u email:password ``` where the `-F` option specifies the path to the PEM file. ## Delete a keystore or truststore You can delete a keystore or truststore by using the [Delete a Keystore or Truststore](https://docs.apigee.com/management/apis/delete/organizations/{org_name}/environments/{env_name}/keystores/{keystore_name}) API: ``` curl -X DELETE \ https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/myKeystoreName \ -u email:password ``` Sample response: ```rust { "certs" : [ ], "keys" : [ ], "name" : "myKeystoreName" } ``` 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..