Form.io Digital Signature - Coming Soon

Introduction

Form.io Digital Signature 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.

Key aspects of the Digital Signature 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 Digital Signatures. The Digital Signatures are stored in your database.

• 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 Digital Signatures 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 Digital Signature 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 the Digital Signature stamp. Use your custom templates for the Digital Signature stamp.

Availability

The Digital Signature module is not yet released. This functionality will be available only for self-hosted environments that has both Security Compliance Module and Digital Signature enabled within their license configuration. Contact [email protected] to acquire a License

After Digital Signatures are enabled for the license key, the Digital Signatures tab is available under the Modify section in the navigation bar of any form.

Digital Signature tab

The Digital Signature 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'.

Digital Signature Settings

Digital Sinature 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 Settings

• Digital Signature Component - The form component that will be used as a signature.

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

• Do not disable signed data - 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.

Digital Signature Templates

The Templates settings enables users to customize UI for Digital Signature stamp and tooltip using the JavaScript Lodash 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).
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.
utils	An instance of the FormioUtils 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:

{% 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 Digital Signature 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 Digital Signature, 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
{% } %}

Digital Signature Tooltip Template

Example of a custom tooltip template:

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

Digital Signature Cryptography

Digital Signature uses the asymmetric cryptographic keys to sign and verify a snapshot of the data. The key is required and must be provided by you.

There are 2 ways to provide keys for Digital Signature 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 Digital Signature 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 the private key.

Check the deployment documentation to know more about environment variables:

https://help.form.io/deployments/deployment-guide/enterprise-server

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:

    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 Digital Signature keys, add Digital Signature integration settings on the project level.

AWS KMS

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

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

2. Log in to your AWS account;

3. Open Services -> Security, Identity, & Compliance -> Key Management Service;

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

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

AWS KMS Key - step 1

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

Key Settings

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

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

2. Open the project's Settings, and click Digital Signature.

3. Add your AWS KMS settings:

AWS KMS Integration Settings

1. Save the project settings. From this point, the AWS KMS API will be used for the Digital Signature cryptographic operations for this project.

DigitalSignature Examples

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.

Example Form

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.

Configure the example Digital Signature:

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

Revisions configuration

1. From the toolbar, go to Modify > Digital Signature. Click the 'Add Digital Signature' button and configure Digital Signature for Field 4:

Modify Tab

Digital Signature config for field 4

1. Click Save. Add Digital Signatures for Field 5 and Field 7 and save them:

Digital Signature config for field 5 and 7

1. Save the Digital Signature settings clicking on the 'Save Settings' button.

Save Settings

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

Field 4 Digital Signature

DigitalDigital Signature on hover

1. 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 Digital Signature is created for field 5.

2. Fill in fields 6 and 7 and submit the form. Digital Signatures are created for all signature fields:

Signed Form

Digital Signature validation when 'Do not disable signed data' is enabled

When the signed fields are not disable from modification in UI, 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 expected to sign again.

Example:

1. Follow steps 1-2 from the previous example.

2. Open Digital Signature settings and enable Do not disable signed data. Save Digital Signature settings by 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 Digital Signatures for fields 4 and 5 become invalid and signature values are reset.

Invalid Digital Signatures

Invalid Digital Signature on hover

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

Use Digital Signature with PDF-first forms in the same way as with web forms.

The PDF of the web form submission on a form that contains Digital Signatures, displays a Digital Signature stamp.

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

1. Connect the Digital Signature module in your application:

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

Formio.use(esignature);

1. Import the Digital Signature module styles in your application:

import '@formio/esignature/esignature.css';