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 properties specified in install.properties are only used during the installation step of EJBCA and won’t be compiled into the EJBCA EAR file.

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.

Property
Default Value
Description
ca.name ManagementCA The 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.dn CN=ManagementCA,O=EJBCA Sample,C=SE The subject DN of the management CA.
ca.tokentype soft The 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

 null Set’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 nCipher module protection.
ca.tokenproperties /home/ejbca/ejbca/conf/catoken.properties Link to a file which defines the HSM token being used by the Management CA. Can be ignored if using a soft key store.
ca.keyspec 2048 Key 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

 RSA The key type for the Management CA’s keys. Available values are RSA, ECDSA or DSA.
ca.signaturealgorithm SHA256WithRSA The signature algorithm for the Management CA. Available algorithms are: SHA1WithRSA, SHA1withECDSA, SHA256WithRSA, SHA256withECDSA.

ca.validity

 3650 Validity 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

 ROOTCA Certificate 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.

Property
Default Value
Description

allow.external-dynamic.configuration

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

ca.rngalgorithm

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

ca.serialnumberoctetsize

 20 The 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.

custom.class.whitelist

 A comma separated list of custom classes that need to pass EJBCA’s deserialization filter, for example custom extensions.

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.

Property
Default Value
Description

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

 true Whether 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

 false Allows 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.

Property
Default Value
Description

web.nosslconfigure

 false Set 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

 changeit The 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

 SuperAdmin The 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.validity 2y Allows specifying the superadmin certificate validity during installation. If not set (commented out), the default of 2 years superadmin certificate validity is used.
Use the ISO 8601 date format according to the following examples: [yyyy-MM-dd HH:mm:ssZZ]: ‘2019-12-10 11:56:19+01:00’
or
(*y *mo *d *h *m *s) – y=365 days, mo=30 days
Setting a superadmin.validity value creates an End Entity profile and a Certificate Profile specifically used for the purpose of changing the default superadmin user’s validity.

superadmin.password

 ejbca The password for the initial super admin’s key store (superadmin.p12).

superadmin.batch

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

httpsserver.password

 serverpwd The password for the application server’s key store (keystore.jks).

httpsserver.hostname

 localhost The 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

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

httpserver.pubhttps

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

httpserver.privhttps

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

httpserver.external.privhttps

 The same as httpserver.privhttps The 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.0 Set to only allow connections from the defined IP.

web.reqcertindb

 true Set 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.

Property
Default Value
Description

datasource.jndi-name

 EjbcaDS The name of the datasource of the EJBCA database.

database.name

 h2 The 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

 h2 The name of the database driver.

database.username

 sa The username set for the EJBCA database.

database.useSeparateCertificateTable

 false Set 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.

Property
Default Value
Description

databaseprotection.enablesign

 false Sets 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

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

For step-by-step instructions for how to configure database protection with HMAC, see How to Configure Database Protection using HMAC.