EJBCA support, development and maintenance by

*** 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 AdminCA. 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 5 and OracleJVM bug ***

If you are using Oracle's JDK and JBoss 5.1.x you need to copy EJBCA_HOME/lib/bc*.jar to JBOSS_HOME/server/default/lib/. Remember this when it's time for upgrades! This is a bug tracked by JBoss as JBAS-7882. OpenJDK works just fine though, such as the OpenJDK distributed with RedHat, Ubuntu, Debian etc.

The same bug is present on JBoss 6.0, but the workaround is different, the same workaround as for JBoss 5.1 does not work with JBoss 6. The only way to work around this with Oracle JDK and JBoss 6 is to copy ejbca/lib/bc*.jar to $JAVA_HOME/jre/lib/ext, and to remove lib/bc*.jar from the deployed ejbca.ear file. See the JBAS-7882 issue for more information.

*** JBoss 5.1 WS WSDL location ***

On JBoss 5.1.x (not on JBoss 6.0.x) the WSDL location gets incorrectly generated by default. To fix this (see JBoss settings during install) edit:

 APPSRV_HOME/server/default/deployers/jbossws.deployer/META-INF/jboss-beans.xml

and comment out the line:

<property name="webServiceHost">${jboss.bind.address}</property>

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

*** JBoss 5 and multiple mail configuration ***

JBoss 5.1.x has a bug with multiple mail configurations. If you will be using mail notifications see conf/mail.properties.sample for configuration instructions. Tracked by JBoss as JBPAPP-3766. This should be resolved in JBoss EAP 5.1.

*** JBoss 5 Memory configuration ***

The memory parameters for Java is by default configured very low, for JBoss it is set by default to allow a maximum memory usage of 512mb, which is sufficient for most configurations. We still recommend that you check your configuration of java memory arguments to set them to at least '-Xms128m -Xmx512m -XX:MaxPermSize=256m'. For JBoss this is done in APPSRV_HOME/bin/run.conf where the line:

JAVA_OPTS="-server -Xms128m -Xmx512m -XX:MaxPermSize=256m"

can be changed.

*** JBoss 5 using Tomcat native SSL connector ***

Instead of the regular Tomcat SSL connector you can configure to use the native connector, which is supposed to improve performance.

See documentation in src/appserver/tomcat60jboss5, and the JBoss documentation for installing the native connector.

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

Version JBoss AS 7.1.1.Final, EAP 6.1 and EAP 6.2 (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.1.5.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.1.5.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.1.5.jar"/>
     </resources>
     <dependencies>
       <module name="javax.api"/>
       <module name="javax.transaction.api"/>
     </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.jdbc.jdbc2.optional.MysqlXADataSource)
   :reload
   

   Or for MariaDB, mariadb-java-client-1.1.5.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)

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

JBoss 7/EAP 6 isolates away most sun classes. That means you will not be able to send certificates through remote EJB calls, and will not be able to use the Sun PKCS#11 provider. These classes can be made available by editing the file modules/sun/jdk/main/module.xml (JBoss 7.1/EAP6.0) and adding the following packages to the list of system export paths:

<path name="sun/security/x509"/>
<path name="sun/security/pkcs11"/>
<path name="sun/security/pkcs11/wrapper"/>

This will allow an application to use these internal Sun/Oracle/OpenJDK classes.

This is not needed in JBoss EAP 6.1/JBoss 7.2, because the two first packages are exported by default since JBPAPP6-1748. One package is however needed still. In JBoss EAP 6.1 the file is located in modules/system/layers/base/sun/jdk/main/module.xml.

<path name="sun/security/pkcs11/wrapper"/>

*** 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 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 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 5 these are added, commented out in src/appserver/jboss/ejbca-mail-service.xml, for JBoss 7 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 5 configuration:

• Edit jboss/server/default/deploy/ejb2-timer-service.xml
• Remove the commenting around the following line, so the NoopPersistencePolicy is enabled:
  

  <mbean code="org.jboss.ejb.txtimer.NoopPersistencePolicy" name="jboss.ejb:service=EJBTimerService,persistencePolicy=noop"/>
  

• Edit the EJBTimerService and change 'PersistencePolicy' from database to noop.
  

  <mbean code="org.jboss.ejb.txtimer.EJBTimerServiceImpl" name="jboss.ejb:service=EJBTimerService">
    <attribute name="TimerIdGeneratorClassName">org.jboss.ejb.txtimer.UUIDTimerIdGenerator</attribute>
    <attribute name="TimedObjectInvokerClassName">org.jboss.ejb.txtimer.TimedObjectInvokerImpl</attribute>
    <depends optional-attribute-name="RetryPolicy">jboss.ejb:service=EJBTimerService,retryPolicy=fixedDelay</depends>
    <depends optional-attribute-name="PersistencePolicy">jboss.ejb:service=EJBTimerService,persistencePolicy=noop</depends>
    <depends optional-attribute-name="TransactionManagerFactory" proxy-type="org.jboss.tm.TransactionManagerFactory">
      jboss:service=TransactionManager
    </depends>
  </mbean>
  

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

