# Form.io eSignature - Coming Soon

## Introduction

Form.io eSignature is aimed to confirm that the signed piece of data and its context (the form, custom properties, etc.) have not changed since it was signed.

Peculiarities of the eSignature solution provided by form.io:

* **Zero-trust.** Deployed in your app, in your environment means you don't have to trust 3rd-party providers with your eSignatures. The eSignatures are stored in your database.
* &#x20;**API-driven digital signatures**. You can access any signed data/form via API using its submission ID that's native to Form.io.
* **Decoupled from PDFs**. Form.io eSignature 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 eSignature private key.** Signature data is stored in DB as a token signed with the private key provided by you. You can store your keys outside of your 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 your eSignature stamp.** Use your custom templates for the eSignature stamp.

## Availability

{% hint style="info" %}
**The eSignature is not yet released.** This functionality will be available only for self-hosted environments that has both Security Compliance Module and eSignature enabled within their license configuration.
{% endhint %}

{% hint style="info" %}
Contact **sales@form.io** to acquire a License
{% endhint %}

Once eSignature is enabled for the license key, you will see the eSignature tab under the Modify section in the navigation sidebar of any form.

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FkK61nFozRGAKjzQD6xD6%2F1.%20esign%20tab.PNG?alt=media&#x26;token=4c7abd88-d978-40d7-ab4c-ef0e0a11bfc5" alt=""><figcaption><p>eSignature tab</p></figcaption></figure>

The eSignature 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'.

## eSignature Settings

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FZfqy67Ei9wpmM5JSGt3H%2F2.%20esign%20settings.PNG?alt=media&#x26;token=2698d7ad-52a7-43e9-83db-93f15214aa58" alt=""><figcaption><p>eSignature Settings</p></figcaption></figure>

1. **eSignature components.** First of all, decide what form components will be used as signature(s) in your form and add them to the eSignature configuration.  Click 'Add eSignature' to attach eSignature functionality to some of your form components. A form can have one or more eSignatures.

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FkWx2cQWdmL2aOIoq0Elq%2F3.%20esign%20componet%20setting.PNG?alt=media&#x26;token=61374801-c647-4e93-8542-070e90d0d7b8" alt=""><figcaption><p>eSignature Component Settings</p></figcaption></figure>

* _eSignature Component_ is a form component that will be used as a signature.
* _eSignature Data_. Select the form components those data is be confirmed by the eSignature. If the signed value of these components changes, the eSignature becomes invalid and the data is expected to sign again.
* _Include all form data in eSignature_. When this setting is enabled, the eSignature will be responsible for all form data. If the value of some form component is changed, the eSignature will be invalid and the data is expected to sign again.

2. The **'Submission properties to include in eSignature'** are the comma separated paths to the data inside the submission object that will be used for the eSignature verification. Use this setting if you want the eSignature to confirm that some submission properties (except for submission data) stays unchanged since it was signed, e.g. some metadata properties.&#x20;
3. **Do not disable signed data**. By default, the signed data is disabled in UI to protect it from modifications. Enable this setting, if you do not want to disable signed data.
4. The **Templates** settings allow to change the default template of the eSignature stamp and tooltip.

## eSignature Templates

