Backward Incompatible Peer Connector Protocol Change Affecting EST

A backward incompatible change was required in the peer connector protocol to enforce domain security for RAs. This change impacts EST proxying from RA to CA and was implemented by adding a new method call in the protocol and disabling the old one.

Failover for the CRL Updater Service

The CRL updater service will fail over to another node in the cluster if it is unable to complete its work. Before running, it will check if the CRL signing key is accessible by performing a test signature. If at least one CRL signing key for an active CA is inaccessible, the work is deferred to give another node in the cluster a chance to run the service. In previous versions of EJBCA, the service would fail and then run again on the same node.

An important side-effect to be aware of is that if a CRL signing key is inaccessible for one CA it will block issuance of CRLs for all CAs on that instance. If the CRL signing key is accessible on another node in the cluster, the work will be handed over automatically. If not, you need to deactivate the CA - whose CRL signing key is inaccessible, before the service can run again.

Post Upgrade

Being a minor release, no post upgrade is required.

OCSP Responses no longer include Unspecified Reason Code

As of EJBCA 7.4.2, OCSP responses where the certificate is revoked with the "Unspecified" reason code, will no longer include the reason code attribute.

This change is needed to comply with changes in CA/B Forum Baseline Requirements version 1.7.1, effective 2020-09-30.

Post Upgrade

Being a minor release, no post upgrade is required.

OCSP Signing Cache Update by Default Disabled

As of EJBCA 7.4.1, the OCSP signing cache update is not performed by default if the CA issuing the certificate is not known. This improves the performance (by reducing database hits) when EJBCA handles OCSP requests, especially in clustered environments.

To enable OCSP signing cache update, and restore the old behavior if needed, select the Enable OCSP signing cache update option (disabled by default) in the global OCSP configuration section (System functions > Internal Key Bindings > OcspKeyBinding). For more information, see OCSP Management.

Post Upgrade

Being a minor release, no post upgrade is required.

Required Procedures

In versions of EJBCA prior to 7.4.0, the Request Processors (as defined by the org.cesecore.certificates.ca.ExtendedUserDataHandler interface) were defined by setting them as the certreqhandler.class property for individual CMP aliases. In EJBCA 7.4.0, use of Request Processors has been extended to the REST and WS APIs as well, and thus their configuration moved to individual CAs instead. This change can't be made automatically, so to keep using Request Processors on existing installations, use the following procedure to maintain 100% uptime:

1. Upgrade EJBCA on all existing nodes in a cluster but do not yet run post-upgrade.

2. On each CA meant to use Request Processors, edit that CA and choose the used implementation.
   

3. After all CAs have been configured, run post-upgrade in order to remove the vestigial property from the CMP aliases.
   

Database Changes

Behavioral Changes

Post Upgrade

When upgrading to EJBCA 7.4.0, you must perform a post-upgrade after all nodes have been upgraded. The post-upgrade is required because of a change in how partitioned CRLs are represented in CRLData. The post-upgrade will also reindex CRLData if the database user has sufficient privileges.

To perform the post-upgrade, click the EJBCA System Upgrade menu option, and then click Start post-upgrade. For more information, see Upgrading EJBCA.

Database Changes

Behavioral Changes

EJBCA 7.3.0.X to EJBCA 7.3.1

EJBCA 7.3.1 to EJBCA 7.3.1.1

EJBCA 7.3.1.1 to EJBCA 7.3.1.2

EJBCA 7.3.1.3 to EJBCA 7.3.1.4

Behavioral Changes

EJBCA 7.2.0 to EJBCA 7.2.1

Database Changes

A new column, crlPartitionIndex, has been added to the CertificateData, NoConflictCertificateData and CRLData database tables. If your EJBCA database user does not have GRANT privileges, you will need to run the ALTER commands in the upgrade scripts. Please note that if you use the Validation Authority Publisher with CRL publishing, you must upgrade at least the CRLData tables on the VAs (or the whole database) before you upgrade the CAs.

After EJBCA 7.1.0 is deployed, it is safe to remove hardtokendata, hardtokenissuerdata, hardtokenprofiledata and hardtokenpropertydata database tables.

