Managing EJBCA Configurations

EJBCA maintains its static configurations under the conf directory. The directory includes various configuration files (saved as *.properties.sample), which need to be renamed to *.properties to become active. For production installations, it's recommended to maintain the configuration files in a separate directory, in order to retain the configuration when upgrading EJBCA. 

Required Configuration

Before continuing, some configuration files need to be modified to ensure that the basic EJBCA installation performs as expected. Other changes can be made after the installation and can be effected by redeploying EJBCA.

install.properties 

The configuration file install.properties specifies the properties of the Management CA. The following lists properties required to be configured prior to installation. Note that the configuration file may include other properties than the ones listed below.

PropertyDefault ValueDescription
ca.nameManagementCAThe name of the management CA created during the installation. This value and the following can be ignored if no Management CA is being created for this instance.
ca.dnCN=ManagementCA,O=EJBCA Sample,C=SEThe subject DN of the management CA.
ca.tokentypesoftThe key store for the Management CA's keys. soft results in a PKCS#12 key store stored in the database, while the value org.cesecore.keys.token.PKCS11CryptoToken should be used if the key store is stored in an HSM.

ca.tokenpassword

nullSet's the token password for the Management CA's key store. Should be null if no password is being used, such as for soft key stores or nChipher module protection.
ca.tokenproperties/home/ejbca/ejbca/conf/catoken.propertiesLink to a file which defines the HSM token being used by the Management CA. Can be ignored if using a soft key store.
ca.keyspec2048Key specification for the Management CA's keys. RSA keys are defined by their key length, while ECDSA keys by their curve name, or the value implicitlyCA. For more information, see ECDSA Keys and Signatures.

ca.keytype

RSAThe key type for the Management CA's keys. Available values are RSA, ECDSA or DSA.
ca.signaturealgorithmSHA256WithRSA

The signature algorithm for the Management CA. Available algorithms are: SHA1WithRSA, SHA1withECDSA, SHA256WithRSA, SHA256withECDSA.

ca.validity

3650Validity for the Management CA.

ca.policy

null

The policy id of the Management CA. Policy id determines which PKI policy the CA uses. Use 2.5.29.32.0 for 'any policy' (rfc5280) or null for no policy at all.

ca.certificateprofile

ROOTCACertificate profile used by the Management CA. Requires the profile to be imported prior to installation.

cesecore.properties

The following lists properties required to be configured prior to installation. Note that the configuration file may include other properties than the ones listed below.

PropertyDefault ValueDescription

allow.external-dynamic.configuration

falseAllows EJBCA to read cesecore.properties from an external directory. For more information, see Handling Configurations in a Separate Directory.

ca.rngalgorithm

SHA1PRNGThe algorithm used by EJBCA's RNG. SHA1PRNG should not be confused with the deprecated signature algorithm SHA1, and is FIPS compliant.

ca.serialnumberoctetsize

20The default size of certificate serial numbers, as defined in numbers of octets. Octet sizes will be configurable per CA, but this value will be set for the Management CA. The sign bit of a serial number is included, and as the field size is of constant length (no matter the length of the serial number), entropy will be slightly larger than 20*8 -2. Acceptable values (as defined by RFC5280) are between 4 and 20.

securityeventsaudit.implementation.X

0=org.cesecore.audit.impl.log4j.Log4jDevice
1=org.cesecore.audit.impl.integrityprotected.IntegrityProtectedDevice

Used to define audit log devices. The X allows multiple devices to be used. All EJBCA distributions use the Log4jDevice (which outputs to the server log) and the IntegrityProtectedDevice, which outputs audit logs to the database, but the implementation is constructed to allow for custom audit log devices. To explicitly ignore one of these devices, either value may be set to null. Audit logging will occur during the EJBCA installation to log the values set for the Management CA.

ejbca.properties

The following lists properties required to be configured prior to installation. Note that the configuration file may include other properties than the ones listed below.

PropertyDefault ValueDescription

appserver.home

$APPSRV_HOME

The home directory of the application server. By default, an environment variable set to $APPSRV_HOME will be used.

appserver.type

<auto-detect>

The type of application server being used, but normally this will be auto-detected by the installation scripts. If needed to be set explicitly, possible values are jboss, glassfish.

ejbca.productionmode

trueWhether EJBCA should be deployed in production mode, which means omitting some classes which are used only for testing and may be a security risk if deployed in a production environment.

allow.external-dynamic.configuration

falseAllows EJBCA to read ejbca.properties from an external directory. For more information, see Handling Configurations in a Separate Directory.

web.properties

The following lists properties required to be configured prior to installation. Note that the configuration file may include other properties than the ones listed below.

