EJBCA Upgrade Notes Summary

The following lists summarized upgrade notes for all EJBCA versions released. For more information on a specific release, see the respective EJBCA Upgrade Notes for details.

For upgrade instructions and information on upgrade paths, see Upgrading EJBCA. For details of new features and improvements in a respective release, see the EJBCA Release Notes.

EJBCA 8.2 to EJBCA 8.3.x

Microsoft Auto-Enrollment via RA in EJBCA 8.3.1

Customers using Microsoft Auto-enrollment via the RA will face an issue in EJBCA 8.3.1, causing enrollment to fail. Affected customers are advised to upgrade to EJBCA 8.3.2, where this issue has been corrected.

Before upgrading to EJBCA 8.3.2, customers using EJBCA 8.3.1 and Microsoft Auto-enrollment via the RA can manually export the certificate profiles used by the MSAE aliases from the CA side using either the GUI or the EJBCA ConfigDump tool. Importing the profiles on the RA will then make the RA accept Microsoft Auto-enrollment requests successfully.

Behavioral Changes

Changed behavior of REST API createcrl endpoint

Previously, when using /v1/ca/{issuеr_dn}/createcrl with 'deltacrl' set to "false", it resulted in the creation of a base CRL. When set to "true", it was supposed to create a base CRL and attempt to create a delta CRL, but it was empty because no certificates were revoked since the previous base CRL was created. Now, when the 'deltacrl' parameter is set to "true", it results in the creation of a delta CRL, and when set to "false", it creates a base CRL.

ocsp.untilNextUpdate, ocsp.maxAge and ocsp.expires.useMaxAge have been moved from ocsp.properties into database configuration.

These properties will be automatically be migrated from ocsp.properties into the database, can now be modified from the UI or ConfigDump instead and may be removed from ocsp.properties after upgrade. See the OCSP Overview page for more information.

Stricter Subject DN validation

Previous versions of EJBCA would accept but silently change malformed parts of Subject DN components when there are un-escaped characters.

For example,  "CN=Example=Test" would become "CN=Example".

Since EJBCA 8.3, these will now give an error. In particular, the SOAP API will respond with an EjbcaException with the message "badly formatted directory string" and the REST "endentity" call will give HTTP error 400.

Pre-certificate revokation service

The service has a changed behaviour and hence a new name. It is now called Pre-certificate maintenance service, and the revokation of the not fully issued certificates which are residing in the IncompleteIssuanceJournalData table is now optional.

It could be configured via GUI under the Services configuration page in EJBCA admin web. It is recommended to keep this option disabled. It will by default be disabled for the newly created services (EJBCA 8.3 and onwards) and for the services created in the older versions, it will be enabled by default, to preserve the backward compatibility. 

EJBCA 8.1 to EJBCA 8.2

Customers upgrading to EJBCA 8.2 are advised to specifically upgrade to version 8.2.0.3 since this specific version includes important updates.

Behavioral Changes

Changed behavior when searching for certificates in RA Web 

Before EJBCA 8.2.0, certificate search in RA Web always looked up entries using partial subject distinguished name, subject alternative name, username, full serial number, or external account ID. 

Starting from version 8.2.0, the default behavior has changed, and entries will be searched only by full serial number and partial subject distinguished name, with the option to extend search parameters by selecting the relevant checkboxes. This change was introduced to avoid full table scans by default which may cause the query to timeout on large databases.

VA Peer Publisher will always publish CA and OCSP signer certificate content

As of EJBCA 8.2.0, the Validation Authority Peer Publisher will always publish the full certificate base64 data for CA and OCSP key binding certificates to remote VAs, irrespective of the setting Store certificate at the Validation Authority. As a result, unintended errors during OCSP response generation are avoided.

EJBCA 8.0 to EJBCA 8.1

Behavioral Changes

Changed behavior when editing or adding end entity through SOAP/WS

When using the "edituser" command to add or edit an end entity through web services, the end entity profile setting Modifiable was previously ignored for Start Time and End Time.

This has now been changed and it is no longer possible to update Start Time or End Time with new values unless allowed by the profile. It is also not possible to add a new end entity with other values for Start Time and End Time than those specified in the profile, unless they have been configured in the profile as Modifiable.

Improved error handling in v1/certificate/certificaterequest

The REST endpoint v1/certificate/certificaterequest would previously return HTTP response status code 500 Internal Server Error in a number of scenarios where a 400 Bad Request or 409 Conflict would have been more appropriate. Errors related to misconfigured custom extensions or a malformed CSR will now return the response status code 400. Errors related to the Subject DN of the End Entity or the Public Key of the CSR conflicting with existing ones now return the response status code 409.

Unintended API Breakage in Peer Connections in 8.0

The 8.0 release contained an unintended API breakage in Peer Connections. In EJBCA 8.0.0.1 the API was restored to work as in 7.x again (ECA-11731).

If you are planning on using a mixed version environment, with some nodes running 8.0 and others running later or earlier versions, please refer to the EJBCA 8.0 Upgrade Notes.

EJBCA 7.12.x to EJBCA 8.0

New packages need to be added to logger

In EJBCA 8.0, some code has been migrated to the com.keyfactor package. To configure the log level for these classes, perform the following operation against the JBoss CLI:

/opt/wildfly/bin/jboss-cli.sh --connect '/subsystem=logging/logger=com.keyfactor:add(level=INFO)'

TLS v1.3 Support

As of EJBCA 8.0, TLS v1.3 cipher suites are supported for features such as Peer connections. In order to utilize it, TLS v1.3 has to be configured for your application server. For more information about configuring TLS for your application server, see the corresponding Configure TLS section for your Application Server.

Deprecated algorithms affecting MS auto-enrollment

