EJBCA 6.14 to EJBCA 6.15.0

EJBCA 6.13 to EJBCA 6.14.0

/**
 *
 * @param requestId the ID of an approval request
 * @return the number of remaining approvals required, or STATUS_REJECTED (-1) if request was rejected
 * @throws ApprovalException if a request of the given ID didn't exist
 * @throws AuthorizationDeniedException if the current requester wasn't authorized. 
 * @throws ApprovalRequestExpiredException if sought approval request has expired
 * 
 */

/**
 * 
 * @param requestId the ID of an approval request
 *
 @return the remaining number of approvals for this request (with 0 
meaning that the request has passed) or -1 if the request has been 
denied
 * @throws ApprovalException if a request of the given ID didn't exist
 * @throws AuthorizationDeniedException if the current requester wasn't authorized.
 * @throws ApprovalRequestExpiredException if approval request was expired before having a definite status
 * 
 */

EJBCA 6.12 to EJBCA 6.13.0

EJBCA 6.11 to EJBCA 6.12.0

EJBCA 6.10 to EJBCA 6.11.0

EJBCA 6.11 introduces the EST protocol to EJBCA. Note that as a security measure the EST responder is by default turned off (as will all new protocols from now on) and needs to be activated under System Configuration.

EJBCA 6.11 upgrades the Peers Protocol with information about protocol (CMP, ETC, etc) rights. Due to a minor bug in the protocol versioning system it's highly recommended to upgrade RAs/VAs before the CAs, though the consequences for performing the upgrade in the incorrect order is merely that any CMP or WS proxying will cease to work during the upgrade.

We've made running external scripts from within EJBCA (the new External Command Certificate Validator, and the old General Purpose Custom Publisher) configurable under System Configuration. This setting will be turned off by default, mostly to avoid confusion in environments where they can't be applied. If you're currently running a General Purpose Custom Publisher, this setting will be set to active during upgrade.

SHA1WithRSA and SHA1WithECDSA are no longer acceptable signature algorithms for an OCSP responder. If you are running a legacy responder that still need to use these deprecated algorithms, you have to configure these in the setting 'ocsp.signaturealgorithm' in conf/ocsp.properties.

Incorrectly padded base64 encoded strings are no longer accepted by Bouncy Castle's base64 decoder used in EJBCA.

EJBCA 6.9.x to EJBCA 6.10.0

There are no upgrade operations required when upgrading from 6.9.x to 6.10.

EJBCA 6.8.x to EJBCA 6.9.0

When upgrading to EJBCA 6.9.0, all changes are automatically performed and no post-upgrade step is required.

On the database, the only change is the creation of the table BlacklistData. This table is empty by default, but can be filled with data to validate requests against a blacklist using the new Validators feature. If this table is expected to contain much data, there is a recommended index to apply in the create-index-ejbca.sql file.

EJBCA 6.7.x to EJBCA 6.8.0

When upgrading to EJBCA 6.8.0, the initial upgrade will occur automatically when 6.8.0 is deployed. All in all the following changes will have takenplace, or will take place in the post-upgrade step. Note that complete descriptions of these steps follow:

1. Post-upgrade can now be performed in the Admin GUI
2. The role, role member and access rule implementations have changed
3. Approval Profiles can now be set per action in CA and Certificate Profile

Besides this, branches and custom implementations based on EJBCA code need to take the following changes into account:

4. AuthenticationTokens are now loaded dynamically and custom implementations will need modification.

Lastly, the following behavioral changes should be taken into account:

5. The ability to search for information in the 'Details' column of the audit log has been removed
6. WebService API has changed for approvals
7. The CLI command 'role addadmin' has been renamed 'role addrolemember'
8. In the CMP protocol, more stringent chain validation of certificate in the extraCerts fields (used in 3GPP Vendor mode and RA mode) has been introduced.

EJBCA 6.6.1 to EJBCA 6.7.0

EJBCA 6.7.0 removes the value ocsp.responderidtype as read from ocsp.properties. The responder ID type (default keyhash) has, since the introduction of Internal Key Bindings back in EJBCA 6.0.0, been set for each OCSP keybinding individually, and thus the value from ocsp.properties has only been used for CAs acting as their own responders. From EJBCA 6.7.0 this value will be set from the OCSP Keybindings tab instead of in ocsp.properties.

EJBCA 6.5.x to EJBCA 6.6.0

Upgrading to 6.6.0 will require replacing the approval settings in CAs and certificate profiles with approval profiles. If approvals are used in any capacity, you need to run the following command after deploying the new version of EJBCA:

and restart JBoss. If approvals are currently not in use, this step is not needed.

Upgrading to 6.6.0 involves the following changes:

1. Changes to CertificateData

2. Changes to ApprovalData

   1. Public Web Self Registration
      

3. Changes to WebService Approvals

4. Removal of the access rule /ca_functionality/store_certificate

5. 100% Upgrade Uptime Notes

   1. Approval Profiles

EJBCA 6.4.2 to EJBCA 6.5.0

Upgrading to 6.5.0 involves the following changes:

1. Key algorithm constraints in certificate profiles

2. Configuration changes in CMP Proxy

3. Database maximum query count

4. CMP error message

5. healthcheck.publisherconnections property

These changes are documented at length below:

1. Key algorithm constraints in certificate profiles

EJBCA 6.5.0 allows configuration of key algorithm constraints in certificate profiles and by default any type compatible with the current allowed

key lengths will be preselected during the upgrade. If you allow 1024 bits, both RSA and DSA will be allowed and since it is now possible to

request tokens using any allowed key algorithm from the public web, requesting a DSA 1024 keystore will be allowed compared to earlier when only RSA

was available over this interface.

2. Configuration changes in CMP Proxy

For those running the CMP Proxy, the following values have changed names in cmpProxy.properties:

From: To:

cmp.backend.extra.caservicecertpath cmp.backend.caservicecertpath

cmp.backend.extra.issuerchainpath cmp.backend.issuerchainpath

cmp.backend.extra.keystorepath cmp.backend.keystorepath

cmp.backend.extra.keystorepwd cmp.backend.keystorepwd

The old values will continue to function for the time being, but will get dropped at a future date.

3. Database maximum query count

The maximum query count (maximum number of object retrieval from the database in a single request), previously several predefine constants, can now

be set from the web UI (in the Systems Configuration screen).

4. CMP error message

