How to enable SSL on Jetty for HTTPS in REST API. |
This knowledge article may contain information that does not apply to version 21.05 or later which runs in a container environment. Please refer to Article Number 000385088 for more information about troubleshooting BMC products in containers. Important: This procedure assumes that you already have a Keystore and an SSL Certificate ready for use in Jetty. If you require more information on how to create, import or manage a Keystore or SSL Certificate, you can find the following resources: Keytool: Manage a keystore (database) of cryptographic keys, X.509 certificate chains, and trusted certificates. Pre-requisites You need a Java based Keystore with an SSL Certificate signed; it could be:
Self Signed Certificates are not recommended for Production environments. Configuration files and their differences across different versions AR Server from 9.0 to 9.1.03: The main configuration file is: <ARSystem>/jetty/etc/jetty-selector.xml AR Server 9.1.04 and newer: The main configuration file is: <ARSystem>/jetty/etc/jetty-http.xml Steps to enable SSL 1.- In your AR Server, navigate to the following location: <ARSystem>/jetty/etc
2.- Place your Keystore file in this location;/etc/ will become your Application's Root 3.- Open your configuration file: <jetty-selector.xml> or <jetty-http.xml> 4.- Locate the HTTPS Connector and un-comment it. 5.- Locate the following strings, and configure the name of your keystore: jetty-selector.xml
<Set name="keyStore"><Property name="jetty.home" default="." />/etc/<Your_Keystore_File></Set> <Set name="trustStore"><Property name="jetty.home" default="." />/etc/<Your_Keystore_File></Set> jetty-http.xml <Set name="KeyStorePath"><Property name="jetty.home" default="." />/etc/<Your_Keystore_File></Set> <Set name="TrustStorePath"><Property name="jetty.home" default="." />/etc/<Your_Keystore_File></Set> 6.- Obfuscate the password for security purposes: 6.1) Navigate to the following directory: <ARSystem>/lib/start/startlevel1
6.2) Locate the jetty-util JAR file. (i.e jetty-util-9.4.15.v20190215.jar for 20.02). 6.3) Execute the following command on a CMD (Windows) or Console (Unix), for example: java -cp jetty-util-9.4.15.v20190215.jar org.eclipse.jetty.util.security.Password jetty <password_to_obfuscate> Note:
If Java is not configured in your Environment variables, you can call java with the full path. i.e: (Windows) C:\Java\bin\java -cp jetty-util-9.4.15.v20190215.jar org.eclipse.jetty.util.security.Password jetty <password_to_obfuscate> (Unix) /opt/java/bin/./java -cp jetty-util-9.4.15.v20190215.jar org.eclipse.jetty.util.security.Password jetty <password_to_obfuscate> 7.- Copy the OBF: string output and set this on your configuration file. <Set name="KeyManagerPassword">OBF:yourObfuscatedPassword</Set>
<Set name="KeyStorePassword">OBF:yourObfuscatedPassword</Set> <Set name="TrustStorePassword">OBF:yourObfuscatedPassword</Set> 8. - Save the changes. 9.- Make sure arserver.conf or arserverd.config includes the bouncycastle option. Add the option using the following statement as an example:
jvm.option.21=-Dorg.apache.activemq.broker.BouncyCastlePosition=100 Note: Use the next available number for the jvm.option.## relevant to your installation. The Bouncy Castle Crypto package is a Java implementation of cryptographic algorithms. The package is organized so that it contains a light-weight API suitable for use in any environment (including the newly released J2ME) with the additional infrastructure to conform the security algorithms to the JCE framework. 10.- Save changes and restart the AR Server. How to change the HTTPS port? By default, HTTPS port is set to 8443. If you require to change it, follow the next steps: A) On AR Server 9.1.03 or below: We only need to modify the jetty-selector.xml file. 1.- Locate and modify the following string at the end of your HTTPS Connector:
<Set name="port">8443</Set>
2.- Save changes and restart the AR Server.
B) On AR Server 9.1.04 or newer: We need to modify both, jetty-http.xml and jetty.xml file: 1.- In jetty-http.xml file, locate and modify the following string at the end of your HTTPS Connector:
<Set name="port">8443</Set>
2.- In jetty.xml file, locate and modify the following string:
<Set name="securePort">8443</Set>
3.- Save changes on both files and restart the AR Server.
How to check if REST API ports are working fine? You can follow the next article in order to check the REST API ports: TestHttpClient - Command line tool to test HTTP(S) services. In addition, you can enable the restapi.log or basic access logs for more details: Remedy - AR System Server - How to turn logging on for RESTAPI problems Remedy AR System Server - How to enable Jetty basic access logs for REST API Notes: If you are using OpenJDK (Or one of the latest JDK 1.8.0_X e.g. 1.8.0_271) consider adding Bouncy castle algorithm to your AR Server's arserver.config file in: (Unix): /opt/bmc/ARSystem/bin/arserverd.conf (Windows): C:\Program Files\BMC Software\ARSystem\arserver.config 1.- Add the following line at the end of your arserver.config / arserverd.conf file: jvm.option.<next_no>=-Dorg.apache.activemq.broker.BouncyCastlePosition=100 (Change <next_no> to the following number in your file). 2.- Restart AR Server. Video: |