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.
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.
To use a certificate chain provided by a certificate authority, you will need to perform several additional steps. These are documented below.
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.
Private key extracted from certificate chain.
Client certificate extracted from certificate chain.
Temporary keystore containing client certificate and associated private key.
Final PKCS12 keystore file for use by the Java Communications Process (JCP).
$ openssl pkcs12 -in wildcard_company_local.pfx -infoEnter Import Password: <Enter the password provided with your certificate>MAC Iteration 2000MAC verified OKPKCS7 DataShrouded Keybag: pbeWithSHA1And3-KeyTripleDES-CBC, Iteration 2000Bag Attributes localKeyID: 01 00 00 00 Microsoft CSP Name: Microsoft RSA SChannel Cryptographic Provider friendlyName: MyCompanyServerAuthenticationKey Attributes X509v3 Key Usage: 10Enter 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 DataCertificate bagBag Attributes: <Empty Attributes>subject=/C=US/O=MyCompany/CN=MyCompany Root CAissuer=/C=US/O=MyCompany/CN=MyCompany Root CA-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----Certificate bagBag Attributes: <Empty Attributes>subject=/C=US/O=MyCompany/CN=MyCompany Intermediary CAissuer=/C=US/O=MyCompany/CN=MyCompany Root CA-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----Certificate bagBag Attributes localKeyID: 01 00 00 00subject=/C=US/O=MyCompany/CN=ae-test.mycompany.comissuer=/C=US/O=MyCompany/CN=MyCompany Intermediary CA-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----
$ openssl pkcs12 -in ./wildcard_company_local.pfx -nocerts -out ./wildcard_company_local.keyEnter Import Password:<Enter the password provided with your certificate>MAC verified OKEnter PEM pass phrase: <For simplicity, use the same password>Verifying - Enter PEM pass phrase: <Re-enter the same password again>
$ openssl pkcs12 -in ./wildcard_company_local.pfx -clcerts -nokeys -out ./wildcard_company_local.crtEnter Import Password: <Enter the password provided with your certificate>MAC verified OK
$ openssl pkcs12 -inkey ./wildcard_company_local.key -in ./wildcard_company_local.crt -export -out ./wildcard_company_local.pkcs12Enter 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>
$ 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
$ keytool -list -v -keystore ./httpsRESTKeyFileEnter keystore password: <Enter the same password as above>Keystore type: PKCS12Keystore provider: SunJSSEYour keystore contains 1 entryAlias name: jettyCreation date: Sep 1, 2021Entry type: PrivateKeyEntryCertificate chain length: 1Certificate:...
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.
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.
2021.09.20Added instructions for setting hostname parameter in ucsrv.ini file, and instructions for installing CA certificates for the AWI.2021.09.01Initial version.