The RC4 algorithm has been deprecated since Java 8 and removed in later versions. With Java 11 as the new baseline, auto-enrollment deployments using RC4 in their Kerberos configuration will fail with the following error:

 WARN  [org.ejbca.msae.Krb5TicketValidateAction] (default task-5) Invalid ticket for HTTP/ejbcaserver.yourcompany.com@YOURCOMPANY.COM: java.security.PrivilegedActionException:
Failure unspecified at GSS-API level (Mechanism level: Encryption type RC4 with HMAC is not supported/enabled)

Resolution

• Update krb5.conf, keytab as well as the service account configured for the auto-enrollment alias to support AES instead. You may also need to purge to old RC4 Kerberos ticket before the change takes effect.
• Add "allow_weak_crypto" in krb5.conf (not recommended)
  

Configuration change for MSSQL and Postgres users

Due to differences between databases in how batches are read, MSSQL and PostgreSQL installations should have database.crlgenfetchordered set to 'true'. For more information, see cesecore.properties in Managing EJBCA Configurations.

Changed Transaction Handling in Enrollment Protocols

In order to support parallel enrollment requests with the same username (ECA-4347), the handling of database insertion/updates of end-entities has been changed in several enrollment operations. This affects the following enrollment protocol operations and enrollment APIs:

• EST: simpleenroll in RA mode
• CMP: IR & CR requests in RA mode
• REST API: /v1/certificate/pkcs10enroll
• EjbcaWS SOAP API: The certificateRequest method

The following changes have been made:

• End entity updates are suppressed if there are no meaningful changes:
  • If only the modification timestamp changed.
  • For end entities that enter the GENERATED state, changes of the password hash are also ignored.
• End entity insertions/updates are run in a separate transaction, and conflicts are ignored, if:
  • A new end entity is being created.
  • The end entity is in GENERATED state, and after the enrollment operation, it remains in GENERATED state.

Unintended API Breakage in Peer Connections

The 8.0 release contained an unintended API breakage in Peer Connections. This can cause enrollment, search and key recovery to fail when one, but not both, of the CA and the RA is running 8.0.

In EJBCA 8.0.0.1 the API has been restored to work as in 7.x again (ECA-11731), see EJBCA 8.0 Upgrade Notes. 

EJBCA 7.11 to EJBCA 7.12

Database Changes

A new column invalidityDate has been added to CertificateData and NoConflictCertificateData. If your EJBCA database user does not have ALTER TABLE privileges, you will need to run the ALTER commands in the upgrade scripts.

Behavioral Changes

Auto-enrollment LDAP Connection Timeout

The timeout for LDAP connections to Active Directory is now configurable per auto-enrollment alias and the default is set to 5 seconds. Previously the default JDK connection timeout was used which caused unnecessarily long timeouts, blocking enrollment attempts.

EJBCA 7.10.x to EJBCA 7.11

Behavioral Changes

OCSP Extensions always returned if configured

As of EJBCA 7.11, the OCSP responder will always return an extension if possible, if configured. Previously, extensions were only returned if specified by the client in the request. 

REST API requires Certificate Profile setting to backdate revocations

EJBCA 7.11 brings a minor behavioral change in how the certificate revocation endpoint works with backdated revocation dates. During revocation of certificates or changing revocation reason of previously revoked certificates, the /revoke REST endpoint requires the Allow Backdated Revocation setting to be enabled in related certificate profiles. For more information on backdated revocation, see Certificate Profile Fields.

Custom header mandate for REST calls from browser

EJBCA 7.11 includes a minor security fix to prevent Cross-Site Request Forgery (CSRF) attacks against the EJBCA REST API. A system configuration setting has been added to mandate a custom header for REST endpoints when invoked from the browser (System Configuration > Available Protocols). Backend service calls and browser calls are distinguished by the presence of any of the two forbidden headers "Sec-Fetch-Mode" and "Sec-Fetch-Dest". Hence, there should not be any impact on backend services unless these headers were forwarded to EJBCA. These forbidden headers are added by most modern browsers except Safari.

Deprecations

Validation CLI Tool Removed

As announced in the previous release, the Validation CLI tool has been removed.

EJBCA 7.9.x to EJBCA 7.10

Post Upgrade

When you upgrade to EJBCA 7.10.0.1, you must perform a post-upgrade. The post-upgrade is required for ACME pre-authorization and if a post-upgrade is not performed, order creation will fail for pre-authorized identifiers and a new authorization must be requested by the ACME client. ACME pre-authorizations expire after 24 hours. To avoid these cases, disable the ACME protocol (under EJBCA System Configuration > Protocol Configuration > ACME) before the update and re-enable it after the post-upgrade is complete.

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

Behavioral Changes

Produce Pre-signed OCSP Responses Only for non-expired Certificates

The OCSP Response Pre-Signer worker now generates responses for non-expired certificates and updates the expired responses for non-expired certificates. The expired certificates will keep receiving OCSP responses generated online. For more information, see OCSP Response Pre-Signer.

ConfigDump Import Improvements

The EJBCA ConfigDump tool will now only import or update role members if the token being used is important to the role being updated. A token is considered important for a role if the access rights granted to the token by the role are not duplicated in some other role that has the same token as a member. For more information, see ConfigDump Tool

More Fine-grained Access Rules for RA GUI

The access rules /ca_functionality/use_username and /ca_functionality/use_approval_request_id have been added and correspond to the pages with the same name in the EJBCA RA UI. These access rules are added automatically to all roles with /ca_functionality/create_certificate access. For more information, see Access Rules and RA Administrator Access Rules.

New Extension Added by Default During MS Auto-enrollment

Addressing a recent vulnerability discovered for Microsoft Certificate-Based Authentication, EJBCA now supports the new extension szOID_NTDS_CA_SECURITY_EXT that maps the certificate to an Active Directory user /computer object. The extension will be allowed by default for all certificate profiles and included in certificates enrolled via EJBCA's Microsoft Auto-enrollment integration. Enrollment via other endpoints and protocols is not affected. For more information, see Microsoft ObjectSid Security Extension in Certificate Profile Fields.