*** XKMS ***

Please do not use XKMS. It is a rather old, generally unused protocol with poor interoperability and client suppport. There are many better options, like CMP, available.

EJBCA may deprecate XKMS in the future, and it is a best effort, cummunity based, support only.

If you decide to use XKMS anyhow you may stumble into some issues.

JBoss 7 / EAP 6: To run XKMS there are three conditions for running XKMS:

• Use JBoss EAP 6.1 (at least).
• Use JDK 7.
• Export some internal sun classes by adding the below to modules/system/layers/base/sun/jdk/main/module.xml in JBoss EAP 6.

<path name="com/sun/xml/internal/bind/marshaller"/>
<path name="com/sun/xml/bind/marshaller"/>
<path name="sun/security/action"/>

JBoss EAP 5.1: In JBoss EAP 5.1 it seems neccessary to use the Java parameter "-Dorg.jboss.ws.enable_doctype_decl=true" to the JBoss startup parameters, otherwise EJBCA will fail to deploy. Add the parameter to bin/run.sh for example.

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

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

*** 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 install
   

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

*** Configure EJBCA ***

The following must be configured for WebLogic:

1. conf/ejbca.properties: 'appserver.home' should be pointing to where weblogic is installed. (weblogic.jar is located under ${appserver.home}/wlserver_10.3/server/lib)
2. conf/database.properties: configure accoring to the used database
3. conf/web.properties: httpserver.pubhttp=7001
4. conf/web.properties: httpserver.privhttps=7002
5. conf/mail.properties: mail.jndi-name=mail/EjbcaMail
6. conf/jndi.properties.weblogic: modify the principal and credentials according to you weblogic domain's setting (same as the user name/password to login weblogic console). The default in the EJBCA installation is weblogic/foobar123.
7. conf/log4j-weblogic.xml: Path and log-levels for EJBCA specific logging.

If you had issued an 'ant' command before, it is now important to do 'ant clean' before building again. Build ejbca.ear (ejbca/dist/ejbca.ear) with 'ant'.

*** Configure Weblogic ***

1. Access the Weblogic management console at: http://127.0.0.1:7001/console/
2. Services -> DataSources:
   Create a new Generic DataSource "EjbcaDS" with JNDI name "EjbcaDS" of type "Oracle". (The URL for the pool should be something like "jdbc:oracle:thin:@127.0.0.1:1521:XE" for Oracle XE.)
3. Deployments -> Install -> wlserver_10.3/common/deployable-libraries/jsf-1.2.war as a library named "jsf".
4. Increase transaction timeout: Services -> JTA -> Timeout Seconds=300
5. Create a new java mail session for user notification in EndEntityManagementSessionBean. In Weblogic, the JNDI name should be "mail/EjbcaMail" (same as you configured in mail.properties).
   key in the properties:

     mail.store.protocol=pop3
     mail.transport.protocol=smtp
     mail.user=foouser
     mail.pop3.host=pop.foo.com
     mail.smtp.host=smtp.foo.com
     mail.smtp.port=25
     mail.smtp.auth=false
     mail.smtp.starttls.enable=false
     mail.from=foouser@foo.com
     mail.debug=false
     

   Do not forget to activate the mail session in you target server.

*** Deploy and setup ***

1. Deploy EJBCA: Install "$EJBCA_HOME/dist/ejbca.ear" that you built with Ant. It should deploy straight away without errors.
2. Run 'ant install' to do the installation. Everything should work here with no errors. If you get errors these must be resolved before we can move on.
   The command 'ant install' is only run once, when the CA is first installed. It creates lots of things in the database, and can not be run again (it will give an error if you try).
3. Configure SSL in Weblogic:
   
   1. Go to Environment -> Servers -> AdminServer -> KeyStores
   2. KeyStores: Custom Identity and Custom Trust
   3. Custom Identity Keystore: /path/ejbca/p12/tomcat.jks
   4. Custom Identity Keystore Passphrase: serverpwd (httpsserver.password in conf/web.properties)
   5. Custom Trust Keystore: /path/ejbca/p12/truststore.jks
   6. Custom Trust Keystore Passphrase: changeit (java.trustpassword in conf/web.properties)
   7. Go to Environment -> Servers -> AdminServer -> SSL
   8. Click Advanced
   9. Two Way Client Cert Behavior: Client Certs Requested But Not Enforced
   10. Private Key Alias: localhost (httpsserver.hostname in conf/web.properties)
   11. Private Key Passphrase: Same as in 'Custom Identity Keystore Passphrase' above.
   12. Go to Environment -> Servers -> AdminServer -> General
   13. Check 'SSL Listen Port Enabled'

