Skip to main content
Kofax

Usage and requirements of signing certificates

Summary 

This"FastPublish" solution is based on one case only and most likely doesn't cover all possible solution scenarios or error descriptions. This solution is provided as is and may contain limited technical imperfections and consequently may be revised at any time. If you have the same or similar error situation and the provided solution doesn't help in resolving your issue, or if you have further questions or possible additions, please contact your next level of support. 13841

Customer Situation

When using the previously successfuly working P12 certificate with the latest versions of Kofax SignDoc there is an error when signing:

2017-00315 NTLdYRtmKTPMaU-9VzHVURhc 2017-06-19_13-26-51-355 2017-06-19 15:27:05.712
[http-/0.0.0.0:8081-1] de.softpro.sdweb.SPSDSignHelper - validateAndSign: Exception occurred cannot build certificate chain: broken chain

java.lang.IllegalStateException: cannot build certificate chain: broken chain
    at de.softpro.sdweb.SPSDDocumentHelper.addSignatureEX(SPSDDocumentHelper.java:1495)
    at de.softpro.sdweb.SPSDDocumentHelper.addSignature(SPSDDocumentHelper.java:437)
    at de.softpro.sdweb.SPSDSignHelper.validateAndSign(SPSDSignHelper.java:293)
    at de.softpro.sdweb.controllers.SignDocWebController.sign(SignDocWebController.java:292)
    at sails.app.controllers.SigndocController.sign(SigndocController.java:649)
    at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)

When using the P12 demo certificate there are no issues.

Solution

The issues is related to the usage of the certificate that must now be valid and trusted from the EE-certificate (End- Entity) to the root-certificate which may also include intermediate certificates.

Self-signed certificates will be accepted the same way as before.

Please also make sure that the certificates (root or intermediate) are placed in the appropriate certificate store and not present in any other certificate store either.

Also please make sure that the EE-certificate is not imported into any certificate store but present on the application side only.

Root-Certificates

Root-Certificates are usually imported into and made available via the operating system.

If an individual company certificate is used, it must be imported as a trusted root-certificate into the operating system.

Windows: SignDoc verifies certificates against trusted root certificates in the Windows Certificate Store (Trusted Root Certification Authorities).

Linux and OS X: SignDoc uses OpenSSL for verifying certificates. The OpenSSL root directory is /etc/softpro/ssl. Put trusted certificates into file /etc/softpro/ssl/cert.pem.
You can also make /etc/softpro/ssl a symbolic link to /etc/ssl to use the certificates trusted by the operating system.

In SignDoc SDK it is also possible, to add root-certificates to SignDoc SDK at runtime via…

SignDocDocumentLoader loader = ...;
loader.loadTrustedCertificatesFromFile(..);

or

SignDocDocumentLoader loader = ...;
loader.loadTrustedCertificatesFromStream(..);

Multiple root-certificates can be loaded by…

  • PEM encode multiple certificates in one file
  • executing loadTrustedCertificatesFromFile(..) multiple times

Intermediate-Certificates

Instead of being included in the PKCS#12 file, Intermediate-Certificates can also be imported into the Windows Certificate Store (Intermediate Certification Authorities).

Please find below additional information on how certificates have to be used in the various products:

Kofax SignDoc Standard

If an EE certificate requires intermediate certificates for validation, use a PKCS#12 file that contains the private key, the EE-certificate, and intermediate certificates.

Signing Certificates are set/defined/applied in descending order of priority…

  • per signer: by using a Client Side Certificate plugin
  • per account: by account administrators when uploading the certificate via REST API or the Management Client
  • as global setting: by SignDoc Web configuration in sdweb_config.groovy:

[sdweb_config.groovy]
sdweb.certificate.store.pkcs12.file="c:/path/to/pkcs12/file"
sdweb.certificate.store.pkcs12.password="xxxxx"

Kofax SignDoc Web

If an EE certificate requires intermediate certificates for validation, use a PKCS#12 file that contains the private key, the EE-certificate, and intermediate certificates.

Signing Certificates are set/defined by a global SignDoc Web configuration setting in sdweb_config.groovy:

[sdweb_config.groovy]
sdweb.certificate.store.pkcs12.file="c:/path/to/pkcs12/file"
sdweb.certificate.store.pkcs12.password="xxxxx"

Kofax SignDoc SDK

If an EE certificate requires intermediate certificates for validation, they can be set by these approaches…

  • Use a PKCS#12 file that contains the private key, the EE-certificate, and intermediate certificates.
  • Set the intermediate certificate at runtime with…

SignDocSignatureParameters params = ...;
params.setBlob("IntermediateCertificate", data);

The data blob must contain a DER-encoded X.509 certificate or one or more PEM-encoded X.509 certificates.

Applies to

  • Kofax SignDoc Standard 1.3.1.0.0.4144
  • Kofax SignDoc Web 5.2.1-1330
  • Kofax SignDoc SDK 4.2.0.11

Keywords: Certificate, KSD, SDWeb, SignDoc, Standrad, Web

  • Was this article helpful?