Deprecations

Script-based Auto-enrollment

The legacy script-based auto-enrollment (relevant before Microsoft Auto-enrollment was integrated into EJBCA proper) has been removed. For more information on auto-enrollment in EJBCA, see Microsoft Auto-enrollment Overview.

Validation CLI Tool

The legacy Validation CLI has not been supported for several years and is being sunset in this release, to be removed in the next major/feature release. 

EJBCA 7.8.x to EJBCA 7.9.0

EJBCA 7.8.2 to EJBCA 7.9.0

Behavioral Changes

URI Name Constraints Declaration in the UI

Updated handling of URI Name Constraints in the user interface. Previous behavior expected protocol to be part of the name constraint, which was not in line with RFC 5280. This behavior has been amended in the UI but does not affect name constraints declared through WS or REST. 

"View End Entity" and "Delete End Entity" Access no longer Required for Enrollment from RA GUI

In previous versions of EJBCA, it was necessary to grant Delete End Entity access to make a role able to create certificate requests in the RA GUI. Additionally, View End Entity access was required when enrolling via CSR. As of EJBCA 7.9.0, neither of these access rules are required, and only Create End Entity access is needed. For more information, see RA Administrator Access Rules.

Recommended use of Bundled Bash Scrips with CLI Applications   

If running one of our various CLI applications such as the CAA checker, the EJBCA CLI, or ClientToolBox, we strongly recommend running the bundled .sh script as opposed to running the application straight from the command line using java -jar. If doing so, note that the flag -Dlog4j1.compatibility=true needs to be added to the command. 

New Microsoft Azure APIs

As of version 7.9, EJBCA no longer uses the deprecated ADAL library to access Microsoft Azure APIs. If your EJBCA installation uses Intune SCEP, the Microsoft Intune Certificate Revocation Service, or the Azure CRL Publisher, you may need to update your configuration.

Also, if you are using a peer for any of the above services, both the peer and the main CA will need to be running at least version EJBCA 7.9.

Deprecations

Legacy External RA GUI 

The UI section of the legacy External RA (which was recommended prior to the implementation of the EJBCA RA) has been deprecated and removed. 

Batch Enrollment GUI

The Batch Enrollment GUI has been out of support for several years and has now been deprecated and removed. 

EJBCA 7.8.1 to EJBCA 7.8.2

Recommended use of Bundled Bash Scrips with CLI Applications   

If running one of our various CLI applications such as the CAA checker, the EJBCA CLI or ClientToolBox, we strongly recommend running the bundled .sh script as opposed to running the application straight from the command line using java -jar. If doing so, please be aware that the flag -Dlog4j1.compatibility=true needs to be added to the command. 

EJBCA 7.8.0 to EJBCA 7.8.1

End Entity Profile Size Limits Extended

End Entity Profiles have been upgraded to support up to 10,000 SDN, SAN, or SDA fields.

Note that exports performed through StateDump or the CA UI prior to 7.8.1 will no longer be valid after this change. ConfigDump exports are unaffected.

EJBCA 7.7.0 to EJBCA 7.8.0

Upgrade Actions

AUD Claim needs to be set for OAuth Providers prior to Post-Upgrade

Upon performing the upgrade to EJBCA 7.8.0, a new field will be added to each defined OAuth provider defining an Audience claim. Post-upgrade will refuse to run until this field has been filled in for all defined OAuth providers.

Checking the aud claim for all OAuth authenticated users will commence after post-upgrade has been run. If no OAuth providers have been defined, then this step can be disregarded. 

Behavioral Changes

ACME Certificate Enrollment

End entity profiles used for ACME certificate enrollment must have the Batch generation (clear text pwd storage) option enabled. For more information, see End Entity Profile Configuration in ACME.

Database Changes

Table added to tracking aborted issuance operations

A new table, IncompleteIssuanceJournalData, has been added to track failed or aborted certificate issuance operations when Certificate Transparency is being used.

Just like other tables, this table is by default created on startup.

Table definitions are available in doc/sql-scripts/create-tables-ejbca-*.sql

Important Notes

Improving Reliability of Direct Publishing

This section is only relevant when using direct publishing.

A new option, Use safe direct publishing, has been added to Publishers. With this option enabled, EJBCA will temporarily write certificates to the publisher queue even if direct publishing is enabled, so publishing can resume in case the transaction fails.

Additionally, this option makes the issuance operation finish just before direct publishing happens, instead of after.

It is recommended to enable the Use safe direct publishing option for publishers, where direct publishing is used, and maximum reliability is required. For some high volume PKIs this may lead to a slight performance drop. 

Improving Reliability of Certificate Transparency Submission

This section is only relevant when using Certificate Transparency timestamps (SCTs) in certificates.

As of EJBCA 7.8.0, EJBCA keeps a journal (in IncompleteIssuanceJournalData) of pre-certificates, so they can be revoked if an outage occurs after pre-certificate generation, but before the final certificate generation has finished.

A new type of Service has been added, Pre-Certificate Maintenance Service, which revokes pre-certificates after a defined amount of time (by default 30 minutes), if the issuance operation has not finished.

It is recommended to add the Pre-Certificate Revocation Service if Certificate Transparency timestamps are used in certificates.

EJBCA 7.6.0 to EJBCA 7.7.0

Behavioral Changes

Approvals for ACME account management

EJBCAs ACME implementation now supports approvals for the newAccount and keyChange resources.

RA Name Generation Scheme for ACME

The name for end entities used to issue certificates with EJBCAs ACME implementation can be determined by a name generation scheme. The functionality supports prefixes and postfixes with either random, constant, or end entity names derived by the subject DN attributes such as the CN or others.