Upgrade scripts are available in the src/upgrade/700_710 folder.

Behavioral Changes

EJBCA 7.0.0 to EJBCA 7.0.1

Database Changes

The certificateRequest column has been added to the CertificateData, NoConflictCertificateData and Base64CertData tables. The new column is nullable and by default empty. There are upgrade scripts available in the src/upgrade/615_70 folder. Note that the field is unused at the moment but will be used in future releases for storing the CSR along with an issued certificate.

Behavioral Changes

Database Changes

With the introduction of ACME protocol support in EJBCA 6.15, we've had to introduce the following new tables to EJBCA:

• AcmeAccountData

• AcmeAuthorizationData

• AcmeChallengeData

• AcmeNonceData

• AcmeOrderData

As always, these can either be created automatically if database user rights are sufficient or created manually using the bundled creation scripts.

We've created indexes for:

• AcmeAccountData

• AcmeAuthorizationData

• AcmeChallengeData

• AcmeOrderData

The indexes are found in doc/sql-scripts/create-index-ejbca.sql and we recommend applying them on any production environment using ACME.

Behavioral Changes

Access Rules Changes

The access rule requirements for generating CSRs from the UI for internal keybindings have been changed from /cryptotoken/keys/ generate/ to /cryptotoken/ use/ in order allow for these roles to be separated.

Changes to EJBCAWS

/**
 *
 * @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
 * 
 */

Upgrading CAA Validators

A minor bug was found in 6.13 where the list of ignored Top Level Domains was reduced to a single entry if the validator has been edited or saved. EJBCA will automatically upgrade the validators when they are edited in 6.14, but for this reason it's required that CAA Validators are not edited during the upgrade. Besides that, CAA Validators will otherwise function entirely as normal.

Creation of the NoConflictCertificateData Table

Upgrading to EJBCA 6.13.0 requires the creation of the table NoConflictCertificateData. The table will either be created automatically by the application server if the database user has creation rights, or can be created manually using the standard database creation scripts in EJBCA. This table is only used by installations using the Oracle database using asynchronous setups, and will only be used if any certificates are configured for Throw Away mode.

RA Role Management

EJBCA 6.12 changes how role namespaces works for administrators with access to the "/"-access rule. In previous version Prior to 6.12, access to the "/"-rule would implicitly grant access to all Role Namespaces, even if the administrator was only added to roles in one or more specific namespaces. As of 6.12, this is no longer the case, and administrators must be explicitly added to roles under the namespaces they should be able to access. Note that the Super Administrator role by default has access to the root namespace, and is not affected by this change, unless the role has been moved to a different namespace.

UnidFnr

In previous versions of EJBCA, trustdir and CA Certificate were defined in ocsp.properties for the UnidFnr OCSP Extension. During upgrade to EJBCA 6.12.0, the extensions defined by OID in ocsp.properties will added to each OCSP Key Binding. Additionally, each certificate in the specified UnidFnr trustdir will be imported as trust entries for each Key Binding. If UnidFnr is enabled in your installation, the CA certificate pointed to by "ocsp.unidcacert" MUST be imported into EJBCA before upgrading.

EJBCA 6.10.0 to EJBCA 6.10.1

Upgrading to 6.10.1 will only affect users who write to Certificate Transparency logs during certificate issuance. 6.10.1 introduces the concept of LABELS, which allow CAs to order CT logs into different groups. Labels replace the 'Mandatory' checkbox introduced in 6.10, allowing CA's to be more fine grained as to which logs they need to write to. The upgrade process will add labels automatically; any logs belonging to Google or checked as mandatory will be labeled as 'MANDATORY', while all others will be labeled as 'UNLABELED'. After upgrade, post-upgrade needs to be run in order to clean the logs of old references.

Complete Descriptions of Changes:

EJBCA 6.6.0 to EJBCA 6.6.1

The upgrade to EJBCA 6.6.1 enables seconds precision for CA and user certificate configuration and allows the issuance of short living certificates. To achieve this, for the CA and the certificate profile a new field for the validity is implemented. This field is populated when a CA and certificate profile is loaded from data object for the first time.

