EzSign Properties
The server’s configuration is contained within a properties file. The properties file must be passed to the server (as a parameter) at start up. The server loads the properties and waits for client requests
Essentially the properties file contains information about the IP Addresses and Ports to listen on, the key store location, logging settings and channel configurations. These are contained in a single properties file. The description below breaks out the sections for easier reading
Click here to view a sample properties file
Server Properties
The following settings dictate what ports and interfaces the server listens on and other settings that are relevant to the running server, rather than individual channels
| Property | Description | Example |
|---|---|---|
| server.bindIpAddress | The interface/IP Address the server will bind to. If omitted the server will listen on all available interfaces | 10.100.15.32 |
| server.port | The port the server will listen on | 5656 |
| server.allowedSourceIpAddresses | A comma separated list of IP Addresses which can connect to the server. If omitted any client can connect | 10.100.15.40,10.100.15.41 |
| server.threadPoolSize | The pool size that will be created at start up and used to process requests. If omitted, defaults to 1 | 5 |
| server.waitTimeoutIfAllBusy | The maximum time to wait for a thread to become free. If all instances in the thread pool are busy the server will wait this number of milliseconds before returning an error. If omitted, defaults to 1000 (i.e. 1 second) | 1000 |
| server.waitForMessageTimeout | The maximum time to wait for a message to be sent following connection. This should be increased if there are connection issues under load. If omitted, defaults to 1000 (i.e. 1 second) | 1000 |
| server.logMessages | If false, the received and sent messages will not be logged. If encrypting sensitive data, set this to false to prevent cleartext being sent to the log file. If omitted defaults to true | true |
| server.ctrl.bindIpAddress | The interface/IP Address the control server will bind to. If omitted the server will listen on all available interfaces | 127.0.0.1 |
| server.ctrl.port | The port the control server will listen on | 5657 |
| server.ctrl.allowedSourceIpAddresses | A comma separated list of IP Addresses which can connect to the control server. If omitted no client can connect | 10.100.15.40,10.100.15.41 |
| server.ctrl.logStatusMessages | By default the server will log every status request message sent to the control interface. If regular monitoring is in place this can fill logs. Set this value to false to switch off this logging. Defaults to true | true |
| server.authCode | The passphrase used to encrypt messages between the client and server. If set the client must pass the same string to the constructor. If not set, messages will be sent in the clear (which may be OK if client and server are on the same machine or using a private network) | x55tHH#ih65W |
| keyStoreDir | The folder beneath which all channel key stores will be held | /opt/ezsign/STORE |
| log.level | The logging level. The range is from 0 to 4 as follows: 0: Logging is off, 1: Only error messages will be logged, 2: Errors and Warning messages will be logged, 3 : Errors, Warnings and Events will be logged, 4 : This is the debug level - all messages (as well as low level events) will be logged | 4 |
| tls.trustStore.type | If using TLS to communicate with an HSM (such as the payShield) and you are supplying a custom trust store, this specifies the trust store type. Options are jks or pkcs12 | jks |
| tls.trustStore.filename | The full path to the truststore file | /opt/stores/payshield.jks |
| tls.trustStore.password | The encrypted password that protects the trust store. Use the Management Utility to set this password | yjjWoLfE…Zlew== |
| tls.clientKeyStore.type | If using TLS to communicate with an HSM (such as the payShield) and a client TLS certificate is required, this specifies the client store type. Options are jks or pkcs12 | pkcs12 |
| tls.clientKeyStore.filename | The full path to the client keystore file | /opt/stores/client.jks |
| tls.clientKeyStore.password | The encrypted password that protects the client key store. Use the Management Utility to set this password | FGchg3Kv…Ycsg== |
Generic Channel Properties
The properties file may have multiple channels specified. Each channel must have a number assigned e.g.
channel.1.name=CHANNEL1
channel.1.type=PKI
...
channel.2.name=CHANNEL2
channel.2.type=SYM
...
channel.3.name=AnotherChannel
...
This number is represented by N in the following sections. There is no limit on the number of channels
| Property | Description | Example |
|---|---|---|
| channel.N.name | The name of the channel. This will also be used as the folder name where the keys and certificates for this channel will be stored | CHAN1 |
| channel.N.type | The channel type: PKI or SYM. PKI channels can perform signature generation and verification SYM (symmetric) channels can perform encryption or decryption | PKI |
| channel.N.enabled | If false, the channel is disabled and will not be loaded. If missing, defaults to true | true |
| channel.N.tokenType | The token type: SOFTWARE, PKCS11, PAYSHIELD (or HSM9000), GOOGLEKMS, AZUREKEYVAULT | SOFTWARE |
| channel.N.token.password | The token password required for all token types and will be used to encrypt key store objects. This must be set by running the ezsign-manange script. If tokenType=PKCS11 this is the PIN or Passphrase. For nCipher devices this will be the operator smartcard passphrase | zijFhJ….vA== |
| channel.N.defaultKeyLabel | Relates to symmetric channels only (type=SYM). Specifies the default AES key label to use if none is passed to the client | key1 |
| channel.N.saveObjectsToDisk | If this is true, files will not be written to the keystore folder. Use this option if you are passing properties to EzSign and managing key storage externally e.g. in a database | true |
PKCS11 Token Properties
If channel.N.tokenType=PKCS11 is set then the following properties must also be configured. These are specific to the HSM being used and its configuration
| Property | Description | Example |
|---|---|---|
| channel.N.token.useModuleProtection | If an HSM normally requires a password to logon (such as some PKCS#11 tokens). This can be overridden by setting this value to true. This means the HSM will not be logged on to and only the module’s keys will be used (rather than an operator card set etc) | false |
| channel.N.token.pkcs11.library | The full path to the PKCS11 library | /opt/nfast/toolkits/p11/ibcknfast.so |
| channel.N.token.pkcs11.slot | The PKCS11 slot number | 0 |
| channel.N.token.pkcs11.model | The particular HSM model. Options are: Generic, NCipher, Luna, AWSCloudHSM, Utimaco, YubiHSM, Custom | Utimaco |
| channel.N.token.pkcs11.customTemplateClass | If the model above is Custom, then the class containing the customised templates must be specified here. See here for more details. Version 4.2.1 onwards | NewHsmTemplates |
GoogleKMS Token Properties
If channel.N.tokenType=GOOGLEKMS is set then the following properties must also be configured. You will obtain these from your Google KMS configuration
| Property | Description | Example |
|---|---|---|
| channel.N.token.googleKms.project | The ID of the project as created in the Google Cloud Console. For full details on the setup for Google KMS refer to the specific tech note | ezsign |
| channel.N.token.googleKms.location | The location of the key ring e.g. europe-west2 | global |
| channel.N.token.googleKms.keyRing | The name of the key ring | ezsignkeys |
| channel.N.token.googleKms.credentialFile | The JSON file containing the private key associated with the service account with permissions to the KMS | /opt/google/googlekms.json |
| channel.N.token.googleKms.jsonCredentialString | The raw JSON text provided as a string (rather than a file as above). Note: supply one of jsonCredentialString or credentialFile. If both are provided credentialFile takes priority | { “type”: “service_account”, “project_id”: “pkcloud”….} |
| channel.N.token.googleKms.keyImportVersion | If using imported keys that are not at version 1 set this to the version of the keys you use to be imported | 1 |
Azure KeyVault Token Properties
If channel.N.tokenType=AZUREKEYVAULT is set then the following properties must also be configured. Refer to your Azure KeyVault configuration for details
| Property | Description | Example |
|---|---|---|
| channel.N.token.azureKeyVault.clientId | The client ID as configured on the Azure platform | eb1739f5-6dd2-43b1-9bf7-266717a24cf4 |
| channel.N.token.azureKeyVault.tenantId | The Tenant ID as configured on the Azure platform | d12c3e45-350c-4413-2bb3-34514a35407c |
| channel.N.token.azureKeyVault.keyVault | The full DNS name of the Key Vault e.g. https://yourvault.vault.azure.net/ | https://yourvault.vault.azure.net/ |
PayShield Token Properties
If channel.N.tokenType=PAYSHIELD or HSM9000 then the following properties must also be configured.
Note properties named hsm9000 (e.g. channel.N.token.hsm9000.port) are still supported but all new properties will use the payShield name.
| Property | Description | Example |
|---|---|---|
| channel.N.token.payShield.ipAddress | The IP Address of the HSM9000 | 10.100.15.101 |
| channel.N.token.payShield.port | The port the HSM9000 listens on. Required if tokenType=HSM9000 | 1500 |
| channel.N.token.payShield.timeoutMs | The time to wait for a response from the HSM before failing. Required if tokenType=HSM9000 | 3000 |
| channel.N.token.payShield.headerLen | The HSM command header length. Required if tokenType=HSM9000 | 4 |
| channel.N.token.payShield.useVariantLmk | If the HSM has a variant LMK installed, set this to true. If not specified, defaults to false (meaning a KeyBlock LMK will be used). Ensure this matches against the lmkId and port numbers (that usually map to specific LMKs) | false |
| channel.N.token.payShield.lmkId | If the HSM has multiple LMKs loaded, set this to the LMK ID that you wish EzSign to use. Range 0-99. If not specified, the default LMK (as configured on the HSM) will be used | 0 |
| channel.N.token.payShield.useTls | Whether communications between the client and HSM are protected using TLS. Options are true or false. If true then the tls server properties must also be set to configure the client key store (and optionally the trust store). See Server Properties above. | false |
Signature Generation and Verification Properties
There are various options when generating and verifying signatures. The following settings also dictate what algorithms, key-sizes etc. that will be used when CSRs are generated
| Property | Description | Example |
|---|---|---|
| channel.N.signature.algorithm | The signature key algorithm. Possible values are: RSA and ECDSA. If RSA is chosen the keysize must also be specified. If elliptic curve (ECDSA) is chosen the curve must also be specified. See here for more details | RSA |
| channel.N.signature.keySize | The RSA key (modulus) size in bits (1024, 2048, 4096, 8192, 16384, 32768 | 2048 |
| channel.N.signature.ecc.curve | The named curve e.g. secp192r1, secp224r1, secp256r1, secp384r1, secp521r1 or any name supported by the version of java or HSM being used | secp256r1 |
| channel.N.signature.hash | The hash that will be generated over the data to be signed before signing. Possible values: SHA1, SHA256, SHA512, SHA3-224, SHA3-256, SHA3-384, SHA3-512 | SHA256 |
| channel.N.signature.type | The signature type to generate. Options are: PKCS7, RAW. If RAW is chosen the signature will be PKCS#1 formatted if RSA is chosen | PKCS7 |
| channel.N.signature.includeCerts | What certificates to include in the signature. Possible values: ALL – all certificates including the root will be included, ALLEXCEPTROOT – all certificates except the root will be included, SIGNERONLY – only the signer certificate will be included | ALLEXCEPTROOT |
| channel.N.signature.includeContent | Whether to include the content with the signature or not | false |
| channel.N.signature.includeSignedAttribs | If true signed attributes will be included in the signature including signing time, message digest and content type | true |
| channel.N.signature.keyId | The key which will be used to generate the signature. This can be set by running the ezsign-manange script | 15723e16cd89401 |
| channel.N.verify.pathCheckClass | To override the default path checker with a custom version, specify the path checker class here. This must be in the classpath. If omitted the default path check class is used | org.pathcheck.PathChecker |
| channel.N.verify.signedAttribsRequired | If true and signed attributes are not included in a signature being verified the signature will be rejected | true |
| channel.N.verify.denyWeakSignatureHash | If true, signatures will be rejected if they have not been generated with a SHA-2 or SHA-3 hash | false |
| channel.N.verify.denyWeakCertificateHash | If true, certificates will be rejected if they have not been generated with a SHA-2 or SHA-3 hash | false |
| channel.N.verify.relaxRootCertExtensionChecks | If true, none of the usual certificate extension checks will be performed on the root certificate (including, key usage, basic constraints or key size). Defaults to false | false |
| channel.N.verify.relaxAllCertExtensionChecks | If true, none of the usual certificate extension checks will be performed including key usage criticality, basic constraints or key size. Defaults to false | false |
| channel.N.verify.nonRepudiationRequired | If true, a signer certificate must have the non-repudiation key usage set. Defaults to true | true |
| channel.N.verify.caBasicConstraintsRequired | If true, a CA certificate must have basic constraints CA extension. Defaults to true | true |
| channel.N.verify.minKeySize | Sets the minimum permitted key size for all certificates in the chain. Defaults to 1024 | 2048 |
| channel.N.verify.maxKeySize | Sets the maximum permitted key size for all certificates in the chain. Defaults to 8192 | 8192 |
| channel.N.allowExpiredCerts | Whether to permit expired certificates. This MUST only be set to true in extreme circumstances (such as to maintain a live service) where other checks can be performed that ensure the certificate would otherwise still be valid | false |
| channel.N.allowExpiredCertsForDays | If allow ExpiredCerts=true then the number of days permitted to all an expired certificate for e.g. if set to 5 a certificate will be permitted for 5 days after it has expired | 5 |
Revocation Checker Properties
The revocation check options are configured with the following settings. If nothing is specified, no revocation checking will be performed
| Property | Description | Example |
|---|---|---|
| channel.N.revocationChecker.type | The revocation checker type. Possible values: NONE - No revocation checking will be performed. CRL - CRLs will be used to check revocation. OCSP - OCSP will be used to check revocation. ANY - OCSP will be tried first. If this fails (e.g. if there is no OCSP URL or if the server or status is unavailable) then CRL will be attempted | OCSP |
If NONE is chosen as the revocation checker, no further settings are required
If CRL is chosen, refer to the CRL Specific Properties below
If OCSP is chosen, refer to the OCSP Specific Properties below
If ANY is chosen, both the CRL and OCSP specific properties will be applied
OCSP Specific Properties
if revocationChecker.type=OCSP then the following settings can be applied
| Property | Description | Example |
|---|---|---|
| channel.N.revocationChecker.ocsp. connectTimeoutSecs | If revocationChecker.type=OCSP then this determines the OCSP Server connection timeout. Defaults to 5 seconds | 5 |
| channel.N.revocationChecker.ocsp. readTimeoutSecs | If revocationChecker.type=OCSP then this determines the OCSP Server read timeout. Defaults to 5 seconds | 5 |
| channel.N.revocationChecker.ocsp.useDefaultUrl | If revocationChecker.type=OCSP then this determines whether the default URL (which must be specified) will always be used or, if false, the certificate’s AIA extensions will be used to extract the OCSP URL | true |
| channel.N.revocationChecker.ocsp.defaultUrl | If useDefaultUrl is true the default URL must be specified in this property | https://ocsp.server.com |
| channel.N.revocationChecker.ocsp.signRequest | If true, the OCSP request will also be signed | true |
| channel.N.revocationChecker.ocsp.signingKeyId | if signRequest=true. The signing key used to sign the OCSP requests. This is set to the same key as the signature signing key | 15723e16cd89401 |
| channel.N.revocationChecker.ocsp.signatureHash | The hash used in the OCSP request signature generation. Used when signRequest=true. Possible values: SHA1, SHA224, SHA256, SHA384, SHA512 | SHA256 |
| channel.N.revocationChecker.ocsp.checkOcspSigningCertUsage | Whether to check the key usage on the certificate used to sign the OCSP response. If true, the certificate’s extended key usage will be checked for the ocsp-signing attribute | false |
| channel.N.revocationChecker.ocsp.maxProducedAtAgeMins | Revocation checking will fail if the time the OCSP was generated (indicated in the producedAt field) is more than this number of minutes in the past i.e. this is the maximum lifetime allowed for an OCSP response. If omitted this will not be checked | 4 |
| channel.N.revocationChecker.ocsp.onlyCheckEndEntity | If this is true, only the end-entity certificate will be checked for revocation i.e. none of the other certificates in the path (nor any OCSP signing certificates) will be checked | false |
| channel.N.revocationChecker.ocsp.relaxSigningPath | RFC 6960 requires that the issuer of the certificate being checked sign the OCSP request or this is performed by a certificate that it has issued. If the response is signed by another trusted certificate (e.g. a root CA issued certificate – as is often the case for IdenTrust responders), set this option to true | false |
| channel.N.revocationChecker.ocsp.ignoreSSLErrors | If true, when sending an OCSP request, if SSL/TLS is used and the SSL certificate is not specifically trusted, setting this to true will still permit the connection | false |
| channel.N.revocationChecker.ocsp.enableCache | Enable or disable OCSP response caching. Default is false | true |
| channel.N.revocationChecker.ocsp.cacheSeconds | If enableCache is true, this is the maximum time to cache an OCSP response in seconds. Default is 120 | 60 |
| channel.N.revocationChecker.ocsp.cacheCaCertsOnly | If true, only OCSP responses for CA certs will be cached i.e. end entities will always be checked. Default is true | true |
| channel.N.revocationChecker.ocsp.useProxy | Whether to send OCSP requests via a proxy. If true the other proxy settings are required | true |
| channel.N.revocationChecker.ocsp.proxyServer | If useProxy=true, this specifies the proxy server address | proxyserver |
| channel.N.revocationChecker.ocsp.proxyPort | If useProxy=true, this specifies the proxy server port | 8080 |
| channel.N.revocationChecker.ocsp.proxyAuthRequired | If useProxy=true and the server requires authentication set this to true and specify the username and password below | false |
| channel.N.revocationChecker.ocsp.proxyUsername | If proxyAuthRequired=true set the username here | user1 |
| channel.N.revocationChecker.ocsp.proxyPassword | If proxyAuthRequired=true set the password here | password |
CRL Specific Properties
if revocationChecker.type=CRL then the following settings can be applied
| Property | Description | Example |
|---|---|---|
| channel.N.revocationChecker.crl.downloadFolder | The location to which CRL files will be downloaded and stored | /opt/ezsign/crl |
| channel.N.revocationChecker.crl.forceDownload | Whether to force the download of the CRL for each request. | false |
| channel.N.revocationChecker.crl.allowExpiredCrl | Whether to allow expired CRLs or not Note: This MUST only be used in extreme circumstances e.g. a live service outage as a revoked certificate may be accepted | false |
| channel.N.revocationChecker.crl.allowExpiredCrlForDays | If allowExpiredCrl=true then the number of days expiry that will be permitted | 1 |
| channel.N.revocationChecker.crl.onlyCheckEndEntity | If this is true, only the end-entity certificate will be checked for revocation i.e. none of the other certificates in the path will be checked | false |
| channel.N.revocationChecker.crl.ignoreSSLErrors | If true, when sending an OCSP request, if SSL/TLS is used and the SSL certificate is not specifically trusted, setting this to true will still permit the connection | true |
| channel.N.revocationChecker.crl.useProxy | Whether to download CRLs via a proxy. If true the other proxy settings are required | false |
| channel.N.revocationChecker.crl.proxyServer | If useProxy=true, this specifies the proxy server address | proxyserver |
| channel.N.revocationChecker.crl.proxyPort | If useProxy=true, this specifies the proxy server port | 8080 |
| channel.N.revocationChecker.crl.proxyAuthRequired | If useProxy=true and the server requires authentication set this to true and specify the username and password below | true |
| channel.N.revocationChecker.crl.proxyUsername | If proxyAuthRequired=true set the username here | user2 |
| channel.N.revocationChecker.crl.proxyPassword | If proxyAuthRequired=true set the password here | password1 |