EJBCA 7.5.x to EJBCA 7.6.0

Behavioral Changes

OCSP Logging Configurable in the GUI

The OCSP Audit Log and the OCSP Transaction Log configuration are now configured in the EJBCA GUI instead of in the ocsp.properties configuration file, see OCSP Responder Management. Your existing configuration in ocsp.properties is migrated to the database when EJBCA 7.6.0 is deployed for the first time. The property ocsp.log-timezone is ignored and the timezone specified in ocsp.log-date is used instead.

Stricter Enforcement of Script Execution from the General Purpose Custom Publisher

The enforcement of which local scripts are allowed to be executed from the General Purpose Custom Publishers has been improved to verify against script enablement and an allow list every time the publisher runs. If you are using a General Purpose Custom Publisher to run scripts locally on the CA, verify that access to scripts are enabled in the EJBCA System Configuration (System Configuration → External Scripts → Enable External Script Access). If scripts are enabled and no allow list enforced, you are not affected by the change. If scripts are enabled and an allow list is enforced, ensure that the script executed is on the allow list.

Additional Password Masking in ConfigDump and Statedump

ConfigDump exports previously included certain passwords that allowed importing the passwords into other environments. As of EJBCA 7.6.0, all passwords are masked. This means you now need to either edit the exported configuration file before import or edit the values in EJBCA after the import. For more information, see ConfigDump Tool.

Alias passwords are exported in encrypted form in the Statedump tool. If importing a Statedump configuration file into a system with a different encryption key configured, the input cannot be decrypted, and instead, the hex string with the (old) encryption will be used as the alias password. You can edit passwords in Statedump XML files before import, or change the passwords after import using the EJBCA CLI or CA UI.

CMP Revocation Applying Multi-tenant Controls on Issuing End Entity Profile

When using an RA calling EJBCA with CMP, utilizing client certificate authentication (signed CMP messages), revocation requests now always control the RA authorization against the end entity profile used to issue the certificate. This enables RA separation based on end entity profiles. Note that if you were relying on only the revoke privilege for RAs, this may now prevent revocation if your access rules do not allow revocation from the same end entity profiles for which issuance is permitted.

Extended Key Usage Enforced for Peer Connections

Due to an issue in earlier versions of EJBCA, outgoing peer connections would accept server certificates having an Extended Key Usage (EKU) extension, but without the Server Authentication value.

The EKU certificate extension is now enforced. This affects only systems with incorrectly configured EKU certificate extensions. Systems with correctly configured EKU certificate extensions will not require any changes.

EJBCA 7.5.0.1 to EJBCA 7.5.1

Behavioral Changes

Extended Key Usage is now enforced for peer connections

Due to a bug in earlier versions of EJBCA, outgoing peer connections would accept server certificates having an Extended Key Usage (EKU) extension, but without the Server Authentication value.

The EKU certificate extension is now enforced. This affects only systems with incorrectly configured EKU certificate extensions. Systems with correctly configured EKU certificate extensions will not require any changes.

EJBCA 7.4.x to EJBCA 7.5.0.1

Below are important changes and requirements when upgrading from EJBCA 7.4 to EJBCA 7.5.0.1.

EJBCA 7.5.0 was an internal release, not generally available for customers.

Database Changes

EJBCA 7.5.0.1 contains the new columns accountBindingId in CertificateData and tokenProviderId in RoleMemberData as well as subjectDn, email in ApprovalData (added in EJBCA 7.4.3).

The columns are created automatically by Hibernate when EJBCA 7.5.0.1 is deployed for the first time. However, if your EJBCA database user does not have GRANT privileges, you need to run the ALTER commands in the upgrade SQL scripts before deploying EJBCA. SQL scripts are located under doc/sql-scripts/.

Behavioral Changes

New Secure Authentication Web Property

To support authentication with both certificate and OAuth2 token, a new web.reqauth property has been added to the web.properties configuration file, replacing and deprecating the former property web.reqcert.

The new web.reqauth property enforces secure authentication by the client TLS certificate or OAuth2 token to access the EJBCA Administration interface. The change is backward compatible and thus the former web.reqcert property can still be used in existing configurations. Note, however, that new installations should only use the web.reqauth property.

Improved RA and CA Approvals Handling

RA approvals and CA approvals are now handled in their respective UIs.

RA Related Approvals Moved To RA UI

Approvals for the following actions are now managed using the RA UI and are no longer listed in the CA UI:

• Add/Edit End Entity
• Key recovery
• Revocation

CA Related Approvals Moved To CA UI

CA related approvals are shown in the CA UI (Supervision Functions > Approve Actions) and approvals for the CA Token Activation are no longer listed in RA UI. For more information, see Approving Actions.

Default Encoding of Policy Notice Text X.509 Certificate Extension Changed to UTF-8

When creating a new CA, the option Use UTF-8 in policy notice text previously defaulted to false in order to support older versions of Windows. Since Windows now supports the standard UTF-8 encoding, the default value of Use UTF-8 in policy notice text has been changed to true (enabled). The change only applies to creating new CAs and values of existing CAs are not changed.

Removed Support for Native Browser Enrollment

The Public Web menu option Create Browser Certificate has been removed since relevant browsers no longer support this functionality.

eIDAS Edition

If upgrading a software installation of EJBCA eIDAS edition, the following two options need to be enabled in conf/web.properties in order for the Utimaco CP5 HSM options to be visible in the Admin UI when creating new crypto tokens and activating keys in crypto tokens.

p11ng.cryptotoken.enabled=true
p11ng.utimacocp5.enabled=true

EJBCA 7.4.2 to EJBCA 7.4.3

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.

To avoid any uptime issues when upgrading:

• Upgrade the RAs before you upgrade the CA
  or
  
