Setting up certificates for a self-managed gateway

Generate certificates to secure a self-managed gateway, and import them into either the API Connect built-in certificate management tool, or to IBM Cloud Secrets Manager.

1. On your computer, open a command window and navigate to a folder where you can create and store the certificates.
2. Use OpenSSL to generate a CA key and certificate.

   This step is optional if you plan to use a third-party certificate authority (such as Digicert or Let'sEncrypt) to generate certificates. Having a central CA is important for supporting certificate rotation without worrying about re-trusting either side.

   1. Run the following command to create the CA private key:

      openssl genrsa -out ca.key 2048

   2. Run the following command to create the CA certificate:

      openssl req -new -x509 -days 3650 -key ca.key -out ca.pem

      Provide inputs to the prompts according to your organization's needs.

3. Generate a server key and certificate (for trust)

   Generate the certificate that the server (DataPower, in this case) will present to the client (API Connect API Manager). The server key and certificate establish one-way trust, enabling API Manager to view DataPower as "trustworthy."

   1. Create a file named server_cert_ext.cnf and paste the following content into it to define acceptable certificate extensions:

      basicConstraints = CA:FALSE
      nsCertType = server
      nsComment = "OpenSSL Generated Server Certificate"
      subjectKeyIdentifier = hash
      authorityKeyIdentifier = keyid,issuer:always
      keyUsage = critical, digitalSignature, keyEncipherment
      extendedKeyUsage = serverAuth

   2. Generate a new private key for the server by running the following command:

      openssl genrsa -out server.key 2048

   3. Generate a new certificate signing request by running the following command, which uses the private key that you generated in the previous step:

      openssl req -new -key server.key -out server.csr

      Provide inputs to the prompts according to your organization's needs.

      Important: Ensure that the "common name" exactly matches the FQDN of your DataPower Gateway Director endpoint (for example, rgwd.apic.acme.com).
   4. Generate the server certificate by running the following command, which uses the CSR and extension file:

      openssl x509 -req -in server.csr -CA ca.pem -CAkey ca.key -out server.pem -CAcreateserial -days 265 -sha256 -extfile server_cert_ext.cnf

4. Generate a client key and certificate (for authentication)

   Create the certificate that allows API Manager to authenticate with the gateway server.

   1. Create a file named client_cert_ext.cnf and paste the following content into it to define acceptable certificate extensions:

      basicConstraints = CA:FALSE
      nsCertType = client
      nsComment = "OpenSSL Generated Client Certificate"
      subjectKeyIdentifier = hash
      authorityKeyIdentifier = keyid,issuer
      keyUsage = critical, nonRepudiation, digitalSignature, keyEncipherment
      extendedKeyUsage = clientAuth

   2. Generate the client key by running the following command:

      openssl genrsa -out client.key 2048

   3. Generate a certificate signing request by running the following command, which uses the client key that you created in the previous step:

      openssl req -new -key client.key -out client.csr

   4. Generate the client certificate by running the following command:

      openssl x509 -req -in client.csr -CA ca.pem -CAkey ca.key -out client.pem -CAcreateserial -days 265 -sha256 -extfile client_cert_ext.cnf

   You now have a client certificate that can authenticate with the gateway director endpoint.

5. If you are using IBM Cloud Secrets Manager, import the certificates:

   If you are using the API Connect built-in certificate management tool, skip this step and proceed to step 6.

   1. Log in to IBM Cloud.
   2. Provision an instance of IBM Cloud Secrets Manager.

      API Connect V10 Reserved requires you to secure the gateway using IBM Cloud Secrets Manager. For more information on managing certificates with IBM Cloud Secrets Manager, see Getting Started with Secrets Manager.

   3. Upload the certificates that you generated for the new gateway.

      When you register the DataPower gateway with API Connect V10 Reserved instance, select the certificates that you stored in IBM Cloud Secrets Manager.

6. If you are using the API Connect built-in certificate management tool, import the certificates:
   1. In your API Connect Reserved instance, click the Configure TLS tile on the administration Home page.
   2. Set up a truststore with CA certificates:
      1. In the "Truststores" section, click Create.
      2. On the Create Truststore page, provide a Title for the truststore.
      3. Upload your CA certificates in .pem format.
      4. Click Save.
   3. Set up a keystore with the client key and the client certificates:
      1. In the "Keystores" section, click Create.
      2. On the Create Keystore page, provide a Title for the keystore
      3. In the Step 1: Upload private key section, upload your certificate and key using the appropriate method:
         • If your file uses the .p12 extension, upload it.
         • If your file uses the .pfx extension, rename the file to use the .p12 extension, and then upload it. .pfx files are not supported in the API Connect built-in certificate management tool.
         • If you have certificates and a key as 2 separate files using the .pem and .key formats, choose one of the following methods:
           • Create a new .pem file and populate it with the contents of both the .pem and the .key files, and then upload it (omitting the key results in an error).
           • Create a new .p12 file using the .pem and .key files.
             You can use the following command for generating .p12 files:

             openssl pkcs12 -export -out <filename.p12> -inkey <privatekey.key> -in <cert.pem or cert.cer or cert.crt>

             If you are prompted for an export password and the file is assigned with a password, enter the password in the Private key password field.
   4. Set up a keystore with the server key and the server certificates.

      Use the instructions from setting up the client keystore in step (6.c).

   5. Set up a TLS client profile with a matching keystore and truststore:
      1. In the TLS Client Profile section, click Create.
      2. On the Create TLS Client Profile page, provide a Title for the TLS client profile.
      3. In the "Keystore/truststore" section, click Keystore and select the keystore containing the client certificate and the private key.
      4. Click Truststore and select the truststore containing the CA certificates.
      5. Click Save.
   6. Set up a TLS server profile with a matching keystore and truststore:
      1. In the TLS Server Profile section, click Create.
      2. On the Create TLS Server Profile page, provide a Title for the TLS server profile.
      3. In the "Keystore/truststore" section, click Keystore and select the keystore containing the server certificate and the private key.
      4. Click Save.

   When you register the DataPower API Gateway with your V10 Reserved instance, use the TLS client profile and TLS server profile that you created.