NPKD Installation with JBoss EAP 6.4

This NPKD Installation guide covers how to install NPKD with JBoss eap 6.4:

Install JBoss

  1. Update the /opt/primekey/jboss/standalone/configuration/standalone.xml according to the following (see full file in Appendix A)

    1. After the "extensions" section, add the following "system-properties" section:

      <system-properties>
      	<property name="org.apache.catalina.connector.URI_ENCODING" value="UTF-8"/>
          <property name="org.apache.catalina.connector.USE_BODY_ENCODING_FOR_QUERY_STRING" value="true"/>
          <property name="javax.net.ssl.trustStore" value="${jboss.server.config.dir}/keystore/truststore.jks"/>
          <property name="org.jboss.as.logging.per-deployment" value="false"/>
      </system-properties>
    2. Under the "profile" section, under subsystem "urn:jboss:domain:logging:1.5", add the EJBCA and the CESECORE loggers:

      <logger category="org.ejbca">
      	<level name="INFO"/>
      </logger>
      <logger category="org.cesecore">
      	<level name="INFO"/>
      </logger>
    3. Under the "profile" section, under subsystem "urn:jboss:domain:datasources:1.2", remove the datasource "java:jboss/datasources/ExampleDS" and change the driver to mariaDB driver:

      <subsystem xmlns="urn:jboss:domain:datasources:1.2">
      	<datasources>
          	<drivers>
              	<driver name="org.mariadb.jdbc.Driver" module="org.mariadb">
                  	<xa-datasource-class>org.mariadb.jdbc.MySQLDataSource</xa-datasource-class>
                  </driver>
              </drivers>
          </datasources>
      </subsystem>
    4. Under the "profile" section, under subsystem "urn:jboss:domain:deployment-scanner:1.1", add a deployment timeout:

      <subsystem xmlns="urn:jboss:domain:deployment-scanner:1.1">
      	<deployment-scanner path="deployments" relative-to="jboss.server.base.dir" scan-interval="5000" deployment-timeout="300"/>
      </subsystem>
    5. Under the "profile" section, under subsystem "urn:jboss:domain:web:2.2", change the "enable-welcome-root" to "false":

      <subsystem xmlns="urn:jboss:domain:web:2.2" default-virtual-server="default-host" native="false">
      	<connector name="http" protocol="HTTP/1.1" scheme="http" socket-binding="http"/>
          <virtual-server name="default-host" enable-welcome-root="false">
          	<alias name="localhost"/>
              <alias name="example.com"/>
          </virtual-server>
      </subsystem>
  2. Change /opt/primekey/jboss/bin/standalone.conf to increase the memory and force using 2048-bit DH key. (For an example standalone.conf file, see Appendix B).

    1. Increase the memory by setting the JAVA_OPTS variable to:

      JAVA_OPTS="-Xms2048m -Xmx2048m -Djava.net.preferIPv4Stack=true"
    2. Force use of 2048-bit DH keys in order to mitigate https://weakdh.org/ by adding the following line:

      JAVA_OPTS="$JAVA_OPTS -Djdk.tls.ephemeralDHKeySize=2048"
  3. If an HSM is to be used, add the following patches to all JBoss instances in the file /opt/primekey/jboss/modules/system/layers/base/sun/jdk/main/module.xml after all paths.
    (For an example module.xml file, see Appendix C).

        <path name="sun/security/x509"/>
        <path name="sun/security/pkcs11"/>
        <path name="sun/security/pkcs11/wrapper"/>
  4. Copy the MariaDB Java Client mariadb-java-client-1.5.2.jar into the JBoss directory:

      mkdir -p /opt/primekey/jboss/modules/system/layers/base/org/mariadb/main/
      cp mariadb-java-client-1.5.2.jar /opt/primekey/jboss/modules/system/layers/base/org/mariadb/main/
      ln -s /opt/primekey/jboss/modules/system/layers/base/org/mariadb/main/mariadb-java-client-1.5.2.jar /opt/primekey/jboss/modules/system/layers/base/org/mariadb/main/mariadb-java-client.jar
  5. Create the file /opt/primekey/jboss/modules/system/layers/base/org/mariadb/main/module.xml with the following content:

    <?xml version="1.0" encoding="UTF-8"?>
    <module xmlns="urn:jboss:module:1.0" name="org.mariadb">
      <resources>
        <resource-root path="mariadb-java-client.jar"/>
      </resources>
      <dependencies>
        <module name="javax.api"/>
        <module name="javax.transaction.api"/>
        <module name="org.slf4j"/>
      </dependencies>
    </module>

