Standalone VA Installation
1. On the EJBCA VA - Configure the VA
A Validation Authority installation is at first glance identical to a standard CA installation, but only a subset of services need to be activated for it to function as a VA. This means that an EJBCA installation could in practice be used as both its own CA and as a VA for another CA at the same time.
The VA is configured using the same configuration files as EJBCA. Files that are of special interest to an installation acting as a VA are va.properties, ocsp.properties, crlstore.properties and certstore.properties. For the certificate and CRL store services, the sample file should be enough to understand how to set the VA up. For the OCSP responder, all default options for the OCSP behavior are set in the conf/ocsp.properties and conf/va.properties files and the AdminGUI (or the command line). In the OCSP responder case, you may also want to configure conf/cesecore.properties for "Secure audit log configuration", i.e. if you want to log to database or file. The database audit log is only used for security events, i.e. access control and configuration change events when using the GUI or CLI.
2. On the EJBCA VA - Build the VA
The VA is built in the same way as the CA. So after starting JBoss, run the following command from EJBCA home directory:
ant deploy
If you have not disabled SSL (by setting 'web.nosslconfigure' in web.properties file), you will need to copy tomcat.jks and truststore.jks from EJBCA_HOME/p12 directory on the CA to the EJBCA_HOME/p12 directory on the VA (You might need to configure web.properties to use the right passwords). Then, from EJBCA home directory, run the following commands:
ant deploy-keystore ant web-configure
3. On the EJBCA CA - Data Synchronization
*** a. Using VA Publisher (Enterprise feature only) ***
The EJBCA CA should be configured the same when installing a VA as for any other installation with the addition of setting preferences for the VA database in conf/va-publisher.properties. The VA database is the master database for the standalone VA installations and where the master CA will publish certificates when they are issued or revoked.
In the case of the VA being an OCSP responder, the data source 'java:/OcspDS' should be set in JBoss. The VA data source should not be involved in transactions (a no-tx-datasource in JBoss), and it should have autocommit (should be default in JBoss). See Installation for instruction on how to create this data source if needed.
*** b. Using EJBCA Peer System (Enterprise feature only) ***
Instead of configuring va-publisher.properties, it is possible to publish certificate data through a peer connector. For instruction on how to set up an outgoing peer connector see Managing EJBCA Peer Systems.
When setting up a new Peer System, all previously issued certificates need to be pushed to the VA. To do this, use the following procedure:
- In the Admin GUI, go to
Peer Systems - Click
Managefor the peer connector representing the VA and select theCertificate Data Synchronizationtab - Configure the relevant subset of information to synchronize and click Start to initiate the synchronization as a background task. The progress can be followed either in this view or in the Peer Systems overview.
/peerincoming /peerpublish/readcert /peerpublish/writecert /ca/[CAName] access
rules to be able to check synchronzation data and push missing or outdated certificate entries.
4. On the EJBCA CA - Add a Publisher (Enterprise feature only)
Add a new publisher to the main CA server (not the VA). All CAs that publish certificates and CRLs to the VA should have a reference to this publisher. To configure this you must be a super administrator.
This publisher is added on the "Edit Publishers" page in the Admin GUI.
*** a. Using VA Publisher (Enterprise feature only) ***
Use publisher type "Validation Authority Publisher". The settings for this publisher are as follows:
- 'Data Source' - is the database of the standalone VA where this publisher will publish certificates. Use java:/OcspDS if ocsp-datasource.jndi-name=OcspDS. This must be a non-tx/jta=false data source (see Installation for instruction how to create this manually if needed).
- 'Store certificate at the Validation Authority' - stores the complete certificate on the VA. If this is unchecked only the information needed to answer OCSP requests are stored, but not the certificate itself. There are good reasons not to publish the whole certificate. It is large, thus making it a bit of heavy insert and it may contain sensitive information. On the other hand some OCSP Extension plug-ins may not work without the certificate. A regular OCSP responder works fine without the certificate. A publisher for CA certificates (used on a 'Edit Certificate Authorities' page) must have this enabled.
- 'Publish only revoked certificates' - If checked only revoked certificate are stored on the VA. The OCSP responder of the VA must have the 'nonexistingisgood' (conf/ocsp.properties) enabled if only revoked certificates are published. A publisher for CA certificates (used on a 'Edit Certificate Authorities' page) must have this disabled.
- 'Store CRL at the Validation Authority' - should be set if the CRL store service of the VA should be used for a CA (only has a meaning for publishers used on a 'Edit Certificate Authorities' page). In order to use this option you must also check 'Store certificate at the Validation Authority', and you must not check 'Publish only revoked certificates'. This is because the CA certificate(s) must also be stored in the VA when CRLs are stored there.
If the VA is a certificate or a CRL store service, the installation of the VA is complete. If the VA is an OCSP responder, continue the installation by following the steps described in OCSP installation.
VA database
Certificate revocation information for the VA services must be present in the database of the instance acting as VA/OCSP responder. If the issuing CA and VA instances of EJBCA uses different databases, Publishers are used to push real-time information from the CA to the VA database.
Error handling
If there is an error publishing to the VA database, the VA/OCSP Responder will be out of sync with the CA. It is very important to re-synchronize the databases in that case.
In case of failure to publish to the VA database the following error message will appear in the server log on the EJBCA server:
Validation Authority ERROR, publishing is not working
This will be followed by more details of the error.
The log must be monitored to discover such a fault and if such a fault is discovered an alarm should notify the operator that he has to fix whatever is wrong and then synchronise the VA database with the EJBCA database (see 'Synchronise the database of the responder').
Synchronise the database of the responder
At the beginning and after failure in publishing to the VA responder, the master database of the publishers must be synchronized with the CertificateData and CRLData table of the database of EJBCA. If you only use OCSP and not CRL store, only the CertificateData table needs to be synchronized.
If there is a single certificate out of sync you can re-sync it by doing a 'Republish' from the AdminGUI.
The following procedure may be used to synchronize the database of EJBCA with the database of a pure VA instance (e.g. where all certificates are issued on another instance):
The example is for MySQL and should be adapted to your environment (database, hostnames, database name and database credentials).
1. Prevent any further issuing of new certificates and revocation of old certificates until the
synchronization is finished. This might be done by simply blocking the port to the AdminGUI.
2. On the host of CA the following commands can be used to make the synchronization:
Run on the OCSP responder machine (as root user in mysql):
mysql -u ejbca -p ocsp_db mysql> drop table CertificateData; mysql> drop table CRLData;
This drops and re-creates the tables containing certificate and CRL information. Run on the CA server:
mysqldump -u ejbca -p --compress ejbca_db CertificateData > CertificateData.dat mysqldump -u ejbca -p --compress ejbca_db CRLData > CRLData.dat cat CertificateData.dat | mysql -h ocspresponder ocsp_db cat CRLData.dat | mysql -h ocspresponder ocsp_db
3. Check that the publishing is working before allowing issuing and revoking.