Configuring the REST API by using SSL certificates

The primary reason for using Secure Sockets Layer (SSL) certificates is to encrypt sensitive information sent across the internet so that only the intended recipient can understand it. This security is important because the information you send on the internet is passed from one computer to another before reaching the recipient. Any computer between you and the recipient can use 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 correct recipient and not to an unknown user. You can ensure authentication by using an SSL certificate from a trusted SSL provider.

Related topics

Integrating-AR-System-forms-with-a-third-party-application-by-using-the-REST-API

The keytool utility (available with Oracle JDKs) is used to obtain a digitally signed certificate to replace the self-signed certificate. This Java keytool is a key and certificate management utility that allows users to manage their own public or private key pairs and certificates. The Java keytool stores the keys and certificates necessary for authentication in a keystore, which is located in the JREHome/bin directory of the Java installation file.

Configuring the Jetty webserver

You can create new keystores by using one of the following methods: 

For information about troubleshooting Jetty startup issues, see BMC Knowledge Base article ID 000253953.

To configure REST API for HTTPS connection

  1. 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, you must 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

    The keystore file gets created in the current directory of the command window.

  2. Obfuscate the SSL connector keystore password for greater security. 
    For more information, see Obfuscating the password.

  3. Update the jetty-http.xml file with the new password for the keystore.

     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.

    For example:
    <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>


    <!-- Uncomment this to add SSL support for REST API,
            replace the values to match your environment -->
     <!-- <New id="httpsConfig" class="org.eclipse.jetty.server.HttpConfiguration">
           <Call name="addCustomizer">
               <Arg>
                   <New class="org.eclipse.jetty.server.SecureRequestCustomizer" />
               </Arg>
           </Call>
    <Set name="sendServerVersion">false</Set>
       </New>

     <New id="sslContextFactory" class="org.eclipse.jetty.util.ssl.SslContextFactory">
       <Set name="KeyStorePath"><Property name="jetty.home" default="." />/etc/keystore</Set>
    <Set name="KeyManagerPassword">OBF:1uh41zly1x8g1vu11ym71ym71vv91x8e1zlk1ugm</Set>
       <Set name="KeyStorePassword">OBF:1uh41zly1x8g1vu11ym71ym71vv91x8e1zlk1ugm</Set>
       <Set name="TrustStorePath"><Property name="jetty.home" default="." />/etc/keystore</Set>
       <Set name="TrustStorePassword">OBF:1uh41zly1x8g1vu11ym71ym71vv91x8e1zlk1ugm</Set>
    <Set name="IncludeCipherSuites">
     <Array type="String">
         <Item>TLS_DHE_RSA.*</Item>
         <Item>TLS_ECDHE.*</Item>
     </Array>
    </Set>
    <Set name="ExcludeCipherSuites">
      <Array type="String">
       <Item>SSL_RSA_WITH_DES_CBC_SHA</Item>
       <Item>SSL_DHE_RSA_WITH_DES_CBC_SHA</Item>
       <Item>SSL_DHE_DSS_WITH_DES_CBC_SHA</Item>
       <Item>SSL_RSA_EXPORT_WITH_RC4_40_MD5</Item>
       <Item>SSL_RSA_EXPORT_WITH_DES40_CBC_SHA</Item>
       <Item>SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA</Item>
       <Item>SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA</Item>

       <Item>.*NULL.*</Item>
       <Item>.*RC4.*</Item>
       <Item>.*MD5.*</Item>
       <Item>.*DES.*</Item>
       <Item>.*DSS.*</Item>
       <Item>.*_DHE_RSA_.*</Item>

      </Array>
    </Set>
    <Set name="ExcludeProtocols">
        <Array type="java.lang.String">
            <Item>SSL</Item>
            <Item>SSLv2</Item>
            <Item>SSLv2Hello</Item>
            <Item>SSLv3</Item>
        </Array>
    </Set>     
     </New>
     
     <New id="sslConnectionFactory" class="org.eclipse.jetty.server.SslConnectionFactory">
           <Arg name="sslContextFactory">
               <Ref refid="sslContextFactory" />
           </Arg>
           <Arg name="next">http/1.1</Arg>
     </New>

     <New id="sslConnector" class="org.eclipse.jetty.server.ServerConnector">
       <Arg name="server"><Ref refid="Server" /></Arg>
       <Arg name="factories">
           <Array type="org.eclipse.jetty.server.ConnectionFactory">
               <Item><Ref refid="sslConnectionFactory" /></Item>
               <Item>
                   <New class="org.eclipse.jetty.server.HttpConnectionFactory">
                     <Arg name="config"><Ref refid="httpsConfig" /></Arg>           
                   </New>
               </Item>
           </Array>
       </Arg>
    <Set name="port">8443</Set>        
     </New>

    <Call name="setConnectors">
           <Arg>
               <Array type="org.eclipse.jetty.server.ServerConnector">
                   <Item>
                       <Ref refid="sslConnector" />
                   </Item>
               </Array>
           </Arg>
       </Call>
         -->
    </Configure>

  4. Restart the

    Some content is unavailable due to permissions.

    .

    After you restart the

    Some content is unavailable due to permissions.

    , the following message is displayed and runtime errors may occur:

    WARN:oejob.JettyBootstrapActivator:main: OSGi support for java.util.ServiceLoader may not be present.
  5. Perform the following steps to turn on the logging for the Jetty:

    1. Enable Jetty log level in the arserver.config file on Windows or the arserverd.conf file on Linux.
      Use the following JVM option:

      -Dorg.eclipse.jetty.LEVEL=DEBUG

    2. Enable extra Jetty Related 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 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. You can prevent the certificate warning by adding the self-signed certificate to the Trusted Root Certification Authorities store. 

To obfuscate 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 org.eclipse.jetty.util.http.security.Password class is used to generate all types of secure passwords. Create password at ARSystemInstallDirectory\lib\start\startlevel1 location. Use the following command to create a new password:

Syntax
java org.eclipse.jetty.util.security.Password [<username>] <password>

The <username> parameter in the command is optional.

Example
java -cp jetty-util-9.4.11.v20180605.jar org.eclipse.jetty.util.security.Password username password

The version-specific jar file is located in the ARSystemInstallDirectory\lib\start\startlevel1 folder. Use the same file in the command.

If you are using a reverse proxy, uncomment the following section in the jetty-http.xml file:

<Call name="addCustomizer">
       <Arg><New class="org.eclipse.jetty.server.ForwardedRequestCustomizer"/></Arg>
     </Call>

To configure REST API for HTTP connection

  1. Locate the Jetty subdirectory from the

    Some content is unavailable due to permissions.

    installation directory. 

  2. 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.

      <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> 
  3. Restart the

    Some content is unavailable due to permissions.

    .


 


 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*