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 are defined by their curve name. 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. | 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. |
| database.crlgenfetchordered | false | 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.
| 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. |
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 | 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 | The name(s) and location(s) of all used PKCS#11 library files. | |
cryptotoken.p11.attr.N.name | 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.