The Templates settings enables users to customize UI for eSignature stamp and tooltip 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 eSignature object                                                                           |
| esignTooltip        | The markup of the eSignature tooltip represented as a string (available only for the stamp template).   |
| esignInvalidMessage | The default message for invalid eSignature (available only for the stamp template).                     |
| esignIconClass      | The class of the eSignature default stamp icon (available only for the stamp template).                 |
| 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](http://formio.github.io/formio.js/docs/identifiers.html#utils) object. |
| util                | An alias for "utils".                                                                                   |

#### esign object&#x20;

The _esign_ variable is available in both stamp and tooltip templates and contains main information about eSignature.&#x20;

The _esign_ object typically has the following properties:

* _created_ - the ISO formated date of eSigature creation;
* _valid_ - if eSignature is valid it has a true value, if not - the massage why eSignature is not valid;
* _\_id_ - eSignature ID;
* _\_sid_ - ID of the submission that contains this eSignature;
* _signature_ - the object with eSignature data that has the following properties:
  * _compPath_ - path to eSignature component inside the form JSON;
  * _valuePath_ - path to the value of the eSignature component in submission data;
  * _user_ - the id and email of the user who signs the eSignature field;
  * _submission_ - the submission revision object (without submission data) created together with eSignature.

### eSignature Stamp Template

Example of a custom stamp template:&#x20;

```
{% if (esign.valid === true) { %}
<span class="formio-esign-stamp">
  <i ref="esignTooltip" style="cursor:pointer" data-tooltip="{{esignTooltip}}" class='{{esignIconClass}}' aria-hidden='true'></i>
  <span class="formio-esign-stamp-description">
    Signed on {{new Date(esign.created).toLocaleString()}}
  </span>
</span>
{% } %}
{% if (esign.valid !== true) { %}
<span class="formio-esign-stamp formio-esign-stamp-invalid formio-esign-stamp-description">
  <i ref="esignTooltip" style="cursor:pointer" data-tooltip="{{esignTooltip}}" class='{{esignIconClass}}' aria-hidden='true'></i>
  Invalid eSignature
</span>
{% } %}
```

_**Tips**:_

* To use tooltip with your eSignature stamp, add the following attributes to some HTML element inside your stamp template: _ref="esignTooltip" data-tooltip="\{{esignTooltip\}}._

```
 <i ref="esignTooltip" data-tooltip="{{esignTooltip}}" class='{{esignIconClass}}'></i>< ref="esignTooltip" style="cursor:poer" data-tooltip="{{esignTooltip}}" class='{{esignIconClass}}' aria-hidden='true'></i>
```

* To use different stamp template for the form and printed PDF (when viewing submission as PDF), check if _instance.options.pdf_ is true:

```
{% if (instance.options.pdf) { %}
 // stamp template for printed PDF
{% } %}
{% if (!instance.options.pdf) { %}
 // stamp template for the form
{% } %}
```

* To use different stamp template for valid and invalid eSignature, check if _esign.valid_ is equal to true or not.

```
{% if (esign.valid === true) { %}
 // stamp template for valid eSignature
{% } %}
{% if (esign.valid !== true) { %}
 // stamp template for invalid eSignatrue
{% } %}
```

### eSignature Tooltip Template

Example of a custom tooltip template:&#x20;

```
<div class="formio-esign-tooltip">
  <span class="{{esign.valid !== true ? 'formio-esign-tooltip-header-invalid' : ''}} formio-esign-tooltip-header">
    <span>eSignature</span>
    <span class="formio-esign-tooltip-status" >{{esign.valid !== true ? 'invalid' : 'verified'}}</span>
  </span>
  <ul class="formio-esign-tooltip-info">
    <li class="formio-esign-tooltip-info-item"><span class="formio-esign-tooltip-info-item-title">ID:</span><<span>{{esign?._id || '-'}}</span></li>
    <li class="formio-esign-tooltip-info-item"><span class="formio-esign-tooltip-info-item-title">Path:</span><span>{{esign?.signature?.valuePath || '-'}}</span></li>
  </ul>
</div>

```

## eSignature Cryptography

The eSignature uses the asymmetric cryptographic keys to sign and verify the snapshot of data. The key is required and must be provided by you.&#x20;

There are 2 ways to provide keys for eSignature cryptographic operations:

* set ESIGN\_PRIVATE\_KEY variable for the form.io server deployment;
* add integration with third-party key management service (e.g. AWS KMS).

### ESIGN\_PRIVATE\_KEY server variable

The simplest way to provide your keys for eSignature is to set the ESIGN\_PRIVATE\_KEY variable for your deployment of the **formio/formio-enterprise** . There is no need to set the public key as an environment variable as it can be easily extracted from your private key.

{% hint style="info" %}
Check the deployment documentation to know more about environment variables:

[https://help.form.io/deployments/deployment-guide/enterprise-server](https://help.form.io/deployments/deployment-guide/enterprise-server)
{% endhint %}

Requirements for a private key set to ESIGN\_PRIVATE\_KEY:

* key type: RSA;
* key size: 2048-bit;
* public key: type - 'spki', format - 'pem';
* private key: type - 'pkcs8', format - 'pem'.

Example of the 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)

If you prefer to use a third party provider to store and manage your eSignature keys, add eSignature integration settings on the project level.&#x20;

#### AWS KMS&#x20;

The form.io eSignature can use AWS KMS API to sign and verify the eSignature data. Follow these steps to add AWS KMS integration:

1. create RSA2048 key available for 'sign and verify' operations in AWS KMS:

1.1. log in to your AWS account;

1.2. open Services -> Security, Identity, & Compliance -> Key Management Service;

1.3. click on the 'Create a key' button in the main AWS KMS page or select 'Customer managed keys' on the sidebar and click on the 'Create a key' button on the top of the keys list:

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FTHmlJNaRaXThSscwiArG%2F4.%20aws%20kms%20main.PNG?alt=media&#x26;token=fc9ae667-7fee-4653-97ac-9b262bcf528f" alt=""><figcaption></figcaption></figure>

1.4. follow the key setup wizard to create your key. The step 1 key settings are expected to look like this:

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2F5TKdAVLzdhTaEgJ8A1C4%2F5.%20aws%20config%20step%201.PNG?alt=media&#x26;token=920ebfa8-cca5-4193-a386-15761cf3630b" alt=""><figcaption><p>AWS KMS Key - step 1</p></figcaption></figure>

1.5. Open the created key from the key list in the 'Customer managed keys' section and copy the key ID:

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FI3HCL2rR8R0OCnz25dnP%2F6.%20key%20id%20copy.PNG?alt=media&#x26;token=7d1364c7-58b5-4a9e-afe1-4c1f0efb4953" alt=""><figcaption><p>Key Settings</p></figcaption></figure>

2. Create an Access Key for your AWS account and copy your Access Key ID and Secret Key. Check AWS documentation to create the access key for your account:

[https://docs.aws.amazon.com/IAM/latest/UserGuide/id\_credentials\_access-keys.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html)

3. Add AWS KMS integration settings to the project settings in your form.io developers\` portal:

3.1. Open your project Settings -> eSignature;

3.2. Add your AWS KMS settings:&#x20;

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FrUys2E3cMSEKJvqfnjiR%2F7.%20aws%20kms%20project%20settigns.PNG?alt=media&#x26;token=28ca8d02-56e6-431c-9ebd-067f45f1bba2" alt=""><figcaption><p>AWS KMS Integration Settings</p></figcaption></figure>

3.3. Save the project settings. From this point, the AWS KMS API will be used for the eSignature cryptographic operations for this project.

## eSignature Examples

1\. Create a new form and add components as shown in the example below, or import the form using URL: [https://remote-next.form.io/authoring-rwghbgwsuvdthxs/esignaturedemo](https://remote-next.form.io/authoring-rwghbgwsuvdthxs/esignaturedemo).

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FFLbYtCr7Ha15m3ic0Ux6%2Fexample%201%20form.PNG?alt=media&#x26;token=c163c718-2a44-4ad2-96c9-209aa0730b60" alt=""><figcaption><p>Example Form</p></figcaption></figure>

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 express his approval of 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.

2. Configure the eSignature:

2.1. Enable submission revisions and original form revisions for the form:

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FOcmZudWOMMp7yoWNSNnJ%2Fex%201%20revisions%20configuration.PNG?alt=media&#x26;token=d4609886-f6a6-4e94-85d5-8fcd936b84a1" alt=""><figcaption><p>Revisions configuration</p></figcaption></figure>

2.2. Go to the Modify tab  -> eSignature. Click the 'Add eSignature' button and configure eSignature for the field 4:

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FBgI3GtyAH58Dp4BLd5Z0%2Fmodify%20tab.PNG?alt=media&#x26;token=a2ca5086-d168-4f98-9679-418075b37d95" alt=""><figcaption><p>Modify Tab</p></figcaption></figure>

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FAg8Fu2bkWwU2kbjIDHoW%2Fexample%201%20sign%201.PNG?alt=media&#x26;token=29ee7957-da63-415b-a175-aec4aeb0683b" alt=""><figcaption><p>eSignature config for field 4</p></figcaption></figure>

Click Save. Add eSignatures for fields 5 and 7 and save them:

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FnYTa6dcipdypHrtA007h%2Fsign%202%20and%203.PNG?alt=media&#x26;token=0400dfed-8f9c-4dd8-b8b9-ec62bac00a27" alt=""><figcaption><p>eSignature config for field 5 and 7</p></figcaption></figure>

2.3. Save eSignature settings clicking on the 'Save Settings' button.

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FfxsFji1YWibPVrDz0yL7%2Fsave%20settings.PNG?alt=media&#x26;token=e7524a7d-d0da-41da-a5fb-a7868a098ae2" alt=""><figcaption><p>Save Settings</p></figcaption></figure>

3. Go to the Use tab, fill in fields 1-4 and submit the form. When viewing/editing this submission, the green eSignature stamp is displayed under field 4. This stamp confirms that the eSignature was created and the eSignature data (fields 1-4) and the form have not been changed since it was sign. More eSignature details are available on the stamp hover, :

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FvHHARVSMUyb3RJZbQWzJ%2Fsigned%20field%204.PNG?alt=media&#x26;token=edf9242d-62e0-489b-89d3-5f3d0588db1e" alt=""><figcaption><p>Field 4 eSignature</p></figcaption></figure>

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FrbMt53yCjW681LDQIr4s%2Fsignture%20on%20hover.PNG?alt=media&#x26;token=5535f64c-bc87-46af-a8f1-40370e4019ee" alt=""><figcaption><p>eSignature on hover</p></figcaption></figure>

4. Edit the submission. Pay attention that the signed fields 1-4 are disabled. Fill in field 5 and submit the form. You will see that eSignature is created for field 5.&#x20;
5. Fill in fields 6 and 7 and submit the form. eSignatures are created for all signature fields:

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2F1Ndyr4prPh2sz7WEdLM8%2Ffully%20signed.PNG?alt=media&#x26;token=39201936-4df0-4b4c-b895-6ee1fcf229cd" alt=""><figcaption><p>Signed Form</p></figcaption></figure>

#### **eSignature validation when 'Do not disable signed data' is enabled**

When the signed fields are not disable from modification in UI, eSignature data is validated on the client side. If some signed value is changed, eSignature becomes invalid and the signature field is cleared. That means the changed data is expected to sign again.

Example:

1. Follow steps 1-2 from the previous example.
2. Open eSignature settings and enable 'Do not disable signed data'. Save eSignature settings clicking on the 'Save Settings' button.
3. Sign the form following steps 3-5 from the previous example. Note that signed fields are not disabled.
4. Edit the submission and change the quantity field from 1 to 2. As a consequence, the eSignatures for fields 4 and 5 become invalid and signature values are reset.

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FBgWoD22VS4hOvie9dKPU%2Finvalid%20esignatures.PNG?alt=media&#x26;token=9d5eb2c6-aa64-44bf-aeab-aed7c650591b" alt=""><figcaption><p>Invalid eSignatures</p></figcaption></figure>

<figure><img src="https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FvQ4ovHERRmWhWIXmkaw4%2Finvalid%20eSignatue.PNG?alt=media&#x26;token=1641379e-243b-4b1e-9309-fd4a0c8f3322" alt=""><figcaption><p>Invalid eSignature on hover</p></figcaption></figure>

The eSignature for field 7 is still valid as it is only responsible for the data in field 6. Change field 6, the field 7 value will be cleared and the eSignature will become invalid. You will have to sign these fields again and new eSignatures will be created for the form.

## eSignature and PDF

Use eSignature with PDF-first forms in the same way as you would with web forms.&#x20;

The PDF of the web form submission, that contains eSignature(s), displays eSignature stamp.

## Render eSignature in your application

Use **@formio/esignature** module to render eSignatures in your application.&#x20;

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 eSignature module in your application:

```
import {Formio} from 'formiojs';
import esignature from '@formio/esignature';

Formio.use(esignature);

```

3. Import the eSignature module styles in your application:

<pre><code><strong>import '@formio/esignature/esignature.css';
</strong></code></pre>
