*** Configuration files ***

The configuration of EJBCA that can not be configured in the Admin GUI is located in properties files in the conf directory. All properties are documented in sample files and to configure an option you copy the sample file, for example copy conf/ejbca.properties.sample to conf/ejbca.properties and configure conf/ejbca.properties. You should at least familiarize your self with the options in conf/install.properties, conf/ejbca.properties and conf/cesecore.properties. Most options, except those in install.properties can be changed after installation.

*** EJBCA configuration ***

1) Copy conf/install.properties.sample to conf/install.properties, conf/ejbca.properties.sample to conf/ejbca.properties and conf/cesecore.properties.sample to conf/cesecore.properties Customize if needed. The default values works fine for a test installation.

You must configure 'appserver.home' in ejbca.properties to point to your application server directory. You find examples of how to do this in ejbca.properties.sample.
This makes libraries from the application server available to EJBCA during the build.

If you are only testing EJBCA at this stage and is not setting up a production environment, you can skip the rest of this step. There are default configuration options, that should work in a test environment, for everything.

• Customize the CA properties in conf/ejbca.properties if you need to do so. For production use you need to do this, don't forget to edit passwords to be secure and secret. Keep conf/ejbca.properties as secret as possible. DO NOT forget the passwords, if you need to re-install the software sometime.
• To use a hard ca token from start change ca.tokentype, ca.tokenpassword and ca.tokenproperties in install.properties. You also need to add the appropriate values to the ca.tokenproperties file for the HSM. Read the HSM documentation for the right values.
• To put the initial superadmin certificate on a smartcard, set superadmin.batch=false in web.properties. Enroll from public web after the installation is complete, as you would with any other smartcard user. Username is "superadmin" and password is superadmin.password from web.properties.
• If you are deploying on JBoss EAP you probably want to look at the property 'jboss.config' as well, since 'production' may be the default server to start on JBoss EAP (depends on your configuration).

• Customize the database in conf/database.properties if needed. But easiest thing is to keep the default as it is, it will use the JBoss embedded HSQLDB and everything will be easier for you. For production use you should use a real database instead of the embedded one.

*** Configure application server ***

Due to differences, and bugs, in different application servers you have to configure your application server with some settings, and EJBCA with server specific settings.
See the application servers section.

*** Considerations ***

When everything is prepared, there are a few things to configure before starting your applications and running everything in a production environment.

In a production environment you should use something like the following structure:

1. Go through the install process creating an ManagementCA. Use a simple DN. This CA should only used to issue the administrator certificates. Not published in LDAP. If you want to use an HSM for this CA, see the documentation in the configuration file conf/ejbca.properties.sample.
2. Once installed, create all your REAL CAs using the admin-GUI. Now you can use the certificate profiles etc that you like. These certificates can be published in LDAP. See doc/howto/HOWTO-multiplecas.txt for example of a detailed configuration guide.

In a production environment you should use something else than the default Hypersonic database that comes with JBoss for the reasons:

1. Hypersonic database is in-memory, which means that over time it will consume more memory. If a large number of certificates is issued, it will become an issue after a while.
2. Hypersonic does not support full SQL, in particular ALTER statements. When a new version of EJBCA is released we can not create scripts that updates the database if some tables changed. This will make upgrades much much harder.

For information about installing JDBC drivers for other databases, see the document 'doc/howto/HOWTO-database.txt' in the distribution.

*** JBoss 7/EAP 6 General Notes ***

Version JBoss AS 7.1.1.Final, EAP 6.1-6.4 (and possibly later ones) has been tested with EJBCA, and it should work. There's a couple of caveats and notes you should be aware of:

• Start and connect with the JBoss 7/EAP6 cli like this:

  ./jboss-cli.sh
  connect
  

• If you're having problem with HornetQ start-up, try switching to Java NIO with the following commands in JBoss CLI administration tool:

  /subsystem=messaging/hornetq-server=default:write-attribute(name=journal-type,value=NIO)
  :reload
  

• You don't need to start/stop JBoss 7, deployment is done with a live system (in fact you should have the JBoss 7 running at all times).

*** JBoss 7/EAP 6 JDBC Drivers and Data Sources ***

In JBoss 7/EAP6 it is not enough to just drop the JAR archive with a database JDBC driver into the deployments directory. Instead you will have to perform the following steps (for MySQL):

1. Create the necessary directories (relative to JBoss 7 base directory):
   On JBoss 7.1.1 or EAP 6.0:

   mkdir -p modules/com/mysql/main/
   

   On JBoss 7.2 or EAP 6.1/6.2:

   mkdir -p modules/system/layers/base/com/mysql/main/
   

   Or for MariaDB, mariadb-java-client-1.2.0.jar:

   mkdir -p modules/org/mariadb/main/
   

   On JBoss 7.2 or EAP 6.1/6.2:

   mkdir -p modules/system/layers/base/org/mariadb/main/
   

