Skip to main content
Skip table of contents

Install Protocol Gateway

This article describes how to install the Protocol Gateway component in Smart ID Certificate Manager

The CM client installation package must be installed on the Protocol Gateway host. Select the PGW component to install. Optionally the AWB and RA clients may be selected since they are required for the tasks below. This will make all necessary files available on the Protocol Gateway host. Normally, the Protocol Gateway host would not be the same as the CM server host. However, multiple hosts is not a requirement for completing this setup. The variables used in file path specifications are defined as follows:

  • <configroot>
    • On Windows, <configroot> corresponds to %ALLUSERSPROFILE%/Nexus/cm-gateway/
    • On Linux to /var/cm-gateway/.
  • <client_root> - refers to the base folder of a CM client installation.
  • <CATALINA_BASE> - refers to the base folder of an Apache Tomcat instance. If Apache Tomcat is not set up to run several instances this variable references the same folder as CATALINA_HOME.
  • <CATALINA_HOME> - refers to the base folder of an Apache Tomcat installation.


Prerequisites

Protocol Gateway requires the following external components for its operations:

Step-by-step instruction

Install CM clients with Protocol Gateway option

If the Protocol Gateway client is not already installed:

  1. Follow the steps in either of these instructions and make sure to check Protocol Gateway in the list of clients, as well as Administrator's workbench (AWB) and Registration Authority (RA) that are needed to set up CA and policy objects:
    1. Install Certificate Manager clients on Windows
    2. Install Certificate Manager clients on Linux
Copy Protocol Gateway .war file

To copy the Protocol Gateway .war file:

  1. Go to the CM installation folder, for example \CM\clients\web\pgwy\

  2. Copy the file pgwy.war file to the Tomcat webapps folder, for example \Tomcat\webapps
  3. Start Tomcat. After the startup is complete, just stop it again. 
    When Protocol Gateway is started the first time, the \conf folder and initial configuration files will be created, for example C:\ProgramData\Nexus\cm-gateway\conf\. Error messages can be ignored at this point.
Deploy Protocol Gateway

The following actions perform a static deployment of the Protocol Gateway application in Apache Tomcat. The Protocol Gateway application is delivered as a web archive file, pgwy.war, which is located in a CM client installation.

  1. Copy the pgwy.war file from the <client_root>/web/pgwy folder to the <CATALINA_BASE>/webapps folder. 
  2. Start Apache Tomcat. After the startup is complete, just shutdown Apache Tomcat again. When Protocol Gateway is started the first time the <configroot>/conf folder and initial configuration files will be created. Error messages can be ignored at this point.
Configure Tomcat service

To configure Tomcat: 

  1. On Windows
    1. Run the Tomcat application. 
      For how to setup Apache Tomcat 10.1 as a Windows service see Apache Tomcat 10. Tomcat10w is a GUI application for monitoring and configuring Apache Tomcat services. Start the Tomcat10w.exe application to configure the Apache Tomcat properties and to set the Java parameters that are required by the Protocol Gateway application. 
    2. Go to the Logging tab, and set Log path to C:\ProgramData\Nexus\cmgateway\logs..

    3. Go to the Java tab, and set the following properties: 

      Example: Java options

      CODE
      -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager
      -Djava.util.logging.config.file=C:\ProgramData\Nexus\cm-gateway\conf\logging.properties
      -Dnexus.var=C:\ProgramData\Nexus\cm-gateway
  2. On Linux

    1. Open the script file setenv.sh in the Apache Tomcat bin folder for editing. 

    2. Set the following options in CATALINA_OPTS as a string separated by spaces.

      Example: Set options in setenv.sh

      CODE
      CATALINA_OPTS="-Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager \
          -Djava.util.logging.config.file=/var/cm-gateway/conf/logging.properties \
          -Dnexus.var=/var/cm-gateway"

      Configuring Protocol Gateway as a service on Linux depends on the distribution used and is not covered here.

  3. Do not restart Tomcat yet. 
    Restarting Tomcat would lead to an error message, since Protocol Gateway is not yet configured.  

Secure Tomcat service - some recommendations

Securing the Apache Tomcat Service is outside the scope of the Protocol Gateway application. Here are some recommended steps to secure the Tomcat service: 

Disable TLSv1.0 and TLS1.1 protocols and allow only strong ciphers. In the file: <CATALINA_BASE>/conf/server.xml modify the SSLHostConfig, so it includes the attribute:

CODE
protocols="TLSv1.3,TLSv1.2"

Enable only strong ciphers and force the clients to respect the server's cipher order. In the file: <CATALINA_BASE>/conf/server.xml modify the SSLHostConfig, so it includes the attributes: 

CODE
honorCipherOrder="true"
ciphers="HIGH:!3DES:!DES:!SHA1:!SHA256:!SHA384:!SEED"

Example server.xml connector configuration. 

CODE
<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
maxThreads="150" SSLEnabled="true">
<SSLHostConfig
honorCipherOrder="true"
ciphers="HIGH:!3DES:!DES:!SHA1:!SHA256:!SHA384:!SEED"
protocols="TLSv1.3,TLSv1.2">
<Certificate
certificateKeystoreFile="conf/localhost-rsa.p12"
certificateKeystorePassword="1234"
certificateKeystoreType="PKCS12"
type="RSA" />
</SSLHostConfig>
</Connector>

Initial configuration

To do initial configuration of Protocol Gateway, see Initial configuration of Protocol Gateway.

Configuration examples

For configuration examples in Protocol Gateway, see Configuration examples in Protocol Gateway.

Upgrade Protocol Gateway

To upgrade to a newer version of Protocol Gateway, see Upgrade Protocol Gateway.


JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.