A couple of error messages for CMP have been changed.

- When submitting a request with a URL that does not match an existing CMP alias, a HTTP 404 (not found) is returned instead of a CMP badRequest error message.

- When trying to revoke a certificate that has already been revoked, a CMP certRevoked error message is returned instead of a CMP badRequest error message.

5. healthcheck.publisherconnections property

The property healthcheck.publisherconnections was documented as defaulting to false, but actually defaulted to true. This has now been corrected to default to false.

EJBCA 6.3.2 up to EJBCA 6.4.0

Upgrading to 6.4.0 will require some minor additions of access rules, which will be performed in post-upgrade. All additions create more granularity, so while role will be given access to anything they didn't have before the upgrade, rules can be restricted manually after the upgrade to make access control more restrictive.

Upgrading to 6.4.0 involves the following changes:

1. New Access rules for Auditors

2. XKMS no longer supported

3. Extended Key Usages and Custom Certificate Extension are imported to the database from the previously static configuration files

4. New Access rules to update Extended Key Usages and Custom Certificate Extensions

5. Changes to Custom Certificate Extensions

1. New Access rules for Auditors:

A new default Role has been added named "Auditor", which is a role which has view access to all pages but not rights to make any changes or perform any actions. Some new rules had to be added to accommodate this role, and authorization to certain GUI pages has been made more fine grained as a result. During upgrade, all roles which previously had access rights using the previous rules will automatically be given access to the new rule. These are as follows:

Any roles which had access to: Now also have access to:

/ca_functionality/basic_functions/activate_ca or /ca_functionality/view_ca

/ca_functionality/ (recursive)

/ca_functionality/edit_certificate_profiles /ca_functionality/view_certificate_profiles

/ca_functionality/edit_publisher /ca_functionality/view_publisher

/ra_functionality/edit_end_entity_profiles /ra_functionality/view_end_entity_profiles

/ /services/edit and /services/view

/internalkeybinding /internalkeybinding/view (recursive)

The pages that will be available to this new role are the following:

Page Name: Notes:

CA Activation

CA Structure & CRLs

Certificate Profiles Certificate Profiles previously not accessible (due to lack of access to CAs or

root access) will be rendered view only.

Certification Authorities All CA's will now be listed (instead of only the ones which the admin had access to, but

ones without access will be greyed out.

End Entity Profiles

Publishers

Crypto Tokens

Services

Internal Key Bindings

2. XKMS no longer supported

Support for XKMS was removed and is no longer available. When upgrading to EJBCA 6.4.0, internal keystores for XKMS will be removed and is upgrading in a 100% uptime cluster, the XKMS option in older versions of EJBCA will also disappear.

3. Extended Key Usages and Custom Certificate Extension are imported to the database from the previously static configuration files:

The configuration files 'extendedkeyusage.properties' and 'certextensions.properties' are automatically read into EJBCA database during deployment of the new code. Future changes to Extended Key Usages and Custom Certificate Extensions will have to be done through the AdminGUI under 'System Configuration'->'Extended Key Usages' and 'System Configuration'->'Custom Certificate Extensions'

In the case of Custom Certificate Extension, only the extensions with 'id<ID>.used=true' are imported into the database. Please note that extensions related to OCSP responses are not effected. Only the handling the content of 'extendedkeyusage.properties' and 'certextensions.properties' files is effected.

4. New Access rules to update Extended Key Usages and Custom Certificate Extensions:

New Access Rules has been added to add, remove or edit Extended Key Usages and Custom Certificate Extensions. During upgrade, all roles which previously had the access right '/system_functionality/edit_systemconfiguration', will automatically be given access to the new rules '/system_functionality/edit_available_extended_key_usages' and '/system_functionality/edit_available_custom_certificate_extensions'

5. Changes to Custom Certificate Extensions.

Several changes have been implemented in how Custom Certificate Extensions are handled:

5.a Available Custom Certificate Extensions are no longer limited to only 255 extensions:

The limitation on how many Custom Certificate Extensions EJBCA can have available at one time has now been removed.

5.b Used Custom Certificate Extensions in a Certificate Profile are now identified by their OIDs:

The Used Custom Certificate Extensions in a Certificate Profile used to be a list of numbers representing the extensions' IDs. This has now been changed to a list of Strings representing the extensions' OIDs instead. This is done by adding a new field containing the OIDs of the Used Custom Certificate Extensions. The field containing the list of IDs is not changed, but all functions are now referencing the new field containing the list of OIDs. This way, an older version of EJBCA can still work on a newer database content without disrupting any functions.

5.c Custom Certificate Extensions must implement the CustomCertificatExtension marker interface.

EJBCA 6.2.7 up to EJBCA 6.3.0

EJBCA 6.3.0 introduces one new table, PeerData. This table is automatically created at deployment to the appserver. If you prefer to do the database upgrade manually, see src/upgrade for SQL scripts for your specific database.

Certain features have been shifted from the Community to Enterprise version of EJBCA, among these are SCEP RA Mode, CMP Proxy and EV Certificate specific DN fields. If you are running Community and require these features, please contact a sales representative at Primekey Solutions.

EJBCA 5.0.x to EJBCA 6.0.x

See release notes for more details on changes.

Index:

1. Basic Upgrade Procedure for EJBCA

2. Basic Upgrade Procedure for Validation Authorities

a. Notable Changes

b. Upgrade Process

c. Post Upgrade

3. 100% Uptime Upgrade Notes

a. Upgrading CryotoTokens

b. Upgrading the OCSP CA Extended Service

4. CMP Configuration Handling

5. CLI Commands Renamed

6. Miscellaneous Issues

1. Basic Upgrade Procedure for EJBCA:

The 'ant bootstrap' target has been deprecated, and now it's covered by the 'ant

deploy' target. Behavior for the 'ant deploy' has been changed, and the old

command is equivalent to the following sequence:

- ant deploy

- ant deploy-keystore

- ant web-configure

(there is also an ant deployear target that only deploys an updated ejbca.ear file, excellent for upgrading or changing configuration)

For more information about new deployment instructions and ant targets, please

refer to EJBCA installation guide.

Backup your database first! If the upgrade fails, you can always go back to the earlier version.

If you are upgrading a cluster, update the software on all the nodes.