2. Place the mysql.jar or mariadb.jar file in the directory you just created.
3. Create, in the created directory, the JDBC module configuration file module.xml with the following contents (replace mysql.jar with the full name of your jar file for example mysql-connector-java-5.1.18-bin.jar):

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

   Or for MariaDB, mariadb-java-client-1.2.0.jar:

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

4. Register the driver by running the following two commands in the JBoss 7 CLI administration tool:

   /subsystem=datasources/jdbc-driver=com.mysql.jdbc.Driver:add(driver-name=com.mysql.jdbc.Driver,driver-class-name=com.mysql.jdbc.Driver,driver-module-name=com.mysql,driver-xa-datasource-class-name=com.mysql.jdbc.jdbc2.optional.MysqlXADataSource)
   :reload
   

   Or for MariaDB, mariadb-java-client-1.2.0.jar:

   /subsystem=datasources/jdbc-driver=org.mariadb.jdbc.Driver:add(driver-name=org.mariadb.jdbc.Driver,driver-module-name=org.mariadb,driver-xa-datasource-class-name=org.mariadb.jdbc.MySQLDataSource)
   :reload
   

For PostgreSQL you would use the following values instead:

mkdir -p modules/system/layers/base/org/postgresql/main/

<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.0" name="org.postgresql">
  <resources>
    <resource-root path="postgresql-9.1-903.jdbc4.jar"/>
  </resources>
  <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>

/subsystem=datasources/jdbc-driver=org.postgresql.Driver:add(driver-name=org.postgresql.Driver,driver-module-name=org.postgresql,driver-xa-datasource-class-name=org.postgresql.xa.PGXADataSource)
:reload

Datasources are normally created automatically by EJBCA during deployment and installation. Here we describe how to create a datasource in JBoss7/EAP6 for reference. The examples are for installing a MariaDB datasource using the jboss-cli with the driver installed as described above.

A normal datasource:

data-source add --name=ejbcads --driver-name="org.mariadb.jdbc.Driver" --connection-url="jdbc:mysql://127.0.0.1:3306/ejbca" --jndi-name="java:/EjbcaDS" --use-ccm=true --driver-class="org.mariadb.jdbc.Driver" --user-name="ejbca" --password="ejbca" --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;"

A no-tx / jta="false" datasource (OCSP publisher and Unid):

data-source add --name=unidds --jta=false --driver-name="org.mariadb.jdbc.Driver" --connection-url="jdbc:mysql://127.0.0.1:3306/unid" --jndi-name="java:/UnidDS" --use-ccm=true --driver-class="org.mariadb.jdbc.Driver" --user-name="uniduser" --password="unidpass" --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;"

(note that 'select 1' must be different for DB2 and Oracle)
(note that for JBoss EAP 6 you need to add --enabled=true to the commands above, or else the datasource will not be enabled)

*** JBoss 7 and EAP 6 logging ***

Logging can be configured using the CLI:

 /system-property=org.jboss.as.logging.per-deployment:add(value=false)
 /subsystem=logging/logger=org.ejbca:add
 /subsystem=logging/logger=org.ejbca:write-attribute(name=level, value=DEBUG)
 /subsystem=logging/logger=org.cesecore:add
 /subsystem=logging/logger=org.cesecore:write-attribute(name=level, value=DEBUG)

The per-deployment feature was added in EAP 6.0.0 and is not present in GA 7.1.

In JBoss EAP 6 you can also configure a completely custom Log4J configuration by:

• Do _not_ set 'org.jboss.as.logging.per-deployment' to false above, by default it's value is true, but you can also set it manually to true.
• Create a $EJBCA_HOME/conf/log4j-jbosseap6.xml, you can use log4j-jbosseap6.xml.sample as a template. Set paths to the desired log files.
• Redeploy with 'ant clean deployear'.

*** JBoss 7/EAP 6 PKCS11 ***

JBoss 7/EAP 6 by default isolates away most sun classes. Since version 6.6.3 EJBCA configures JBoss to expose these classes (sun/security/pkcs11/wrapper)by using a jboss-deployment-structure.xml. This makes configuration in modules/sun/jdk/main/module.xml (JBoss 7.1/EAP6.0) or modules/system/layers/base/sun/jdk/main/module.xml (JBoss EAP 6.1 and later and WildFly) not needed. For previous versions of EJBCA, look in the documentation for older releases for detailed information.

*** JBoss 7/EAP 6 CMP TCP ***

Note that the TCP transport of the CMP protocol is deprecated in the standard draft. TCP transport may be removed in future EJBCA releases.

JBoss 7/EAP 6 isolates away most sun classes. This means that the CMP TCP library is not able to get system properties. The needed classes can be made available by editing the file modules/sun/jdk/main/module.xml (JBoss 7.1/EAP6.0) or modules/system/layers/base/sun/jdk/main/module.xml (JBoss 7.2/EAP6.1)) and adding the following package to the list of system export paths:

<path name="sun/security/action"/>

*** JBoss 7/EAP 6 URI encoding and WSDL location ***

This section is a reference section, the configurations here are done automatically in JBoss 7 by the 'ant deploy' command in EJBCA.

