Skip to main content
Skip table of contents

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.

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 nCipher 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, if generated on a soft key store. RSA keys are defined by their key length, while ECDSA keys are defined by their curve name. For more information, see ECDSA Keys and Signatures. Can be ignored if using an HSM.

ca.keytype

RSAThe key type for the Management CA's keys, if generated on a soft key store. Available values are RSA, ECDSA or DSA. Can be ignored if using an HSM.
ca.signaturealgorithmSHA256WithRSA

The signature algorithm for the Management CA. Available algorithms are: SHA256WithRSA, SHA256withECDSA, SHA384WithRSA, SHA384WithECDSA, and more.

ca.validity

3650Validity for the Management CA.

ca.policy

null

The policy ID of the Management CA, to be put in the Management CA certificate. 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. Anything but the default 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.
password.encryption.key

This password (strictly speaking, PBE input password) is used for encrypting passwords that may optionally be stored in EJBCA, e.g. clear text end entity passwords for batch generation, crypto token passwords for auto-activation, CMP Alias, SCEP, MASE (etc) alias passwords stored in database. This property should be set before initial EJBCA installation and it should't be changed later, because there could exist passwords encrypted with the key about to be changed and EJBCA would be unable to decrypt them. This property should use any password you consider safe, but it is strongly recommended that you use a randomly generated alphanumeric (using full character set) password.

See also EJBCA Security.

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.

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 can make use of 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.
database.crlgenfetchorderedfalse

Whether EJBCA should request ordered fetching of revoked certificates when generating CRLs. EJBCA relies on Hibernate to return data in batches (see the database.crlgenfetchsize setting, to control the read batch size). However, Microsoft SQL Server 2016  and PostgreSQL are known to return duplicates and/or missing entries when multiple batches are read. This setting should be set to true for these databases.

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. Setting to false will for example enable the swagger REST API development UI.

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

java.trustpassword

changeitThe password for the Java trust key store (truststore.jks) for TLS connection, that is generated during install . 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.validity2y

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

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

superadmin.batch

trueSet to false if you don't want the super admin key store to be generated during installation, in order to generate it manually or use an externally generated administration certificate.

httpsserver.password

serverpwdThe password for the application server's key store (keystore.jks) for TLS connections, that is generated during install.

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 allow the use of authentication certificates that is issued by a known CA, but not present 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 for a specific PKCS#11 library, 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.useSeparateCertificateTable

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

database.url

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

The URL to the database. Used by external tools such as ejbca-db-cli, can be ignored for an EJBCA server installation.

database.driver

h2The name of the database driver. Used by external tools such as ejbca-db-cli, can be ignored for an EJBCA server installation.

database.username

saThe username set for the EJBCA database. Used by external tools such as ejbca-db-cli, can be ignored for an EJBCA server installation.

databaseprotection.properties

ENTERPRISE

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.

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.

Related Content

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.