# Form.io E-Sign+ ## Introduction Form.io E-Sign+ is an enterprise-level digital signature module that enables the capture and verification of cryptographically secure signatures associated with submission data — all within your own environment and without relying on external signature services. E-Sign+, as a digital signature tool, is designed to confirm that the signed piece of data and its context (the form, custom properties, etc.) have not changed since it was signed. Key aspects of the E-Sign+ solution provided by Form.io: * **Zero-trust.** It exists entirely within the app, in your environment; you don't have to trust 3rd-party providers with your digital signatures. The digital signatures are stored in your database. * **API-driven**. You can access any signed data/form via API, using its native submission ID. * **Decoupled from PDFs**. E-Sign+ lets you take an immutable snapshot of data within your app without relying on PDFs (but still export to PDF if you need). * **Full control on E-Sign+ private key.** Signature data is stored in the database as a token signed with the private key provided by you. You can store your keys outside of the deployment (e.g. using AWS KMS) or set it as the Form.io enterprise server environment variable. * Sign using **any field type, any context**. Any input field can be used as a signature: checkbox, email, signature, text field and so on. Your signature can sign the whole form data or just a part of it. * **Customize the E-Sign+ stamp.** Use your custom templates for the E-Sign+ stamp. ## Licensing {% hint style="info" %} The E-Sign+ module is only available for self-hosted environments that have both Security Compliance Module and E-Sign+ enabled within their license configuration.\ \ Contact **** to acquire a License. {% endhint %} After E-Sign+ is enabled for the license key, the Signatures tab is available under the **Signatures** section in the navigation bar of any form.

## Enabling E-Sign+ E-Sign+ configuration is available after the form has the following settings enabled: 1. Submission Revisions 2. Form Revisions set to 'Use original form revisions when viewing submissions'. ## E-Sign+ Settings

To implement digital signatures in a form, first decide what form components will be used as signatures in the form. Different components can serve as a digital signature. To set a component as a digital signature: 1. Add the component(s) to the form. 2. Click **Add Digital Signature** to attach digital signature functionality to the desired components. A form can have one or more components that serve as digital signatures. ### **Digital Signature Component Settings** When a component is set to be a digital signature, the following settings are configurable:

* **Digital Signature Component** - The form component that will be used as a signature.\ The following components are selectable as the Digital Signature Component when present in a form:

Basic	Advanced	Data*	Premium
Text Field	Email	Container _{(child field)}	Data Source
Text Area	URL		File
Number	Phone Number
Password	Tags
Checkbox	Date & Time
Select Box	Day
Select (Must use HTML5)	Time
Radio	Currency
	Survey
	Signature

