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

Next Step: Creating the Database

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