EJBCA - Open Source PKI Certificate Authority
Search ejbca.org on Google:
EJBCA 6.7.0 Enterprise (r25420)

Questions

General

Answers

Timeouts and errors during 'ant deploy' with EJBCA 6+ and JBoss 7 / EAP 6.

Ensure JBoss 7 / EAP 6 has enough cores (more than one), enough CPU (otherwise timeouts will occur) and enough memory (will also slow down the system).

The current installation procedures for JBoss 7 / EAP 6 uses the JBoss CLI to configure the application server. The JBoss CLI turns out not to be too well suited for automated deploys, so functions can break. For example if the machine has too few cores CLI connections will mysteriously terminate and report errors.
Contributions to improve the automated installation on JBoss 7 / EAP 6 are welcome.

I get an error during installation on JBoss 5, 6 or 7 using Oracle JDK (JCE cannot authenticate the provider BC).

Note that if you are using EJBCA 6.1 with JBoss 7, you should not encounter this issue as it was worked around in ECA-3371.

For older versions this answer still applies:
This is because JBoss 5, 6 and 7 have a bug using security providers with Oracle JDK. See JBoss issue JBAS-7882.

Everything works fine using OpenJDK, such as the one included with RedHat or Ubuntu servers.
The way to work around this is different on JBoss 5 and JBoss 7.

On JBoss 6 with Oracle JDK copy ejbca/lib/bc*.jar to $JAVA_HOME/jre/lib/ext, and remove lib/bc*.jar from the deployed ejbca.ear file. If you are unsure about this workaround (and the implications it has for upgrades) we suggest using JBoss 5.1.0 instead, where there is a simpler workaround.

On JBoss 5.1 with Oracle JDK copy ejbca/lib/bc*.jar to $JBOSS_HOME/server/default/lib. Don't forget this when you upgrade EJBCA.

On JBoss 7 you may be able to install the BC libraries as modules. See description in the JBAS-7882 issue linked above.

I get an error with "Illegal key length" when using EJBCA.

This is because you have not installed the "Unlimited Strength Crypto Policy Files" in the Oracle JDK. See the prerequisites section in the the installation guide.
Even if you think you have installed them, you have not. This error is simple and unique.

It may also be that you are trying to enroll for a certificate passing in a public key with length that is shorter than the required key length specified in the Certificate Profile.

What certificates does EJBCA support?

EJBCA support X.509 v3 certificates and CVC certificates according to EAC 1.11 (BSI TR-03110).

Does EJBCA support Netscape certificate extensions?

Yes through custom extensions, see admin guide and src/java/certextensions.properties for details. These extensions are old and should not be used. There are no common clients that needs them anymore and it is almost certain to cause you more trouble than they solve. Please don't use them.

Does EJBCA support Microsoft certificate extensions?

Yes some through the Admin GUI and others through custom extensions, see Admin Guide, certificate profiles and src/java/certextensions.properties for details. many MS extended key usages are supported and all common (all we know at least) windows functions using certificates works with EJBCA certificates.

I get an error with "Java heap space" when building EJBCA (during ant deploy).

The error should be something like:
/usr/local/ejbca_3_6_b1/compile.xmli:239: Java heap space

This error is because the default maximum allowed memory allocation for Java is too low.
Do this in unixes:

      export ANT_OPTS=-Xmx=512m
      ant deploy
      

On windows set the environment variable ANT_OPTS to -Xmx=512m, and restart your shell.

That should work.

My installation failed for some reason that is now fixed, how do I proceed?

The best way to recover is usually o start over from scratch:

I get strange errors during 'ant deploy' or 'ant install'.

This is most usually due to a database configuration error. In the server log (JBOSS_HOME/server/default/log/server.log) you will probably see some SQLException errors. You should then:

See the configuration and troubleshooting section in doc/howto/HOWTO-database.txt for additional database related information.

After upgrade I get a "java.lang.NoSuchMethodError" error accessing the admin GUI.

JBoss (5.1) is bad at cleaning temporary files, sometimes we have to help. Remove the directories JBOSS_HOME/server/default/tmp and JBOSS_HOME/server/default/work and restart JBoss.

During the build process I get errors like: BUILD FAILED /usr/ejbca/build.xml:789: java.lang.ExceptionInInitializerError

You probably have ant pre-installed as a package from Fedora or Suse. Those pre-installations does not contain all default ant modules. You need the "optional tasks" included in the official ant distribution. Either add modules to the installed ant, or download the latest ant from http://ant.apache.org/.

A simple fix is to change the /etc/ant.conf to point to your user installed ant (in /your/ant/home). Change from:

#
# ant.conf (Ant 1.6.x)
# JPackage Project (http://www.jpackage.org/)
#

# Validate --noconfig setting in case being invoked
# from pre Ant 1.6.x environment
if [ -z "$no_config" ] ; then
  no_config=true
fi

# Setup ant configuration
if $no_config ; then
  # Disable RPM layout
  rpm_mode=false
else
  # Use RPM layout
  rpm_mode=true

  # ANT_HOME for rpm layout
  ANT_HOME=/usr/share/ant