1. Copy conf/*.properties from the earlier installation into the conf directory of the new release.

Or better yet, use the ejbca-custom feature for easier upgrades, see User Guide.

NOTE: if you are using the default Hypersonic database in JBoss 5, you now need to configure this in database.properties (default test database is now for JBoss 7/EAP6).

2. Copy the directory 'p12' from the earlier installation.

3. If using JBoss 5.1 or older, then shut down JBoss.

4. Run the 'ant deploy' target with new version.

5. Run the 'ant deploy-keystore' target with new version (not needed if deploying to same JBoss instance as the old version).

6. Run the 'ant web-configure' target with new version (not needed if deploying to same JBoss instance as the old version).

7. Clear the tmp and work directories in the servers, then restart JBoss.

8. If you are running in a cluster, you should now upgrade on all cluster nodes.

The newly deployed nodes should be running now.

9. Restart JBoss to flush all caches.

10. Go into the Admin GUI and verify your settings.

If you get a "java.lang.NoSuchMethodError" in the admin GUI it is because JBoss 5 does not clean temporary files very well.

Delete the directories JBOSS_HOME/server/default/tmp and JBOSS_HOME/server/default/work and restart JBoss to get it working.

If you are upgrading from EJBCA 4.x, you also need to run additional upgrade targets, see upgrade notes from EJBCA 4 to EJBCA 5.

2. Basic Upgrade Procedure for Validation Authorities:

***********************************************************

2.a. Notable Changes:

*****************************

The external Validation Authority build has been removed and external VA deployments are now full EJBCA deployments.

- Database privileges on the VA host must be the same as used by the CA (all tables must exist).

- Key-stores, certificates and trust-stores (both soft and HSM based) will be automatically converted on first startup.

(or as soon as the password has been made available using clientToolBox if ocsp.activation.doNotStorePasswordsInMemory=true)

to CryptoTokens and OcspKeyBindings.

- Trusted certificates (ocsp.signtrustdir) must be imported in EJBCA as "External CAs", for example using the "bin/ejbca.sh ca importcacert"

command.

- Health-check URL is now the same as for CA installations, and it will check the usability of ACTIVE OcspKeyBindings.

- OcspKeyBindings and CryptoTokens can still be managed without the AdminGUI using the EJB CLI (bin/ejbca.sh).

- OCSP signing or re-keying certificates no longer need to be present in the HSM slot (migrated to the CertificateData table).

- Using a manually activated CryptoToken replaces the use of ocsp.activation.doNotStorePasswordsInMemory.

- Behavior of OCSP responses (like untilNextUpdate etc) can now be configured per OcspKeyBinding.

(Certificate Profile or URL specific settings in ocsp.properties has highest priority, then the OcspKeyBinding properties

and finally the default configuration in ocsp.properties).

- The re-keying key-store will be migrated to an AuthenticationKeyBinding.

- Management of *KeyBindings and CryptoTokens will be audit logged. Configure it before the upgrade to have proper traceability

from this point on.

- The 'ejbca.productionmode' property should be set to 'true' or 'false'. 'va' or 'ocsp' options are no longer supported.

- Some configuration options in ocsp.properties have moved to (or been deprecated by) web.properties. You should migrate these configuration

changes. You will be warned during build if you are using these options and have not migrated them.

- Usage of Crypto Tokens, where you can configure multiple tokens to be used. The responder is not longer limited to one PKCS#11 configuration in

ocsp.properties.

- Usage of Internal Key Binding, where you can configure specific key pairs matching specific certificates in the database. This enables flexible

and simple configuration of OCSP responder keys and certificates. It is no longer necessary to import the OCSP signer certificate into a slot on

the HSM.

- Usage of the Admin GUI. You can now use the EJBCA Admin GUI to manage Crypto Tokens and Key Bindings, making configuration and administration of

the OCSP responder so much easier.

- The OCSP healthcheck has been integrated into the standard EJBCA healtcheck, so no separate call is required.

All this means that the upgrade from an earlier version of EJBCA OCSP is a process. Naturally EJBCA 6 handles all the upgrade for you and will try to

automatically import your old configuration seamlessly. To benefit from all the new features you should read the VA Installation, OCSP Installation

and User Guide in the documentation.

2.b. Upgrade Process:

*****************************

1. Copy configuration files, database.properties, ocsp.properties and web.properties from your old installation.

2. Note that there can be some deprecated properties (j2ee.web-noconfigure). You will be notified of this during build.

3. Configure logging in conf/cesecore.properties if you do not want to audit log security events in the database (see OCSP Installation).

4. Build and configure the EJBCA VA as described in "Standalone VA Installation".

5. When JBoss is started the first time new database tables will be created. These are the same tables as exist in an EJBCA installation. If

your database user has restricted access, you can create the tables manually from the database scripts in doc/sql-scripts.

6. The next step involves creating OCSP Key Bindings, which are objects that represent an external OCSP responder.

a. If passwords are allowed to be store in memory (ocsp.activation.doNotStorePasswordsInMemory=true in ocsp.properties) then all key

bindings are created automatically. When JBoss is started the first time your ocsp.properties will be read and upgraded into crypto

tokens and ocsp key bindings. This will create objects in your database in the CryptoTokenData and InternalKeyBindingData. Also initial

access rules will be created, see "OCSP Installation" for more information about this.

b. If passwords are not stored in memory, the slot has to be opened up. To do this, make a call via the OCSPActivate command in

clientToolBox, and the internal key binding will be created automatically at the first call.

7. If you are requiring signed requests, verified by specific CAs, you need to import those CA certificates as "External CAs" in EJBCA, and

configure the trust anchors in the OCSP Key Binding (use bin/ejbca.sh ca importcacert or the Admin GUI).

2.c. Post Upgrade:

*****************************

Once all OCSP Responders have been recreated as OCSP Key Bindings and crypto tokens, the following properties can be removed from ocsp.properties

* ocsp.restrictsignatures

* ocsp.restrictsignaturesbymethod

* ocsp.signtrustdir

* ocsp.signtrustvalidtime

* ocsp.keys.dir

* ocsp.keys.storePassword

* ocsp.keys.keyPassword

* ocsp.activation.doNotStorePasswordsInMemory

* ocsp.p11.sharedLibrary

* ocsp.p11.sunConfigurationFile

* ocsp.p11.p11password

* ocsp.p11.slot

3. 100% Uptime Upgrade Notes:

***********************************************************

3.a. Upgrading CryotoTokens:

*****************************

The CryptoToken concept has extended the internal CA Token concept. CA's now reference a named set of keys in a CryptoToken and CA Service and

CryptoToken activation are clearly separated. Upgrades are made during first startup. Older EJBCA nodes will continue to function during a 100%

up-time upgrade, as long as newer instances has been deployed with "db.keepinternalcakeystores" set to true. For 100% up-time upgrade, or possibility

to back out of upgrade, set db.keepinternalcakeystores to true (default is false).

Settings relevant for 100% up-time upgrades are:

- db.keepinternalcakeystores (5.0->5.2)

- db.keepjbossserialization (4.0->5.0)

- app.version.effective (3.11->4.0)

3.b. Upgrading the OCSP CA Extended Service:

*****************************

The service for running OCSP services on internal CAs has now become an integral part of the OCSP responder. For this reason, the old

CA Extended Service will be removed at first upstart when a system has been upgraded from 5.0 to 6.0. The result of this is that for nodes sharing

a database, those nodes that haven't been upgraded to 6.0 will lose OCSP services until they've been upgraded as well. In order to keep internal

OCSP services running (external OCSP services are not affected) on the entire cluster during the whole upgrade process, set "ca.keepocspextendedservice"

to 'true' for all nodes except the last one, which then finally remove the service from the database.

- ca.keepocspextendedservice (5.0 -> 6.0)

4. CMP Configuration Handling:

***********************************************************

In EJBCA 6.0.0, the CMP configuration handling has been rewritten. CMP configurations are no longer read from conf/cmp.properties file, instead, CMP

configurations can be set either in the admin GUI or in the command line (execute './bin/ejbca.sh config cmp' from EJBCA home directory for command

line documentation). If you do use CMP, you can upload your old cmp.properties file by executing the following command in EJBCA home directory:

$ ./bin/ejbca.sh config cmp uploadfile --file conf/cmp.properties --alias cmp

In the adminGUI -> CMP Configuration, you will see the alias 'cmp' among the list of CMP alias. This alias will contain all your old CMP

configurations (except for one, see next note) and should be used to manage your CMP configurations in the future.

For CMP users who use NestedMessageContent in RA mode and use EndEntityCertificate as an authentication module: if you now skip performing some

verifications on the certificate in extraCert field by setting the authentication parameter of EndEntityCertificate to '-', this will no longer be

possible in EJBCA 6.0.0. Instead, a new configuration variable should be set to reflect this option. After uploading the conf/cmp.properties file

according to the instructions above, go to the admin GUI -> CMP Configurations; in the page for editing the CMP alias 'cmp', check the box that says

'Omit Verifications in EndEntityCertificate Authentication Module'

For CMP users who use KeyUpdateRequest in RA mode, in EJBCA 6.0.0, the authentication module EndEntityCertificate would have to be set among the

configured authentication modules, otherwise, the request will fail.

In EJBCA 6.0.0, TCP configurations have been moved from conf/cmp.properties file (which has been removed) to conf/cmptcp.properties. So if you are

using TCP (a deprecated protocol in EJBCA and the RFC), you should set your TCP configuration values in the new file. You should also upload

conf/cmp.properties file according to the instructions above, and rename the alias 'cmp' to 'tcp'. See Admin Guide -> CMP -> 'CMP over TCP' and

execute './bin/ejbca.sh config cmp' for details.

5. CLI Commands Renamed:

***********************************************************

CLI commands have been updated to reflect the new nomenclature introduced in EJBCA 5.0. This mainly involves the change of the command

'admins' -> 'roles' (to reflect that Admin Groups have been renamed Roles) and to the subcommmands under 'ra' which have been renamed to reflect the

name change from 'User' to 'End Entity' (e.g. adduser -> addendentity). The old commands have been deprecated but are still functional, and may be

removed entirely in a future version.

6. Miscellaneous Issues:

***********************************************************

- batchtool.properties is no longer searched for in bin/ but in conf/ instead. Note that everything in this file is commented out by default, so

it can be removed if it hasn't been modified.

- In EJBCA 6.0.0 new versions of BouncyCastle jars are included. If you have been copying ejbca/lib/bc*.jar files to JBoss

(jboss/server/default/lib), you must remove the old jars from JBoss and copy new jars from EJBCA.

- In EJBCA 6.0.0 the API for custom certificate extensions was changed. If you have created your own custom certificate extension java classes,

you need to update the API with one new argument (can be null). There is no effect if you used standard custom extensions in the

certextensions.properties, only custom java classes.

- In EJBCA 6.0.5 the Public Web interface logo filename was changed. If you have customized your own logo, you need to rename the logo filename

from 'logotype.png' or 'ejbca_pki_by_primekey_logo.png' to 'banner_ejbca-public.png'.

- Starting with EJBCA 6.0.0 custom services and publishers are automatically detected using meta-data in the Jar files, and class names can no

longer be specified manually. If you need to use old custom classes from before 6.0 (i.e. not autodetected classes) you can enable manual entry

with the option web.manualclasspathsenabled=true in web.properties.

- The class CliAuthenticationToken and associated classes have been moved from the CLI module to reside next to the other

authentication classes under src. This means that approval requests using the CliAuthenticationToken created in 5.0.x will not

be forwards compatible.

- PKCS#11 libraries for presentation in the AdminGUI are autodetected. If you have a library that is not automatically detected by

EJBCA you can add it to the configuration. See web.properties.sample for PKCS#11 library auto-detection configuration.

- HSM configuration options have been updated to support different slot reference types (slot id, index or label).

See Admin Guide, databaseprotection.properties.sample, ocsp.properties.sample and catoken.properties.sample for information and examples how to

update you current PKCS#11 configuration in these files. Configuration in the Admin GUI should be automatically upgraded.

- If you are using the default Hypersonic database in JBoss 5 for testing, you now need to configure this in database.properties. The default test database

(when no database.properties is configured) is now H2 for JBoss 7/EAP6.

EJBCA 4.0.x to EJBCA 5.0.x

100% up-time upgrade notes:

For some serialized classes serialization is changed to a portable format. For 100% up-time upgrade, or possibility to back out of upgrade, set db.keepjbossserialization to true (default is false). After all nodes have been upgraded, db.keepjbossserialization can be set to false again.

Support for the old LogEntryData has been dropped in EJBCA 5.0 and is replaced by a new AuditRecordData. If you need to old audit records export the logs before upgrading. There is also a tool to export them after upgrade. The new audit log function have the capability for audit record protection, at the same time as being cluster friendly.

EJBCA 5.0 introduces a new access control mechanism that can provide more functionality and more well defined operations. Some of the older access rules, such as the super administrator, has changed and needs to be modified in the post-upgrade step. It is recommended that you verify that your access roles and rules after an upgrade.

Backup your database first! If the upgrade fails, you can always go back to the earlier version. If you are upgrading a cluster, update the software on all the nodes.

1. Copy conf/*.properties from the earlier installation into the conf directory of the new release.

Or better yet, use the ejbca-custom feature for easier upgrades, see User Guide.

2. Copy the directory 'p12' from the earlier installation.

3. Shut down JBoss and do 'ant bootstrap' with the new version.

4. Start up JBoss.

5. Issue the command 'ant upgrade' from EJBCA_HOME.

This will upgrade access rules to rules that are compatible with the new access control system.

6. If you are running in a cluster, you should now upgrade (ant bootstrap) on all cluster nodes.

The newly deployed nodes should be running now.

7. Do 'ant post-upgrade' on one of the nodes.

This will make the necessary database updates.

Note: On some application server you may have to upgrade the database manually, see below.

This will also upgrade CertificateProfile objects and possible CA objects in the database.

After this upgrade, it may not be possible to downgrade to EJBCA 4.0.x again.

8. Stop JBoss, clear the tmp and work directories in the servers, then start JBoss again to flush all caches.

9. Go into the Admin GUI and verify you settings.

The database schema upgrade is normally done automatically for you when you run 'ant post-upgrade'.

Some application servers will not let you deploy unless the database is in sync though (or your database user may not have privileges for schema updates), so you may have to run the SQL commands manually.

Check src/upgrade/400_500 to find the correct sql files(s) for your database.

A practical note is that when upgrading from EJBCA 4.0 you can not use the CLI in EJBCA 5.0 before you have finished migrating all your 4.0 nodes and run post-upgrade.

NOTE:

If you need to downgrade EJBCA to 4.0.x again after a completed 'ant post-upgrade', you must add back the

dropped database column (caId in AdminEntityData, value 0 is fine) in the database.

If should be possible to downgrade to 4.0.4 again after an 'ant post-upgrade' in EJBCA 5.0.

You should be able to upgrade from EJBCA 3.11.x directly to 5.0.x, by following the same instructions as above (this upgrade is not thoroughly tested though).

NOTE: Some configuration options in ejbca.properties has moved to cesecore.properties. You should migrate these configuration changes.

You will be warned during build if you are using these options and have not migrated them.

If you get a "java.lang.NoSuchMethodError" in the admin GUI it is because JBoss does not clean temporary files very good.

Delete the directories JBOSS_HOME/server/default/tmp and JBOSS_HOME/server/default/work and restart JBoss to get it working.

NOTE: You may see 'new' administrator roles after upgrade.

* DEFAULT - This role can be safely deleted. It was used internally by EJBCA.

* Public Web Users - This role can be safely deleted. It was used internally by EJBCA.

* Super Administrator Role - This role contains the ejbca cli user. If you remove rights for the ejbca user you will not be able to use the CLI.

Note for upgrade to 5.0.6:

In EJBCA 5.0.6 new versions of BouncyCastle jars are included. If you have been copying ejbca/lib/bc*.jar files to JBoss (jboss/server/default/lib), you must remove the old jars from JBoss and copy new jars from EJBCA.

EJBCA 3.11.x to EJBCA 4.0.x

If you installed fresh on or upgraded to EJBCA 3.11.0 or EJBCA 3.11.1 on MySQL, start by reading the next section before continuing.

Support for ProtectedLog that was deprecated in EJBCA 3.10.0 has been dropped. If you use this feature, export the logs before upgrading. When the data from these tables are securely stored elsewhere or if you never used this feature, these tables and indexes can be dropped.

Support for table protection (configured in proptecion.properties) that was deprecated in EJBCA 3.11 has now been dropped. If you don't have any data in these tables, the indexes and tables can be dropped.

EJBCA 4.0 requires an application server supporting JEE5. For JBoss this means at least JBoss 5.1.x.

For details on how the application server should be configured, see the installation document.

*Notes for on-line upgrades*

1. If you were running an earlier version of EJBCA on an older JBoss (4.2.3 was recommended for EJBCA 3.x), *and* you need to do an on-line upgrade (upgrade one cluster node while another is running) you should first upgrade your cluster to run on JBoss 5.1.x before upgrading any of the cluster nodes to EJBCA 4.

2. Configure "app.version.effective=3.11.x" in conf/ejbca.properties for all but the last node that you deploy with EJBCA 4.0.x. Comment out the property and redeploy the other nodes again. This will ensure that the JBoss serialization still works for the deployed EJBCA 3.11.x nodes during the migration.

The values of "customAvailableAccessRules" and "RNGAlgorithm" (Random Number Generator) are now configurable from conf/ejbca.properties instead of being read through the ENC.

The 'database.name' property in database.properties changed from mssql2000 to mssql for MS-SQL Server.

The 'database.url' property in database.properties no longer needs XML escaping for '&'-characters.

The 'ocsp-database.url' property in ocsp.properties no longer needs XML escaping for '&'-characters.

Backup your database first! If the upgrade fails, you can always go back to the earlier version.

If you are upgrading a cluster, update the software on all the nodes.

1. Copy conf/*.properties from the earlier installation into the conf directory of the new release.

Or better yet, use the ejbca-custom feature for easier upgrades, see User Guide.

2. Copy the directory 'p12' from the earlier installation.

3. Shut down JBoss and do 'ant bootstrap' with the new version.

4. Start up JBoss.

5. If you are upgrading on JBoss, do 'ant post-upgrade' on one of the nodes. This will convert all

JBoss serialized objects into regular Java serialized objects and allow you to switch

application server in the future.

6. Restart JBoss again to flush all caches.

7. Go into the Admin GUI and verify you settings.

New in EJBCA 4.0 is that we have a well defined database schema, that is functionally equal for all supported databases. You can verify that your database schema is correct by comparing it to the SQL table create script for your database ('doc/sql-scripts/create-tables-ejbca4-{database name}.sql').

Note: Some deprecated methods have been removed in 4.0. For example in the publisher API. If you used those methods to create custom publishers you need to update your code to match the new interfaces. To make it easy there is onlynew parameters that are not needed to use.

EJBCA 3.9.x to EJBCA 3.10.x

Backup your database first! If the upgrade fails, you can always go back to the earlier version.

If you are upgrading a cluster, you should run the upgrade process with only one node running,

and then simply update the software on the other nodes.

1. Copy conf/*.properties from the earlier installation into the conf directory of the new release.

Or better yet, use the ejbca-custom feature for easier upgrades, see User Guide.

2. Copy the directory 'p12' from the earlier installation.

3. Shut down JBoss and do 'ant bootstrap' with the new version.

4. Start up JBoss. You might see some errors during startup due to that the database is not upgraded yet.

5. Issue the command 'ant upgrade' from EJBCA_HOME. This will make the necessary database updates.

Note: On some application server you may have to upgrade the database manually, see below.

6. Restart JBoss again to flush all caches.

7. Go into the Admin GUI and verify you settings.

8. Do 'ant post-upgrade' if you want "Enforce unique public keys" to check against old certificate (see below).

In EJBCA 3.10 some unused code related to the "protection.keyref" property in conf/protection.properties has been dropped. This also means a small database change where the unused column TableProtectData.keyRef is dropped. To see which database structural changes are made you can find the SQL commands for your database in src/upgrade/39_310/39_310-upgrade-<<database name>>.sql.

Approvals that are pending during the upgrade process will be upgraded automatically. These are Java Objects and cannot be upgraded manually using custom SQL. If you need to perform a manual SQL update all pending approvals should be taken care of before the upgrade.

A quick fix for the LogEntryData table that was spread in the wild in 2005 will also be corrected in this release. The column "comment" (or "comment_" on Oracle) will change name to "logComment" for all databases. Since older versions of DB2 than 9.7 cannot rename columns, it requires a massive UPDATE operation on this database. DB2 9.7+ users can alter src/upgrade/39_310/39_310-upgrade-db2.sql to use "ALTER TABLE LogEntryData RENAME COLUMN comment TO logComment;" instead. For all other databases thisrenaming will be handled automatically by "ant upgrade". Please note that logging to the OldLogDevice will not work during this upgrade.

The database upgrade is normally done automatically for you when you run 'ant upgrade'.

Some application servers will not let you deploy unless the database is in sync though, so you may have to run the SQL commands manually.

The ProtectedLogDevice has been deprecated, since it's hard to configure right and extremely inefficient. There are currently plans to create a LogDevice aiming at non-repudiation rather than detection of missing log-entries.

The option to use a separate soft keystore for the internal OCSP responder is no longer available. The upgrade will remove the soft keystore and OCSP requests will be signed directly by the CA signing certificate (currently the default behavior). External OCSP installations are not affected.

To improve testing there is a new configuration option to allow changing used properties through Remote EJB access using conf/ejbca.properties#ejbca.productionmode. Default is to not allow configuration changes, but some of the development system tests will fail until this is allowed.

The External RA module is now a part of the main EJBCA bundle and uses JPA for persistence. DataSources used by the workers are configured in conf/externalra.properties. Properties for each worker are configured under Services in the Admin GUI. Also the external SCEP RA application is now built from the main bundle and is configured in conf/scep.properties. The documentation is available as a part of the generated doc. The API as such has not changed and old client should still work, but External RA workers in EJBCA have to be reconfigured.

Note that this version contains an inevitable API change for custom extensions because the CA key used to sign certificates does not have to be the same as the currently active CA key.If you have created any custom extensions Java classes, you must add:

"PublicKey caPublicKey"

to the parameter list in the getValue method. The value does not have to be handled.

Two more checks are now done before adding a certificate. See

https://ejbca.org/docs/userguide.html#Enforce%20unique%20public%20keys and

https://ejbca.org/docs/userguide.html#Enforce%20unique%20DN

These checks are enabled on all CA:s that existed before the upgrading. It should not be any problem to have them enabled (different users do not normally share same keys or subject DN) in most installations. But if you know that your users shares subject DNs or keys with each other they could be disabled.

A new column in the database (subjectKeyId) for "Enforce unique public keys" is added when 'ant upgrade' is executed. To check the public key in new certificates against certificates issued before the upgrade this column has to be set (after upgrade all rows of the column is null). The columns is set by 'ant post-upgrade' (see step 8 above). Please note that 'post-upgrade' might take some minutes if there are many certificates in the database. After the upgrade, two new indexes for the enforcing uniqueness should be applied:

create index certificatedata_idx9 on CertificateData(subjectKeyId,issuerDN);

create index certificatedata_idx10 on CertificateData(subjectDN,issuerDN);

To be able to use the OCSP monitoring tool the 'subjectKeyId' column should be added to the External OCSP responders, but it does not have to be populated. See src/upgrade/39_310/39_310-upgrade-<<database name>>.sql for the exact syntax to use for your OCSP database.

You should be able to upgrade from EJBCA 3.2.x directly to 3.10.x, by following the same instructions as above (this upgrade is not thoroughly tested though). Also see instructions below for additionalissues when upgrading all the way from a much older version.

If you are using some databases, specifically an older version of Derby, you may have to manually upgrade your database. See src/upgrade/39_310/39_310-upgrade-derby.sql.

EJBCA 3.8.x to EJBCA 3.9.x

Backup your database first! If the upgrade fails, you can always go back to the earlier version.

If you are upgrading a cluster, you should run the upgrade process with only one node running, and then simply update the software on the other nodes.

1. Copy conf/*.properties from the earlier installation into the conf directory of the new release.

Or better yet, use the ejbca-custom feature for easier upgrades, see User Guide.

2. Copy the directory 'p12' from the earlier installation.

3. Shut down JBoss and do 'ant bootstrap' with the new version.

4. Start up JBoss. You will see some errors during startup due to that the database is not upgraded yet.

5. Issue the command 'ant upgrade' from EJBCA_HOME. This will make the necessary database updates.

Note: On some application server you may have to upgrade the database manually, see below.

6. Restart JBoss again to flush all caches.

7. Go into the admin-GUI and verify the settings.

In EJBCA 3.9 there are new possibilities for filtering certificates on certificateProfileId and tags.

This requires a small database change. To see which database structural changes are made you can find

the SQL commands for your database in src/upgrade/38_39/38_39-upgrade-<<database name>>.sql.

The database upgrade is normally done automatically for you when you run 'ant upgrade'.

Some application servers will not let you deploy unless the database is in sync though, so you may have to run

the SQL commands manually. The assigned certificateProfileId for each new CertificateData is default 0.

If you want to assign the last used certificateProfileId used for the same user you can manually execute

UPDATE CertificateData SET certificateProfileId=(SELECT certificateProfileId FROM UserData

WHERE CertificateData.username=UserData.username);

UPDATE CertificateData SET certificateProfileId=0 where certificateProfileId is null;

but this will take a *very* long time for a large population.

EJBCA 3.9 also has a new table in the database. If you are using JBoss this is created automatically for you. If you are using another application server, created the table in your database using the create statement for the table PublisherQueueData from one of the create-tables scripts in doc/howto.

You should be able to upgrade from EJBCA 3.2.x directly to 3.9.x, by following the same instructions as above (this upgrade is not thoroughly tested though). Also see instructions below for additional issues when upgrading all the way from a much older version.

Note! If you are using the external RA you need to upgrade to ExtRA 3.9 and follow upgrade instructions in the ExtRA package.

Note! If you have changed the 'tomcat' username for the JBoss SSL server certificate you should check the certificate profile used.

This is because the old ENDUSER certificate profile can no longer be used for SSL server certificates.

The corresponding upgrade sql in the normal upgrade script is:

update UserData set certificateProfileId=9 where username='tomcat' and certificateProfileId=1;

Note! If you are using an external OCSP responder using EJBCA's publishing from EJBCA to the responder, you need to update the responders database table CertificateData using the SQL commands above.

Note! If you are using JBoss 5.x. Don't forget to copy new BC jars from EJBCA_HOME/lib/bc*.jar to JBOSS_HOME/server/default/lib, replacing to old ones that you copied there from the old version of EJBCA.

EJBCA 3.7.x to EJBCA 3.8.x

Note that if using JBoss, you need JBoss 4.2.x or later to run EJBCA 3.8.x.

From EJBCA 3.8.0 you are able to mix administrators from different CAs in the same Administrator Group. This improvement requires a small database change.

The "Administrator" flag on end entities has been dropped, so if you match administrators on CN and uses this to distinguish between admins and nonadmins, you should switch to using certificate serial number or another unique identifier instead.

Backup your database first! If the upgrade fails, you can always go back to the earlier version.

If you are upgrading a cluster, you should run the upgrade process with only one node running, and then simply update the software on the other nodes.

1. Copy conf/*.properties from the earlier installation into the conf directory of the new release.

Or better yet, use the ejbca-custom feature for easier upgrades, see User Guide.

2. Merge changes from *.properties.sample into your *.properties files.

3. Copy the directory 'p12' from the earlier installation.

4. Shut down JBoss and do 'ant deploy' with the new version.

5. Start up JBoss. You could see some errors during startup due to that the database is not upgraded yet.

6. Issue the command 'ant upgrade' from EJBCA_HOME. This will make the necessary database updates.

Note: On some application server you may have to upgrade the database manually, see below.

7. Go into the admin-GUI and verify you settings.

8. Restart JBoss again to flush all caches.

Ant upgrade is needed to make the database changes in the authorization module.To see which database structural changes are made you can find the SQL commands for your database in src/upgrade/37_38/37_38-upgrade-<<database name>>.sql. Note that ant upgrade does more than these sql lines.

You should be able to upgrade from EJBCA 3.1.x directly to 3.8.x, by following the same instructions as above (this upgrade is not thoroughly tested though). Also see instructions below for additional issues when upgrading all the way from a much older version.

If an upgrade option for your database is not included, take a look in src/upgrade/37_38 where upgrade sql scripts are located. We will happily include upgrade scripts for other databases as well.

EJBCA 3.6.x to EJBCA 3.7.x

Upgrade from EJBCA 3.6.x to 3.7.x is a plug-in upgrade.

If you are upgrading a cluster, you should run the upgrade process with only one node running, and then simply update the software on the other nodes.

1. Copy conf/*.properties from the earlier installation into the conf directory of the new release.

Or better yet, use the ejbca-custom feature for easier upgrades, see User Guide.

2. Copy the directory 'p12' from the earlier installation.

3. Shut down JBoss and do 'ant bootstrap' with the new version.

4. Start up JBoss.

5. Go into the admin-GUI and verify you settings.

You should be able to upgrade from EJBCA 3.1.x directly to 3.7.x, by following the same instructions as above, but answering yes to the second question (this upgrade is not thoroughly tested though).

Also see instructions below for additional issues when upgrading all the way from a much older version.

If you are using PrimeCardHSM you need to upgrade to a new version, matching EJBCA 3.7.

EJBCA 3.5.x to EJBCA 3.6.x

Backup your database first! If the upgrade fails, you can always go back to the earlier version.

Upgrade from EJBCA 3.5.x to EJBCA 3.6.x requires one small database change.

If you are upgrading a cluster, you should run the upgrade process with only one node running, and then simply update the software on the other nodes.

1. Copy conf/*.properties from the earlier installation into the conf directory of the new release.

Or better yet, use the ejbca-custom feature for easier upgrades, see User Guide.

2. Merge changes from *.properties.sample into your *.properties files.

3. Copy the directory 'p12' from the earlier installation.

4. Shut down JBoss and do 'ant bootstrap' with the new version.

5. Start up JBoss. You could see some errors during startup due to that the database is not upgraded yet.

6. Issue the command 'ant upgrade' from EJBCA_HOME. This will make the necessary database updates.

If you are upgrading from EJBCA 3.4 or 3.5, answer 'no' to the second and third question.

Note: On some application server you may have to upgrade the database manually, see below.

7. Go into the admin-GUI and verify you settings.

8. Restart JBoss again to flush all caches.

If you don't want to do step 6 above (doing step 6 is the recommended way though) and instead want to do the upgrade

of the database manually, you can simply issue the following sql command:

MySQL:

alter table CRLData add deltaCRLIndicator int(11) NOT NULL DEFAULT -1;

PostgreSQL:

alter table CRLData add deltaCRLIndicator INT;

update CRLData set deltaCRLIndicator = -1;

alter table CRLData alter column deltaCRLIndicator set not null;

alter table CRLData alter column deltaCRLIndicator set default -1;

Oracle:

alter table CRLData add deltaCRLIndicator NUMBER(10) default -1;

If you are using another application server than JBoss, you need to create new tables in the database manually. Create the new tables ProtectedLogData, ProtectedLogExportData and ProtectedLogTokenData fromone of the database scripts in doc/howto/create-tables-xxx.sql.

You should be able to upgrade from EJBCA 3.1.x directly to 3.6.x, by following the same instructions as above, but answering yes to the second question (this upgrade is not thoroughly tested though).

Also see instructions below for additional issues when upgrading all the way from a much older version.

If an upgrade option for your database is not included, take a look in src/upgrade/35_36 where upgrade sql scripts are located. We will happily include upgrade scripts for other databases as well.

The JBoss Mbean create CRL service has been removed in EJBCA 3.6. It has been replaced with the much easier, more portable etc CRL Update Service configured in the Admin-GUI. See the User Guide about CRL creation for details.

If you are using PrimeCardHSM you need to upgrade to a new version, matching EJBCA 3.6.

Note. In EJBCA 3.6 we changed the case of some database column to get full Sybase compatibility. This will not affect other database (in that case you would have had problems already), but it can be good to know.

Column cases changed for most columns in ApprovalData, for cAId in LogEntryData, and for cAId in ProtectedLogData.

EJBCA 3.4.x to EJBCA 3.5.x

See release notes for details between certain versions.

EJBCA 3.5 is a plug-in upgrade from EJBCA 3.4.x. A few steps are still needed for upgrade though.

Simply copy conf/*.properties from the earlier installation.

Merge changes (if there are any) from *.properties.sample into your *.properties.

Copy the directory 'p12' from the earlier installation and do 'ant deploy' with the new version.

The new root-less install on linux systems makes it much easier to have control of you Java truststore (which CAs that are allowed for administrator certificates) both on linux and windows.

You must make these steps during upgrade on both linux and windows:

- copy $JAVA_HOME/jre/lib/security/cacerts $EJBCA_HOME/p12/truststore.jks

- ant clean; ant deploy

In EJBCA 3.5 when you run the command 'ant javatruststore' or 'ant -Dca.name=MyCAName javatruststore' it is now the file $EJBCA_HOME/p12/truststore.jks that will be updated and copied to $JBOSS_HOME/server/default/conf/keystore.

You should also read about the new external merge directory 'ejbca-custom', where you can collect all your own files. See 'Handling changes in a separate tree' in the User's guide.

There are some parameter name changes in ejbca.properties and web.properties. These parameters are only used when freshly installing EJBCA though. If you plan to do this using old configuration files, you should merge changes from ejbca.properties.sample and web.properties.sample.No worry if you forget though, since you will be prompted for the values instead.

You should be able to upgrade from EJBCA 3.1.x directly to 3.5.x, by following the same instructions for database upgrade as for EJBCA 3.4.

EJBCA 3.3.x to EJBCA 3.4.x

Backup your database first! If the upgrade fails, you can always go back to the earlier version.

Upgrade from EJBCA 3.3.x to EJBCA 3.4.x requires one small database change.

If you are upgrading a cluster, you should run the upgrade process with only one node running, and then simply update the software on the other nodes.

1. Copy ejbca.properties from the earlier installation into the conf directory of the new release.

Or better yet, split up your ejbca.properties file to match the new improved conf structure.

2. Merge changes from *.properties.sample into your *.properties files.

3. Copy the directory 'p12' from the earlier installation.

4. Shut down JBoss and do 'ant deploy' with the new version.

5. Start up JBoss. You will see some errors during startup due to that the database is not upgraded yet.

6. Issue the command 'ant upgrade' from EJBCA_HOME. This will make the necessary database updates.

If you are upgrading from EJBCA 3.2 or 3.3, answer 'no' to the second question.

Note: On weblogic you have to upgrade the database manually, see below.

7. Go into the admin-GUI and verify you settings, specially verify the DN encoding in 'Edit Certificate Authorities'

as noted below.

8. Restart JBoss again to flush all caches.

If you don't want to do step 6 above (doing step 6 is the recommended way though) and instead want to do the upgrade of the database manually, you can simply issue the following sql command:

MySQL:

alter table CAData add updateTime bigint NOT NULL DEFAULT 0;

PostgreSQL:

alter table CAData add updateTime INT8;

update cadata set updateTime = 0;

alter table cadata alter column updateTime set not null;

alter table cadata alter column updateTime set default 0;

Oracle:

alter table CAData add updateTime NUMBER(19) default 0;

Note: Since the default DN encoding changed to UTF8, there is an option in the CA configuration (Edit Certificate authorities) called 'Use PrintableString encoding in DN'. Checking this checkbox causes the old behaviour to be used, using PrintableString as the default encoding. The upgrade process tries to guess how this value should be set (upgrading an old CA we usually want to keep the old behaviour).After the upgrade process, check your CA configuration to verify that the option is set to your liking.

Note: If you intend to use the XKMS service or the CMS service (log signing), then you should go into the Admin-GUI after upgrading and press the button "Republish CA Certificates" for all CAs. Otherwise you will not be able to revoke the certificates issued to these services, or view the certificates in the GUI.

You should be able to upgrade from EJBCA 3.1.x directly to 3.4.x, by following the same instructions as above, but answering yes to the second question (this upgrade is not thoroughly tested though).

EJBCA 3.2.x to EJBCA 3.3.x

Upgrade from EJBCA 3.2.x to EJBCA 3.3.x is a plug-in upgrade, because there are no database changes, or the database changes are only new tables and not changed ones.

You should still follow this advice:

Backup your database first! If the upgrade fails, you can always go back to the earlier version.

Simply keep/copy ejbca.properties from the earlier installation.

Merge changes from ejbca.properties.sample into your ejbca.properties.

Copy the directory 'p12' from the earlier installation and 'ant deploy' (or deploywithjbossservice) this new one.

You should be able to upgrade from EJBCA 3.1.x directly to 3.3.x, by following the same instructions as when upgrading from 3.1.x to 3.2.x (untested though).

If you are using Eracom HSM, please notice that property names have changed for determining which key is used.

After upgrading EJBCA, you must go into CA configuration and update your HSM properties.

The property names are now the same for all different HSMs.

EJBCA 3.1.x to EJBCA 3.2

Support for this upgrade is no longer available from EJBCA 3.9.x. Please use the latest EJBCA release from the 3.8-branch as a first step if you need to upgrade from all the way from here.