Furthermore, the handling of leap years was changed. Previously, EJBCA would take leap years into account when creating a CA or certificate profile when a validity was specified in terms of years (with "10y" syntax), and add extra days accordingly. Since 6.6.1, EJBCA always counts a year as 365 days, so if you need to account for leap years, then you need to specify them manually, for example as "10y 2d". CAs and certificate profiles from earlier versions will keep their existing validity times unchanged.

1. Changes to CertificateData

CertificateData has three new columns "notBefore", "endEntityProfileId" and "subjectAltName".

CertificateData is for storing issued certificates and can be quite large. Even though deploying the new version EJBCA will eventually performthe schema change on larger installations, we strongly recommend that you manually alter the table before deploying the new version of EJBCA. (Otherwise you might need to force a restart of the application server.) Since CertificateData is used by EJBCA running as a Validation Authority, you need to make this database schema change to your VAs as well before upgrading for publishing to work.

See src/upgrade/650_660/650_660-upgrade-<database>.sql for the correct SQL ALTER statement.

In the case where the endEntityProfileId and subjectAltName has not changed for End Entities since certificate issuance, you can copy this value using a SQL statement like (consult your DBA for the proper syntax and feasibility of executing this query on your production database):

2. Changes to ApprovalData

ApprovalData has a new approval profile concept. Approvals created prior to 6.6.0 will still be available, but performing approvals on nodes running EJBCA versions prior to 6.6.0 on an upgraded database (i.e during upgrade) is not supported. As part of this change, approval notifications are now configured per approval partition instead of globally. Check your Approval Profile afterdeploying the new code.

3. Changes to WebService Approvals

If you have been using Approvals with the WebService API you have configured approval settings in jaxws.properties (only related to calls to genTokenCertificates and/or viewHardToken). This configuration setting has changed as part of the new approval profile concept. Look at jaxws.properties and configure a new approval profile for the WebService Approvals.

4. Removal of the access rule /ca_functionality/store_certificate

The access rule /ca_functionality/store_certificate has been removed for the simple reason that it wasn't actually used. It will not be cleaned from anyexisting roles due to being harmless (and invasive to remove).

5. 100% Upgrade Uptime Notes

EJBCA 6.5.1 to EJBCA 6.5.3

6.5.3 involves a minor change to the CLI command "ca editca". The "-listFields" and "-getValue" flags have been removed, and have been replaced with the "ca listcafields" and "ca getcafield" commands instead.

EJBCA 6.5.0 to EJBCA 6.5.1

EJBCA 6.5.1 involves two minor changes to CMP aliases:

• End Entity Profiles (for RA configurations) were referred to by name instead of by ID. Since End Entity Profile Names are both volatile and not guaranteed unique, this led to issues where renaming a profile could cause a CMP alias to enter an error state. 6.5.1 will automatically convert existing CMP aliases to the new format while preserving the old value for 100% uptime needs. CMP will function, no configuration changes should be made during the upgrade.

• As a result of this, EJBCA no longer supports the ra.endentityprofile=KeyId or ra.certificateprofile=KeyId configuration values, which was deprecated in 2013 (ECA-2948).

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.

Configuration changes in CMP Proxy

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

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

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

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.

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.4.0 to EJBCA 6.4.2

EJBCA 6.4.2 adds a couple of additional rules to any existing Auditors introduced since 6.4.0, as well as their analogs (i.e. an admin with edit rights will be given view rights as well). This upgrade will happen automatically and the database version will be set to 6.4.2.

The changes will be as follows. Any roles matching up to the 6.4.0 Auditors will be given the full set of rules, while non-auditors will be handled as follows:

Auditors will receive all of the above rules, in addition to:

/ra_functionality/view_end_entity

The additional pages available to the Auditor are the following:

• Search End Entities

• Administrator Roles

• CMP Configuration

• SCEP Configuration

• System Configuration

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:

• 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

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.

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.

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'