fi
      

to this

#
# ant.conf (Ant 1.6.x)
# JPackage Project (http://www.jpackage.org/)
#

# Validate --noconfig setting in case being invoked
# from pre Ant 1.6.x environment
if [ -z "$no_config" ] ; then
  no_config=true
fi

# Setup ant configuration
if $no_config ; then
  # Disable RPM layout
  rpm_mode=false
else
  # Use RPM layout
  rpm_mode=false

  # ANT_HOME for rpm layout
  ANT_HOME=/your/ant/home
fi      
      

For Ubuntu things are much easier, just 'sudo apt-get install ant' and 'sudo apt-get install ant-optional'.

An error that a user can not have the same Subject DN as another user appears when issuing certificates.

Since EJBCA 3.10 different end entities can not, by default, have the same subject DN issued from one CA. This is to enforces subject DN uniqueness. In some cases this is not convenient because one user can appear as multiple end entities.

You can enable/disable this function in the "Edit Certificate Authorities" screen in the Admin GUI. In the CA configuration uncheck 'Enforce unique DN'.

I get an exception with an SQL error like "Value too large for column USERDATA.SUBJECTALTNAME" (or SUBJECTDN) when adding a new user.

This can happen if you have specified one or more fields of the "Subject Alternative Name" with a total length exceeding 255 characters. To avoid this problem you can safely extend the size of the column SUBJECTALTNAME and SUBJECTDN of the table USERDATA and SUBJECTDN of CERTIFICATEDATA.

An example for extending the subjectDN and altName columns in MySQL (version > 5.0.3) is;

mysql> alter table CertificateData modify subjectDN varchar(2048);
mysql> alter table UserData modify subjectDN varchar(2048);
mysql> alter table UserData modify subjectAltName varchar(2048);
      

With the new size of columns you can get problems applying indexes in some versions of databases, for example:
""Specified key was too long; max key length is 767 bytes"

You can circumvent this by creating the index over a subset of the column:

mysql> create index certificatedata_idx4 ON CertificateData (subjectDN(250));      
      

How can I run JBoss as a service in Windows?

There is documentation over at JBoss for several different options:
http://community.jboss.org/wiki/RunJBossAsAServiceOnWIndows

In short summary you should download JBoss Native, that has a script for installing JBoss as a windows service.

Enroll manually for a server - why are my PKCS10 DN fields Ignored?

PKCS#10 is a standard format for sending the public key (self signed to provide proof-of-possession) to a CA.

EJBCA does not trust the DN parts the user enters when he creates the PKCS10 request. The only way to match the certificate with what you enter in the pkcs10 is to enter the same thing in the end entity in EJBCA.

If you really trust your RAs that send certificate requests, there is an option "Allow DN Override" in Certificate Profiles that can be used. This is described more in detail in the docs.

Where is the log file stored for tracking errors and debug information?

JBOSS_HOME/server/default/log/server.log or where you configured conf/log4j-appserver.xml to store them.

Note that JBoss 6 and Glassfish does not use Log4j natively. For thos application servers you configure where EJBCA should log in ejbca/conf/log4j-appserver.xml

How do I configure log level in JBoss?

See the Installation guide in the JBoss section for instructions.

I want to add my own static pages under http://hostname:8080/ejbca/ ?

Put your files (static HTML is easy) under modules/publicweb-gui/resources/, do a full build and re-deploy.

I get an error message when accessing the Admin GUI, "Could not establish an encrypted connection because your certificate was rejected ... Error code: -12224"?

1) Make sure you have imported to correct superadmin.p12 in your browser.

2) You may have to delete and import the CA certificate in your applicatioon server trust-store:

ant javatruststore

You can also import another CA than the initial ManagementCA (My CA in the example) with the command:

ant -Dca.name="My CA" javatruststore

Make sure you restart JBoss after making changes to the java trust store.

Perhaps the JBoss/Tomcat configuration was not done automatically because you are running another configuration than 'default' in JBoss. the file 'jboss-5.1.0.GA/server/default/deploy/jbossweb.sar/server.xml' holds the Tomcat configuration. The configuration should be like the following, where 'serverpwd' is the 'httpsserver.password' as configured in web.properties.

<!-- HTTPS Connector requiring client cert on port 8443 -->
<Connector port="8443" address="${jboss.bind.address}"
    maxThreads="100" strategy="ms" maxHttpHeaderSize="8192"
    emptySessionPath="true"
    scheme="https" secure="true" clientAuth="true"
    keystoreFile="${jboss.server.home.dir}/conf/keystore/keystore.jks"
    keystorePass="serverpwd" sslProtocol = "TLS" />

Also the file '$EJBCA_HOME/p12/tomcat.jks' must be copied to '$JBOSS_HOME/server/default/conf/keystore/keystore.jks', where 'default' should be replaced with the JBoss configuration you are using.

I get a blank page on the Admin GUI after start?