*** Configure EJBCA ***

Configure the following for a test setup:

• conf/ejbca.properties#appserver.home=/opt/IBM/WebSphere/AppServer
• conf/database.properties#database.name=db2
• conf/log4j-websphere.xml (use conf/log4j-websphere.xml.sample)
• conf/web.properties#java.trustpassword=changeit
• conf/web.properties#superadmin.cn=SuperAdmin
• conf/web.properties#superadmin.dn=CN=${superadmin.cn}
• conf/web.properties#superadmin.password=ejbca
• conf/web.properties#httpsserver.password=serverpwd
• conf/web.properties#httpsserver.hostname=localhost
• conf/web.properties#httpsserver.dn=CN=${httpsserver.hostname},O=EJBCA Sample,C=SE
• conf/web.properties#httpserver.pubhttp=9080
• conf/web.properties#httpserver.privhttps=9443
• conf/mail.properties#mail.jndi-name=EjbcaMail
• conf/xkms.properties#xkms.enabled=true
• conf/jndi.properties.websphere Set the currect port from Servers->Application servers->server1 (your server)->Ports->BOOTSTRAP_ADDRESS.

*** WebService API ***

WebSphere 7 does not automatically expose @WebService annotated Sesison Beans. A tool bundled with WAS (endptEnabler.sh) will be invoked during the build to generate the WAR and add it to the "ejbca.ear" file.
The wsdl is accessible using the url: https://127.0.0.1:9443/ejbca/ejbcaws/ejbcaws?wsdl

*** Configure Websphere ***

Configure Websphere in the admin console.

1. Navigate to 'Resources->Mail->Mail sessions' and create a new MailSession called 'MailSession' with jndiName same as mail.jndi-name configured in conf/mail.properties (EjbcaMail).
2. Setup JDBC Provider under "Resources ? JDBC ? JDBC Providers":
   • Scope: node01, server1
   • Database type: DB2
   • Provider type: DB2 Universal JDBC Driver Provider
   • Implementation type: Connection pool data source
   • ${DB2UNIVERSAL_JDBC_DRIVER_PATH}: /opt/IBM/WebSphere/AppServer/deploytool/itp/plugins/com.ibm.datatools.db2_2.1.102.v20091026_1945/driver
   • ${DB2UNIVERSAL_JDBC_DRIVER_NATIVEPATH} : /opt/IBM/WebSphere/AppServer/deploytool/itp/plugins/com.ibm.datatools.db2_2.1.102.v20091026_1945/driver
   (the paths depend on where the jdbc-driver is available)
3. Setup DataSource (DB2 database running on the same machine):
   • Scope: node01, server1
   • Data source name: EjbcaDS
   • JNDI Name: jdbc/EjbcaDS
   • Select an existing JDBC provider: DB2 Universal...
   • Driver type: 4
   • Database name: ejbca
   • Server name: 127.0.0.1
   • Port number: 50000
   • Click on the EjbcaDS DataSource -> JAAS - J2C authentication data -> New
   • Alias: <database username>
   • UserId: <database username>
   • Password: <database password>
   • Save
   • Go back to the DataSource and select the new authentication info for "Component-managed authentication alias". Save.
   • Edit custom properties for the DataSource and set isolation level to 2.

*** Deploy and setup ***

Log into the admin console of Websphere to deploy EJBCA.

1. Install new application.
2. Select ejbca.ear and 'Fast Path' and click next.
• Precompile JavaServer Pages files
• Distribute app
• Deploy enterprise beans
• Deploy Web services
• Process embedded configuration
• Allow EJB reference targets to resolve automatically
3. Click next until it is install. Save.
4. Start application.
5. Now you can run 'ant install' to install EJBCA.

Efter deployment and installation you want to configure SSL in Websphere so you can access the Admin-GUI in EJBCA. The admin-GUI in EJBCA requires client certificate authentication.
Configure the SSL port to require client certificate in order to access the admin-GUI:

1. Navigate to Security -> SSL certificate and key management -> NodeDefaultSSLSettings -> Quality of protection (QoP) settings: Client authentication=Supported
2. Navigate to Security -> SSL certificate and key management -> Key stores and certificates
   NodeDefaultKeyStore=/usr/local/ejbca/p12/tomcat.jks
   NodeDefaultTrustStore=/usr/local/ejbca/p12/truststore.jks
   

Public web will be at: http://127.0.0.1:9080/ejbca/ and https://127.0.0.1:9443/ejbca/
Admin web will be at: https://127.0.0.1:9443/ejbca/adminweb/