Link Search Menu Expand Document

Upgrading to EzSign 4.6


Version 4.6.0 makes signature verification and revocation checking follow the standards (RFC 5280 for certificates, RFC 6960 for OCSP) more closely. As a result, some signatures, certificates, CRLs or OCSP responses that were accepted before may now be refused. This page lists the issues you are most likely to see after upgrading, the error you will see, and what to do

Each new check can be switched off with a setting in the server properties file. Before switching a check off, consider why it failed: the check is there because accepting the certificate or response carries a risk. Switching a check off is a decision for your organisation. The risks of each are described in Certificate Path Checking

In the settings below, replace channel.1 with the number of your channel

This page will be updated as more is learnt from upgrades


Before upgrading

  • Replace the whole EzSignServer/lib folder with the new one. Do not copy the new jars into the existing folder (see Jar or class errors below)
  • Keep a copy of your current properties file and lib folder, so you can go back if needed
  • Test signature verification with a sample of your real signatures and certificates before upgrading production. Most of the issues below show up the first time a signature is verified


Jar or class errors

What you see - errors such as these in the logs, often only when a particular operation is carried out:

java.lang.NoSuchMethodError: 'void com.krestfield.ezsign.KRevocationException.<init>(java.lang.String, com.krestfield.ezsign.KRevocationException$Reason)'
java.lang.NoClassDefFoundError: ...

or, from version 4.6.0, when the server starts:

ERROR Classpath conflict: com.krestfield.ezsign.KRevocationException is in 2 places (the copies differ): .../lib/ezsign-4.6.0.jar, .../lib/ezsign-client-4.4.0.jar. Either copy may be loaded, ...

Why - the server and Management Tool scripts load every jar in the lib folder. If a jar from the previous version is still there, or a jar has been copied in from elsewhere, the same class can be in two jars at different versions and either may be loaded. Older EzSign client jars contained classes with the same names as the server’s, so a client jar in the server’s lib folder causes exactly this

What to do - remove the out of date jar named in the error, or replace the lib folder with the one from the 4.6.0 release. The EzSign client jar is for client applications and is never needed in the server’s lib folder

The Management Tool prints the same warning when it starts. From version 4.6.0 it also needs the ezsign-users jar, which is in the server’s lib folder. If you run the Management Tool on another machine, copy the whole lib folder

To stop the server starting at all when there is a conflict, set:

server.failOnClasspathConflicts=true


Signer certificates with an extended key usage that does not permit signing

What you see

The signer certificate CN=... has the extended key usages [1.3.6.1.5.5.7.3.8], none of which is allowed for signing. Allowed are [...] (set with allowedExtendedKeyUsages). Set relaxExtendedKeyUsageChecks=true to allow this

Why - RFC 5280 (section 4.2.1.12) says that if a certificate has the extended key usage extension, it must only be used for the purposes listed. Version 4.6.0 rejects a signer certificate whose purposes do not include one that EzSign accepts, e.g. a certificate with only time stamping (1.3.6.1.5.5.7.3.8) or OCSP signing (1.3.6.1.5.5.7.3.9). Certificates without the extended key usage extension are not affected

The purposes accepted by default are: any extended key usage, email protection, code signing, document signing, Microsoft document signing, Adobe authentic documents trust, and TLS server authentication (1.3.6.1.5.5.7.3.1) and client authentication (1.3.6.1.5.5.7.3.2). Server and client authentication certificates are accepted because EzSign also verifies signatures made for authentication, so certificates with only these purposes continue to work after upgrading

What to do - preferably, have the certificates reissued with a purpose that permits signing. Otherwise, add the purpose to the accepted list. The setting replaces the default list, so include the defaults as well. For example, to also accept time stamping:

channel.1.verify.allowedExtendedKeyUsages=2.5.29.37.0,1.3.6.1.5.5.7.3.4,1.3.6.1.5.5.7.3.3,1.3.6.1.5.5.7.3.36,1.3.6.1.4.1.311.10.3.12,1.2.840.113583.1.1.5,1.3.6.1.5.5.7.3.1,1.3.6.1.5.5.7.3.2,1.3.6.1.5.5.7.3.8

Or, to accept any extended key usage (a warning is logged each time a certificate would have been rejected):

channel.1.verify.relaxExtendedKeyUsageChecks=true

See Allowed extended key usages


Certificates with a critical extension EzSign does not process

What you see

The certificate CN=... has the critical extension 1.3.6.1.4.1.12345.1, which is not supported. It can also be added to allowedCriticalExtensions. Set relaxCriticalExtensionChecks=true to allow this

Why - RFC 5280 (section 4.2) says a certificate with a critical extension that is not recognised must be rejected. A CA marks an extension critical when the certificate must not be used by software that does not understand it, e.g. policy constraints or a private extension. The root certificate is not checked

What to do - if you know the extension and it is safe to ignore, add its OID (shown in the error) to the list. This is the narrowest option:

channel.1.verify.allowedCriticalExtensions=1.3.6.1.4.1.12345.1

The extension is still not processed; the certificate is just no longer rejected for carrying it. To accept every unknown critical extension instead (a warning is logged each time):

channel.1.verify.relaxCriticalExtensionChecks=true

See Allowed critical extensions


Certificates that break a CA’s name constraints

What you see

