The Unified Access Gateway capability in your pod requires SSL for client connections. When you want the pod to have a Unified Access Gateway configuration, the pod deployment wizard requires a PEM-format file to provide the SSL server certificate chain to the pod's Unified Access Gateway configuration. The single PEM file must contain the full entire certificate chain including the private key: the SSL server certificate, any necessary intermediate CA certificates, the root CA certificate, and private key.

For additional details about certificate types used in Unified Access Gateway, see the topic titled Selecting the Correct Certificate Type in the Unified Access Gateway product documentation.

In the pod deployment wizard step for the gateway settings, you upload a certificate file. During the deployment process, this file is submitted in to the configuration of the deployed Unified Access Gateway instances. When you perform the upload step in the wizard interface, the wizard verifies that the file you upload meets these requirements:

  • The file can be parsed as PEM-format.
  • It contains a valid certificate chain and a private key.
  • That private key matches the public key of the server certificate.

If you do not have a PEM-format file for your certificate information, you must convert your certificate information into a file that meets those above requirements. You must convert your non-PEM-format file into PEM format and create a single PEM file that contains the full certificate chain plus private key. You also need to edit the file to remove extra information, if any appears, so that the wizard will not have any issues parsing the file. The high-level steps are:

  1. Convert your certificate information into PEM format and create a single PEM file that contains the certificate chain and the private key.
  2. Edit the file to remove extra certificate information, if any, that is outside of the certificate information between each set of ----BEGIN CERTIFICATE---- and -----END CERTIFICATE----- markers.

The code examples in the following steps assume you are starting with a file named mycaservercert.pfx that contains the root CA certificate, intermediate CA certificate information, and private key.

Prerequisites

  • Verify that you have your certificate file. The file can be in PKCS#12 (.p12 or .pfx) format or in Java JKS or JCEKS format.
    Important: All certificates in the certificate chain must have valid time frames. The Unified Access Gateway VMs require that all of the certificates in the chain, including any intermediate certificates, have valid time frames. If any certificate in the chain is expired, unexpected failures can occur later as the certificate is uploaded to the Unified Access Gateway configuration.
  • Familiarize yourself with the openssl command-line tool that you can use to convert the certificate. See https://www.openssl.org/docs/apps/openssl.html.
  • If the certificate is in Java JKS or JCEKS format, familiarize yourself with the Java keytool command-line tool to first convert the certificate to .p12 or .pks format before converting to .pem files.

Procedure

  1. If your certificate is in Java JKS or JCEKS format, use keytool to convert the certificate to .p12 or .pks format.
    Important: Use the same source and destination password during this conversion.
  2. If your certificate is in PKCS#12 (.p12 or .pfx) format, or after the certificate is converted to PKCS#12 format, use openssl to convert the certificate to a .pem file.
    For example, if the name of the certificate is mycaservercert.pfx, you can use the following commands to convert the certificate:
    openssl pkcs12 -in mycaservercert.pfx -nokeys -out mycaservercertchain.pem
    openssl pkcs12 -in mycaservercert.pfx -nodes -nocerts -out mycaservercertkey.pem
    
    The first line above obtains the certificates in mycaservercert.pfx and writes them in PEM format to mycaservercertchain.pem. The second line above obtains the private key from mycaservercert.pfx and writes it in PEM format to mycaservercertkey.pem
  3. (Optional) If the private key is not in RSA format, convert the private key to the RSA private key format.
    The Unified Access Gateway instances require the RSA private key format. To check if you need to run this step, look at your PEM file and see if the private key information starts with
    -----BEGIN PRIVATE KEY-----
    If the private key starts with that line, then you should convert the private key to the RSA format. If the private key starts with -----BEGIN RSA PRIVATE KEY-----, you do not have to run this step to convert the private key.
    To convert the private key to RSA format, run this command.
    openssl rsa -in mycaservercertkey.pem -check -out mycaservercertkeyrsa.pem
    The private key n the PEM file is now in RSA format ( -----BEGIN RSA PRIVATE KEY----- and -----END RSA PRIVATE KEY-----).
  4. Combine the information in the certificate chain PEM file and private key PEM file to make a single PEM file.
    The example below shows a sample where the contents of mycaservercertkeyrsa.pem is first (the private key in RSA format), followed by the contents from mycaservercertchain.pem, which is your primary SSL certificate, followed by one intermediate certificate, followed by the root certificate.
    -----BEGIN CERTIFICATE-----
    .... (your primary SSL certificate)
    -----END CERTIFICATE-----
    -----BEGIN CERTIFICATE-----
    .... (the intermediate CA certificate)
    -----END CERTIFICATE-----
    -----BEGIN CERTIFICATE-----
    .... (the trusted root certificate)
    -----END CERTIFICATE-----
    -----BEGIN RSA PRIVATE KEY-----
    .... (your server key from mycaservercertkeyrsa.pem)
    ----- END RSA PRIVATE KEY-----
    Note: The server certificate should come first, followed by any intermediate ones, and then the trusted root certificate.
  5. If there are any unnecessary certificate entries or extraneous information between the BEGIN and END markers, edit the file to remove those.

Results

The resulting PEM file meets the requirements of the pod deployment wizard.