EJBCA Quick start guide

Quick start guide

Prerequisites

Note

EJBCA makes use of strong crypto and keystore passwords longer than 7 characters. For this to work you must install the 'Unlimited Strength Jurisdiction Policy Files' for JDK. The policy files can be found at the same place as the JDK download at java.sun.com. The text "Using exportable cryptography" is shown on the first page in the Admin GUI if you fail to install this package. Further information on this can be found in the Sun documentation on the JCE.

Note

The default, and easiest, installation is done on JBoss. EJBCA can however also run on Glassfish, Weblogic and OC4J. If you want to deploy on these application servers, read the section for your application server below. You mileage may vary on other appservers than JBoss, which is the most well supported.

Needed to build and run are:

• JDK 1.5.x or 1.6.x (support for 1.4.x was dropped in EJBCA 3.5).
• Unlimited Strength Jurisdiction Policy Files for your JDK
• JBOSS >=4.2.x (support for JBoss 4.0.x was dropped in EJBCA 3.8).
• Ant >= 1.6.5 to build (http://jakarta.apache.org/ant/)

Note that JBoss 5 contains bugs not present in JBoss 4. EJBCA works on some version of JBoss 5 but not others. Therefore we recommend the latest version of JBoss 4 for running EJBCA.

Set the environment variable APPSRV_HOME to the directory where the appservers root is (/jboss-version). This is done so the compile process will find JEE jar files, and the deploy script will know where files are to be copied on JBoss. On JBoss they are by default copied to the directory $APPSRV_HOME/server/default/deploy.

Windows/Unix: When we describe command line commands below we use unix notation, e.g. 'ejbca.sh' for the executable command files. The same command files are available for windows as cmd-files, e.g. 'ejbca.cmd.'

Java 1.6.0
Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files 6.0
http://java.sun.com/javase/downloads/index.jsp

Java 1.5.0
Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files 5.0
http://java.sun.com/j2se/1.5.0/download.jsp

NOTE: If you are unsure what version of EJBCA you are running, type 'ant ejbcaversion' in the EJBCA_HOME directory. (EJBCA 3.5 and newer.)

Configure

Note

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

*** 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/ejbca.properties . Most options, except those related to the AdminCA can be changed after installation.

*** EJBCA configuration ***

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

 

• Customize the CA 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. 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' is the default server to start on JBoss EAP.

Do the same with other configuration files that you might want to customize. The default values often works fine and is a safe bet if you are unsure. Most options are well documented in the sample files.

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

*** 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'. For JBoss this is done in APPSRV_HOME/bin/run.conf where the line:

JAVA_OPTS="-server -Xms128m -Xmx512m"

can be changed.

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

Install

Note that the installation must be done with a user with privileges to write to APPSRV_HOME and subdirs.

1) Set the environment variable APPSRV_HOME to where your JBoss is installed, example:

APPSRV_HOME=/opt/jboss-4.2.3

Also make sure the right java tools (javac/keytool) are available in your system PATH, ie. /usr/local/jdk1.5.0_11/bin.
Due to Javas memory handling you mey need to assign more memory to ant in order to build the system without OutOfMemory errors. You can do that by setting an environment variable:

ANT_OPTS=-Xmx512m

Note

JBoss 5.x has a bug causing issues with the BC JCE provider when the Sun JVM is used. To work around this you can copy the files EJBCA_HOME/lib/bc*.jar to JBOSS_HOME/server/default/lib/. Remember this when it's time for upgrades!
JBoss 5.x also has a bug with multiple mail configurations. If you will be using mail notifications see conf/mail.properties.sample for configuration instructions.

2) Open a console and type:

ant bootstrap

it will compile, jar, war, ear everything and deploy it to JBoss.

3) Open a console (terminal) and start JBoss. You can start JBoss with the normal command 'run.sh/cmd' from APPSRV_HOME/bin. You should see JBoss picking up everything and deploying the ear without errors.

4) Type:

ant install