Changes to Custom Certificate Extensions

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

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

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

• Custom Certificate Extensions must implement the CustomCertificatExtension marker interface

EJBCA 6.3.1 up to EJBCA 6.3.2

As the VA Publisher was shifted from Community to Enterprise in EJBCA 6.3.1.1, it had to change baseclass, so will thus require a database upgrade. To keep to the 100% uptime requirement, please follow the following procedure:

1. Upgrade EJBCA on all nodes. The old publishers will still function on the new nodes, but they won't be editable in the GUI during the

upgrade procedure.

2. Run 'ant post-upgrade' on any one of the nodes and enter "6.3.1" (as this is will be the current database version). This operation

will replace all of the old publishers with the new ones.

3. Verify that the publishers are correctly configured and can publish certificates and CRLs.

EJBCA 6.2.x up to EJBCA 6.3.1.1

EJBCA 6.3.1.1 is the Community release of EJBCA 6.3. Besides including all upgrade steps in previous releases, the biggest database change in EJBCA 6.3.1.1 is that the VA Publisher has been moved from Community Edition into Enterprise Edition. Since the previous class (and code supporting it) no longer exist in Community, a placeholder class retaining all the old data will replace old publishers to retain the data, but publishing using this class will do nothing. Should any Community Users wish to migrate to the Enterprise Edition, the placeholder will be replaced by the new VA Publisher.

External RA has also been removed from the Community Edition for 6.3.1.1. If you are running Community and require these features, please contact a sales representative at Primekey Solutions.

EJBCA 6.2.7 to EJBCA 6.2.8

A very minor change has been made to how the "EMPTY" (default) End Entity Profile is handled. Previous versions required root access (access to "/" in the admin rules tree) to use this profile, but since we since a few versions back generate rights for this profile like any other, those are now used instead.

The signature of OCSP responses are only verified for the first created response per issuer after a OCSP signer cache reload. Previously we always checked each response. (This is intended to detect failing HSMs. The security aspect of response validation is the OCSP client's responsibility.) Use the health check to detect failing HSMs if you cache the OCSP signers for a long time and want to detect this.

Rules for using the GUI have been made for fine grained.

Differences are:

• End Entity Profiles are access via "/endentityprofilesrules" instead of the deprecated "/super_administrator"

• The "EMPTY" end entity profile has access rules like any other profile.

• System Configuration is now accessed via /system_functionality/edit_systemconfiguration instead of "/" in previous versions

• The rule /ca_functionality/edit_publishers is now all that is required to access the Publisher's page in the GUI, and all publishers assigned

to a CA that the admin has access to, or unassigned to any CA, will show up on the list. The "CA Administrator" role template has been given access to this rule.

These changes require no action during or after upgrade. Since earlier rules were either lower level or non-selectable due to deprecation, any user with access to those rules much have access to the new ones as well. Since the new rules are more specific than the old ones, any users gaining access to the affected resources is presumed to be intentional, but testing should be made for any custom roles.

EJBCA 6.2.x to EJBCA 6.2.7

Behavior of OCSP responder has been changed slightly in order to improve performance. Status of the OCSP signing certificate's CA is now only checked when the cache is reloaded, instead of at every request. If unsure how long the timeout is set for, check the value ocsp.signingCertsValidTime in ocsp.properties.

EJBCA 6.2.x to EJBCA 6.2.4

The configuration from for the OCSP default responder has been moved from ocsp.properties into the global configuration, into a new cache with ID=OCSP.

The old value will automatically be committed into the database by the first upgraded node. If ocsp.properties didn't point to a subject DN matching an existent CA or OCSP keybinding, the old value will be retained until either a CA or keybinding matching it has been created or a valid CA or keybinding has been selected in the GUI.

Default behavior of the default responder has been modified to automatically reply for all externally imported CAs which lack specific OCSP keybindings. Be aware that this may cause unexpected behavior in the case of where an inactivated (due to responder certificate being revoked or expiring) keybinding exists, and that keybinding has a different behavior in regards to unknown certificates than the default responder.

EJBCA 6.1.x to EJBCA 6.1.y

See the procedure, and notes, for upgrading from 6.0.x to 6.0.x.

In EJBCA 6.1.2, the SCEP configuration handling has been rewritten. SCEP configurations are no longer read from conf/scep.properties file, instead, SCEP configurations will be set through the command line (execute './bin/ejbca.sh config scep' from EJBCA home directory for command line documentation).

If you do use SCEP, you need to upload your old scep.properties file to EJBCA after upgrade. You can do that by executing the following command in EJBCA home directory:

./bin/ejbca.sh config scep uploadfile conf/scep.properties scep

The new URL will be: http://HOST:PORT/ejbca/publicweb/apply/scep/CONFIGURATION_ALIAS/pkiclient.exe

It you use the URL: http://HOST:PORT/ejbca/publicweb/apply/scep/noca/pkiclient.exe

or the URL:http://HOST:PORT/ejbca/publicweb/apply/scep/ra/noca/pkiclient.exe

You need to set the property 'ALIAS.includeca' to 'false' in the command line by executing the followingfrom EJBCA home directory:

./bin/ejbca.sh config scep updatealias ALIAS includeca false

If you are using External RA, please note that the name of the scep.properties file has been changed to scepra.properties

EJBCA 6.0.x to EJBCA 6.1.x

Upgrade from EJBCA 6.0 to 6.1 consists of a simple database change in the table KeyRecoveryData. If the database user used for EJBCA has alter table privileges the upgrade will be done automatically when deploying the new version of EJBCA (plug-in upgrade) and starting JBoss. If you prefer to do the database upgrade manually, see src/upgrade for SQL scripts for your specific database.

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, refer to EJBCA Installation.

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 EJBCA Operations Guide
   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.

Basic Upgrade Procedure for Validation Authorities

100% Uptime Upgrade Notes

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.

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.

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 auto-detected. 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.

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.

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.

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.

It 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).

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.

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.

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').

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.11.0 or 3.11.1 to EJBCA 3.11.x

