Global keystore
webPDF uses a central storage, the “Global Keystore”, to provide certificates with public keys and private keys for digital signatures. The certificates can then be used in the Signature web service call.
A keystore is basically a database format that is capable of securely storing certificates (public keys) and private keys (e.g., by using password protection). Keystores can have various (file) formats.
webPDF supports the following file formats for keystores:
| Format | Description |
|---|---|
| JKS (Java Keystore) | A keystore (file) format specifically for use in Java-based applications. |
| PKCS #11 | A keystore format for use with smart cards. It describes an API that allows the use of certificates with cryptographic tokens. |
| PKCS #12 | A file-based keystore format for storing private keys and public certificates that allows password protection. A common standard. |
PKCS #11 is a "Cryptographic Token Interface Standard". It allows access to certificates and private keys that are stored on a cryptographic token (e.g., a smart card).In order for webPDF to be able to work with this standard, the appropriate API for the cryptographic token must be installed.The configuration for the PKCS#11 interface can be found in the pkcs11.cfg file in the Configuration folder of webPDF. The possible settings are described under https://docs.oracle.com/javase/8/docs/technotes/guides/security/p11guide.html in section "2.2 Configuration".
Information about PKCS#11: https://docs.oracle.com/javase/8/docs/technotes/guides/security/p11guide.html
Windows keystores
On Windows systems, the certificate store for user and (local) computer certificates is also supported. Before use, the certificate must be imported into the certificate store together with the private key. Both must be stored in the certificate store under Personal -> Certificates.
If the certificates are stored in the Windows certificate store, it is important to ensure that the private key is stored along with the certificate.
In the keystore configuration, when running on Windows, the two certificate stores are displayed as
– Windows Personal User Certificate Store and
– Windows Personal Computer Certificate Store
If one of these certificate stores is selected, the server searches for the requested certificate in the Personal -> Certificates area.
If the Windows Computer Certificate Store is used, the server must be run with an account that has the corresponding authorizations. This is the case, for example, if the server is run as a service and is run with a Windows Service Account.
Keystore configuration
Select Server -> Keystore from the toolbar of the Admin Portal. In the dialog box, select the type of keystore via Keystore type and you can upload or configure a corresponding file (see image).
The signature service of webPDF cannot be used without this configuration. The key store must contain at least one valid X.509 certificate with its private key. The keystore can be password-protected. The password for the keystore has to be defined in the configuration.
Certificates (and corresponding keystores, as the case may be) are provided by a public Certificate Authority (Certificate Authority; CA).
You can find a tool for creating and editing keystores at: https://keystore-explorer.org/ or https://hohnstaedt.de/xca/. Please note that we do not provide any support for questions arising from the use of this tool. Our support covers webPDF itself only.
The certificate in the key store is selected when the web service is called.
When the server is started, the keystore and all the certificates it contains are loaded. The signature web service can only be used if the keystore has been successfully loaded and activated.
Only certificates for which a private key is available can be used.
Automatic keystore with "self-signed certificate"
You do not have to create a keystore to test the webPDF signature service. If the configuration does not contain a keystore, webPDF will automatically create a certificate (self signed certificate) and a private key when the server is started. This certificate, however, will only be available temporarily (while the server is running) and therefore cannot be validated (see message in the screenshot).
If you want to use a permanent certificate, then you have to provide the server with a keystore, as described above.