The following configuration is recommended to be able to use international characters during certificate and CRL download:

 /system-property=org.apache.catalina.connector.URI_ENCODING:add(value=UTF-8)
 /system-property=org.apache.catalina.connector.USE_BODY_ENCODING_FOR_QUERY_STRING:add(value=true)

On JBoss 7.1.x (and EAP 6.0.x) the WSDL location gets incorrectly generated by default (JBoss bind address, plain http). This will cause the WS client to not work. This can be corrected using the JBoss CLI (the change requires a reload of JBoss server):

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

to force the location to be generated with info from the WSDL request. If this is not done you will get SSL errors about missing client certificate, or "HTTP 302 Moved Temporarily" errors when running the WS client.

*** JBoss Mail TLS configuration ***

There are at least two ways to use TLS for SMTP connection:

• SMTP STARTTLS
• TLS required

The first method can be configured with the setting mail.smtp.starttls.enable in conf/mail.properties. Since mail configuration is done differently in different versions of JBoss we only provide guidance for the second version. There are two options that might be needed:

• mail.smtp.ssl.enable=true
• mail.smtp.socketFactory.class=javax.net.ssl.SSLSocketFactory

For JBoss 7/EAP 6 they should be set using the JBoss command line admin tool.

*** JBoss Service Timer persistence ***

EJBCA uses EJB timers to run services regularly (if you have services configured). By default JBoss persists timers in an internal, in memory, database. If you run services very often this can under some circumstances fill up the memory causing the server to be non-operational due to out ofmemory errors.

EJBCA does not need persistent timers since they are initialized during startup. Therefore it is recommended to run JBoss with non-persistent timers, something that can be configured.

JBoss 7/EAP6 configuration:

JBoss 7 does not use the in memory database to persist timers, but instead stores them in jboss/standalone/data/timer-service-data/ejbca.ejbca-ejb.ServiceSessionBean. This is supposed to ensure that it will not fill up the memory as it did in JBoss 5.
If persisted timers needs to be removed in JBoss 7 the directory jboss/standalone/data/timer-service-data can simply be deleted.

*** JBoss7/EAP6 deployment timeout ***

In the case the deployment fails to complete within 60 seconds it will fail. You can increase this timeout with:

/subsystem=deployment-scanner/scanner=default:write-attribute(name=deployment-timeout,value=300) 

