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 and conf/ejbca.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 and conf/ejbca.properties.sample to conf/ejbca.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 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 6 logging ***

On JBoss 6 logging is not included in the regular server.log file (because JBoss does not use log4j anymore).
Configure conf/log4j-jboss6-xml for logging level and log file locations (default works as well). A sample file is provided.

*** JBoss 6 WS warning during startup ***

On JBoss 6 some warnings related to WebServices are logged during startup.

...duplicate class definition bug occured? Please report this...

This is harmless and dure to a bug in OpenJDK/Jax-WS. See ECA-2163.

*** JBoss 6 Schema validation ***

By default JBoss (at least 6.0.0) tries to validate schemas when deploying for example web services (XKMS is notorious). If you don't have an internet connection this will obviously not work if the appserver does not have all schema built in (it does not for XKMS). You can luckily turn of schema validation. Here is RedHat's description.

Edit file server/default/deployers/ear-deployer-jboss-beans.xml and look for the following sections:

<!-- uncomment to disable xml validation
<property name="useValidation">false</property -->
<!-- in case xml validation is disabled, it's also better to turn off schema validation
<property name="useSchemaValidation">false</property -->

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

*** Using JBoss/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.

*** 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/adminca1.der -storepass changeit -alias adminca1
          

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

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

   On Glassfish Enterprise:
   • cd $APPSRV_HOME/domains/domain1/config
   • /usr/sfw/bin/certutil -A -n adminca1 -t "p,p,p" -i $EJBCA_HOME/p12/adminca1.der -d .
   • verify that adminca1 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 UserAdminSessionBean. 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/log.properties#usedLogDevices=Log4jLogDevice
• 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/