• If you wish to upgrade the CA before the RA or run RAs on version 7.4.2 or older, with a CA on 7.4.3 or newer, you need to set the property raapi.legacyest.enabled=true in the configuration file conf/web.properties, and then re-build and redeploy EJBCA to re-enable the old EST method call. Note that the old method call does not enforce the domain security of the RA, i.e. restrictions set out in the peer connector role will not be enforced.

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. 

EJBCA 7.4.1 to EJBCA 7.4.2

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. 

EJBCA 7.4.0 to EJBCA 7.4.1

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 Responder Management.

Post Upgrade

Being a minor release, no post upgrade is required. 

EJBCA 7.3.x to EJBCA 7.4.0

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

New Table OCSPResponseData

EJBCA 7.4 contains a new table called OCSPResponseData for storing canned OCSP responses.

This table is created automatically by Hibernate when EJBCA 7.4 is deployed for the first time. However, if the database user is not granted CREATE TABLE privileges, you need to add this table manually before deploying EJBCA. SQL scripts for adding this table are located in doc/sql-scripts/.

Also, add the new indexes manually as follows:

CREATE INDEX ocspresponsedata_idx1 ON OcspResponseData (cAId);
CREATE INDEX ocspresponsedata_idx2 ON OcspResponseData (serialNumber);
CREATE INDEX ocspresponsedata_idx3 ON OcspResponseData (nextUpdate);

New Indexes for CRLData

Since the introduction of partitioned CRLs in EJBCA 7.1.0, it has come to our attention that the default index recommendations in doc/sql-scripts/create-index-ejbca.sql no longer work if partitioned CRLs is enabled for a CA. See ECA-8680 for more information.

To fix this, EJBCA will attempt to modify existing indexes during a post-upgrade to EJBCA 7.4.0 as shown in the table below:

If the EJBCA database user does not have sufficient permissions to modify these indexes, an error will be printed in the log but the post-upgrade will succeed. You can then modify these indexes manually.

Behavioral Changes

Stricter Certificate Extensions Check

Earlier versions of EJBCA did not report any error when certificate extensions were present in an End Entity (for example in Web Service requests), but not allowed in the Certificate Profile. In this case, the disallowed certificate extensions were silently ignored.

Since the earlier behavior could potentially cause compliance issues, EJBCA will now report an error and abort issuance if the request contains an extension that is not allowed by the Certificate Profile.

This check is only performed when the certificate extensions are specified in the End Entity. There is no change to the behavior when certificate extensions are specified in a CSR. That is still controlled by the setting Allow extension override by CSR.

CA/B Forum OrgID Check in External Request

If the CA/B Forum Organization Identifier is present in the external request (for example in Web Service requests), but the corresponding Use checkbox in the End Entity Profile is cleared and the one in Certificate Profile is selected, then the certificate issuance will fail with the appropriate error message (previously the certificate was issued successfully).  

In case the request does not contain a CA/B Forum Organization Identifier and the Use checkbox related to it in the Certificate Profile is cleared, but in the End Entity Profile set to Used and Required and Modifiable without a predefined value, the certificate will fail to issue (previously the certificate was issued without the CA/B Forum OrgID inside it). 

If a predefined value is present in the End Entity Profile, then the certificate will be issued using that value even if the CA/B Forum Organization Identifier is missing in the request. 

SCEP Security Fix - More Restrictive CA Access

In earlier versions of EJBCA, the CA for SCEP was only restricted by the configured End Entity Profile and Certificate Profile. The RA CA Name option, while documented as restricting the CA, was in fact only used as a default option.

As of EJBCA 7.4.0 (and 6.15.2.5, 7.3.1.1) a SCEP alias will only allow issuance using the CA selected as RA CA Name. This CA must still be selected in the configured End Entity Profile and the Certificate Profile.

Ignoring Empty Default CA Issuers URI Regardless of how CA was Created

Previously there was an inconsistency between CLI and UI created CAs when issuing certificates with:

• In the certificate profile Authority Information Access>Use CA defined CA issuer enabled.
• In the CA, no default CA issuer URI was set.

With a CLI created CA issuance failed, while with a UI created CA issuance succeeded without a CA Issuer URI in the issued certificate. The behavior has now been made consistent with UI created CAs, i.e. when no CA defined CA issuer URI is configured certificate issuance is successful, without any CA issuer URI in the issued certificate. See ECA-8788 for more details.

SCEP Failure Return Codes modified

The following return codes in SCEP have been modified to better align with the draft and return SCEP FailInfo errors.

RFC 5019 Cache Headers added to POST

In previous versions of EJBCA, only GET requests had the RFC 5019 cache headers. These have now been added to POST as well. 

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.

EJBCA 7.2.x to EJBCA 7.3.0

Database Changes

OCSP Archive Cutoff

As of EJBCA 7.3, if the OCSP archive cutoff extension is enabled for the OCSP key binding, the extension is included in all OCSP responses. In previous versions of EJBCA, the OCSP archive cutoff extension was only included in an OCSP response sent in response to a request for an expired certificate.

The archive cutoff extension is disabled after an upgrade if the property ocsp.expiredcert.retentionperiod has not been configured in ocsp.properties.

Important Upgrade Information

During an upgrade, the property ocsp.expiredcert.retentionperiod specified in ocsp.properties is migrated to the database as follows:

1. The property  ocsp.expiredcert.retentionperiod is read from ocsp.properties.
2. If the property is not found or set to -1, archive cutoff is disabled and there is nothing to migrate.
3. If archive cutoff is enabled, an OCSP archive cutoff extension is added to each OCSP key binding with a retention period as specified by ocsp.expiredcert.retentionperiod.

To ensure that there are no behavioral changes between EJBCA 7.2 and EJBCA 7.3, make sure the following is configured before you upgrade:

• OCSP key bindings are configured for all CAs (only CAs with an OCSP key binding will respond with an archive cutoff extension).
• The property ocsp.expiredcert.retentionperiod in ocsp.properties is set to the correct value.

After the upgrade has completed, you may remove the property ocsp.expiredcert.retentionperiod from ocsp.properties since it is not being used anymore, and optionally enable the setting to base the archive cutoff date on the issuer's notBefore date.

Behavioral Changes

Specifying Certificate Signing Key when Creating CAs

When creating new CAs it is strongly recommended that you specifically select the certificate signing key. Previously you could select the default key, which could be a convenient short-cut in test environments. As a means to improve usability and prevent misconfigurations, we have removed the possibility to specify the default key for the certificate signing key. Generally, the change will not be noticeable as this is what most users already do.

Automatic Certificate Management Environment (ACME) RFC 8555 Compliance

The ACME implementation is now compliant with RFC 8555 and not compatible with the prior release implementing ACME Draft 12. The major changes between these two releases are, that all ACME operations except directory and newNonce have to be authenticated with POST requests. The new release was tested with certbot 0.37.0 (as well as 0.31.0) and PJAC 3.0.1.

EJBCA 7.3.0.X to EJBCA 7.3.1

Behavioral Changes

Certificate Transparency Compliance

A change was made for compliance with CA/B Forum Baseline Requirements. In the case when insufficient SCTs are retrieved from Certificate Transparency logs and no final certificate is issued, EJBCA will now store the precertificate in the CertificateData table (in addition to audit logging it) and respond to OCSP queries with status "good".

EJBCA 7.3.1 to EJBCA 7.3.1.1

Behavioral Changes

SCEP Security Fix - More Restrictive CA Access

In earlier versions of EJBCA, the CA for SCEP was only restricted by the configured End Entity Profile and Certificate Profile. The RA CA Name option, while documented as restricting the CA, was in fact only used as a default option.

As of EJBCA 7.3.1.1 (as well as versions 6.15.2.5 and 7.4.0), a SCEP alias will only allow issuance using the CA selected as RA CA Name. Note that this CA must still be selected in the configured End Entity Profile and the Certificate Profile.

EJBCA 7.3.1.1 to EJBCA 7.3.1.2

Behavioral Changes

CVCA Link Certificate Validity and Signature Algorithm

EXTENDED ACCESS CONTROL (EAC) EPASSPORT ONLY

When renewing a Country Verifying CA (CVCA) in the EJBCA Admin UI, a link certificate is automatically created. In earlier versions of EJBCA, the CVCA link certificate inherited the validity (notAfter date) from the old CVCA certificate. This has now been fixed and the notAfter date of the CVCA link certificate will now match the validity of the new CVCA certificate according to the Common Certificate Policy for the Extended Access Control Infrastructure for Travel and Residence Documents (BSI TR-03139).

When renewing a Country Verifying CA (CVCA) and changing the signature algorithm for the new CVCA, the link certificate was previously signed with the algorithm of the new CVCA. This has now been resolved and the link certificate is now signed with the algorithm of the old CVCA. Note that the algorithm identifier in the link certificate itself is the new algorithm as the algorithm is tied to the public key, not to the certificate signature.

EJBCA 7.3.1.3 to EJBCA 7.3.1.4

Behavioral Changes

Custom Extensions and other plugins need to be declared in cesecore.propertes

EJBCA 7.3.1.2 introduced stricter rules for deserializing objects from the database in order to avoid security concerns regarding execution of hostile code. As a result, most custom code injected into EJBCA has become invalid. Thus, these classes need to be declared in cesecore.properties as a comma-separated list:

custom.class.whitelist=com.widget.WidgetCustomExtension,com.widget.AnotherWidgetCustomExtension

For more information, see Allowing Custom Classes in the Database and Managing EJBCA Configurations.

EJBCA 7.1 to EJBCA 7.2.0

Behavioral Changes

Certificate Store and CRL Store Servlets Always Available

The configuration files certstore.properties and crlstore.properties are removed and should no longer be used.

These configuration files allowed you to specify the context root of the servlet and whether the servlet should be available in the EAR file. As of EJBCA 7.2, these two servlets are always available and the context root property has been removed. Access to these servlets is controlled using Modular Protocols Configuration.

• If you are using a custom context root for these servlets, you should reconfigure your client to use the new context root, or put an HTTP proxy between EJBCA and your client.
• If you are upgrading from EJBCA 6.11 or later, and your previous deployment did not contain the servlet, access to it will be disabled after an upgrade. However, if you are upgrading from EJBCA 6.10 or older (where the Modular Protocols Configuration feature was not implemented) access to the servlet cannot be configured automatically during an upgrade, since there is no way of determining whether your previous deployment contained the servlet or not. If your previous deployment did not contain the servlet and you do not want it to be accessible, you need to manually disable it.

For details, see EJBCA 7.2 Upgrade Notes.

Improved Service Execution Logging

Previously the logs stated that service workers had executed or not, but didn't note the state of the execution (any errors being rendered as parts of output). Service workers have been modified to report to the logs the complete execution state, which can be Successful (if run), Failed (if run, although with some failures) or No Action (if executed, but no actions needed to be taken).

Default CA for SCEP Aliases

If the alias being used is operating in RA mode and the message parameter is not specified in the SCEP request, the SCEP operations GetCACert, GetCACertChain, GetNextCACert and GetCACaps use the RA CA name defined by the alias, instead of relying on the scep.defaultca property. This allows for more flexibility and easier configuration for deployments where editing configuration files is inconvenient or not possible.

The old behavior for determining the CA name to use was as follows:

• If a message was sent, use the CA specified by the message.
• If no message was sent, use the CA specified by the property scep.defaultca.

As of EJBCA 7.2, the name of the CA to use is computed as follows:

• If a message was sent, use the CA specified by the message.
• If the alias is in RA mode and no message is sent, use the RA CA name specified by the alias.
• If the alias is in CA mode, the property scep.defaultca is defined, and no message is sent, use the CA specified by the property scep.defaultca.
• If the alias is in CA mode, the property scep.defaultca is not defined, and no message is sent, produce an error.

For more information, see SCEP.

Certificate Transparency

Persistent Caching

Persistent caching of Certificate Transparency SCTs (Signed Certificate Timestamps) has been added in addition to the existing in-memory caching. This adds a new table, SctData for storing cached SCT data. Please ensure this table exists if you use Certificate Transparency.

As there can be several SCTs per certificate, the SctData table will grow large over time. Therefore, we strongly recommend creating an index on the fingerprint column. Refer to doc/sql-scripts/create-index-ejbca.sql for an SQL command to create the index.

Non-Functional Logs Caching (fast fail)

The "fast fail" cache is now enabled by default. For details, see EJBCA 7.2 Release Notes.

Please make sure that only CAs that are trusted by the CT logs are used in certificate profiles where CT is enabled. If a certificate issued by an untrusted CA is submitted, the CT log will return an error, and EJBCA will consider the log to be non-functional (for all CAs, not just the untrusted one). To disable the "fast fail" cache, set the property ct.fastfail.enabled to false in the file conf/cesecore.properties. For more information, see Certificate Transparency.

Post Upgrade

When upgrading to EJBCA 7.2.0, you must perform a post-upgrade after all nodes have been upgraded. The post-upgrade is required because of an improvement allowing custom certificate start time/end time to be set with seconds granularity. The time value was previously saved with minutes granularity. To perform the post-upgrade, click the EJBCA System Upgrade menu option, and then click Start post-upgrade. For more information, see Upgrading EJBCA.

EJBCA 7.2.0 to EJBCA 7.2.1

Behavioral Changes

EST Renewal

For the EST operation 'simpleenroll', if an end entity with the specified username already exists, it is treated as a renewal: a new certificate is issued for the existing end entity (as long as no settings block this behavior: e.g. Enforce Unique DN or Enforce Unique Public Keys). Previously such a request would be rejected, though not likely to occur since end entity usernames were randomly generated.

EJBCA 7.0.x to EJBCA 7.1.0

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

New Access Rules for RA Roles

Some access rules for roles created in the RA web were missing or not set properly.

The new behavior in EJBCA 7.1 is as follows:

• When Approve end entity actions is selected, access is granted to both view and approve end entities. In previous versions of EJBCA, access was only granted to approve end entities, but not to view approvals.
• When Create certificates is selected, access is granted to issue certificates for an end entity. This access rule was missing from the RA web in previous versions of EJBCA.
• When View end entities and certificates is selected, access is granted to both view end entities and certificates issued to those end entities. In previous versions of EJBCA, access was only granted to view end entities, but not the certificates.

The missing access rules will not automatically be granted to existing roles during an upgrade. You need to manually edit any existing RA roles created in the RA Web and enable the appropriate options for the changes to take effect.

Default CMP response signature algorithm is now SHA256

The signature algorithm used to sign CMP response now defaults to SHA256 instead of SHA1. The default algorithm is only used if the CMP request does not contain a signature algorithm, so for most users, there is no change, and SHA1 will be used if your client sends messages signed with SHA1. The only typical case where the default algorithm is used is when client messages are protected by HMAC protection and the CMP server is configured to answer with signed messages. If your CMP clients understand SHA256, they will be able to process the responses as the algorithm used is part of the response.

EJBCA 7.0.0 to EJBCA 7.0.1

Behavioral Changes

SN Entropy set per CA

As of EJBCA 7.0.1, serial number entropy is set per CA instead of globally from the ca.serialnumberoctetsize property in cesecore.properties, and the default value has been raised from 8 octets to 20 octets. Existing CA's will be automatically upgraded using the existing value set, while new CA's will by default be given 20 octets of entropy.

EJBCA 6.15 to EJBCA 7.0

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

Case sensitivity of Full DN match for Role Members

We have updated the X509: with Full DN match option to match case sensitive. Previously it could perform a case insensitive match, even though it was configured to match case sensitive.

We strongly recommend checking that your administrator roles using X509: with Full DN are correctly set up before upgrading.

Limitations on DN strings with support for multi-value RDNs

We have added background support for multi-value RDNs which includes more strict parsing of DNs. The most notable change is that previously when you used plus signs in a DN, these were automatically escaped. Now, plus signs must be escaped. For more information, see Subject Distinguished Names.

Changed Order of DN Component in Sample File

We have corrected the order of the DN component organizationIdentifier in the example file dncomponents.properties.sample.

If you have been using a custom dncomponents.properties file, building on the sample file and you have used the organizationIdentifier DN component, you may experience issues if you change the custom dncomponents.properties file to match the updated value. Let us know if you are subject to this special case, and we'll assist you.

EJBCA 6.14 to EJBCA 6.15.0

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

Custom Certificate Extensions

With the introduction of wildcards and non-required CCEs, we've tightened how extensions in enrollment requests are handled. Where in prior versions undefined extensions in the request would simply be dropped from the final certificate, in 6.15 and later requests containing unmatched extensions will be treated as erroneous and rejected.

EJBCA 6.13 to EJBCA 6.14.0

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

EjbcaWS.getRemainingNumberOfApprovals

The method org.ejbca.core.protocol.ws.common.IEjbcaWS.getRemainingNumberOfApprovals(int) has changed behavior to conform to real world requirements. The previous javadoc stated:

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

This was incorrect as ApprovalDataVO.STATUS_REJECTED is actually -2. In order to stay true to the API we have changed the return value to be -1 for rejected results. The new javadoc states as following:

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

The additional change is that the older implementation would throw an exception for approvals that had expired after being approved. Since 6.14, this method will return 0 if the approval has passed (or -1 if it has been rejected), even if it has since then expired.