{% hint style="info" %} **Layout** and **Data** components cannot serve as the signature component; only the compatible fields within them can be selected. {% endhint %} * **Digital Signature Data** - Select the form components on which the data will be confirmed by the Digital Signature. If the signed value of these fields changes, the digital signature becomes invalid and the data is expected to sign again. * **Include all form data in Digital Signature** - When this setting is enabled, the Digital Signature will be responsible for all form data. If the value of some form component is changed, the digital signature will be invalid and the data is expected to sign again. * **Submission properties to include in Digital Signatures** - A comma separated path to the data inside the submission object that will be used for the digital signature verification.\ This setting selects the submission properties (except for submission data) that will invalidate the digital signature when they are changed. * **Enable editing of submission data within Digital Signatures** - By default, the signed data is disabled in the UI to protect it from modifications. Enable this setting to leave signed data enabled. * The **Templates** settings sets the default template of the digital signature stamp and tooltip. ## Templates The Templates settings enables users to customize UI for digital signature stamps and tooltips using the JavaScript [Lodash](https://lodash.com/docs/4.17.15#template) library. Several variables are available inside templates: | Variable | Description | | ------------------- | ------------------------------------------------------------------------------------------------------------ | | esign | The form.io Digital Signature object | | esignTooltip | The markup of the Digital Signature tooltip represented as a string (available only for the stamp template). | | esignInvalidMessage | The default message for invalid Digital Signature (available only for the stamp template). | | esignIconClass | The class of the Digital Signature default stamp icon (available only for the stamp template). | | pdfForm | Indicates whether the current form has a PDF display type. | | form | The complete form JSON object | | submission | The complete submission object. | | data | The complete submission data object. | | row | Contextual "row" data, used within DataGrid, EditGrid, and Container components | | component | The current component JSON | | instance | The current component instance. | | value | The current value of the component. | | moment | The moment.js library for date manipulation. | | \_ | An instance of [Lodash](https://lodash.com/docs/). | | utils | An instance of the [FormioUtils](/developers/javascript-development/javascript-utilities.md) object. | | util | An alias for "utils". | #### esign object The *esign* variable is available in both stamp and tooltip templates and contains main information about the Digital Signature. The *esign* object typically has the following properties: * *created* - the ISO formatted date of Digital Sigature creation; * *valid* - if Digital Signature is valid it has a true value, if not - the massage why Digital Signature is not valid; * *\_id* - Digital Signature ID; * *\_sid* - ID of the submission that contains this Digital Signature; * *signature* - the object with Digital Signature data that has the following properties: * *compPath* - path to Digital Signature component inside the form JSON; * *valuePath* - path to the value of the Digital Signature component in submission data; * *user* - the id and email of the user who signs the Digital Signature field; * *submission* - the submission revision object (without submission data) created together with Digital Signature. ### Digital Signature Stamp Template Example of a custom stamp template: ```html {% if (esign.valid === true) { %} Signed on {{new Date(esign.created).toLocaleString()}} {% } %} {% if (esign.valid !== true) { %} Invalid Digital Signature {% } %} ``` ***Tips**:* * To use a tooltip with your Digital Signature stamp, add the following attributes to some HTML element inside the stamp template: \ \&#xNAN;*`ref="esignTooltip" data-tooltip="{{esignTooltip}}.`* An example of this attribute inserted in a HTML is: ```html < ref="esignTooltip" style="cursor:poer" data-tooltip="{{esignTooltip}}" class='{{esignIconClass}}' aria-hidden='true'> ``` * To use a different stamp template for the form and printed PDF (when viewing the submission as a PDF), check if *instance.options.pdf* is true: ```html {% if (instance.options.pdf) { %} // stamp template for printed PDF {% } %} {% if (!instance.options.pdf) { %} // stamp template for the form {% } %} ``` * To use different stamp template to differntiate between valid and invalid Digital Signatures, check if *esign.valid* is equal to true or not: ```html {% if (esign.valid === true) { %} // stamp template for valid eSignature {% } %} {% if (esign.valid !== true) { %} // stamp template for invalid eSignatrue {% } %} ``` ### Digital Signature Tooltip Template The following code snippet provides an example of a custom tooltip template: ```html ``` ## E-Sign+ Cryptography E-Sign+ uses asymmetric cryptographic keys to sign and verify a snapshot of the data. The required key is supplied by the form builder. There are 2 ways to provide keys for E-Sign+ cryptographic operations: * Set `ESIGN_PRIVATE_KEY_FILE` variable for the form.io server deployment. This variable accepts a file path to your private key (e.g., `ESIGN_PRIVATE_KEY_FILE=/user/stuff/mykey.txt`).; * Add integration with third-party key management service (e.g. AWS KMS). ### ESIGN\_PRIVATE\_KEY\_FILE server variable The simplest way to provide keys for a digital signature is to set the following environment variables in your **formio/formio-enterprise** deployment: * `FORMIO_FEATURE_ESIGNATURE=true` — enables the E-Sign+ module. * `ESIGN_PRIVATE_KEY_FILE` — set to the file path of your private key (e.g., `ESIGN_PRIVATE_KEY_FILE=/user/stuff/mykey.txt`). It is not recommended to set the public key as an environment variable, as it can be easily extracted from the private key. {% hint style="info" %} Check the deployment documentation to know more about environment variables: {% endhint %} Requirements for a private key set to ESIGN\_PRIVATE\_KEY\_FILE: * Key type: RSA * Key size: 2048-bit * Public key: * type: 'spki' * format - 'pem'; * Private key: * type - 'pkcs8' * format - 'pem' An example of RSA2048 key generation using the *node*:*crypto* module: ```javascript const crypto = require('crypto'); const { privateKey } = crypto.generateKeyPair( 'rsa', { modulusLength: 2048, publicKeyEncoding: { type: 'spki', format: 'pem', }, privateKeyEncoding: { type: 'pkcs8', format: 'pem', }, } ); ``` ### Integration with Key Management Services (KMS) To use a third party provider to store and manage keys, add E-Sign+ integration settings on the project level. #### AWS KMS The E-Sign+ module can use AWS KMS API to sign and verify the digital signature data. To begin by creating an RSA2048 key available for 'sign and verify' operations in AWS KMS: 1. Log in to your AWS account; 2. Open **Services > Security, Identity, & Compliance > Key Management Service** 3. Click on the **Create a key** button on the main AWS KMS page\ or\ Select **Customer managed keys** on the left-hand sidebar, then click on the **Create a key** button on the top of the keys list:

