Configuration Folder
The configuration folder is represented by the physical path "esign-home/config" and is as the name suggests the folder containing the configuration files. The configuration folder currently contains two files:
-
The log4j2.xml file that is responsible for the configuration of log4j which allows to set debug levels, patterns and any other log4j available configuration, using the "${log-path}" expression in these files will convert to the esign-home/logs physical path.
-
The esign.config file that is responsible for eSign’s configuration explained with further detail below.
esign.config
The esign.config file is essential for eSign to work and is the base of all eSign’s configuration. Although eSign can function properly with only its defaults it should never be used in its default state in production environments as it is unsafe and lacks proper repository configuration (all stored in text files by default).
Although the file is being monitored for changes as to update configurations during runtime, only the properties can be updated without requiring a server restart. |
{
"version" : 1.0,
"_comment" : "List all the server side configurations",
"configurators" :
[
{
"enabled" : boolean,
"class" : String,
"params" : {
"param" : value
}
}
],
"_comment" : "List all the extensions to be used",
"extensions" : [
{
"name" : String,
"class" : String,
"params" : [
{
"param" : value
}
]
}
],
"_comment" : "List all the modules to be used",
"modules" : [
{
"type" : String,
"extension" : String
}
],
"_comment" : "List all the default addins to be used",
"addins" : [
{
"enabled" : boolean,
"type" : String,
"extension" : String
}
],
"_comment" : "List of TSA services by provider",
"tsa" : [
{
"provider" : String,
"url": String,
"user" : String,
"pass" : String
}
],
"_comment" : "Various configurations of the server side",
"properties":
{
"property": value
}
}
|
Configurators
The configurators object is used to point eSign to an external configuration source, i.e. an external database.
As for the values that can be set, there is the enabled parameter and the params parameter that is a simple Map<String,String> and is passed to the class when calling its constructor. As per the following table, there is also the class parameter that must point to a class that extends the ConfigurationSource abstract class (made available in the eSignToolkit).
Parameter | Type | Description |
---|---|---|
enabled |
boolean |
An on and off switch for the configurator object where the values true and false define, respectively, if the configurator is used or not. |
class |
String |
The qualified name of the target class that extends the ConfigurationSource abstract class |
params |
Map<String,String> |
A map of parameters to be received by the class during its initialization. Each parameter would be defined by a name: value pair, an example of a params object would be: "params" : { "endpoint" : "mylocalbd:8098/sql/configurator", "user" : "esign", "pass" : "${enc:hsaddb67346sdfby67fg7w}" } |
Extensions
Extensions can be used to complement or alter the behaviour of the many services made available by eSign. Extensions are classes that implement the interfaces exposed by the Add-ins API.
As for the values to be configured in the esign.config file, the table below explains what each field represents and what values it expects to receive.
Parameter | Type | Description |
---|---|---|
enabled |
boolean |
An on and off switch for the configurator object where the values true and false define, respectively, if the configurator is used or not. |
name |
String |
A identifier that pair this extension to a given functionality on the modules object. |
class |
String |
The qualified name of the target class that extends the IAddin interface |
params |
Map<String,String> |
A map of parameters to be received by the class during its initialization. Each parameter would be defined by a name: value pair, an example of a params object would be: "params" : { "key" : "${enc:hjeduy746hb67fy32rg8g26e23g7d62}"", "endpoint" : "CreatedDocsRepo.com/uploadDoc" } |
Modules
Modules are components that handle eSign’s core functionalities such as engines, repositories, etc. The current available modules are:
Module | Default | Description |
---|---|---|
License Repository |
DummyLicenseRepository |
The repository responsible for license storage. The default, DummyLicenseRepository, is as the name suggests, a repository that does nothing. |
Statistics Repository |
DefaultStatisticsRepository |
The DefaultStatisticsRepository is a file system based implementation and is therefore not suited for production environments. |
Artifact Repository |
FileSystemRepository |
The FileSystemRepository is a file system based implementation and is therefore not suited for production environments |
Signature Repository |
FileSystemRepository |
The FileSystemRepository is a file system based implementation and is therefore not suited for production environments. |
PDF Engine |
iTextEditor |
The module responsible for editing the PDF documents. iTextEditor performs PDF operations using the iText java engine. |
Auditor |
NoAuditor |
The module responsible for managing the auditioning of document accesses and edits. NoAuditor is a dummy class that performs no actions whatsoever. |
As for the values to be configured in the esign.config file, the table below explains what each field represents and what values it expects to receive.
Value | Type | Description |
---|---|---|
enabled |
boolean |
An on and off switch for the configurator object where the values true and false define, respectively, if the configurator is used or not. |
extension |
String |
The indentifier that links this module to a given extension. |
type |
String |
The type as refered in the table above, some of the possible values are: * LICENSE_REPOSITORY * STATISTICS_REPOSITORY * ARTIFACT_REPOSITORY |
Add-ins
Add-ins are extensions that are associated to the default behaviours of eSign’s services. An example would be setting an extension that sends and email with the submitted documents annexed to the interested parties as the artifact_submit add-in. Doing so would define this as the default behaviour whenever a document is submitted.
As for the values to be configured in the esign.config file, the table below explains what each field represents and what values it expects to receive.
Value | Type | Description |
---|---|---|
enabled |
boolean |
An on and off switch for the configurator object where the values true and false define, respectively, if the configurator is used or not. |
extension |
String |
The identifier that links this add-in to a given extension. |
type |
String |
The type of the add-in, the type defines which service is to be customized. The Add-ins API allows for the following add-in types: * artifact_create * artifact_status * artifact_submit * artifact_sign_method * artifact_signing * artifact_access * artifact_audit * session_listener * session_authentication * template_load * pdf_signature_text * qr_code_text * artifact_otp |
TSA
So as to keep documents legal over long periods of time (e.g. long-term validation LTV) or just to keep a timestamped audit of the document, timestamp authorities can be used.
Most timestamp authorities charge for the timestamp service, the integrating party is responsible to use this feature wisely. We recommend using a free timestamp service when making the first development tests to prevent unexpected expenses. |
As for the values to be configured in the esign.config file, the table below explains what each field represents and what values it expects to receive.
Value | Type | Description |
---|---|---|
provider |
String |
The TSA’s provider name, it should be the same as the one in the TSA’s provided certificate. If set to the value "default" the TSA will be used in all timestamp operations by default. |
url |
String |
TSA’s service url where the timestamps are to be fetched. |
user |
String |
The username for the timestamp service authentication purposes. |
pass |
String |
The password for the timestamp service authentication purposes. |
Properties
Properties are used to customize a wide variety of eSign’s configurations (e.g. handwritten signature stroke width or server’s base url), these configurations will be listed and described in the table below.
Property | Type | Description |
---|---|---|
database.autodeploy |
Boolean |
Determines if esign will automatically install the required database scripts. Default value: true |
database.dialect |
String |
Represents the type of database used in hibernate to generate SQL statements for a particular relational database. Default value: null (reverts to H2) |
database.driver |
String |
The JDBC driver name Default value: null (reverts to H2) |
database.url |
String |
The JDBC connection url Default value: null (reverts to in-memeory H2) |
database.user |
String |
Database username Default value: null (reverts to H2 default) |
database.password |
String |
Database password Default value: null (reverts to H2 default) |
database.pool.minimumIdle |
Integer |
Minimum number of idle connections maintained in the pool Default value: (same as maximumPoolSize) |
database.pool.maximumPoolSize |
Integer |
Maximum size that the connection pool is allowed to reach Default value: 10 |
database.pool.idleTimeout |
Integer |
Maximum amount of time that a connection is allowed to sit idle in the pool (ms) Default value: 600000 |
database.pool.connectionTimeout |
Integer |
Maximum time eSign will wait for a connection from the pool (ms) Default value: 30000 |
database.custom.* |
* |
@Since: 1.11.1 You may add as many entries as you wish. |
extensions.scanner.packages |
List |
@Since: 1.11.0 Default value: null |
logging.body.filter |
List |
@Since: 1.10.5 Default value: null |
signing.revocation.skip |
String |
Defines the signing methods that skip the certificate revocation step while signing a document. Also the "ALL" value whitelists all methods. Default value: "" |
signing.hashAlgorithm |
String |
The name of the algorithm used for hash computation, e.g. "SHA256" signing.signAlgorithm String The name of the algorithm used for signing, e.g. "SHA256withRSA" Default value: "SHA256" |
signing.reason |
String |
The reason/message to display in the signature’s watermark. Default value: "Assinatura Digital de Documento" |
signing.location |
String |
Displays the location specified value in the signature’s watermark Default value: "Celfocus Headquarters" |
signing.sessionTimeout |
Integer |
A number that defines the signature session timeout in milliseconds. Default value: 60000 |
signing.tsa.timeout |
Integer |
A number that defines the tsa signing timeout in milliseconds. Default value: 5000 |
signing.ocsp.timeout |
Integer |
A number that defines the ocsp verification timeout in milliseconds. Default value: 5000 |
signing.crl.timeout |
Integer |
A number that defines the session timeout in milliseconds. Default value: 5000 |
signing.crl.embed |
Boolean |
If the qualified certificate (used for signing) revocation status is checked using its Certificate Revocation List (CRL), this CRL will be embed in the signature if the property is set to true. Default value: true |
signing.signmethods |
String |
Sets the allowed signing methods (separated by commas), e.g. "HANDWRITTEN,SMARTCARD,CLICKTOSIGN,OTP,TRANSCRIPTION" Default value: "HANDWRITTEN,SMARTCARD,CLICKTOSIGN,OTP,TRANSCRIPTION" |
signing.signmethods.tsa |
String |
Sets which methods are signed along with a timestamp Default value: "HANDWRITTEN,SMARTCARD,CLICKTOSIGN,OTP" |
signing.signmethods.hidden |
String |
Specifies the methods to be hidden, i.e. the signing methods that are not to be used as default signing options in the documents. Documents will only allow for hidden methods if these are requested during document creation (see subsection Create document). Default value: "TRANSCRIPTION,OTP" |
signing.html5.enabled |
Boolean |
Enables signing with an html5 based canvas. This should not be used in production environments as it registers no pressure and low quantity of points and therefore not acceptable in legal terms. Default value: |
signing.issuer.validation |
Boolean |
Enables the server-side verification of the "signature.qualified.issuers" property. Default value: true |
signing.qualified.validation |
Boolean |
Enables the server-side verification that checks if the certificate used for the signature is qualified or not. Default value: true |
plugin.handwritten.licensekey |
String |
The path to eSign’s signature plugin license file. Default value: "${resources}/pluginLicense.key" |
plugin.support.browsers |
String |
The browsers that the plugin supports, i.e. "IE,Firefox,Edge" Default value: "IE,Firefox,Edge" |
plugin.support.mobile |
Boolean |
Set to true if the plugin supports mobile devices and set to false otherwise. Default value: false |
session.timeout |
Integer |
Sets the timeout of the sessions, i.e. every session will last at most the specified amount in milliseconds Default value: 60000 |
session.brand |
String |
Sets the default brand to be applied in the UI and documents. Default value: "default" |
session.imageFormat |
String |
The format of the signature images, e.g. "png" The default format is gif. Default value: "png" |
session.signImageScale |
Double |
Scales the signature image by the given multiplier factor. Bigger scales increase the image quality but decrease performance. Default value: 2 |
session.qr |
Boolean |
Toggles the qr code when opening the document in the viewer. Default value: false |
session.oauth.providers |
List |
Defines the allowed OAuth providers, e.g. ["google","facebook"]. The specified providers must match the value returned by the method getName. Default value: |
session.saml2.providers |
List |
Defines the allowed Saml2 SSO providers, e.g. ["AuthGovSaml","OpenAMSaml"] The specified providers must match the value returned by the method getName. Default value: [] |
session.close.delay |
Integer |
Defines the lifetime of a session after the last participant left (only affects viewer sessions) in milliseconds Default value: 0 |
session.close.consumer.recurrence |
Integer |
Defines the frequency the consumer thread will check on the sessions to be closed in milliseconds. If the value is 0 then it does it every session.close.delay/2 milliseconds. Default value: 0 |
session.close.consumer.delay |
Integer |
Defines the delay to startup the consumer thread in milliseconds. Default value: 0 |
signature.handwritten.complexity |
Integer |
The minimum amount of collected points per signature, a signature with less points that the specified value Default value: 80 |
signature.handwritten.color |
String |
The hexadecimal RGB code for the handwritten signature’s stroke Default value: "000040" |
signature.handwritten.stroke |
Double |
The width of the signature’s stroke Default value: 5 |
signature.handwritten.pressure.max |
Double |
The maximum value of pressure to be accepted while creating signature images. Any value above the maximum value will be set to the max value instead. (The stored biometrics remain unaltered) Default value: 1.0 |
signature.handwritten.pressure.min |
Double |
The minimum value of pressure to be accepted while creating signature images. Any value above the minimum value will be set to the min value instead. (The stored biometrics remain unaltered) Default value: 0.35 |
signature.handwritten.biometrics |
List |
All the specified signing methods (e.g."HANDWRITTEN") will have their associated biometrics embedded in the document. Default value: ["HANDWRITTEN"] |
signature.handwritten.window.height |
Integer |
The height in pixels of the signature popup window. Default value: 250 |
signature.handwritten.minimum.height |
Integer |
The minimum height in pixels for the display of the signature (i.e. if the signature has only 30px height and the minimum value is of 40px the distance between the points will be stretched as to fit either the minimum signature size or the height of the signed field) Default value: 30 |
signature.handwritten.maximum.size |
Integer |
If the image height or width is greater than this value then the image will be scaled down. Default value: 1000 |
signature.scale |
Double |
Scales the signature image by the given multiplier factor. Bigger scales increase the image quality but decrease performance. Default value: 2.0 |
signature.publickey |
String |
@Deprecated since: 1.11.4 (use Default value: null |
signature.publickey.data |
String |
@Since: 1.11.4 Default value: null |
signature.include.watermark |
Array <string> |
The methods that include a watermark in the signature, e.g. ["SMARTCARD", "CLICKTOSIGN", "OTP"] Default value: null |
signature.exclude.watermark |
Array <string> |
The methods should not include a watermark in the signature, e.g. ["HANDWRITTEN", "TRANSCRIPTION"] Default value: ["HANDWRITTEN", "TRANSCRIPTION"] |
signature.watermark |
String |
The path to the image to use as watermark base Default value: "watermark/logo_small.png" |
signature.watermark.smartcard |
String |
The path to the image to use as watermark base when signing with smartcards |
signature.watermark.otp |
String |
The path to the image to use as watermark base when signing with one-time passwords |
signature.watermark.export |
String |
The path to the image to use as exported watermarks Default value: "watermark/logo_small.png" |
signature.watermark.opacity |
Double |
The opacity factor for watermarks Default value: "0.5" |
signature.qualified.issuers |
String |
A regex expression to filter the qualified certificates that can be used to perform signing actions. Default value: [".+"] |
signatures.list.max |
Integer |
The maximum number of signatures retrieved by the search signature method. Default value: 10 |
signature.qualified.allowed.types |
String |
The type of certificates to be allowed for smartcard signatures. The possible values are, "SIGN","AUTHENTICATION","ALL" Default value: SIGN |
pdf.annotations.title |
String |
@Since: 1.10.5 Any other value, or null, will fallback to USERNAME. Default value: USERNAME |
pdf.defaultReadonly |
String |
Sets the default read only state for each pdf field, the accepted values are "true","false" or "inherit" A read only field is as the name suggests a field that can be seen but not edited. Default value: "true" |
pdf.defaultMandatory |
String |
Sets the default mandatory state for each pdf field, the accepted values are "true","false" or "inherit. A mandatory field is a field that needs to be filled for the document to reach a submitable state. Default value: "inherit" |
pdf.defaultIgnore |
String |
Sets the default ignore state for each pdf field, the accepted values are "true","false" or "inherit". Default value: false |
pdf.checkboxFormat |
Integer |
Defines the style of the checkbox fields. The accepted values are: 1. CHECK 2. CIRCLE 3. CROSS 4. DIAMOND 5. SQUARE 6. STAR Default value: "1" |
pdf.js.reject |
Boolean |
Defines if documents are rejected by the create service if they have embedded Javascript. Default value: true |
pdf.include.font |
String |
List of font names that must not be removed from the shrinked version of the document sent to the viewer. Use this property if fonts displayed in the frontend differ from the ones in the actual pdf document. Default value: null |
pdf.validation.truststore.keyPath.CA |
String |
The path to the CA (Certificate Authorities) certificate trust store pdf.validation.truststore.keyPath.TSA String The path to the TSA (Time Stamp Authorities) certificate trust store Default value: "${resources}/stores/trustedStore_CA.jks" |
pdf.validation.truststore.keyPath.TLS |
String |
The path to the TSL (Trust-Service Status List) certificate trust store Default value: "${resources}/stores/trustedStore_TLS.jks" |
pdf.validation.truststore.keyPath.INTERNAL |
String |
The path to the Internal certificate trust store Default value: "${resources}/stores/trustedStore_INTERNAL.jks" |
pdf.validation.truststore.keyType |
String |
The expected type of keystore (i.e. extension of keystore file), e.g. "JKS" Default value: "JKS" |
pdf.validation.truststore.keyPass |
String |
The password to access the keystore Default value: "$\{enc:KnEeDuH4pen9hx7XWxpbIw==}" |
pdf.validation.errorlevel.notsa |
String |
The log level of the TSA related errors, e.g. "WARNING", "ERROR". Default value: "WARNING" |
pdf.validation.ocsp.tolerance |
Long |
Provides some tolerance when checking if a signature is within the lastUpdate and nextUptate values of an embedded OCSP response. Default value: 5000 |
pdf.validation.oids.enabled |
Boolean |
@Since: 1.10.13 Default value: true |
pdf.validation.oids.keys.values |
List |
@Since: 1.10.13 Default value: [] |
trustcertificateprovider.check.revoked |
Boolean |
If true the certificate provider will check if the certificates have been revoked. Default value: false |
trustcertificateprovider.timeout.connect |
Integer |
Sets the timeout in milliseconds for when trying to connect to the certificate endpoint Default value: 300000 |
trustcertificateprovider.timeout.read |
Integer |
Sets the timeout in milliseconds for when trying to read the certificate endpoint’s response Default value: 300000 |
pdf.barcode.x |
Integer |
The default position for barcodes in the x axis Default value: 535 |
pdf.barcode.y |
Integer |
The default position for barcodes in the y axis Default value: 715 |
pdf.barcode.width |
Integer |
The default width of the barcode Default value: 65 |
pdf.barcode.height |
Integer |
The default height of the barcode Default value: 65 |
pdf.barcode.imageFormat |
String |
The image format in which the barcode will be encoded, e.g. "png" or "gif" Default value: "png" |
pdf.image.dpi.max |
Integer |
Maximum dpi when converting pdf to image. Default value: 300 |
pdf.shrinker.remove.hyperlinks |
Boolean |
@Since: 1.11.2 Default value: true |
artifact.audit.protected |
Boolean |
If set to true the audit will be converted to base64 before being embedded in the documents. Default value: false |
artifact.sign.initialize |
Boolean |
If set to true, the document will be signed right after its creation. This is useful to flag any kind of tampering of the base document after it is generated. Default value: false |
artifact.sign.initialize.tsa |
Boolean |
If set to true, the document will be signed with a time stamp right after its creation. This is useful to flag any kind of tampering of the base document after it is generated. Default value: false |
artifact.sign.finalize |
Boolean |
If set to true, the document will be signed right after it is submitted. This would prevent any kind of tampering after the document is submitted. Default value: false |
artifact.sign.finalize.tsa |
Boolean |
If set to true, the document will be signed with a time stamp right after it is submitted. This would help to flag any kind of tampering after the document is submitted. Default value: false |
artifact.sign.finalize.lock |
Boolean |
@Since: 1.11.3 Default value: true |
artifact.disposable.default |
Boolean |
Defines if the document is to be persisted in the repository. A disposable or non persistable artifact will be deleted from the repository. Once its session loses all participants the document will cease to exist from eSign’s context and will not be recoverable by any mean. Default value: false |
artifact.autoremove |
Boolean |
Defines if documents should be deleted from the repository after submission. Default value: false |
bookmark.interactable |
Boolean |
If set to false, all interactions with the bookmarks side bar are disabled. Default value: true |
analytics.threads.number |
Integer |
The starting number of threads for the Analytics task consumer Default value: 1 |
analytics.threads.max |
Integer |
The maximum number of analytics threads Default value: 10 |
analytics.threads.keep.alive |
Double |
The maximum age in ms of a thread Default value: 30000.0 |
server.crl.caching |
boolean |
Enables or disables the caching of crl responses of the validated certificates. Default value: true |
server.images |
String |
Defines the path to the folder where images are stored. Any path of an image that is fetched by other resources (e.g. watermarks) will have this string as a prefix. Default value: "${resources}/images" |
server.authenticate.viewer |
Boolean |
Enables or disables the authentication step when accessing the viewer. Default value: true |
server.authenticate.services |
Boolean |
Setting this value to true or false respectively enables or disables the authentication step when accessing eSign’s services. Default value: true |
server.authenticate.monitor |
Boolean |
Setting this value to true or false respectively enables or disables the authentication step when accessing eSign’s monitor page. Default value: true |
server.authenticate.monitor.class |
String |
The qualified name of the class that implements the authentication for eSign’s monitor page. Default value: "novabase.connect.paperless.esign.core.extensions.impl.BasicAuthenticationAddin" |
server.authenticate.selfservice |
Boolean |
Setting this value to true or false respectively enables or disables the authentication step when accessing eSign’s self-service. Default value: true |
server.viewer |
Boolean |
Setting this value to true or false respectively enables or disables eSign’s viewer. Default value: true |
server.viewer.menubuttons.hidden |
List |
@Since: 1.10.5 Default value: [] |
server.viewer.clicktosign.confirm |
Boolean |
@Since: 1.10.5 Default value: false |
server.services |
Boolean |
Setting this value to true or false respectively enables or disables eSign’s services. Default value: true |
server.monitor |
Boolean |
Setting this value to true or false respectively enables or disables eSign’s monitor page. Default value: false |
server.selfservice |
Boolean |
Setting this value to true or false respectively enables or disables eSign’s self-service. Default value: false |
server.baseurl |
String |
Sets the base URL returned by the services' responses. Note that forward dashes must be included in the value. An example of the field URL in a create document response would be: "url": "{prefix}{baseurl}?session=doc_session" |
server.prefixurl |
String |
Sets the prefix of the URL returned by the services' responses. Note that forward dashes must be included in the value. An example of the field URL in a create document response would be: "url": "{prefix}{baseurl}?session=doc_session" |
server.domain |
String |
Changes the domain of eSign’s viewer using the javascript code: "document.domain = {value};" This is a cross domain workaround to facilitate eSign’s integration in pages of different domains. server.language String Sets which locale file to use by default, more details at the locale subsection Locale Default value: "/eSignServer/" |
server.language |
String |
The server language Default value: "en-US" |
server.language.force |
Boolean |
Enforces the default language (server.language) regardless of the client’s browser language. Default value: false |
server.viewer.errordetails.show |
Boolean |
Determines if the server-side error message should be presented in the frontend error pop-up (when a error occurs). If disabled, only the generic client-friendly error message will be presented. Default value: true |
server.viewer.errordetails.show |
Boolean |
Determines if the server-side error message should be presented in the frontend error pop-up (when a error occurs). If disabled, only the generic client-friendly error message will be presented. Default value: true |
server.viewer.ie11 |
Boolean |
@Since: 1.11.0 Default value: false |
server.viewer.ie11.force |
Boolean |
@Since: 1.11.0 Default value: false |