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.
esign.config file structure
{
    "version" : 1.0,
    "_comment": "List of all persistence related extensions",
    "persistences": {
		"filesystem": {
			"extensions": [
                {
                    "name" : String,
                    "class" : String,
                    "params" : {
                        "param" : value
                    }
                }
            ]
        },
        "hibernate" : {
            "extensions": [
                {
                    "name" : String,
                    "class" : String,
                    "params" : {
                        "param" : value
                    }
                }
            ]
        }
    },
    "_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
    }
}

  • Resources folder path - writing the path to "esign-home/resources" folders is facilitated with the ${resources} expression.

  • System variable values - ${sys:variable_name} allows for the access of system defined variables and their respective values.

  • Encoded values - the ${enc:value} expression allows for the insertion of obfuscated values as to provide an extra layer of protection on sensitive values. Values must be encoded using eSign’s obfuscate service.

  • Enabled - expects a Boolean value and is merely an on and off switch. It helps to turn features on or off without the hassle of adding or removing JSON entries from the file.

  • Class - receives a string equivalent to the qualified name of the targeted class.

  • Type - links a given module or add-in class to a particular type. For example, the ARTIFACT_REPOSITORY type maps the associated extension class as the implementation for the artifact repository.

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

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

Array<String>

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

Array<String>

Defines the allowed Saml2 SSO providers, e.g. ["AuthGovSaml","OpenAMSaml"] The specified providers must match the value returned by the method getName.

Default value: []

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

Array<string>

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

The path to the file containing the key that is used to sign the fields with biometrics, i.e. to digitally sign the signatures to avoid foul play and modifications.

Default value: "${resources}/DEV.esign.security.public.key"

signature.include.watermark

Array <string>

The methods that include a watermark in the signature, e.g. ["SMARTCARD", "CLICKTOSIGN", "OTP"]

Default value: ["SMARTCARD","CLICKTOSIGN","OTP"]

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. signature.qualified.allowed.types String The type of certificates to be allowed for smartcard signatures. The possible values are, "SIGN","AUTHENTICATION","ALL"

Default value: 10

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.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

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.shrinker.addAnnotations

Boolean

Set to true if annotations are to be included in the shrank versions of pdf. PDF to image properties

Default value: false

pdf.image.dpi.max

Integer

Maximum dpi when converting pdf to image.

Default value: 300

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.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.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