5. Follow the key setup wizard to create your key.\ The step 1 key settings should resemble the following:

6. In the **Customer managed keys** list, open the key that was just created from the key list section and copy the Key ID:

7. Create an Access Key for your AWS account, and copy the Access Key ID and Secret Key.\ Check AWS documentation to create the access key for your account: Next, add AWS KMS integration settings to the Form.io project settings through the Developer Portal: 1. Open the intended project on the Form.io Developer Portal. 2. Open the project's **Settings,** and click **Digital Signature.** 3. Add the AWS KMS settings:

4. **Save** the project settings. From this point, the AWS KMS API will be used for the Digital Signature cryptographic operations for this project. ## Digital Signature Examples Create a new form and add components as shown in the example below:

This form is expected to have 3 signatures: * The signature of the purchase initiator, who is to fill in fields 1-3 and sign this data by adding the name in field 4. * The signature of the head of department, who approves the purchase in field 5. * The signature of the accountant who fills in the budget field and confirms it by adding a signature in field 7. #### Configure the example digital signature: Once the form described above has been created, configure the form settings as follows: 1. Enable submission revisions and original form revisions for the form:

2. From the toolbar, go to **Sign.** Click the **Add Digital Signature** button and configure Digital Signature for Field 4:

3. Click **Save**. 4. Repeat these steps to add Digital Signatures for Field 5 and Field 7, being sure to save them:

Digital Signature config for field 5 and 7

4. Save the Digital Signature settings by clicking on **Save Settings.**

To see the Digital Signatures in action: 1. Go to the **Use** tab, fill in fields 1-4 and submit the form. 2. Go tot he **Data** tab and open the submission that was just made. When viewing/editing this submission, note that the green digital signature stamp is displayed under field 4. This stamp confirms that the digital signature was created, and that neither the Digital Signature data (fields 1-4) nor the form have been changed since it was signed.\ \ Hovering the cursor above the signature stamp reveals the signature metadata.

3. Edit the submission. Note that fields 1-4, protected by the signature, are disabled. 4. Fill in field 5 and **Submit** the form. Note that a digital signature is created for field 5. 5. Fill in fields 6 and 7, then **Submit** the form. Note that digital signatures are created for all signature fields:

#### **Digital signature validation when editing of submission data within Digital Signatures is enabled** When the signed fields are not disabled from modification, digital signature data is validated on the client side. If some signed value is changed, digital signature becomes invalid and the signature field is cleared. That means the changed data is must be signed again. To see this in action: 1. Follow steps 1-2 from the previous example. 2. Open Digital Signature settings and enable **Enable editing of submission data within Digital Signatures.**\ Click the **Save Settings** button to save this change. 3. Sign the form following steps 3-5 from the previous example.\ Note that signed fields are not disabled and can be edited. 4. Edit the submission and change the quantity field from 1 to 2.\ As a consequence, the Digital Signatures for fields 4 and 5 become invalid and signature values are reset.

The digital signature for Field 7 is still valid, as it is only responsible for the data in field 6.\ If there is a change to Field 6, the Field 7 value will be cleared and the Digital Signature will become invalid. These fields will need to be signed again and new Digital Signatures will be created for the form. ## Digital signature and PDF ### PDF-First Form Digital signatures with PDF-first forms function in the same way as with web forms. ### PDF View of Webform Submissions The PDF of the webform submission on a form that contains digital signatures will display a digital signature stamp on any signed fields. ## Render digital signatures in an application Use **@formio/esignature** module to render digital signatures in an application by completing the following steps: 1. Use one of the following terminal commands to install the **@formio/esignature** module into your application: ``` npm i --save @formio/esignature ``` or ``` yarn add @formio/esignature ``` 2. Connect the E-Sign+ module in your application: ```javascript import {Formio} from 'formiojs'; import esignature from '@formio/esignature'; Formio.use(esignature); ``` 3. Import the digital signature module styles in your application: ```javascript import '@formio/esignature/esignature.css'; ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://help.form.io/userguide/form.io-e-sign+.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.