Skip to main content

Managing Certificates

IBM Application Gateway (IAG) handles all configuration data as text, including certificates. Certificate data must always be provided to IAG as ASCII PEM-encoded data.

Working with Private Keys and Certificates

When handling private keys, IAG expects PEM-encoded data containing:

  • a private key
  • a certificate signed with the private key
  • the signer certificate or signer certificate chain (if required)

Note that the signer certificate may not be required if the certificate was issued by a recognised certificate authority, or if a self-signed certificate is being used.

When supplying this information to IAG, ensure that all of the data is in PEM-encoded format and concatenated into a single file, for example:

cat ca.pem ca-chain.pem server.pem server.key > iag-server-cert.pem

The resulting file can be used in the IAG configuration data whenever a private key and certificate is required.

server:
  ssl:
    front_end:
      certificate: "@iag-server-cert.pem"

Private keys and certificates are used by IAG in the following locations:

Location Purpose
server/ssl/front_end/certificate The application gateway front end. This is the default certificate which is presented by the HTTPS interface when clients connect to IAG. If this parameter is not specified, the application gateway will generate a self-signed certificate while bootstrapping.
server/ssl/front_end/sni[]/certificate The application gateway front end for a particular host when the client uses Server Name Indication (SNI) during the TLS handshake. The usage of SNI is optional and the default certificate will be used if SNI is not configured.
resource_servers[]/mutual_auth/certificate_auth/certificate Used by the application gateway to authenticate to a resource server when that resource server requires certificate based mutual authentication.

Generating a Self-Signed Private Key and Certificate

A private key and self-signed certificate can be generated using openssl:

openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout key.pem \
        -out cert.pem -subj /C=us/O=ibm/CN=www.iagdemo.com

The resulting private key and certificate are written to separate PEM-encoded files.

IAG expects both the private key and certificate to be provided in a single file, so the private key and certificate should be concatenated into a single file:

cat cert.pem cert.key > test-iag.cer

This resulting file can then be provided to IAG:

server:
  ssl:
    front_end:
      certificate: "@test-iag.cer"

Using an Existing Private Key and Certificate from a PKCS12 key archive

To use an existing certificate and key from a PKCS12 key archive, the contents must first be extracted to a PEM encoded certificate file. For example:

openssl pkcs12 -in "test-iag.p12" -out "test-iag.pem" -nodes

Note that the source PKCS12 key archive is typically password protected and this operation will produce an PEM-encoded file which is not protected.

The resulting PEM-encoded file can then be provided to IAG:

server:
  ssl:
    front_end:
      certificate: "@test-iag.cer"

Trusting Certificates

If a resource server presents a certificate which was not signed by a known certificate authority, the certificate of the signer must be supplied to IAG. IAG does not trust certificates signed by unknown certificate authorities and will not establish TLS connections to servers presenting certificates which are not trusted.

When handling signer certificate data, IAG expects PEM-encoded data containing:

  • the signer certificate or signer certificate chain.

Note that a signer certificate may not be required if the remote server certificate was issued by a recognised certificate authority.

To provide a signer certificate and chain to IAG, ensure that the certificate data is in PEM-encoded format and concatenated into a single file:

cat resource-ca.pem resource-ca-chain.pem > resource_server.pem

If the required certificate data is just a single certificate, ensure that it is PEM-encoded and provide it as-is.

resource_servers:
  - path: /iagExample
    connection_type: ssl
    ...
    servers:
      - host: exampleHost.ibm.com
        port: 443
        ...
        ssl:
          certificate: "@resource_server.pem"

Signer certificates are used in IAG configuration for:

Location Purpose
resource_servers[]/servers[]/ssl/certificate A signer certificate (if required) that the application gateway can use to assert that it should trust the certificate presented by the resource server.

Retrieving Certificate Data from Remote Servers

If you do not have the certificate or certificate chain for a remote server, openssl can be used to establish a TLS connection to the server and print the certificates presented by the server.

The following command can be used to retrieve the certificate or certificate chain from a remote server.

openssl s_client -showcerts -host "$HOSTNAME" -port "$PORT" < /dev/null | 
    sed -ne '/-----BEGIN CERTIFICATE-----/,/-----END CERTIFICATE-----/p' 
    > resource_server.pem

The created file 'resource_server.pem' will contain the root certificate from the server in PEM-encoded format. Providing this root certificate is the CA certificate it can then be used with IAG.

Note that manual inspection should be performed on the certificate data retrieved using this method to ensure it is correct.

Default Trusted Certificate Authority Certificates

The following certificates are trusted by default:

  • "DigiCert Global Root CA"
  • "Entrust Root Certification Authority - EC1"
  • "Entrust Root Certification Authority - EV"
  • "Entrust Root Certification Authority - G2"
  • "Entrust.net Certification Authority (2048) 29"
  • "Entrust.net Certification Authority (2048)"
  • "Entrust.net Global Client Certification Authority"
  • "Entrust.net Global Secure Server Certification Authority"
  • "Thawte Personal Basic CA"
  • "Thawte Personal Freemail CA"
  • "Thawte Personal Premium CA"
  • "Thawte Premium Server CA"
  • "Thawte Primary Root CA - G2 ECC"
  • "Thawte Primary Root CA"
  • "Thawte Server CA"
  • "VeriSign Class 1 Public Primary Certification Authority - G2"
  • "VeriSign Class 1 Public Primary Certification Authority - G3"
  • "VeriSign Class 1 Public Primary Certification Authority"
  • "VeriSign Class 2 Public Primary Certification Authority - G2"
  • "VeriSign Class 2 Public Primary Certification Authority - G3"
  • "VeriSign Class 2 Public Primary Certification Authority"
  • "VeriSign Class 3 Public Primary Certification Authority - G2"
  • "VeriSign Class 3 Public Primary Certification Authority - G3"
  • "VeriSign Class 3 Public Primary Certification Authority - G5"
  • "VeriSign Class 3 Public Primary Certification Authority"
  • "VeriSign Class 4 Public Primary Certification Authority - G2"
  • "VeriSign Class 4 Public Primary Certification Authority - G3"