Read RELEASE_NOTES carefully in order to see if any particular changes might effect your upgrade.

Normally upgrades within a major release are plug-in upgrades.

• Copy conf/*.properties from the earlier installation (if not using ejbca-custom).

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

Note the possibility to use 'ejbca-custom' directory since EJBCA 3.5.x, this can simplify upgrades.

There is one issue that only affects installations upgraded to or freshly installed on EJBCA 3.11.0.

The database mapping for KeyRecoveryData.certSN on _MySQL_ in 3.11.0 was wrong and can be corrected by running:

ALTER TABLE KeyRecoveryData MODIFY certSN varchar(80) binary NOT NULL DEFAULT '';

The database mapping for UserData.cardNumber in the table create script on _MySQL_ in 3.11.0 and

UPGRADE notes in 3.11.1 was wrong and can be corrected by running:

ALTER TABLE UserData MODIFY cardNumber varchar(250) binary NULL DEFAULT NULL;

The database mapping for ServiceData.nextRunTimeStamp and runTimeStamp was inconsistent on _Sybase_ in 3.11.0 and can be corrected by running:

ALTER TABLE ServiceData MODIFY nextRunTimeStamp DECIMAL(20,0) DEFAULT 0 NOT NULL;

ALTER TABLE ServiceData MODIFY runTimeStamp DECIMAL(20,0) DEFAULT 0 NOT NULL;

ALTER TABLE ServiceData MODIFY runTimeStamp DECIMAL(20,0) DEFAULT 0 NOT NULL;

EJBCA 3.10.x to EJBCA 3.11.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. Do 'ant post-upgrade' to make sure the new database columns in table ServiceData are populated,

and add new database column to PublisherQueueData.

7. Restart JBoss again to flush all caches.

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

The database upgrade is normally done automatically for you when you run 'ant upgrade' and 'ant post-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. Check src/upgrade/310_311 to find the correct sql files for your database.

You should be able to upgrade from EJBCA 3.2.x directly to 3.11.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.

This is very important, depending on your database version you may have to do some additional steps for some of the upgrades.*