Use the following procedure to configure an SSL certificate for the Server Automation REST API.

If necessary, review the OpenSSL documentation at http://www.openssl.org for information about OpenSSL commands and options.

 

Procedure

1. Generate a Certificate Signing Request (CSR) and private key. To do this, using openssl, enter a command such as the following:

$> openssl req -nodes -newkey rsa:4096 -keyout <hostname>.key -out <hostname>.csr -sha512 -subj '/C=<country>/ST=<state>/L=<location>/O=<organization>/OU=<unit>/CN=<hostname>/subjectAltName=DNS.1=<hostname(not fully qualified)>'
  

Example: to create a request for host 'serverA.acme.com' for an organization called ACME Inc:
$> openssl req -nodes -newkey rsa:4096 -keyout serverA.key -out serverA.csr -sha512 -subj '/C=US/ST=CA/L=Los Angeles/O=ACME Inc./OU=IT Dept./CN=serverA.acme.com/subjectAltName=DNS.1=serverA'

 

2. Have the CSR signed by your organization's (or an external) Certificate Authority (CA) and a signed certificate will be returned (the actual file extension or the returned cert might vary, for example 'serverA_signed.crt' or 'serverA_signed.pem').

Check the contents of the certificate using a command such as:
$> openssl x509 -in <certificate_file> -text -noout

 

Example:
$> openssl x509 -in serverA_signed.crt -text -noout

3. PKCS12 format, which combines the certificate and private key into a single file, is required so the artifacts will need to be converted (again, using openssl here). The CA public certificate file should be provided to you by the CA used to sign the CSR in step (1).

A new password (e.g. "changeit") is required when prompted:

$> openssl pkcs12 -export -in <signed_cert_file> -inkey <hostname>.key -out <hostname>.p12 -name default -CAfile <CA_cert_file>
 

Example:
$> openssl pkcs12 -export -in serverA_signed.crt -inkey serverA.key -out serverA.p12 -name default -CAfile acme_ca.crt
$> Enter Export Password: changeit
$> Verifying - Enter Export Password: changeit

4. Shut down the Server Automation REST API by stopping the 'WASLiberty' Windows service.
5. The default location for the Java Keystore used by SA REST is C:\WASLiberty\wlp\usr\servers\defaultServer\resources\security\key.jks. You must overwrite that with a new Java Keystore file with the PKCS12 certificate imported into it. Firstly, if this JKS file already exists, rename it to something else.

$> cd C:\WASLiberty\wlp\usr\servers\defaultServer\resources\security
$> move key.jks key.jks.orig
$> keytool -importkeystore -deststorepass <new_keystore_password> -destkeypass <new_key_password> -destkeystore key.jks -srckeystore <full_path_to_<hostname>.p12> -srcstoretype PKCS12 -srcstorepass <pass_used_in_p12_keystore> -alias default

Example (assuming serverA.p12 is located in C:\certs\):

$> "C:\WASLiberty\wlp\service\ibm-java-jre-8011-win-i386\jre\bin\keytool.exe" -importkeystore -deststorepass changeit -destkeypass changeit -destkeystore key.jks -srckeystore C:\certs\serverA.p12 -srcstoretype PKCS12 -srcstorepass changeit -alias default

 Note: use the keytool.exe file that comes bundled with the Server Automation REST API for this, as shown in the example. The default location is: C:\WASLiberty\wlp\service\ibm-java-jre-8011-win-i386\jre\bin\keytool.exe

6. Check the contents of the new keystore, as follows:

$> keytool -list -v -keystore key.jks
 

Example:
$> "C:\WASLiberty\wlp\service\ibm-java-jre-8011-win-i386\jre\bin\keytool.exe" -list -v -keystore key.jks
Enter keystore password: changeit

Keystore type: jks
Keystore provider: IBMJCE

Your keystore contains 1 entry

Alias name: default
...
 

7. Update the server.xml file (located at C:\WASLiberty\wlp\usr\servers\defaultServer\server.xml by default) if necessary to point to the newly created keystore. You do not need to perform this step if the keystore created in step (5) was "C:\WASLiberty\wlp\usr\servers\defaultServer\resources\security\key.jks". However, you must update the password in server.xml if you are not using "changeit" in the steps above.

...
<!--+

| SECURITY CONFIGURATIONS
+-->

<sslDefault sslRef="defaultSSLSettings"/>
  <keyStore id="defaultKeyStore" password="changeit"/>
  <ssl id="defaultSSLSettings" keyStoreRef="defaultKeyStore" sslProtocol="TLSv1.2"/>
  ...

8. Restart the Server Automation REST API by starting the 'WASLiberty' Windows service.
9. If not already present, the public certificate of the CA used to sign the new server certificate must be imported (and trusted as a CA) into any client (such as a browser) connecting to the SA REST API.