Create keystores and truststores for the Private Cloud version 4.17.09 and earlier

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. 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.

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.

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:

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

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

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

Get TLS certificate details

You can use the Get Cert Details from a Keystore or Truststore 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:

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

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:

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

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

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

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