The certificate CN=... breaks the name constraints of its issuing CA. ... Set relaxNameConstraints=true to allow this

Why - a CA certificate can restrict the names of the certificates below it (e.g. to one organisation’s domain or directory names). Before 4.6.0 these restrictions were ignored. The subject name, email addresses and subject alternative names are now checked against them

What to do - check the certificate was issued correctly. To accept it anyway:

channel.1.verify.relaxNameConstraints=true


A CA certificate used as the signer

What you see

The signer certificate CN=... is a CA certificate (basic constraints CA is true). Set relaxCaSignerCheck=true to allow this

Why - a CA key should only issue certificates and CRLs. Self-signed signer certificates are not affected

What to do - sign with an end-entity certificate. To accept it anyway:

channel.1.verify.relaxCaSignerCheck=true


CRL problems

A CRL issuer without the CRL Sign key usage

The CRL issuer CN=... does not have the CRL sign key usage set. Set relaxCrlSignCheck=true to allow this

The certificate that signs a CRL must have the CRL Sign key usage (RFC 5280 section 4.2.1.3). To accept it anyway:

channel.1.revocationChecker.crl.relaxCrlSignCheck=true

A CRL without a next update time

The CRL issued by ... has no nextUpdate, so it cannot be checked as current

Without a next update time there is no way to tell a CRL is out of date, so it is refused. This cannot be switched off; the CA must issue CRLs with a next update time

Expired CRLs refused when allowExpiredCrl is set

CRL obtained was not valid.  It expired on ... Allow expired CRLs is true but the CRL expired outside of the allowed N days

Before 4.6.0, when allowExpiredCrl=true was set, any expired CRL was accepted, however long ago it expired, because of a bug in the check. allowExpiredCrlForDays is now applied correctly. If you see this error, the CRL has been out of date for longer than you allowed: fix the CRL publication, or (temporarily) increase the number of days


OCSP problems

Old OCSP responses without a next update time

The OCSP response has no nextUpdate and its thisUpdate (...) is more than 60 minutes in the past. To change this set maxAgeWithoutNextUpdateMins

A response without a next update time was accepted at any age, so an old response could be replayed. It is now only accepted for 60 minutes after its thisUpdate time. If your OCSP responder returns cached responses without a next update time, increase the limit (or set 0 to accept any age, as before):

channel.1.revocationChecker.ocsp.maxAgeWithoutNextUpdateMins=240

OCSP responses signed directly by the issuing CA are now accepted

Before 4.6.0, a response signed by the CA that issued the certificate being checked (rather than by a separate OCSP responder certificate) was refused because of a bug in the comparison, unless relaxSigningPath=true was set. These responses are now accepted, as RFC 6960 allows. No action is needed. If you set relaxSigningPath=true only to work around this, you can now remove it

OCSP responders must have the OCSP Signing purpose

The OCSP response was signed by ..., which is not the issuing CA and does not have the 'OCSP Signing' extended key usage, so it is not authorised to sign OCSP responses (RFC 6960). To accept it, set the checkOcspSigningCertUsage property to 'false'

A response signed by a certificate other than the issuing CA (a delegated responder, or one accepted with relaxSigningPath=true) was accepted whatever its purpose, so any certificate the CA had issued could sign responses for the CA’s other certificates. RFC 6960 requires the responder’s certificate to have the OCSP Signing extended key usage (id-kp-OCSPSigning), and this is now checked by default. Responses signed by the issuing CA itself are not affected. Delegated OCSP responders that follow RFC 6960 have this purpose, so no action is normally needed. If a responder you rely on does not, the best fix is to have its certificate reissued. Otherwise:

channel.1.revocationChecker.ocsp.checkOcspSigningCertUsage=false

Before 4.6.0, setting checkOcspSigningCertUsage=true also refused responses signed by the issuing CA itself. It no longer does

ignoreSSLErrors now only applies to that channel

Before 4.6.0, ignoreSSLErrors=true on an OCSP or CRL checker changed the TLS settings for the whole Java process, so it also (silently) applied to every other HTTPS connection, including other channels. It now only applies to that checker’s own connections. If another channel’s OCSP or CRL downloads start failing with TLS certificate errors after the upgrade, they were relying on this side effect: set ignoreSSLErrors on that channel too, or better, trust the server’s certificate


Signatures that are now refused

Raw signatures using SHA-1 or MD5

... is weak and has therefore been rejected.  To permit this algorithm set the denyWeakSignatureHash property to false

The hash used in raw RSA signatures was not checked before. It is now checked as for PKCS#7 signatures. To accept SHA-1 or MD5 signatures:

channel.1.verify.denyWeakSignatureHash=false


Server and socket interface changes

These do not need any action, but may be noticed:

  • Messages are no longer logged by default - server.logMessages now defaults to false (it was true). Set it to true if you relied on the messages being in the log. They can contain the data being signed or decrypted
  • Large messages are refused - messages longer than server.maxMessageSize (64M characters, about 48MB of data) are refused with an error. Increase the setting if you send larger data
  • An empty allowed address list now allows every client - if server.allowedSourceIpAddresses is present but empty, every client can connect (as when it is omitted). Before 4.6.0 an empty value refused every client. IPv6 addresses in the list now also work
  • Clients receive error replies - some errors (e.g. a request that could not be parsed) used to close the connection without a reply. The client now receives the error. Existing clients handle this without changes