Configuring the REST API by using SSL certificates
The primary reason for using Secure Sockets Layer (SSL) certificates is to keep sensitive information sent across the internet encrypted so that only the intended recipient can understand it. This security is important because the information you send on the internet is passed from computer to computer to get to the recipient. Any computer between you and the destination can utilize your user name, passwords, and other sensitive information if the information is not encrypted with an SSL certificate.
In addition to encryption, a proper SSL certificate also provides authentication. With authentication, you can be sure that you are sending information to the right recipient and not to an unknown user. You can ensure authentication by using an SSL certificate from a trusted SSL provider.
The keytool utility is used to obtain a digitally signed certificate to replace the self-signed certificate. This utility is available with Oracle JDKs. The Java keytool is a key and certificate management utility. It allows users to manage their own public or private key pairs and certificates. The Java keytool stores the keys and certificates, which is called as keystore. A keystore contains the private key and any certificates necessary for authentication. The keystore is located in the JavaRuntimeEnvironmentHome/bin directory of your Java installation file.
Configuring the Jetty web server
You can create new keystores by configuring the REST API for an HTTPS or HTTP connection. See the following sections:
For information on troubleshooting Jetty startup issues, see BMC Knowledge Base article ID 000134172.
To configure the REST API for HTTPS connection
Import the existing signed primary certificate into an existing Java keystore:
keytool -import -trustcacerts -alias mydomain -file mydomain.crt -keystore keystore.jks
If you do not have a certificate, create a new keystore by using a new password to secure the certificate:
keytool -keystore keystore -alias jetty -genkey -keyalg RSA
After the keystore is created, provide six parameters that form a distinguished name for a certificate associated with the key.
- CN—Common Name of the certificate owner (usually the name of the host)
- OU—Organizational Unit of the certificate owner
- O—Organization to which the certificate owner belongs
- L—Locality name of the certificate owner
- ST—State or province of the certificate owner
C—Country of the certificate owner
Note
The keystore file is created in the current directory of the command window.
- Obfuscate the SSL connector keystore password for greater security.
For more information, see Obfuscating the password. Update the jetty-http.xml file with the new password for the keystore.
Note
* In
<Set name="KeyStorePath"><Property name="jetty.home" default="." />/etc/keystore</Set>
, remove<Property name="jetty.home" default="." />.
* Replace
/etc/keystore/
with the actual path to the keystore.Restart the AR System server.
After you restart the AR System sever, the following warning is displayed and you may experience runtime errors.
WARN:oejob.JettyBootstrapActivator:main: OSGi support for java.util.ServiceLoader may not be present.
To turn on the logging for Jetty
- In the arserver.config file (Windows) or arserverd.conf file (Linux), enable the Jetty log level and use the following JVM option:
-Dorg.eclipse.jetty.LEVEL=DEBUG
Enable extra Jetty logs in the Jetty/etc/Jetty.xml file. Refer to the following code sample:
<Call class="org.eclipse.jetty.util.log.Log" name="getRootLogger"> <Call name="setDebugEnabled"> <Arg type="boolean">false</Arg> </Call>
Here, set the boolean argument of the setDebugEnabled property to
true
.
After you enable the logging, the Jetty logs are displayed on the server console or in the armonitor.log file. For more information, see the knowledge article on BMC Communities How to turn logging on for RESTAPI problems .
After you create a self-signed certificate, browsers and other programs issue warnings to users about an insecure certificate each time the user authenticates. To prevent the certificate warning, add the self-signed certificate to the Trusted Root Certification Authorities store.
Obfuscating the password
The Jetty passwords are stored as clear text, obfuscated, check-summed, or in encrypted form. For the keystore/ key/ truststore passwords, you must obfuscate the passwords. The class org.eclipse.jetty.util.security.Password
is used to generate all types of secure passwords. Create a password in the installationDirectory\lib\start\startlevel1 location. Use the command below to create a new password. (The username
parameter in the following command is optional.)
java -cp jetty-util-9.4.15.vXXXX.jar org.eclipse.jetty.util.security.Password username password
In the code, the jetty-util-9.4.15.vXXXX.jar file is an example file. The version-specific jar file is located in the ARSystemInstallationDirectory\lib\start\startlevel1 folder. Use the same file name in the command.
If you are using a reverse proxy, uncomment the following section from the jetty-http.xml file.
<Call name="addCustomizer">
<Arg><New class="org.eclipse.jetty.server.ForwardedRequestCustomizer"/></Arg>
</Call>
To configure the REST API for HTTP connection
- Locate the Jetty subdirectory from the AR System installation directory.
In the jetty-http.xml file, uncomment the following HTTP connector if you use a reverse proxy that handles HTTPS and change the default port to 8008 according to your need.
<Call name="addConnector"> <Arg> <New class="org.eclipse.jetty.server.ServerConnector"> <Arg name="server"><Ref refid="Server" /></Arg> <Arg type="java.lang.Integer" name="acceptors">2</Arg> <Arg type="java.lang.Integer" name="selectors">-1</Arg> <Arg name="factories"> <Array type="org.eclipse.jetty.server.ConnectionFactory"> <Item> <New class="org.eclipse.jetty.server.HttpConnectionFactory"> <Arg name="config"><Ref refid="httpConfig" /></Arg> </New> </Item> </Array> </Arg> <Set name="host"><Property name="jetty.http.host" /></Set> <Set name="port"><Property name="jetty.http.port" default="8008" /></Set> <!--Uncomment to Enable Connector Statistics --> <!--<Call name="addBean"> <Arg> <New id="ConnectorStatistics" class="org.eclipse.jetty.server.ConnectorStatistics"/> </Arg> </Call> --> </New> </Arg> </Call>
- Restart the AR System server.
Comments
Hi Team,
In the Obfuscating password section there is an inconsistency between the text and the copy section whereby the "http" is missing. Worse, the actual jar file referenced jetty-util-9.4.11.v20180605.jar does not exist in our 20.02 patch 002 install, it is a 9.4.15.vXXXX file instead. Could it be clarified or corrected accordingly.
Many Thanks, Paul
Hi Paul,
Thank you for your feedback on the documentation. We have updated the topic.
Regards,
Himanshu
Hi! Regarding obfuscating the password: On our 20.02 system the class name is different from the one stated above: org.eclipse.jetty.util.security.Password instead of org.eclipse.jetty.util.http.security.Password (i.e. the actual class name is without .http.)
Joachim.
Hi Joachim,
Thank you for your feedback on the documentation. We have updated the topic.
Regards,
Himanshu
Log in or register to comment.