EjbcaWS.getProfiles

This method was found to potentially leak information about end entity profiles and CA ID's that the requesting admin wasn't authorized to. If requesting an End Entity Profile, the requesting user must be authorized to the following rules:

• /ra_functionality/view_end_entity_profiles

• to any CAs that are referenced in the EEP
• to any CAs that are referenced in any Certificate Profiles referenced to in the EEP

If requesting a Certificate Profile, the requesting user must be authorized to the following rules:

• /ca_functionality/view_certificate_profiles

• to any CAs that are referenced in the Certificate Profile

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.

EJBCA 6.12 to EJBCA 6.13.0

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.

EJBCA 6.11 to EJBCA 6.12.0

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

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.   

Complete Descriptions of Changes:

1. Post-upgrade can now be performed in the Admin GUI

From 6.8.0 and onwards, the "System Upgrade" menu option will be available in the UI when the system is in need of a post-upgrade-step. Post-upgradecan be triggered from here instead of from the CLI.

2. The role, role member and access rule implementations have changed

All rules are now recursive and during upgrade the existing access rules are converted to grant the same access. Note that when new objects are created under a recursive accept rule, access will be automatically granted.

After a post-upgrade, authentication sessions (i.e. administrators) that match multiple Roles will have the combined access from all the Roles.In previous versions different authentication methods had different priority in the case where authenticated session could belong to multiple Roles.

The "Not equals case sensitive" and "Not equals case insensitive" match operators are no longer allowed. If you use currently use them, you needto reconfigure your roles to be able to proceed past the post-upgrade

Each match key now implies if the match should be case sensitive or not. You are recommended to use the default match value operator for existing rules (usually this means "Equals case sensitive").

For the new implementation, two new tables have been introduced: RoleData and RoleMemberData. The tables AdminGroupData, AdminEntityData and AccessRulesData will no longer be updated with new data, but are retained for upgrade and 100% uptime reasons. 

3. Approval Profiles can now be set per action in CA and Certificate Profile

CAs and Certificate Profiles will automatically be upgraded, using the same profiles for the same actions as before. 

Be aware that exported certificate profiles from 6.6 and 6.7 can be imported, but not from prior versions. 

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

Authentication token implementations now implement the AuthenticationTokenMetaData marker interface, which is used to load them dynamically using service manifests. 

5. The ability to search for information in the 'Details' column of the audit log has been removed.

This is due to the fact that search was not delivering results for rows that contain accented characters, which gave inconsistent behavior. This functionality will be reintroduced when the search always delivers the same results. 

6. WebService API has changed for approvals 

During the rework of Approvals in EJBCA 6.7.0, the exception class WaitingForApprovalException was changed, where the attribute approvalId was changed to the more usable requestId. Since this value was of little use for webservice calls we judged that there was little harm in changing it, but any 3rd party implementations of the WS API should be aware of this change.    

NOTE: There is now a possibility to store subject alternative names in CertificateData, and search for certificates based on that. This feature is disabled by default and you need to enable it with 'Search enabled' for 'Subject Alternative Name' in old Certificate Profiles.  

7. The CLI command 'role addadmin' has been renamed 'role addrolemember'

Besides this, the command is identical to previous versions. 

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.

If you have been using CMP clients which have previously slipped by sending incomplete or bad chains in this field, they may now be rejected. This could for example happen if your vendor of eNodeB's use a vendor CA that issues certificates invalid according to the RFC5280 standard. 

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

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:

$ ant upgrade

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

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

UPDATE CertificateData AS a INNER JOIN UserData AS b ON a.username = b.username
SET a.endEntityProfileId = b.endEntityProfileId, a.subjectAltName = b.subjectAltName WHERE a.endEntityProfileId IS NULL;  

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.

   a. Public Web Self Registration

If you have been using the Self Registration in the old Public Web you need to create an Approval Profile, and select to use this for "Add/Edit End Entity"actions either in the CA configuration or in the Certificate Profile configuration.

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

a. Approval Profiles

Approval profiles (of the Accumulative Approval Profile type) will during startup of the first upgraded node be automatically created and set for CAs and Certificate Profiles using approvals. During the upgrade, approval requests may roll in from un-upgraded nodes, and these will automatically be re-parsed when they are read from the upgraded ones, in other words set to use the same profile as if they'd been created on an upgraded node. For the sake of 100% uptime, this means that all actions (enrollment, revocation, CA activation, etc) may continue during the upgrade, and they may be processed from the upgraded nodes. On the other hand, un-upgraded nodes will not be able to approve actions created by or read by the upgraded nodes until the upgrade process is complete. 

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

EJBCA 6.4.2 to EJBCA 6.5.0

Upgrading to 6.5.0 involves the following changes:

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

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. 

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

100% up-time upgrade notes

There should be no issues moving between EJBCA 6.0 and 6.1, older versions of EJBCA will run with the additional database columns added to KeyRecoveryData. 

If you had existing KeyrecoveryData, you need to set the new column cryptoTokenId to 0 (see src/upgrade/600_610).

update KeyRecoveryData set cryptoTokenId=0;

Since EJBCA 6.1.0 OCSP responses no longer include the Root CA Certificate, unless the Root CA is the OCSP signer, and it is configured to include the signer certificate. Having OCSP responses as small as possible is an important performance feature, and since the client must have the root certificate as trusted there is no need to include the root certificate in the chain. 

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.

EJBCA 5.0.x to EJBCA 6.0.x

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

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. 

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

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

100% Uptime Upgrade Notes

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

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)

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.

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. 

   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.

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

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

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. 

   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 Enforce unique public keys andEnforce unique DN.

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. 

    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.

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

 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;

 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.

 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. 

    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.

   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

Refer to the 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.

    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;

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.

 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.

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.