Either you entered a hostname (in httpsserver.hostname in web.properties) that does not resolve to the machine where EJBCA is running during setup, or you changed the port that JBoss listens to. Make sure the hostname resolves to the machine EJBCA is running on.

When running 'ant install' or creating JKS or PKCS12 files you can't use longer password than 7 characters. Anything longer gives an error?

Note, this is only relevant to OracleJDK. OpenJDK does not have this restriction.

If you want to use strong crypto and/or password longer than 7 characters in keystores 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. Further information on this can be found in the Sun documentation on the JCE.

Java 1.7.0
Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files 7.0
http://www.oracle.com/technetwork/java/index.html

I get the error "Object Class Violation : (65)" when publishing certificates in LDAP

You LDAP object class may require some fields in the DN that you have not entered. Some schemas require the DN-attribute SN for instance.

Why do I get the exception/error: Got request with status GENERATED (40), NEW, FAILED or INPROCESS required: foo; nested exception is: javax.ejb.EJBException:null

When using the AuthenticationSession (default) all users have a STATUS. The status lifecycle begins with NEW and ends with REVOKED. Only when the status is NEW, FAILED or INPROCESS is it possible to issue a certificate to a user. After a certificate has been issued, the status is set to GENERATED. This works like a one-time-password scheme. To issue a new certificate to the user his/her status must be reset to NEW, FAILED or INPROCESS. This can be done with the Admin GUI or: bin/ejbca.sh ra setendentitystatus username status Status '10' is NEW. Just enter 'bin/ejbca.sh ra setendentitystatus' to see a list of all status codes.

How do I manipulate EJBCA-keystores using Java's 'keytool'?

EJBCA supports the PKCS12 format for the keystore because it is a standard, and we like standards. Normally keytool (e.g. Java's) can read PKCS12 file but not write, so the BouncyCastle JCE is needed to handle PKCS12 keystores.

keytool -list -alias privateKey -keystore server.p12 -storetype PKCS12 -storepass foo123 -provider org.bouncycastle.jce.provider.BouncyCastleProvider -providerpath $EJBCA_HOME/lib/bcprov-jdk15on-154.jar
	  

It should be possible to import etc as well using keytool.

How do I make a keystore using keytool with a real certificate from EJBCA?

# First generate a new keystore and a keypair:
keytool -genkey -alias mykey -keystore myks.jks -keyalg RSA -dname c=SE,O=AnaTom,CN=Test -keypass foo123 -storepass foo123
# You SUN keystore is now in the file 'myks.jks'. 
# Next generate a certification request (PKCS10):
keytool -certreq -alias mykey -sigalg SHA1WithRSA -file myreq.p10 -keypass foo123 -keystore myks.jks -storepass foo123

You now have the certification request in the file 'myreq.p10'. Open up EJBCA request page in your favorite browser, 'http://127.0.0.1:8080/ejbca', and select the link for NOT having a browser' Download the Root CA certificate by clicking on the link. Save the certificate as 'ca.pem'. Enter the username and password of a valid user with status NEW, see question 'Why do I get the exception/error:' above. Copy and paste the contents of the certification request, 'myreq.p10' into the text field. Save the returned certificate as 'cert.pem'.

# Import the Root CA certificate into the keystore 'myks.jks':
keytool -import -alias cacert -file ca.pem -keystore myks.jks -storepass foo123
# Import the certificate reply into the keystore:
keytool -import -alias mykey -file cert.pem -keystore myks.jks -storepass foo123 -keypass foo123
# Now you can take a look at your SUN keystore with:
keytool -list -keystore myks.jks

In theory, you can use the same method with a BouncyCastle PKCS12 keystore by adding the following arguments to every command above:

-provider org.bouncycastle.jce.provider.BouncyCastleProvider -storetype PKCS12 -providerpath $EJBCA_HOME/lib/bcprov-jdk15on-154.jar

unforturnately a bug in keytool prevents this from functioning properly at the moment, therefore I recommend using the 'bin/ejbca.sh ca' to create PKCS12 keystores. It can be used to create keystores generally, not just for CAs.

What is EJBCA's export classification (ECCN code)?

In theory EJBCA would be classified under ECCN code 5D002.c.1, and the PrimeKey PKI Appliance under 5A002.a.1 and approved for export under License Exception TSU. See The Bureau of Industry and Security website for further details.

However, in EJBCA, SignServer and the PrimeKey PKI Appliance encryption is only used for authentication and digital signatures. The products are therefore not controlled according to 5D002.c.1 or 5A002.a.1.

When a new end entity is created, where and how is the password stored?

A one-time password is stored hashed with BCrypt in the UserData table in the database. If the checkbox 'clear text password' is checked when adding the user the password is stored in clear text, to be used for server side generation.

Where are software based CA keys stored in the database?

These keys are stored in a PKCS#12 file, encrypted with a password. The PKCS#12 is stored in the database in the CAData table.

If I enable key recovery, where are the end entities private keys stored in the database?

The private keys for key recovery is stored in the KeyRecoveryData table in the database. The data is encrypted with the CAs encryption key. The private keys are only stored if key recovery is enabled.