PropertyDefault ValueDescription

web.nosslconfigure

falseSet to true if it's desired to not have the key store deployment command configure the application server's SSL settings. May be used to harden exposed installations such as VAs that may not use TLS.

java.trustpassword

changeitThe password for the Java trust key store (truststore.jks). In order to ward off possible issues with Ant, avoid characters (such as $) that need to be escaped.

superadmin.cn

SuperAdminThe Common Name (CN) for the initial super admin user.

superadmin.dn

CN=${superadmin.cn},O=EJBCA Sample,C=SE

The complete Subject DN for the initial super admin user. Note that it must start with the CN described above.

superadmin.password

ejbcaThe password for the initial super admin's key store (superadmin.p12).

superadmin.batch

falseSet to true if you don't want the super admin key store to be generated during installation, in order to generate it manually.

httpsserver.password

serverpwdThe password for the application server's key store (keystore.jks).

httpsserver.hostname

localhostThe hostname of this instance.

httpsserver.dn

CN=${httpsserver.hostname},O=EJBCA Sample,C=SE

The Subject DN of the TLS certificate used by EJBCA's UI.

httpsserver.an

dnsName=${httpsserver.hostname}The Subject Alternative Name (SAN) of the TLS certificate used by EJBCA's UI. Up to two dnsName fields can be added.

httpserver.pubhttp

8080The public http port to configure the application server for.

httpserver.pubhttps

8442The public https port to configure the application server for.

httpserver.privhttps

8443The private https port to configure the application server for.

httpserver.external.privhttps

The same as httpserver.privhttpsThe private port to expose externally, i.e if an Apache proxy is configured in front of JBoss 443 may be used instead.

httpserver.external.fqdn


The fully qualified domain name (FQDN) of the front-end, e.g. an Apache proxy. In order to build an absolute URL, the server name is retrieved from the web client request. Leave blank if running without Apache proxy, or with Apache proxy via AJP (not with ProxyPass), while ${httpsserver.hostname} should be configured when an Apache proxy is used on the same server as EJBCA. Lastly, set any FQDN when an Apache proxy with a ProxyPass directive is used (on any server).

httpsserver.bindaddress.pubhttp
httpsserver.bindaddress.pubhttps
httpsserver.bindaddress.privhttps

0.0.0.0Set to only allow connections from the defined IP.

web.reqcertindb

trueSet to false in order to all the use of authentication certificates issued by a known CA but not in the database. Typically used if using an external CA to issue administrative certificates, for managing sub CAs or for setup EJBCA as an RA.

cryptotoken.p11.lib.N.name
cryptotoken.p11.lib.N.file


The name(s) and location(s) of all used PKCS#11 library files.

cryptotoken.p11.attr.N.name
cryptotoken.p11.attr.N.file


The PKCS#11 attribute files to be used, in case the ones bundled with EJBCA are not sufficient.

database.properties

The configuration file database.properties specifies the properties required for setting up the database connection with the application server.

The following lists properties required to be configured prior to installation. Note that the configuration file may include other properties than the ones listed below.

PropertyDefault ValueDescription

datasource.jndi-name

EjbcaDSThe name of the datasource of the EJBCA database.

database.name

h2The name of the database being used. Available values are mysql, postgres, mssql, oracle, sybase, onformix, derby, db2, ingres, and h2. For MariaDB, mysql can be used.

database.url

jdbc:h2:~/ejbcadb;DB_CLOSE_DELAY=-1

The URL to the database.

database.driver

h2The name of the database driver.

database.username

saThe username set for the EJBCA database.

database.useSeparateCertificateTable

falseSet to true in order to store the certificate bodies in the Base64CertificateData table instead of along with the other information in the CertificateData table. May increase performance in deployments of 100 million certificates or greater.

databaseprotection.properties

ENTERPRISE  This is an EJBCA Enterprise feature.

The configuration file databaseprotection.properties specifies the configuration used to sign the rows of various tables in order to give evidence of tampering, most commonly the AuditRecordData table.

The following lists properties required to be configured prior to installation. Note that the configuration file may include other properties than the ones listed below.

PropertyDefault ValueDescription

databaseprotection.enablesign

falseSets signing of all tables globally. To enable signing for a specific table, append the table name of the entity object (see the table definitions for a mapping) to the property, i.e

databaseprotection.enablesign.AuditRecordData=true. By setting the value globally to true and an individual table to false, that table may be excluded.

databaseprotection.enableverify

falseEnforces verification of rows when read. Similar to databaseprotection.enablesign, this value can either be set globally or for individual tables.

Next Step: Creating the Database

For more information on setting up your database and creating database indexes, see Creating the Database.

Related Content