Automic Workload Automation

Enabling SSL for the JCP

  • 1.  Enabling SSL for the JCP

    Posted 09-20-2021 08:19 AM
    Edited by Michael A. Lowry 09-22-2021 02:42 AM

    Introduction

    Below are instructions for enabling SSL-secured HTTP (HTTPS) for the Java Communications Process (JCP). These instructions are based on KB94420: How to implement HTTPS for JCP.

    The JCP requires a PKCS12 keystore containing a client certificate with the alias jetty. If the certificate is not self-signed, then an appropriate trust chain must be included in the keystore. The AWI must also be configured to trust the server certificate of the JCP.

    Self-signed certificate

    It's possible to create keystore with a self-signed certificate using a single keytool¹ command:

    $ keytool -keystore ./httpsRESTKeyFile -alias jetty -genkey -keyalg RSA -sigalg SHA256withRSA

    This will allow you to get up and running quickly, or to validate the HTTPS capability of the JCP on a test system. However, for production or customer-facing environments, it is important to use a certificate provided by a trusted certificate authority.

    Certificate from a certificate authority (CA)

    To use a certificate chain provided by a certificate authority, you will need to perform several additional steps. These are documented below.

    Description of file names

    File name

    Description

    wildcard_company_local.pfx

    Certificate chain provided by a certificate authority. This file will typically contain the client certificate for the node running the JCP, a private key, and one or more CA certificates from the relevant certificate authority - either a public CA or one operated by your company. This chain of trust guarantees that the client certificate is genuine.

    wildcard_company_local.key

    Private key extracted from certificate chain.

    wildcard_company_local.crt

    Client certificate extracted from certificate chain.

    wildcard_company_local.pkcs12

    Temporary keystore containing client certificate and associated private key.

    httpsRESTKeyFile

    Final PKCS12 keystore file for use by the Java Communications Process (JCP).

    Instructions

    1. Obtain a server certificate for the server where the JCP will run. The name of the server in the certificate can be either the server's DNS hostname or alias. The name in the certificate and the value of the hostname parameter in the ucsrv.ini file must match. The certificate will typically be provided in the form of a trust chain containing the server certificate plus a chain of parent CA certificates and

    2. Validate the contents of the PKCS12 trust chain provided by the certificate authority (CA). The file typically contains several parts, including a private key, a root CA certificate, one ormore intermediary CA certificates, and the client certificate for the host where you will run the Java Communications Process (JCP).
    $ openssl pkcs12 -in wildcard_company_local.pfx -info
    Enter Import Password: <Enter the password provided with your certificate>
    MAC Iteration 2000
    MAC verified OK
    PKCS7 Data
    Shrouded Keybag: pbeWithSHA1And3-KeyTripleDES-CBC, Iteration 2000
    Bag Attributes
        localKeyID: 01 00 00 00
        Microsoft CSP Name: Microsoft RSA SChannel Cryptographic Provider
      friendlyName: MyCompanyServerAuthentication
    Key Attributes
        X509v3 Key Usage: 10
    Enter PEM pass phrase: <For simplicity, use the same password>
    Verifying - Enter PEM pass phrase: <Re-enter the same password again>
    -----BEGIN ENCRYPTED PRIVATE KEY-----
    ...
    -----END ENCRYPTED PRIVATE KEY-----
    PKCS7 Data
    Certificate bag
    Bag Attributes: <Empty Attributes>
    subject=/C=US/O=MyCompany/CN=MyCompany Root CA
    issuer=/C=US/O=MyCompany/CN=MyCompany Root CA
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----
    Certificate bag
    Bag Attributes: <Empty Attributes>
    subject=/C=US/O=MyCompany/CN=MyCompany Intermediary CA
    issuer=/C=US/O=MyCompany/CN=MyCompany Root CA
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----
    Certificate bag
    Bag Attributes
        localKeyID: 01 00 00 00
    subject=/C=US/O=MyCompany/CN=ae-test.mycompany.com
    issuer=/C=US/O=MyCompany/CN=MyCompany Intermediary CA
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----

    3. Extract the private key.
    $ openssl pkcs12 -in ./wildcard_company_local.pfx -nocerts -out ./wildcard_company_local.key
    Enter Import Password:
    <Enter the password provided with your certificate>
    MAC verified OK
    Enter PEM pass phrase: <For simplicity, use the same password>
    Verifying - Enter PEM pass phrase: <Re-enter the same password again>

    4. Extract the client certificate.
    $ openssl pkcs12 -in ./wildcard_company_local.pfx -clcerts -nokeys -out ./wildcard_company_local.crt
    Enter Import Password: <Enter the password provided with your certificate>
    MAC verified OK

    5. Combine the private key and certificate into a single file.
    $ openssl pkcs12 -inkey ./wildcard_company_local.key -in ./wildcard_company_local.crt -export -out ./wildcard_company_local.pkcs12
    Enter pass phrase for ./wildcard_company_local_key: <Enter the same password as above>
    Enter Export Password: <Use the same password as above>
    Verifying - Enter Export Password: <Re-enter the same password as above>

    6. Convert the combined key/certificate file to a PKCS12 keystore using the keytool¹ program.
    $ keytool -importkeystore -srckeystore ./wildcard_company_local.pkcs12 -destkeystore ./httpsRESTKeyFile -srcstoretype PKCS12 -alias "1" -destalias "jetty"
    Importing keystore ./wildcard_company_local.pkcs12 to ./httpsRESTKeyFile...
    Enter destination keystore password: <Enter the same password as above>
    Enter source keystore password: <Enter the same password as above>
    Existing entry alias 1 exists, overwrite? [no]: yes

    7. List out the keystore contents to confirm that all of the parts are there.
    $ keytool -list -v -keystore ./httpsRESTKeyFile
    Enter keystore password: <Enter the same password as above>
    Keystore type: PKCS12
    Keystore provider: SunJSSE

    Your keystore contains 1 entry

    Alias name: jetty
    Creation date: Sep 1, 2021
    Entry type: PrivateKeyEntry
    Certificate chain length: 1
    Certificate[1]:
    ...

    Under the heading Extensions, you should typically see sections labeled AuthorityInfoAccess, AuthorityKeyIdentifier, CertificatePolicies, ExtendedKeyUsages, KeyUsage, SubjectAlternativeName, and SubjectKeyIdentifier.

    8. Copy your company's CA certificates file (cacerts) the AWI installation directory and add two Java system properties to JAVA_OPTS before starting the AWI.

    -Duser.timezone=Europe/Zurich -Djavax.net.ssl.trustStore=$PWD/cacerts

    The first system property just tells the AWI what time zone to use, and this should be your local time zone. The second system property tells the AWI where to find the trust store containing the CA certificates. This will make the AWI trust the certificate authority. This in turn will make the AWI trust the JCP's server certificate, because its trust chain is based the parent CAs.

    Note

    1. To create a PKCS12 keystore using the keytool program, it may be necessary to first set keystore.type to pkcs12 in the Java security properties file $JAVA_HOME/../lib/security/java.security. See the Oracle documentation page for keytool for more information.

     


    Revision history

    2021.09.20
    Added instructions for setting hostname parameter in ucsrv.ini file, and instructions for installing CA certificates for the AWI.
    2021.09.01
    Initial version.