it will generate all certificates, keys, etc needed to run with an initial CA. You will find admin keys in ${ejbca.home}/p12. (do not delete those files!)
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).

• tomcat.jks is for the servlet container (don't bother with it)
• truststore.jks is for the servlet container (don't bother with it)
• superadmin.p12 should be imported in your browser, that's your administration certificate.

Note

Instead of creating an initial Admin CA and issuing administrator certificates from that, you can install using administrator certificates from an already existing external CA. See Administrators issued by external CAs for more information. This would replace step 4-8, but instead require other steps.

5) Stop JBoss (ctrl+c or whatever)

6) Type:

ant deploy

this will deploy everything again and configure the servlet container with the keystore file (this is why we needed to stop the container).

7) Import the certificate from EJBCA_HOME/p12/superadmin.p12 in your web browser. This is the super administrators certificate used to access the admin GUI. Other administrators with specific privileges can be created later on. The default password for superadmin.p12 is ejbca, and is configured in ejbca.properties.

8) Start JBoss again and go to https://localhost:8443/ejbca/ to access the admin-GUI, or http://localhost:8080/ejbca for the public pages.

If you create other CAs that you want to add as acceptable CAs in the SSL server configuration, or if you renew the CA certificate, you can install any CA certificate in the SSL server configuration afterwards with the following command:

ant -Dca.name="My CA Name" javatruststore

What this does in the background is that it adds the CA certificate to p12/truststore.jks and copies this file to JBOSS_HOME/server/default/conf/keystore, where the SSL keystores are located.

You must stop and start JBoss after doing this.

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/jboss/tomcat60 (if using JBoss 4.2.3) or src/appserver/tomcat60jboss5 (if using JBoss 5).

Additional howtos

In the directory doc/howto in the distribution there are additional howtos for some specific platforms and configurations.

Application servers

