—Rate this article—
 

KeyStores and TrustStores

To configure functionality that relies on public key infrastructure (SSL and SAML, for example) you need to create keystores and truststores that provide the necessary keys and digital certificates.

Learn more:

About keystores and truststores

Keystores and truststores define repositories of security certificates used for SSL encryption. The main difference between the two is where they are used in the SSL handshaking process:

  • A keystore contains an SSL certificate and private key.

    In one-way SSL, when a client connects to the SSL 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.

    In two-way SSL, both the client and the server maintain a keystore with their own cert and private key used for mutual authentication.
  • A truststore contains trusted certificates stored on the client that are used when the client makes an outbound SSL connection to an SSL endpoint. For two-way SSL, the contents of the truststore are used to validate the identity of the server's certificate being presented to the client. Note that a truststore does not contain a private key.

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 file, where the JAR file contains a:

  • SSL 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 sert.
  • 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 files, but no private keys. If the cert is part of a chain, then the truststore must contain all certs in the chain as individual PEM files.

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 SSL 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:

-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----

or:

-----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, then all of the certs have to be combined 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:

-----BEGIN CERTIFICATE-----
(Your Primary SSL certificate)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Intermediate certificate)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Root certificate or intermediate certificate signed by a root certificate)
-----END CERTIFICATE-----

When using a truststore, if you have a chain of certs, you must upload the chain as individual PEM files.

Get details about an existing keystore

Check your environment for any existing keystores by using the List Keystores and Truststores API:

$ curl -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores \
-u myname:mypass

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:

[ "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 OPDK 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 API. For a cloud customer, you should see a single server SSL 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 myname:mypass

The response should appear as:

{
 "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 https://enterprise.apigee.com (cloud) or http://<ms-ip>:9000 (on-premises), where <ms-ip> is the IP address of the Management Server node.
  2. In the Edge management UI menu, select Admin > SSL Certificates.

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:

/META-INF/descriptor.properties
myCert.pem
myKey.pem

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. The certs must be appended to the PEM file in the correct order, meaning:

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:

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

To create a keystore in an environment, you only need to specify the keystore name to the Create a Keystore or Truststore API:

$ curl -H "Content-Type: text/xml" \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores \
-d '<KeyStore name="myKeystore"/>' -u myname:mypass

Sample response:

{
 "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 API:

$ curl -X POST -H "Content-Type: multipart/form-data" \
-F file="@myKeystore.jar" \ "https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/{myKeystore}/keys?alias={key_alias}&password={key_pass}" \
-u myname:mypass

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 myname:mypass

Sample response:

{  
 "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.

You often create a truststore on Edge as part of configuring two-way SSL between Edge and a backend server. In this case, when you configure the truststore on Edge you upload a cert file that you received from the entity hosting the backend server.  

If the cert is part of a chain, then you must upload all certs in the chain separately to the truststore. 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 SSL authentication, client authentication succeeds when the server sends client_cert_1 to the client as part of the SSL 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 SSL handshaking, the request succeeds. This is because Edge allows SSL 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 SSL verification fails.

Create an empty truststore in the environment by using Create a Keystore or Truststore, the same API that you use to create a keystore:

$ curl -X POST -H "Content-Type: text/xml" -d \
'<KeyStore name="myTruststore"/>' \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores \
-u myname:mypass

Upload the certificate as a PEM file to the truststore by using the Upload a Certificate to a Truststore 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 myname:mypass

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 API:

$ curl -X DELETE \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/myKeystoreName \
-u myname:mypass

Sample response:

{
 "certs" : [ ],
 "keys" : [ ],
 "name" : "myKeystoreName"
}

If you delete and recreate a keystore or truststore that is being used by a virtual host, then you must redeploy your API proxies. See Understanding deployment.

Get SSL certificate details

You can use the Get a Cert from a Keystore or Truststore API to view details about SSL 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 myname:mypass

Sample response:

{
 "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 myname:mypass

Sample response:

{
 "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=&quot;GoDaddy.com, Inc.&quot;, 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 https://enterprise.apigee.com (cloud) or http://<ms-ip>:9000 (on-premises), where <ms-ip> is the IP address of the Management Server node.
  2. In the Edge management UI menu, select Admin > SSL Certificates.

Update an expired certificate

If an SSL certificate expires, then you need to update the certificate. The process of updating a certificate depends on your deployment of Edge: cloud or on-premises.

You cannot update an existing keystore to add a new certificate. You must create a new keystore when updating a certificate.

Cloud deployment

For a cloud-based deployment of Edge:

  1. Create a new keystore as described above.
  2. Upload a new JAR file containing the new certificate and private key to the keystore.
  3. For inbound connections, meaning an API request into Edge, contact Apigee Customer Support to update the virtual host configuration to reference the the new keystore and key alias.
  4. 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.  

On-premises deployment

For an on-premises deployment of Edge:

  1. Create a new keystore as described above.
  2. Upload a new JAR file containing the new certificate and private key to the keystore.
  3. For inbound connections, meaning an API request into Edge:
    1. Update any virtual hosts that referenced the old keystore and key alias to reference the new keystore and key alias.
    2. Restart the routers, one at a time.

      No proxy redeployment required.
  4. 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. 

Get help

For help, see Apigee Customer Support.

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)