Send Docs Feedback

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 used to identify the entity during SSL handshaking.

    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 (CA), such as Symantec or VeriSign.

    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 optionally contains certificates used to verify certificates received as part of SSL handshaking. A truststore is not required. If the certificate received by an SSL client is signed by a valid CA, then the client makes a request to the CA to authenticate the certificate.

    In one-way SSL, an SSL client typically uses a truststore to validate self-signed certificates received from the SSL 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, an SSL client connects to an SSL 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 the its truststore to validate the certificate received from the server.

    For two-way SSL, both the SSL client and the the SSL server can use a truststore. 

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:

  • 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 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 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 SSL followed by the chain of certs, in order, to the CA certificate.

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 or truststore, then 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:

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

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

[ "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 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 email:password

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 email:password

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

{  
 "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 must create a truststore on Edge as part of configuring two-way SSL between an SSL client and Edge, where Edge acts as the SSL server. When you configure the truststore on Edge, upload the cert that you received from the client. During SSL 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. 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 email:password

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

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

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 Cert Details 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 email:password

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 email:password

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.

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.  

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.

You can optionally choose to delete the existing keystore and then create a new one with the same name. However, for the time from when the certificate expired until you create the new keystore, you cannot service requests.


If the keystore is used for two-way SSL between Edge and the backend service, and you are using Edge for the Private Cloud, then after deleting and recreating the keystore with the same name, you must restart the Edge Message Processors.


Typically, you create a new keystore before the current certificate expires, and then update your virtual hosts or target endpoints to use the new keystore so that you can continue to service requests without interruption due to an expired certificate. You can then delete the old keystore after ensuring that the new keystore is working correctly.


To check when a certificate is due to expire, go to the Admin > SSL Certificates menu in the Edge management UI. You can also configure that page to indicate if a certificate is due to expire in 10, 15, 30, or 90 days.   

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.  
  5. After you have confirmed that your new keystore is working correctly, delete the old keystore with the expired cert and key as described above.

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. Note that if you deleted the old keystore and created a new keystore with the same name, then no Router restart is necessary.

      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. For any API proxies that reference the keystore and truststore from a TargetEndpoint definition, 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. 
    3. If the keystore is used for two-way SSL between Edge and the backend service, and you deleted/recreated the keystore with the same name, you must restart the Edge Message Processors.
  5. After you have confirmed that your new keystore is working correctly, delete the old keystore with the expired cert and key as described above.

Update your truststore for an expired Apigee cert

Apigee provides all Cloud customers with a cert when they create an account so that the customer can get up and running quickly with Edge. All Cloud customers get a copy of the same Apigee-provided cert.

Based on when you obtained your cert, the Apigee cert will expire on either February 23, 2016 or April 8, 2016. Apigee will be updating all keystores before those dates to upload a new cert and private key.

However, if you have uploaded the Apigee cert to a truststore, you must add the new Apigee cert to your truststore before it expires. You do not have to delete the old Apigee cert, you only have to upload the new one.

Shown below is the new cert:

-----BEGIN CERTIFICATE-----
MIIFHzCCBAegAwIBAgIISzef6agJ+w4wDQYJKoZIhvcNAQELBQAwgbQxCzAJBgNV
BAYTAlVTMRAwDgYDVQQIEwdBcml6b25hMRMwEQYDVQQHEwpTY290dHNkYWxlMRow
GAYDVQQKExFHb0RhZGR5LmNvbSwgSW5jLjEtMCsGA1UECxMkaHR0cDovL2NlcnRz
LmdvZGFkZHkuY29tL3JlcG9zaXRvcnkvMTMwMQYDVQQDEypHbyBEYWRkeSBTZWN1
cmUgQ2VydGlmaWNhdGUgQXV0aG9yaXR5IC0gRzIwHhcNMTYwMTEzMTcyNTU0WhcN
MTkwNDA5MDYzNzEwWjA6MSEwHwYDVQQLExhEb21haW4gQ29udHJvbCBWYWxpZGF0
ZWQxFTATBgNVBAMMDCouYXBpZ2VlLm5ldDCCASIwDQYJKoZIhvcNAQEBBQADggEP
ADCCAQoCggEBALRAjJBUiGcKTEye40tpQjqGnAYn+LgpfS8Wkhh5nUZFvJBbEVDe
heH4Agc1LILOExEtKj/bGRhhFQzojSfTmz3LuGA8oVnzzOamYDvzkTkK5yO+Yd2C
FXgEOQhphcaZms2Z1Kl9cn1fQRl/+KUbiKgV/piu4079cnPqR8uME94mWnHpRurd
ZJqfOxpz+144RbTNaSJdQdiPQ1vzxmLQFFN2SrbWx4OXni/C5QJ0S14uplZHgw+j
Ae/LGAiaJR7nirot3QEk7qdYRF6g86OvrpToDbG6vKSyuIXoOT33oBJnjfFQRkq+
29VcMWwWLe6lmToGpp0xkNxdeyFB0oyQqFsCAwEAAaOCAawwggGoMAwGA1UdEwEB
/wQCMAAwHQYDVR0lBBYwFAYIKwYBBQUHAwEGCCsGAQUFBwMCMA4GA1UdDwEB/wQE
AwIFoDA3BgNVHR8EMDAuMCygKqAohiZodHRwOi8vY3JsLmdvZGFkZHkuY29tL2dk
aWcyczEtMTc4LmNybDBTBgNVHSAETDBKMEgGC2CGSAGG/W0BBxcBMDkwNwYIKwYB
BQUHAgEWK2h0dHA6Ly9jZXJ0aWZpY2F0ZXMuZ29kYWRkeS5jb20vcmVwb3NpdG9y
eS8wdgYIKwYBBQUHAQEEajBoMCQGCCsGAQUFBzABhhhodHRwOi8vb2NzcC5nb2Rh
ZGR5LmNvbS8wQAYIKwYBBQUHMAKGNGh0dHA6Ly9jZXJ0aWZpY2F0ZXMuZ29kYWRk
eS5jb20vcmVwb3NpdG9yeS9nZGlnMi5jcnQwHwYDVR0jBBgwFoAUQMK9J47MNIMw
ojPX+2yz8LQsgM4wIwYDVR0RBBwwGoIMKi5hcGlnZWUubmV0ggphcGlnZWUubmV0
MB0GA1UdDgQWBBROfmwEgDjmhQL41zDFmOsQ/Z/ARTANBgkqhkiG9w0BAQsFAAOC
AQEAq0MW3tOUPPdujGc2JLhd3SpYXCoHvps7JkjJ0yHurzXkCmnDHLAfYYXbu7Ei
B+k3anDavgGpO7odJQaoYtbpTCfZHRlUWSaT0Xef3UUIAMuu2bKIaNIYRTKUA7Jj
X4pCVTQCKHuoYMFjTAqm6d+q68WMv2oW6EERjf0irw++Yecuq+CllKIOird2zS73
Fc3RTp1LcM+J0AwHkA3r8KSCQhsqLdn/Y0JTxJ8d2E4RYH2jpkMB1ogA1/VUj9ZW
xTUVrk3Duw4Wq/66mPpQVGZHfRDJ9TBF5Qt8iUKxEIt4IzaWmk70049ygab29XaC
xaC2QIzKJJbBueo76nvKKpfeGQ==
-----END CERTIFICATE-----
Copy this cert to a PEM file, and then upload the certificate to your truststore. The way you update your truststore is based on it's location and implementation. For example, if it is on your backend servers, use the procedure based on your server implementation.
 
If you are updating a truststore on Edge, use the Upload a Certificate to a Truststore API:
$ curl -X POST -H "Content-Type: multipart/form-data" -F file="@newapigeecert.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.

 

 

Help or comments?