Unless there is a clear reason why this takes longer than 60 seconds (for example an HSM waiting for human input, or a very slow server, check that database indexes are applied and that your network and any used DNS server is fully operational.

*** JBoss 7 and Oracle JDK BC issues ***

In EJBCA 6.0.4 ECA-3371 solved the issue of deploying with OracleJDK.

*** Add database driver ***

Add MariaDB database driver by hot-deploying it into the Deployment directory. This will be picked up by WildFly and deployed so we can create a datasource straight away. You can use a generic name, without version number, in order to get a generic 'driver-name' for the data source command.

>cp mariadb-java-client-2.1.0.jar wildfly_home/standalone/deployments/mariadb-java-client.jar

If you are using another type of database, copy the JDBC driver to the deployments-directory and make note of the driver class and driver-name shown in the server log and for later use when adding the DataSource. E.g.

... INFO  [org.jboss.as.connector.deployers.jdbc] (...) WFLYJCA0005: Deploying non-JDBC-compliant driver class org.postgresql.Driver (version 9.2)
... INFO  [org.jboss.as.connector.deployers.jdbc] (...) WFLYJCA0018: Started Driver service with driver-name = postgresql-jdbc3.jar

*** Increase allowed memory usage ***

By default, only 512MiB of heap is allowed. Edit wildfly_home/bin/standalone.conf to increase this to a more suitable value, e.g.

   JAVA_OPTS="-Xms2048m -Xmx2048m -Djava.net.preferIPv4Stack=true"

*** Create database ***

Before creating the datasource in the following step, create your database. In MariaDB the command to create the database, matching the datasource in the next step, and add privileges to connect to the database is:

 
$ mysql -u root -p
mysql> CREATE DATABASE ejbca CHARACTER SET utf8 COLLATE utf8_general_ci;
mysql> GRANT ALL PRIVILEGES ON ejbca.* TO 'ejbca'@'localhost' IDENTIFIED BY 'ejbca';

You should define secure passwords for your database in production. You can also improve the security by limiting access to tables. See for Database privileges for more information about that.

*** Add datasource ***

Add data source for EJBCA to use.

Start JBoss and run two commands in JBoss CLI. Note that "-jindi-name" is linked to the database.properties value (default value in this example).

> wildfly_home/bin/jboss-cli.sh -c
> data-source add --name=ejbcads --driver-name="mariadb-java-client.jar" --connection-url="jdbc:mysql://127.0.0.1:3306/ejbca" --jndi-name="java:/EjbcaDS" --use-ccm=true --driver-class="org.mariadb.jdbc.Driver" --user-name="ejbca" --password="ejbca" --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;"
> :reload

If you are using another type of database, adapt the statement above with the correct driver-name, connection-url, driver-class and check-valid-connection-sql.

*** Configure WildFly Remoting ***

EJBCA needs to use JBoss Remoting for the EJBCA CLI to work. We configure it to use a separate port (start by removing any old configuration if it exists).

/subsystem=remoting/http-connector=http-remoting-connector:remove
/subsystem=remoting/http-connector=http-remoting-connector:add(connector-ref="remoting",security-realm="ApplicationRealm")
/socket-binding-group=standard-sockets/socket-binding=remoting:add(port="4447")
/subsystem=undertow/server=default-server/http-listener=remoting:add(socket-binding=remoting)
:reload

Wait for reload to complete by checking the server log or the result of ":read-attribute(name=server-state)" before continuing.

*** Configure logging ***

Configure logging in JBoss, to be able to dynamically change logging (DEBUG enabled in this example).

/subsystem=logging/logger=org.ejbca:add
/subsystem=logging/logger=org.ejbca:write-attribute(name=level, value=DEBUG)
/subsystem=logging/logger=org.cesecore:add
/subsystem=logging/logger=org.cesecore:write-attribute(name=level, value=DEBUG)

*** Deploy EJBCA ***

Finally build and deploy the EJBCA (application ear file) to WildFly, without touching any WildFly configuration, by running the following EJBCA command.

Before running deployear below, don't forget to point to your application server by setting APPSRV_HOME, and configure your database in conf/database.properties.

Run the following commands at the regular command prompt in EJBCA_HOME.

ant clean deployear

Check in the JBoss/WildFly console or server.log that EJBCA was deployed without errors.

*** Run install ***

Run installation part of EJBCA creating the initial Management CA (for TLS and Super administrator), as well as TLS and Superadmin keystores.

ant runinstall

*** Deploy TLS keystores to WildFly ***

After the install, TLS keystores have been created. Run this command to copy them to wildfly_home/standarlone/config/keystore.

ant deploy-keystore

*** Remove existing TLS and HTTP configuration ***

Run the following commands in JBoss CLI to remove existing TLS and HTTP configuration (just to be safe).

/subsystem=undertow/server=default-server/http-listener=default:remove
/subsystem=undertow/server=default-server/https-listener=https:remove
/socket-binding-group=standard-sockets/socket-binding=http:remove
/socket-binding-group=standard-sockets/socket-binding=https:remove
:reload

Wait for reload to complete by checking the server log or the result of ":read-attribute(name=server-state)" before continuing.

*** Configure TLS ***

The run the following commands in JBoss CLI (jboss-cli.sh -c) to configure TLS.

Add interfaces, using 0.0.0.0 to make it available for the world:

/interface=http:add(inet-address="0.0.0.0")
/interface=httpspub:add(inet-address="0.0.0.0")
/interface=httpspriv:add(inet-address="0.0.0.0")
/socket-binding-group=standard-sockets/socket-binding=http:add(port="8080",interface="http")
/subsystem=undertow/server=default-server/http-listener=http:add(socket-binding=http)
/subsystem=undertow/server=default-server/http-listener=http:write-attribute(name=redirect-socket, value="httpspriv")
:reload

Wait for reload to complete by checking the server log or the result of ":read-attribute(name=server-state)" before continuing.

Configure identities and socket bindings:

Update the keystore alias to match httpsserver.hostname in web.properties. Also, update the keystore-password for keystore.jks to match httpsserver.password and the keystore-password for truststore.jks to match java.truststore in web.properties.

/core-service=management/security-realm=SSLRealm:add()
/core-service=management/security-realm=SSLRealm/server-identity=ssl:add(keystore-path="${jboss.server.config.dir}/keystore/keystore.jks", keystore-password="serverpwd", alias="localhost")
/core-service=management/security-realm=SSLRealm/authentication=truststore:add(keystore-path="${jboss.server.config.dir}/keystore/truststore.jks", keystore-password="changeit")
/socket-binding-group=standard-sockets/socket-binding=httpspriv:add(port="8443",interface="httpspriv")
/socket-binding-group=standard-sockets/socket-binding=httpspub:add(port="8442", interface="httpspub")

Restart the application server completely. Wait for it to finish start up by checking the server log or the result of ":read-attribute(name=server-state)" before continuing.

/subsystem=undertow/server=default-server/https-listener=httpspriv:add(socket-binding=httpspriv, security-realm="SSLRealm", verify-client=REQUIRED)
/subsystem=undertow/server=default-server/https-listener=httpspriv:write-attribute(name=max-parameters, value="2048")
/subsystem=undertow/server=default-server/https-listener=httpspub:add(socket-binding=httpspub, security-realm="SSLRealm")
/subsystem=undertow/server=default-server/https-listener=httpspub:write-attribute(name=max-parameters, value="2048")
:reload

Finalize Wildfly configuration with some important items:

/system-property=org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH:add(value=true)
/system-property=org.apache.catalina.connector.CoyoteAdapter.ALLOW_BACKSLASH:add(value=true)
/system-property=org.apache.catalina.connector.URI_ENCODING:add(value="UTF-8")
/system-property=org.apache.catalina.connector.USE_BODY_ENCODING_FOR_QUERY_STRING:add(value=true)
/subsystem=webservices:write-attribute(name=wsdl-host, value=jbossws.undefined.host)
/subsystem=webservices:write-attribute(name=modify-wsdl-address, value=true)
:reload

If you are using OCSP GET requests, setting URI encoding and allowing encoding for Query and backslash above is needed.

*** Optional: Enable AJP connector ***

Only needed if you run an Apache front-end in front of WildFly.

/subsystem=undertow/server=default-server/ajp-listener=ajp-listener:add(socket-binding=ajp, scheme=https, enabled=true)

*** Optional: Add support for PKCS#11 (HSMs) ***

WildFly by default isolates away most sun classes. EJBCA configures JBoss/WildFly to expose these classes (sun/security/pkcs11/wrapper), since EJBCA 6.6.3, by using a jboss-deployment-structure.xml. This makes configuration in modules/system/layers/base/sun/jdk/main/module.xml not needed.

*** Optional: Add support for sending email ***

If you need support for sending email (smtp) you can configure EjbcaMail with:

/socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=ejbca-mail-smtp:add(port="993", host="my.mail.server")
/subsystem=mail/mail-session="java:/EjbcaMail":add(jndi-name=java:/EjbcaMail, from=noreply@mymail)
/subsystem=mail/mail-session="java:/EjbcaMail"/server=smtp:add(outbound-socket-binding-ref=ejbca-mail-smtp, tls=true, username=smtpuser, password=smtppassword)
:reload

*** Add database driver ***

Add MariaDB database driver by hot-deploying it into the Deployment directory. This will be picked up by WildFly and deployed so we can create a datasource straight away. You can use a generic name, without version number, in order to get a generic 'driver-name' for the data source command.

>cp mariadb-java-client-1.2.0.jar wildfly_home/standalone/deployments/mariadb-java-client.jar

*** Increase allowed memory usage ***

By default, only 512MiB of heap and 256MiB perm gen space is allowed. Edit wildfly_home/bin/standalone.conf to increase this to a more suitable value, e.g.

   JAVA_OPTS="-Xms2048m -Xmx2048m -XX:MaxPermSize=384m -Djava.net.preferIPv4Stack=true"

*** Add datasource ***

Add data source for EJBCA to use.

Start JBoss and run two commands in JBoss CLI.

> wildfly_home/bin/jboss-cli.sh -c
> data-source add --name=ejbcads --driver-name="mariadb-java-client.jar" --connection-url="jdbc:mysql://127.0.0.1:3306/ejbca" --jndi-name="java:/EjbcaDS" --use-ccm=true --driver-class="org.mariadb.jdbc.Driver" --user-name="ejbca" --password="ejbca" --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;"

*** Configure JBoss Remoting ***

EJBCA needs to use JBoss Remoting for the EJBCA CLI to work. We configure it to use a separate port (start by removing any old configuration if it exists).

/socket-binding-group=standard-sockets/socket-binding=remoting:remove
/subsystem=undertow/server=default-server/http-listener=remoting:remove
/subsystem=remoting/http-connector=http-remoting-connector:remove

/subsystem=remoting/http-connector=http-remoting-connector:add(connector-ref="remoting",security-realm="ApplicationRealm")
/socket-binding-group=standard-sockets/socket-binding=remoting:add(port="4447")
/subsystem=undertow/server=default-server/http-listener=remoting:add(socket-binding=remoting)
:reload

*** Configure logging ***

Configure logging in JBoss, to be able to dynamically change logging (DEBUG enabled in this example).

/subsystem=logging/logger=org.ejbca:add
/subsystem=logging/logger=org.ejbca:write-attribute(name=level, value=DEBUG)
/subsystem=logging/logger=org.cesecore:add
/subsystem=logging/logger=org.cesecore:write-attribute(name=level, value=DEBUG)

*** Remove existing TLS and HTTP configuration ***

Run the following commands in JBoss CLI to remove existing TLS and HTTP configuration (just to be safe).

/core-service=management/security-realm=SSLRealm/authentication=truststore:remove
/core-service=management/security-realm=SSLRealm/server-identity=ssl:remove
/core-service=management/security-realm=SSLRealm:remove
/socket-binding-group=standard-sockets/socket-binding=httpspub:remove
/subsystem=undertow/server=default-server/https-listener=httpspub:remove
/socket-binding-group=standard-sockets/socket-binding=httpspriv:remove
/subsystem=undertow/server=default-server/https-listener=httpspriv:remove
/socket-binding-group=standard-sockets/socket-binding=http:remove
/subsystem=undertow/server=default-server/http-listener=http:remove
/subsystem=undertow/server=default-server/http-listener=default:remove
/system-property=org.apache.catalina.connector.URI_ENCODING:remove
/system-property=org.apache.catalina.connector.USE_BODY_ENCODING_FOR_QUERY_STRING:remove
/interfaces=/interface=http:remove
/interfaces=/interface=httpspub:remove
/interfaces=/interface=httpspriv:remove
:reload

Wait for reload to complete by checking the server log or the result of ":read-attribute(name=server-state)" before continuing.

*** Deploy EJBCA ***

Finally build and deploy the EJBCA (application ear file) to WildFly, without touching any WildFly configuration, by running the following EJBCA command.

ant clean deployear

*** Run install ***

Run installation part of EJBCA creating the initial Management CA (for TLS and Super administrator), as well as TLS and Superadmin keystores.

ant runinstall

*** Configure TLS ***

Copy keystores to WildFly:

ant deploy-keystore

The run the following commands in JBoss CLI to configure TLS (again removing any old configuration first just to be safe).

/interfaces=/interface=http:add(inet-address="0.0.0.0")
/interfaces=/interface=httpspub:add(inet-address="0.0.0.0")
/interfaces=/interface=httpspriv:add(inet-address="0.0.0.0")
/socket-binding-group=standard-sockets/socket-binding=http:add(port="8080",interface="http")
/subsystem=undertow/server=default-server/http-listener=http:add(socket-binding=http)
/subsystem=undertow/server=default-server/http-listener=http:write-attribute(name=redirect-socket, value="httpspriv")
:reload

Wait for reload to complete by checking the server log or the result of ":read-attribute(name=server-state)" before continuing.

/core-service=management/security-realm=SSLRealm:add()
/core-service=management/security-realm=SSLRealm/server-identity=ssl:add(keystore-path="${jboss.server.config.dir}/keystore/keystore.jks", keystore-password="serverpwd", alias="localhost")
/core-service=management/security-realm=SSLRealm/authentication=truststore:add(keystore-path="${jboss.server.config.dir}/keystore/truststore.jks", keystore-password="changeit")
/socket-binding-group=standard-sockets/socket-binding=httpspriv:add(port="8443",interface="httpspriv")
/subsystem=undertow/server=default-server/https-listener=httpspriv:add(socket-binding=httpspriv, security-realm="SSLRealm", verify-client=REQUIRED)
/subsystem=undertow/server=default-server/https-listener=httpspriv:write-attribute(name=max-parameters, value="2048")
/socket-binding-group=standard-sockets/socket-binding=httpspub:add(port="8442", interface="httpspub")
/subsystem=undertow/server=default-server/https-listener=httpspub:add(socket-binding=httpspub, security-realm="SSLRealm")
/subsystem=undertow/server=default-server/https-listener=httpspub:write-attribute(name=max-parameters, value="2048")
:reload

Wait for reload to complete by checking the server log or the result of ":read-attribute(name=server-state)" before continuing.

/system-property=org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH:add(value=true)
/system-property=org.apache.catalina.connector.CoyoteAdapter.ALLOW_BACKSLASH:add(value=true)
/system-property=org.apache.catalina.connector.URI_ENCODING:add(value="UTF-8")
/system-property=org.apache.catalina.connector.USE_BODY_ENCODING_FOR_QUERY_STRING:add(value=true)
/subsystem=webservices:write-attribute(name=wsdl-host, value=jbossws.undefined.host)
/subsystem=webservices:write-attribute(name=modify-wsdl-address, value=true)
:reload

If you are using OCSP GET requests, setting URI encoding and allowing encoding for Query and backslash above is needed.

*** Optional: Enable AJP connector ***

Only needed if you run an Apache front-end in front of WildFly.

/subsystem=undertow/server=default-server/ajp-listener=ajp-listener:add(socket-binding=ajp, scheme=https, enabled=true)

*** Optional: Add support for PKCS#11 (HSMs) ***

WildFly by default isolates away most sun classes. EJBCA configures JBoss/WildFly to expose these classes (sun/security/pkcs11/wrapper), since EJBCA 6.6.3, by using a jboss-deployment-structure.xml. This makes configuration in modules/system/layers/base/sun/jdk/main/module.xml not needed.

*** Remove existing TLS and HTTP configuration ***

Run the following commands in JBoss CLI to remove existing TLS and HTTP configuration (just to be safe).

/core-service=management/security-realm=SSLRealm/authentication=truststore:remove
/core-service=management/security-realm=SSLRealm/server-identity=ssl:remove
/core-service=management/security-realm=SSLRealm:remove
/socket-binding-group=standard-sockets/socket-binding=httpspub:remove
/subsystem=undertow/server=default-server/https-listener=httpspub:remove
/socket-binding-group=standard-sockets/socket-binding=httpspriv:remove
/subsystem=undertow/server=default-server/https-listener=httpspriv:remove
/socket-binding-group=standard-sockets/socket-binding=http:remove
/subsystem=undertow/server=default-server/http-listener=http:remove
/subsystem=undertow/server=default-server/http-listener=default:remove
/system-property=org.apache.catalina.connector.URI_ENCODING:remove
/system-property=org.apache.catalina.connector.USE_BODY_ENCODING_FOR_QUERY_STRING:remove
/interface=http:remove
/interface=httpspub:remove
/interface=httpspriv:remove
:reload

*** Configure TLS ***

Copy keystores to WildFly:

ant deploy-keystore

The run the following commands in JBoss CLI to configure TLS (again removing any old configuration first just to be safe).

/interface=http:add(inet-address="0.0.0.0")
/interface=httpspub:add(inet-address="0.0.0.0")
/interface=httpspriv:add(inet-address="0.0.0.0")
/socket-binding-group=standard-sockets/socket-binding=http:add(port="8080",interface="http")
/subsystem=undertow/server=default-server/http-listener=http:add(socket-binding=http)
/subsystem=undertow/server=default-server/http-listener=http:write-attribute(name=redirect-socket, value="httpspriv")
:reload

Wait for reload to complete by checking the server log or the result of ":read-attribute(name=server-state)" before continuing.

/core-service=management/security-realm=SSLRealm:add()
/core-service=management/security-realm=SSLRealm/server-identity=ssl:add(keystore-path="${jboss.server.config.dir}/keystore/keystore.jks", keystore-password="serverpwd", alias="localhost")
/core-service=management/security-realm=SSLRealm/authentication=truststore:add(keystore-path="${jboss.server.config.dir}/keystore/truststore.jks", keystore-password="changeit")
/socket-binding-group=standard-sockets/socket-binding=httpspriv:add(port="8443",interface="httpspriv")
/subsystem=undertow/server=default-server/https-listener=httpspriv:add(socket-binding=httpspriv, security-realm="SSLRealm", verify-client=REQUIRED)
/subsystem=undertow/server=default-server/https-listener=httpspriv:write-attribute(name=max-parameters, value="2048")
/socket-binding-group=standard-sockets/socket-binding=httpspub:add(port="8442", interface="httpspub")
/subsystem=undertow/server=default-server/https-listener=httpspub:add(socket-binding=httpspub, security-realm="SSLRealm")
/subsystem=undertow/server=default-server/https-listener=httpspub:write-attribute(name=max-parameters, value="2048")
:reload

Wait for reload to complete by checking the server log or the result of ":read-attribute(name=server-state)" before continuing.

/system-property=org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH:add(value=true)
/system-property=org.apache.catalina.connector.CoyoteAdapter.ALLOW_BACKSLASH:add(value=true)
/system-property=org.apache.catalina.connector.URI_ENCODING:add(value="UTF-8")
/system-property=org.apache.catalina.connector.USE_BODY_ENCODING_FOR_QUERY_STRING:add(value=true)
/subsystem=webservices:write-attribute(name=wsdl-host, value=jbossws.undefined.host)
/subsystem=webservices:write-attribute(name=modify-wsdl-address, value=true)
:reload

If you are using OCSP GET requests, setting URI encoding and allowing encoding for Query and backslash above is needed.

*** Optional: Add support for sending email ***

If you need support for sending email (smtp) you can configure EjbcaMail with:

/socket-binding-group=standard-sockets/remote-destination-outbound-socket-binding=ejbca-mail-smtp:add(port="993", host="my.mail.server")
/subsystem=mail/mail-session="java:/EjbcaMail":add(jndi-name=java:/EjbcaMail, from=noreply@mymail)
/subsystem=mail/mail-session="java:/EjbcaMail"/server=smtp:add(outbound-socket-binding-ref=ejbca-mail-smtp, tls=true, username=smtpuser, password=smtppassword)
:reload

*** Using Derby database (Glassfish built in) ***

1. Start JavaDB and create the database instance.

     cd $APPSRV_HOME
     bin/asadmin start-database
     export DERBY_HOME=$APPSRV_HOME/javadb
     javadb/bin/ij   
     ij> connect 'jdbc:derby://localhost:1527/ejbca;create=true';
     ij> quit;
   

2. Start the application server:

   bin/asadmin start-domain
   

   The default user/password for the web console is admin/adminadmin.
   Access the Glassfish admin console at http://127.0.0.1:4848/.


3. Create a connection pool for your database. In the admin console this is done in Resources->JDBC->Connection Pools.
   When adding a Derby Pool use values: Name=EjbcaPool, Type=javax.sql.DataSource, Vendor=JavaDB.
   Properties: user=APP, password=APP, DatabaseName=ejbca
   Save and use the Ping-button for the pool. If you get 'Parameter wrong for this method : off', go to Additional Properties and delete 'Ssl'.
   Command line alternative:

       bin/asadmin create-jdbc-connection-pool --datasourceclassname org.apache.derby.jdbc.ClientDataSource --property user=APP:password=APP:DatabaseName=ejbca:ServerName=localhost:port=1527 EjbcaPool
       

4. Create a datasource called jdbc/EjbcaDS, in the admin console this is done in Resources->JDBC->JDBC Resources. Use the connection pool you just created.
   Command line alternative:

       bin/asadmin create-jdbc-resource --connectionpoolid EjbcaPool jdbc/EjbcaDS
       

   If security is enabled you have to add "--user admin --passwordfile pwd.txt" as command line parameters where pwd.txt contains 'AS_ADMIN_PASSWORD=adminadmin'.

*** Using MySQL database ***

1. Start the database and create the MySQL database "ejbca". Grant privileges to the "ejbca" user with password "ejbca_pwd" (don't use this password in production!)
2. Copy the MySQL JDBC JAR to APPSRV_HOME/lib/
3. Start the application server:

   asadmin start-domain
   

4. Add the Connection Pool and DataSource from the Glassfish Admin Console (see "Derby") or use command line:

   asadmin create-jdbc-connection-pool --datasourceclassname com.mysql.jdbc.jdbc2.optional.MysqlDataSource --property user=ejbca:password=ejbca_pwd:DatabaseName=ejbca:ServerName=localhost:port=3306 EjbcaPool
   asadmin create-jdbc-resource --connectionpoolid EjbcaPool jdbc/EjbcaDS
   

*** Configure EJBCA ***

1. Edit conf/ejbca.properties, you should at least set appserver.home
2. Edit conf/log4j-glassfish.xml, to configure EJBCA logging.
3. Edit conf/database.properties, you should at least set the database settings for your chosen database. Derby and MySQL has been tested with Glassfish.
4. Edit conf/web.properties, you should set desired values and also the http/s ports (default 8080 and 8181) for your installation.

*** Deploy and setup ***

1. If your appserver does not requires a password for deployment (asadmin deploy) you can build and deploy EJBCA with
   

   ant clean
   ant bootstrap
   

   or otherwise with an additional step.

   ant clean
   ant
   asadmin deploy --precompilejsp $EJBCA_HOME/dist/ejbca.ear
   

   You can check that everything was ok in APPSRV_HOME/domains/domain1/logs/server.log.


2. Install EJBCA

   ant runinstall
   

3. Configure SSL in Glassfish
   Configuration->HTTP Service->HTTP Listeners->http-listener-2, SSL tab
   • Client Authentication: Enabled
   • Certificate Nickname: s1as (get alias name by running 'keytool -list -v -keystore $APPSRV_HOME/domains/domain1/config/keystore.jks', password changeit)
   • SSL3: Enabled
   • Ciphers Suite: All
   Add CA certificate to cacerts file:

          cd $EJBCA_HOME
          keytool -exportcert -keystore p12/truststore.jks -file p12/managementca.der -storepass changeit -alias managementca
          

   Install the CA certificate in the application servers truststore.
   On Glassfish open source:

          keytool -delete -keystore  $APPSRV_HOME/domains/domain1/config/cacerts.jks -alias managementca -storepass changeit
              (will fail if this hasn't been done before)
          keytool -importcert -keystore $APPSRV_HOME/domains/domain1/config/cacerts.jks -file p12/managementca.der -alias managementca -storepass changeit
          

   On Glassfish Enterprise:
   • cd $APPSRV_HOME/domains/domain1/config
   • /usr/sfw/bin/certutil -A -n managementca -t "p,p,p" -i p12/managementca.der -d .
   • verify that managementca has been added to the store with '/usr/sfw/bin/certutil -L -d .'.
   
   
4. (Optional) Replace the SSL keystore and truststore with default passwords.
   In a production environment you probably want to change the keystore passwords, to do this you must edit both the http-listener and the IIOP-listeners.

       cd $EJBCA_HOME
       cp p12/tomcat.jks p12/keystore.jks
       keytool -list -keystore p12/keystore.jks -storepass serverpwd
           Read the alias for the "PrivateKeyEntry" e.g. 'localhost'.
       keytool -keypasswd -keystore p12/keystore.jks -alias localhost -storepass serverpwd -keypass serverpwd -new changeit
       keytool -storepasswd -keystore p12/keystore.jks -storepass serverpwd -new changeit
       keytool -changealias -keystore p12/keystore.jks -alias localhost -destalias s1as -keypass changeit -storepass changeit
       cp p12/keystore.jks $APPSRV_HOME/domains/domain1/config/keystore.jks
       

5. Restart server

       asadmin stop-domain
       asadmin start-domain
       

6. Access protected EJBCA pages
   Import $EJBCA_HOME/p12/superadmin.p12 in your browser and go to url:
   https://127.0.0.1:8181/ejbca/
   You can now click "Administration" to get to the admin-GUI.


7. (Optional) Change how often an EJBCA Service can run: Configuration -> EJB Container -> EJB Timer Service -> Minimum Delivery Interval: 1000. Restart application server.
   This can also be changed using the "minimum-delivery-interval-in-millis" attribute in the domain.xml-file when the appserver isn't running.
8. (Optional) Apply workaround to enable redeployment without application server restart: See ECA-1887.

*** Glassfish Ubuntu package ***

The above instructions are tested on the official release from Glassfish's homepage. We had this report from a user of the glassfish package on ubuntu.

I had to modify the following to make it work with the Ubuntu 9.04 glassfish package.

1. Modify /usr/bin/asadmin
   #GF_DOMAIN_DIR=$HOME/glassfishv2
   GF_DOMAIN_DIR=/var/lib/glassfishv2/domains
2. Set APPSRV_HOME to /usr/share/glassfishv2