EJBCA can currently be run on JBoss (covered above), Glassfish (Sun AS), Weblogic, OC4J (Oracle AS) and Websphere.
(Websphere is not really supported, it's only one old version of EJBCA on one version of Websphere) .

Glassfish

Currently EJBCA works both with Glassfish v1 and v2 with the Derby/JavaDB database.

Don't forget to install 'Unlimited Strength Jurisdiction Policy Files' for Java.

*** Configure EJBCA ***

 

1. Set the environment variable APPSRV_HOME to the directory where Glassfish is installed. For example APPSRV_HOME=/home/sun/glassfish. The variable must be available when working with EJBCA.
2. Edit conf/ejbca.properties, you should at least set appserver.type, appserver.home and logging.log4j.config.
3. Edit conf/database.properties, you should at least set datasource.jndi-name-prefix, and the database settings for your chosen database. Derby is supported for Glassfish, and default options for Derby should work.
4. Edit conf/web.properties, you should set desired values and also the http/s ports (default 8080 and 8181) for your installation.
5. Configuration of ejbcaws and xkms only have to be done in Glassfish v1.
   On Glassfish v2 it deploys nicely, even though the functionality does not work completely.
   See https://jira.primekey.se/browse/ECA-607 for details.
   (Tips how to solve these probles are welcome.)
   • Edit conf/jaxws.properties and set 'ejbcaws.enabled=false'.
   • Edit conf/xkms.properties and set 'xkms.enabled=false'. (Default from EJBCA 3.10.)

Build ejbca with 'ant'.
Do 'ant clean' first if you have tried with different appservers, or database settings.

*** Configure Glassfish ***

 

1. Do yourself a favor and configure this in the JVM settings of Glassfish v1 (default in v2):
   

   -XX:MaxPermSize=192m

   Restart Glassfish
2. Derby:
   1. Start the database: asadmin start-database.
   2. Create a database and a database user with privileges.

        > cd /home/sun/glassfish/bin
        > export DERBY_HOME=/home/sun/glassfish/javadb; ../javadb/bin/ij   
         (For glassfish v1 use this command instead: 
          > export DERBY_HOME=/home/sun/glassfish/javadb; ../javadb/frameworks/NetworkServer/bin/ij.ksh)
      
        ij> connect 'jdbc:derby://localhost:1527/ejbca;create=true';
        ij> run '/home/sun/ejbca/doc/howto/create-tables-ejbca3-derby.sql';
        ij> quit;
      

3. Start the application server: 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/.
4. 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
5. 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.

*** Deploy and setup ***

 

1. Deploy ejbca.ear using:
   ./asadmin deploy ../../ejbca/dist/ejbca.ear
   The relative path to ejbca.ear depends on where you installed ejbca and glassfish. You can check that everything was ok in 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
   • bin/ejbca.sh ca getrootcert AdminCA1 ca.der -der
   Install the CA certificate in the application servers truststore.
   On Glassfish open source:
   • keytool -import -keystore $APPSRV_HOME/domains/domain1/config/cacerts.jks -file $EJBCA_HOME/ca.der
   • password is 'changeit'
   On Glassfish Enterprise:
   • cd $APPSRV_HOME/domains/domain1/config
   • /usr/sfw/bin/certutil -A -n adminca1 -t "p,p,p" -i $EJBCA_HOME/ca.der -d .
   • verify that adminca1 has been added to the store with '/usr/sfw/bin/certutil -L -d .'.
   Restart server
   (you would probably want to install your own server certificate from $EJBCA_HOME/p12/tomcat.jks instead of the default Glassfish cert, to do this you must edit both the http-listener and the IIOP-listeners. You can also generate a new $APPSRV_HOME/domains/domain1/config/keystore.jks with key alias s1as, or even easier change the alias in tomcat.jks with keytool -changealias)
4. 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.

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

The Ubuntu package has the domains and binaries separated. When following the install instructions, when you do anything with the domain you have to point to /var/lib/glassfishv2/[directory] instead of $APPSRV_HOME/[directory].

Weblogic

EJBCA should work fine with Weblogic 9.x or 10.x on Oracle 9 or 10 databases, except as noted below.
Running on weblogic has some limited functionality compared to JBoss:

• The CMP tcp listener, which runs as a JBoss MBean does not work on Weblogic.
• Web service interface (including xkms), which uses JaxWS does not work (yet).
• The timer service does not work on Weblogic 10.3, so EJBCA services will not work.

Note: After installing Weblogic, don't forget to install the "Unlimited Strenth Crypto" jce files in Weblogics jre and jrockit. It's the same way as for a regular installation, see User's Guide.

*** Configure EJBCA ***

 

1. Set the environment variable APPSRV_HOME pointing to for example /bea/weblogic92 (weblogic.jar is located under APPSRV_HOME/server/lib).
2. Edit conf/ejbca.properties and change/set some values:
   appserver.type=weblogic
   logging.log4j.config=basic
3. Edit conf/database.properties and edit/set some values that are specific for Weblogic:
   datasource.jndi-name-prefix=
   weblogic-oracle-columntype=@weblogic.dbms-column-type Blob
4. Edit conf/web.properties and change/set some values:
   httpserver.pubhttp=7001
   httpserver.privhttps=7002
5. Edit conf/mail.properties and set:
   mail.jndi-name=mail/EjbcaMail
   (it can be anything of your choice, but this is our suggestion).
6. Edit conf/jaxws.properties and change/set some values:
   ejbcaws.enabled=false
7. Edit conf/web.properties and set at least default ports:
   Default http port of Weblogic is 7001.
   Default SSL port of Weblogic is 7002.
8. Edit conf/jaxws.properties. Disabling ejbcaws must be done until we have fixed JaxWS configuration for weblogic.
   ejbcaws.enabled=false
   See https://jira.primekey.se/browse/ECA-687, tips are welcome.
9. Edit conf/xkms.properties and change/set some values:
   xkms.enabled=false (Default from EJBCA 3.10.)
   Disabling xkms must be done until we have fixed JaxWS configuration for weblogic.
10. Edit 'jndi.properties.weblogic' in the directory 'ejbca/conf'and 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 system/weblogic.
    Every time you issue a 'ant clean' command, you must re-do this step.

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. Create EJBCA domain with weblogic configuration wizard, select Basic weblogic server domain, Express, Development mode, sun's JDK at bea's home directory, and remember the admin username/password.
   • Wls 9.2 will create a default 'mydomain' for you the first time it is started.
   • Access the Weblogic management console at: http://127.0.0.1:7001/console/
   • You can set WLS_USER and WLS_PW environment variables so you don't have to enter username/pwd when starting Weblogic.
2. Create EjbcaPool and EjbcaDS in Weblogic, the JNDI name should be the one specified in ejbca.properties.
   In Weblogic9, you only create a 'Data Source', no Pools exists any longer.
   Don't forget to apply a Target for your DataSource.
   Example EjbcaDS in Weblogic 9.2:
   

   URL: jdbc:bea:oracle://127.0.0.1:1521
   Driver: weblogic.jdbcx.oracle.OracleDataSource
   Properties: user=weblogic
                  portNumber=1521
                  SID=XE
                  serverName=127.0.0.1
   

3. Create tables in the database configured for EjbcaPool and EjbcaDS in Weblogic.
   You can do an 'ant bootstrap' to JBoss if you want JBoss to create the tables for you.
   On oracle XE you can run for example: sqlplus weblogic@XE @create-tables-ejbca3-oracle.sql
   select table_name from user_tables; -- to list tables
   See the file create-tables-ejbca3-oracle.sql for table definitions, or just run /doc/howto/create-tables-ejbca3-oracle.sql for Oracle.
4. 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=[e-mail]
     mail.debug=false
     

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

If installing with Oracle, perhaps you need to replace jdbc driver at weblogic_home\server\lib, weblogic_home\server\ext\jdbc\oracle\920, 10g all to 10.1.0.2, in my case which is Weblogic 9.2.0. I have used Beas Oracle driver in Weblogic 9.2 with Oracle XE 10, and that works fine. Your mileage may vary, some JDBC drivers were known to be buggy earlier, but it seems to have improved.

*** Deploy and setup ***

 

1. Deploy the ejbca.ear file in weblogic, it should deploy straight away without errors. Activate the deployment.
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. (Optional for Weblogic 10.3:) Copy $EJBCA_HOME/p12/truststore.jks to $BEA_HOME/jre/lib/security/cacerts, so that Weblogic can trust the initial CA installed when doing 'ant install'.
      You can create a new 'cacerts' file with 'rm $EJBCA_HOME/p12/truststore.jks' and then 'ant javatruststore'. Type 'ant -p' to get a description how you can run 'ant javatruststore' with arguments to point to a specific keystore etc. You can get the CA certificate with 'bin/ejbca.sh ca getrootcert cert.pem'.
   2. Configure weblogic server for SSL.
      For Weblogic 9.2.0: Servers->Myserver->Configuration->Keystores (or SSL), click "Change", select "Custom Identity and Java Standard Trust"
      - Custom Identity Keystore: path to tomcat.jks generated while "ant install" (ejbca/p12/tomcat.jks),
      - Private Key Alias: localhost (httpsserver.hostname in conf/web.properties).
      The alias is what you configured as httpsserver.hostname in conf/web.properties
      - Passphrase: serverpwd (httpsserver.password in conf/web.properties).
      The password is what you configures as httpsserver.password in conf/web.properties.
      
      For Weblogic 10.3.0: Servers->examplesServer->Keystores (or SSL), select "Custom Identity and Custom Trust"
      Same as for Weblogic 9.2.0, but you can also configure custom trust:
      - Custom Trust Keystore: path to truststore.jks generated while "ant install" (ejbca/p12/truststore.jks),
      - Passphrase: changeit (java.trustpassword in conf/web.properties).
      
      Servers->Myserver->Configuration->SSL->Advanced->Server Attributes->Two Way Client Cert Behavior:
      - Client Certs Requested But Not Enforced
      
      Servers->Myserver->configuration->general, check "SSL Listen Port Enabled", note that the port should be same as httpserver.privhttps in ejbca.properties.

This should make the Admin GUI work, note to install the Unlimited Strength Jurisdiction Policy Files from java.sun.com for both sun's JDK and BEA's JDK first before installation. For Weblogic 10.3 it wa possible to skip the installation of the bundled JDK's and use a pre-installed Sun JDK.

*** TransactionTimeoutException in Weblogic ***

If you are running on a not-so-fast machine, you may experience TransationTimeoutException during 'ant install'. This is due to that it takes a long time for RSA key generation. To configure the transaction timeout to a larger value in weblogic:

1. logon to Weblogic Console with IE, for example, http://localhost:7001/console.
2. click "Services" at the left "Domain Structure" navigation frame to expand the service list.
3. click "JTA" to display the JTA property setting page at right content frame.
4. update the first property "Timeout Seconds" to a rational value that is enough to execute EJBCA installation (about 100s to finish the whole installation, but I recommend at least 5 minutes, i.e. 300s).

OC4J (EJBCA >=3.6)

EJBCA has been tested on Oc4j 10g (10.1.3.5.0) using Oracle 10g database.

Don't forget to install 'Unlimited Strength Jurisdiction Policy Files' for Java.

A bug in the version of TopLink bundled with Oc4j causes BLOB deserialization to fail under Java 6. See Glassfish bug report on the subject.

EJBCA's automatic authorization tests fails. This might be a lack of working transactions with Toplink. Suggestions are appreciated.

*** Configure EJBCA ***

 

1. Set environment variable APPSRV_HOME=$OC4J_HOME
2. Edit conf/ejbca.properties, you should at least set appserver.type, appserver.home and logging.log4j.config.
3. Edit conf/database.properties, you must configure the database settings for your chosen database, including username and password.
   use 'datasource.jndi-name-prefix=jdbc/'
4. Edit conf/web.properties, you should set desired values and also http/s ports.
5. Edit conf/mail.properties set and 'mail.jndi-name=mail/DefaultMail'
6. Edit conf/jndi.properties.oracle
7. You may have to remove line 186 in build.xml to make everything compile:
   <jsp-compile uriroot="${adminweb.build}" />

Build EJBCA with 'ant'.
(toplink-ejbca-jar.xml will be populated with your configured database settings)
Do 'ant clean' first if you have tried with different appservers, or database settings.

*** Configure OC4J ***

 

1. Create tables in your Oracle database using the script supplied in doc/howto/create-tables-ejbca3-oracle.sql.
2. Configure $OC4J_HOME/j2ee/home/config/application.xml to not create tables: autocreate-tables="false"
3. Configure a mail session in $OC4J_HOME/j2ee/home/config/application.xml.
   

    <mail-session location="mail/DefaultMail" smtp-host="localhost">
     <property name="mail.transport.protocol" value="smtp"/>
     <property name="mail.smtp.from" value="localhost"/>
   </mail-session>
   

4. Configure transaction timeout in OC4J to a bit longer (in order to be able to generate 4096 bit keys for example).
   In $OC4J_HOME/j2ee/home/config/transaction-manager.xml, change:
   transaction-timeout="30"
   to
   transaction-timeout="300"
   
5. Configure a connection pool (EjbcaPool) and a datasource in Oracle AS (EjbcaDS, jdbc/EjbcaDS).
6. There is an orion-application.xml under src/deploy/ear/META-INF that you can edit if you really know what you are doing with OC4J.
   Normally you don't edit this file.
7. Give the server some more PermGen space, otherwise re-deploying and re-starting will not work very often. Do this by adding '-XX:MaxPermSize=192m' as a new parameter under server->Administration->Server Properties->Start-parameters or use OC4J_JVM_ARGS="-XX:MaxPermSize=192m".

*** Deploy and setup ***

To be able to use the WS-API you must select 'search local classes first' for 'ejbcaws' under 'Configure classloading' (step 3) when deploying the ejbca application. Otherwise you have to set 'xkms.enabled=false' in conf/xkms.properties (default from EJBCA 3.10), and 'ejbcaws.enabled=false' in conf/jaxws.properties, and also edit src/deploy/ear/META-INF/orion-application.xml

1. Start OC4J (bin/oc4j -start) and log into the admin console of Oracle AS and deploy EJBCA.
   'Automatically create a new deployment plan' = checked in step 1.
   'Application Name' = ejbca in step 2.
   'Configure Class Loading' -> 'Search Local Classes First' = true for 'ejbcaws' and 'xkms' in step 3.
   
2. Now you can run 'ant install' to install EJBCA. You should configure OC4J to use a single RMI port for EJB access, and configure this port in conf/jndi.properties.oracle.
3. Configure SSL in OC4J and make sure the SSL information is passed on to Java, not terminated in Apache.
   
   • If you have SSL directly in OC4J:
     Copy file $OC4J_HOME/j2ee/home/config/default-web-site.xml to $OC4J_HOME/j2ee/home/config/secure-web-site.xml and edit to reflect these changes:

      <?xml version="1.0"?>
         <web-site xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://xmlns.oracle.com/oracleas/schema/web-site-10_0.xsd"  
             port="8889" display-name="OC4J 10g (10.1.3) Secure Web Site" schema-major-version="10" schema-minor-version="0" secure="true">
             <default-web-app application="default" name="defaultWebApp" />
             <access-log path="../log/secure-web-access.log" />
             <ssl-config keystore="path-to-ejbca/p12/tomcat.jks" keystore-password="serverpwd" needs-client-auth="true" />
         </web-site>
     

     Add the following to $OC4J_HOME/j2ee/home/config/server.xml

     <web-site path="./secure-web-site.xml" />
     

     Also figure out a way to bind ejbca to the secure site, or it may disappear from time to time... If you know how this works, please let us know...
   • If you have an Apache front-end:
     
     • Enable SSL in Apache:
       These options must be enabled in ssl.conf:
       SSLVerifyClient require
       SSLOptions +StdEnvVars +ExportCertData
     • Add EJBCA CA-certificate to wallet with owm (oracle wallet manager)
     • Enable SSL in opmn
       Open opmn.xml in a text editor.
       In the <ias-component id="HTTP_Server"> entry, change the start mode from "ssl-disabled" to "ssl-enabled".
       After modification is made, the entry should look like the following:
       <data id="start-mode" value="ssl-enabled"/>
     • Update mod_oc4j.conf
       Add this line
       Oc4jExtractSSL On
       
     • opmnctl shutdown; opmnctl startall

After this you should be able to access the admin-GUI in EJBCA.

*** Runtime ports ***

OC4J have a habit of changing the runtime ports used for remote EJB calls every time it starts. This causes problems with the EJBCA command line interface. The port used by the EJBCA cli is configured in conf/jndi.properties.oracle, and you don't want to change this and to a complete 'ant' cycle every time you restart the server. To make OC4J use a fixed runtime port you can go to Cluster Topology->Runtime Ports page of the Application Server Control. Set 'Port Range' to the single value, that you can pick from 'Port in Use'.

Websphere (EJBCA 3.6)

EJBCA 3.6 has been tested with Websphere ND 6.1 and Oracle 10g or PostgreSQL 8.2 database.
(Websphere Express seems broken and Websphere Community Edition is a completely different appserver).

Note! Due to the massive work involved to support Websphere not all versions will be deployable. Currently only EJBCA 3.6 is possible to install on Websphere.

Install the Unlimited strength crypto policy files for the IBM java shipped with Websphere. You need to download these files from IBM. The IBM policy files version 1.4.2 works with IBM JDK 5.

Websphere runs with IBMs java 5 and EJBCA should be compiled with this compiler as well.

Installing Websphere on Ubuntu linux requires you to change /bin/sh to /bin/bash in all shell scripts, because Ubuntu uses /bin/dash as /bin/sh but Websphere requires bash.

sudo perl -p -i -e "s/\/sh$/\/bash/"  /opt/IBM/WebSphere/AppServer/bin/*.sh

(point the IBM directory to where you install Websphere)

*** Configure EJBCA ***

 

1. Edit conf/ejbca.properties, you should at least set appserver.type, appserver.home and logging.log4j.config.
2. Edit conf/database.properties, you must configure the database settings for your chosen database.
   use 'datasource.jndi-name=EjbcaDS' (default)
   use 'datasource.jndi-name-prefix=jdbc/'
3. Edit conf/web.properties, you should set desired values and also http/s ports (i.e. 9080 etc).
4. Edit conf/mail.properties, set 'mail.jndi-name=EjbcaMail'
5. Edit conf/jaxws.properties, set 'ejbcaws.enabled=false'
   You can use the WS-API, i.e set the property to true, in WebSphere. But if you do not plan to use it, we recommend that you keep it as false. See below for more WS-API info.
6. Edit conf/xkms.properties, set 'xkms.enabled=false' (default from EJBCA 3.10)
7. Edit conf/log.properties, enable the ProtectedLogDevice, 'usedLogDevices=Log4jLogDevice;ProtectedLogDevice'
8. Edit conf/jndi.properties.websphere and set the currect port from Servers->Application servers->server1 (your server)->Ports->BOOTSTRAP_ADDRESS.

Build EJBCA with 'ant'.
(files in src/deploy/websphere will be populated with your configured database settings)
Do 'ant clean' first if you have tried with different appservers, or database settings.

*** WebService API ***

If is possible to use the WebService API in WebSphere. Most API functions are working, while a few seems to be hit by incompatibility issues. When EJBCA with WS-API is deployed in WebSphere you can use the regular WS CLI (command line interface) to make WS calls from another machine.
The wsdl is accessible using the url: http://localhost:9080/ejbca/ejbcaws/ejbcaws?wsdl

It is also possible to deploy EJBCA WebService API in Websphere as a separate war file.
AFTER you have deployed and installed EJBCA below you can perform these steps:

1. Generate the stand alone ejbcaws.war file for Websphere with 'ant ejbcaws.war.standalone'.
2. Deploy the file dist/ejbcaws.war in Websphere.
3. Get the generated WSDL with url: http://127.0.0.1:9080/ejbcaws/ejbcaws?wsdl
4. Configure the ejbcaws CLI in dist/ejbcawscli/ejbcawsracli.properties.

*** Configure Websphere ***

Configure Websphere in the admin console.

1. Create tables in your database using the script supplied in doc/howto/create-tables-ejbca3-oracle.sql or doc/howto/create-tables-ejbca3-postgres.sql.
2. 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).
3. Create a new DataSource:
   Creating a datasource for Oracle:
   • Install the oracle jdbc jar (ex ojdbc4.jar) in $WAS_HOME/lib.
   • Navigate to Resources->JDBC->JDBC Providers
   • Select for example Cell scope, and click New
   • Select 'Oracle' from 'Database type' dropdown
   • Select 'Connection pool data source' from 'Implementation type' dropdown
   • Insert the path to the jar file, i.e. $WAS_HOME/lib
   • Finish and save
   • Navigate to Resources->JDBC->Data sources
   • Select for example Cell scope, and click new
   • Provide a data source and Jndi name, jndi name must match the jndi-name-prefix and jndi-name configured in database.properties, e.g. jdbc/EjbcaDS
   • Click next
   • Select your created JDBC Provider, and click Next
   • Enter the database URL, e.g. jdbc:oracle:thin:@127.0.0.1:1521:ejbca
   • Select 'Oracle10g data store helper', and click Next. The checkbox 'Use this data source in container managed persistence (CMP)' must be checked.
   • Finish
   • Navigate to Resources->JDBC->Data sources
   • Select the created data source
   • Click on the 'JAAS - J2C authentication data' link
   • Add new record:
     Alias: ejbca
     User ID: ejbca
     Password: ejbca
   • Save all changes
   • Go back to the datasource and select the create authentication provider as 'Component-managed authentication alias'
   • Click OK and save all changes
   • You can now go in and 'Test Connection' for your new DataSource. Make sure it is successful
   Creating a datasource for PostgreSQL:
   
   • DataSourceProvider: For postgres I used 'User-defined' type and implementation class name 'org.postgresql.jdbc3.Jdbc3ConnectionPool', or 'org.postgresql.xa.PGXADataSource'. I used the jdbc driver postgresql-8.2-507.jdbc3.jar.
   • DataSource: You have to add Custom Properties to the datasource with databaseName, serverName and port (port is optional).

*** Deploy and setup ***

Log into the admin console of Websphere to deploy EJBCA.

1. Install new application.
2. Select ejbca.ear and 'Show me all installation options and parameters' and click next.
3. Click next. Click next all the time unless anything else is noted here.
4. When you get the option to select database type at Step 3 (Deploy EJB option - Database type) select 'ORACLE_V10G' for Oracle, or empty for PostgreSQL.
5. At the next step, Step 4, select Current Backend Id, ORACLE_V10_1 for Oracle or CLOUDSCAPE_V51_1 for PostgreSQL (if using Oracle you may not get this choice).
6. Click next until you reach the end, or jump directly to the last step by clicking in the left meny.
7. Click finish
8. In order to use the cli in EJBCA you must copy the generated ejbca-ejb.jar to local lib, so we have it in the classpath for command line operations. example: cp /opt/IBM/WebSphere/AppServer/profiles/AppSrv04/installedApps/computerNode01Cell/EJBCA.ear/ejbca-ejb.jar $EJBCA_HOME/lib/.
9. 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 Servers->Application servers->server1->Web Container Settings->Web container transport chains
2. Change the WCInboundDefaultSecure to require client certificate. The trick is to create a new node SSL configuration that manages this connection. You don't want to require SSL in the NodeDefaultSSLSettings, since that will apply to your Websphere admin as well. You set 'require client cert' in the Quality of protection settings.
3. Add the CA certificate from EJBCA to the default trust store and use that. In Websphere ND you add certificates to the truststore under Security->SSL Certificateas and key mgmt->Key stores and certificates->CellDefaultTrustStore->Signer certificates.
   You can download the certificate for AdminCA1 for example with the CLI command:
   bin/ejbca.sh ca getrootcert AdminCA1 adminca1.der -der
   Then you add the certificate in CellDefaultTrustStore as 'Binary DER data'.
4. You have to restart the server after configuring this (complete restart with server, node and mgr).
5. (You can also add a new server SSL keystore by creating a PKCS12 file in EJBCA and adding that in 'Key stores and certificates' and using it in the SSLSettings for WCInboundDefaultSecure).

After this you should be able to access the admin-GUI in EJBCA after installing $EJBCA_HOME/p12/superadmin.p12 in your browser.

Public web will be at: http://127.0.0.1:9080/ejbca/index.jsp
Admin web will be at: https://127.0.0.1:9443/ejbca/adminweb/index.jsp

The default password for SSL keystore (key.p12) in Websphere is WebAS.

Files deployed

Here we describe shortly which files are copied during ant bootstrap and ant deploy. These targets only modified files automatically on the JBoss platforms, but it will give an indication as well for other platforms what configuration steps are needed.

ant bootstrap

• deploy/ejbca-ds.xml
• deploy/ejbca-mail-service.xml
• deploy/ejbca.ear

ant deploy

• Files from ant bootstrap
• conf/keystore/keystore.jk
• conf/keystore/truststore.jks
• deploy/jboss-web.deployer/server.xml