Configure NPKD Database Connection in JBoss

  1. Start JBoss CLI on a different terminal to configure data source:

    /opt/primekey/jboss/bin/jboss-cli.sh --connect
  2. Add a datasource as follows and ensure to use the right database name, username, and password, and the correct date-source name as configured in /opt/primekey/npkd/conf/npkd_deploy.properties:

    Run in JBoss CLI

    data-source add --name=<DS NAME> --driver-name="org.mariadb.jdbc.Driver"\
    --connection-url="jdbc:mysql://<HOST>:<PORT>/<DATABASE NAME>" \
    --jndi-name="java:/npkdDS" --use-ccm=true \
    --driver-class="org.mariadb.jdbc.Driver" --user-name="<DB USERNAME>" \
    --password="DB_PASSWORD" --validate-on-match=true \
    --background-validation=false --prepared-statements-cache-size=50 \
    --share-prepared-statements=true --min-pool-size=5 --max-pool-size=150 \
    --pool-prefill=true --transaction-isolation=TRANSACTION_READ_COMMITTED \
    --check-valid-connection-sql="select 1;" --enabled=true
    :reload

    If the data source was configured successfully, the output will be similar to:

    "outcome" => "success"


  3. Exit the JBoss CLI:

    Run in JBoss CLI

    exit

Set up JBoss KeyStore

  1. Copy the keystore file as /opt/primekey/jboss/standalone/configuration/keystore/keystore.jks and the trust store as /opt/primekey/jboss/standalone/configuration/keystore/truststore.jks.

  2. Start JBoss CLI:

    /opt/primekey/jboss/bin/jboss-cli.sh --connect
  3. Configure interfaces using the appropriate bind address:

    Run in JBoss CLI

    /interface=http:add(inet-address="0.0.0.0")
    /interface=httpspriv:add(inet-address="0.0.0.0")
  4. Set-up the private port which requires client certificate. Use appropriate values for key-alias (hostname), password (keystore password), ca-certificate-password (truststore password), and supported protocols.

    Run in JBoss CLI

    /socket-binding-group=standard-sockets/socket-binding=httpspriv:add(port="8443",interface="httpspriv")
    /subsystem=web/connector=httpspriv:add(protocol=HTTP/1.1, scheme=https, socket-binding=httpspriv, secure=true)
    /subsystem=web/connector=httpspriv/ssl=configuration:add(key-alias="<HOST_NAME>")
    /subsystem=web/connector=httpspriv/ssl=configuration:write-attribute(name=password, value="<KEYSTORE_PASSWORD>")
    /subsystem=web/connector=httpspriv/ssl=configuration:write-attribute(name=certificate-key-file, value="${jboss.server.config.dir}/keystore/keystore.jks")
    /subsystem=web/connector=httpspriv/ssl=configuration:write-attribute(name=verify-client, value=true)
    /subsystem=web/connector=httpspriv/ssl=configuration:write-attribute(name=ca-certificate-password, value="<TRUSTSTORE_PASSWORD>")
    /subsystem=web/connector=httpspriv/ssl=configuration:write-attribute(name=ca-certificate-file, value="${jboss.server.config.dir}/keystore/truststore.jks")
    /subsystem=web/connector=httpspriv/ssl=configuration:write-attribute(name=protocol,value="TLSv1,TLSv1.1,TLSv1.2")
  5. Redirect-port for the http connector to point to the ssl port (JBoss default is 8443):

    Run in JBoss CLI

    /subsystem=web/connector=http:write-attribute(name=redirect-port, value="8443")
  6. Since some transactions (like full listing download or rerunning revocation checks) can take some time, the default-timeout should be increased from the default value 300 seconds. Recommended is half an hour.

    Run in JBoss CLI

    /subsystem=transactions:write-attribute(name="default-timeout", value="1800")

Fix Web Service Problem

  1. Configure WSDL web-host rewriting to use the request host. Needed for webservices to work correctly when signing Master Lists and Deviation Lists.

    Run in JBoss CLI

    /subsystem=webservices:write-attribute(name=wsdl-host, value=jbossws.undefined.host)
    /subsystem=webservices:write-attribute(name=modify-wsdl-address, value=true)
    :reload


  2. Exit JBoss CLI:

    Run in JBoss CLI

    exit

Deploy NPKD

  1. Deploy NPKD:

    cd /opt/primekey/npkd
    ant deploy-ear
  2. Restart JBoss:

    sudo systemctl restart jboss
  3. Verify that NPKD has deployed correctly:

    tail -n20 /opt/primekey/jboss/standalone/log/server.log | grep "npkd.ear"
  4. Install your SuperAdmin certificate in the web browser.

  5. Connect to NPKD in the web browser using the URL: https://FQDN:8443/npkd

    FQDN is the fully qualified domain of the NPKD server.
  6. The first time you login to the system, the following message is shown: "Access Control Module is NOT initialized. Error accessing NPKD <SUBJECT DN> is not authorized to access the NPKD GUI". Click Register.

  7. Confirm by clicking Yes in the pop-up window.

  8. Re-load/refresh the browser.