Configure Document Encryption

This page contains information and guidance on enabling and performing document encryption in Autoform DM. It applies to both Standalone and Clustered setups.

Autoform DM has application-level encryption for documents; specifically the ability to encrypt files that are stored in the archive. This feature adds an additional layer of security to help protect against unauthorised access or processing of sensitive data.

For new installations, Autoform DM can be configured to enable encryption by default, so that as documents are added to the archive they will be encrypted on the fly.

For existing installations that are upgraded, encryption can be enabled in the same way, but the migration of already existing documents into an encrypted state can be scheduled at any time via the new Encryption tab in the Autoform DM interface. This provides a flexible solution to migrating installations of any size to an encrypted state, over a period of days, weeks or months if required.

Autoform DM makes use of a hybrid encryption method (symmetric asymmetric), to balance security and speed to ensure that overall system performance is not impacted once encryption has been enabled. Documents and files are encrypted using AES (256 bit), with the encryption key stored in the header of the document. This key is then encrypted using RSA (2048 bit), with the key being held in the Autoform DM keystore.

Set Up Document Encryption

Warning

After encryption has been enabled on your system, it cannot be disabled. We recommend that you perform a full backup of your database and chunks folder prior to enabling encryption, so you can roll back if required.

The following steps must be completed to fully enable the Document Encryption feature:

• Specify that document encryption should be enabled.

• Obtain the encrypted master password for the keystore and set this in the configuration.

• Choose whether to use system-generated keys or import your own.

These steps are documented in detail for standalone configurations. Please read through them all before configuring document encryption so you understand the options available and what is required.

For clustered configurations, the steps are similar but there are a few differences which include the location of the configuration and how the keystore is imported. For more information, please see the cluster-specific configuration section at the end of this page.

Enable Encryption

To enable encryption the node.properties file must be updated. This can be located here:

\AUTOFORM DMServer_*\\standalone\configuration\

For example:

C:\Program Files\Formpipe Software\Autoform DM\Server_*\wildfly-*.*.*.Final\standalone\configuration\

Note

We strongly recommend that you take a backup of your node.properties file before making any changes to it.

By default, encryption is not enabled. To enable the feature, uncomment and change the value of efs.document.encryption.enabled from false to true.

For example, change #efs.document.encryption.enabled=false to efs.document.encryption.enabled=true

Encrypt the Master Password

The master password will be used for the internal keystore. When importing your own keys, this must also be the password for the keystore being imported.

This password must first be encrypted before entering it into the configuration. To do so, start Autoform DM and log in as an administrator, navigate to the Administration screen, then to the Document Encryption page.

Enter the keystore master password in order to get the encrypted version. In the Master Password section, enter your password twice, click Encrypt and then copy the displayed value.

You can set this encryted value in the master password property in the node.properties file.

For example: efs.encryption.master.password=3C8EE09C35704431

We recommend that you keep a copy of your master password safe at all times.

Choose Encryption Keys

In order to fully enable encryption on your system, the next step is to specify whether you wish to use system generated keys to encrypt your documents, or to import your own.

In both cases, a master password must be chosen, encrypted (using the tool in the Autoform DM interface), and then set in the configuration.

The system will not start until the correct configuration for either system-generated or manually imported keys has been set.

Use an Automatically Generated Keystore

To let the system automatically generate the encryption keys for you, uncomment the efs.encryption.keystore.mode property and set its value to auto.

For example, change #efs.encryption.keystore.mode=[auto/manual] to efs.encryption.keystore.mode=auto

The system will now generate the keys for document encryption and decryption and store these in the system keystore.

The master password used to secure the internal keystore must be chosen and encrypted; to do this, see the next section.

Save the node.properties file. Encryption is now enabled and configured.

Example Completed Keystore Configuration for System Generated Keys

# Enable Document Encryption

efs.document.encryption.enabled=true

# Specify the encrypted password for the internal keystore

efs.encryption.master.password=3C8EE09C35704431

# Automatically Generate Encryption Keys

efs.encryption.keystore.mode=auto

Use Your Own Keys

You can also choose to provide your own keys to use for document encryption.

The keystore being imported can be in either JKS (Java Key Store) or PFX (industry standard) format.

To configure Autoform DM to use your provided keys, uncomment the efs.encryption.keystore.mode property and set the value to manual

For example, change #efs.encryption.keystore.mode=[auto/manual] to efs.encryption.keystore.mode=manual

You must also set the initial path to the keystore holding the keys to be imported, the alias for these keys, and the keystore password.

Note

Currently, the alias used must be exactly 8 characters.

The password for the keystore being imported must be encrypted first. This password is also used for the internal keystore. Please see the next section for instructions on how to encrypt your password.

The example code block shows where the values should be entered.

Example Completed Keystore Configuration for Imported Keys

# Enable Document Encryption

efs.document.encryption.enabled=true

# Specify the encrypted password to use for both the keystore to import and the internal keystore

efs.encryption.master.password=AABBCCDDEEFFGG112233

# Import the encryption keys

efs.encryption.keystore.mode=manual

# Import the encryption keys from the keystore located at ''c:\keystores\dm_encryption.keystore''

efs.encryption.keystore.initial=c:/keystores/dm_encryption.keystore

# Import and use the keys identified by the alias 'myalias1' (8 characters)

efs.encryption.keystore.alias=myalias1

Final Steps

New Standalone Installations

You do not need to do anything else. New documents will be encrypted as they are added to your archive.

For Upgraded Standalone Installations

As new documents are added to your archive they will be encrypted; however, your existing documents and files will remain in an unencrypted state until they are migrated by the encryption service.

Scheduling Encryption Migration (UI)

If you are upgrading from a previous version of Autoform DM, once you have enabled encryption and chosen your keystore, the next step is to encrypt all of your existing documents / files.

Note

The migration will only cover your current archive directory. Any existing historical archive directories will be ignored.

Depending on your installation, the size of your archive, network load and your encryption schedule, this could take anywhere from a few hours to a number of days. Whilst the overhead of encrypting documents is low, for general performance and network health we recommend that your perform this operation outside of your peak business operating hours.

The first step is to log in to the Autoform DM front end. If your encryption migration is configured correctly you should see Database Upgrade appear when you arrive on the login screen. Once this is complete, log in with an administrator account and navigate to Administration > Encryption.

Whilst a full breakdown of the interface and possible values have been provided for your reference, the process of scheduling is simply to:

1. Choose your active hours using the selectors.

2. Click Start.

Progress can be monitored using the Migration Report page. See Migration Report for more detail.

Document Encryption

Document Migration

Active Hours

Controls

Migration Report

To check on the progress of your encryption migration, you can view the migration report at any time. The report is automatically updated every 10 seconds and can be sorted or filtered based on any of the column headers. It is possible to see, at a glance, the number of files that have been processed and how many have failed (if any).

You can customise the migration report table using the menu button (the three stacked lines) at the far right of the table. Clicking this will give you a drop-down list of available columns you can include in your report. You can toggle which columns you want to see (or not see) based on your own preferences.

To sort the data in any column, click the small arrow head to the right of each column name and choose from ascending / descending values. You can also choose to hide the column.

To filter the data in any column you can enter a value in the boxes just below the column names. Only records that match your entered value will then be shown. This can help to identify problem files, or times during which errors occurred.

Clustered Setups

As per the standalone setup, we recommend that you read through this page in full before enabling encryption so you know what to expect and what your options are. The decisions that you need to make and the information you will require will be the same as the standalone setup, so they will not be covered here again in detail.

The process for enabling encryption on a clustered installation is slightly different to that of the standalone setup, in that much of the configuration information should instead be added into the Wildfly management console, so that it can be easily propagated to all of the nodes in the cluster. If you are using your own keys rather than automatically generated ones, you will also need to configure a chosen Autoform DM node to perform the import of the keys into the Autoform DM Database for the whole of the cluster to use.

Initial Steps

1. Ensure that your cluster is fully deployed and is ready to use.

2. Log in to a running Autoform DM node and navigate to the Document Encryption settings from the Administration page.

3. Enter and encrypt your master password. If using your own keys, your master password should be the same as the password for the keystore you are importing. For more information see Encrypting the Master Password.

4. Log in to the Wildfly management console via your PDCs IP address or hostname, and its management port. Unless changed during install, the default management port is 9990 (for example, http://192.0.0.168..:9990). Using the management account you created for Wildfly during the PDC installation process, use your credentials to log in.

5. From the management console navigate to: Runtime > Server Groups > dm-server-group, then click View.

   

6. Click System Properties.

   

7. Add your encryption configuration into the following fields, overwriting the default values with your own:

   • efs.document.encryption.enabled : [false]

   • efs.encryption.keystore.mode : [auto / manual]

   • efs.encryption.master.password : [encrypted password]

Example: Cluster Using Automatic Keystore

efs.document.encryption.enabled: true

efs.encryption.keystore.mode: auto

efs.encryption.master.password: your-encrypted-password

Example: Cluster Using Manual Keystore

efs.document.encryption.enabled: true

efs.encryption.keystore.mode: manual

efs.encryption.master.password: your-encrypted-password

For an Automatically Generated Encryption Keystore

The configuration must be initialised. Use the Wildfly Management Console to start a single Autoform DM application node. Once it has started, we recommend logging in and navigating to the encryption screen to confirm encryption is correctly enabled. After this is done any other DM application nodes in the cluster can also then be started.

If everything is configured correctly encryption will now be enabled for your cluster.

We recommend that you keep a copy of your master password safe at all times.

For a Manually Configured Encryption Keystore

If you have chosen to use your own keys, the next step is to import your keystore into the database so it is accessible by all nodes in the cluster. To do this, you must choose one node in the cluster to perform the import. For simplicity, we recommend that you stop the cluster whilst you are in the wildfly management console, as all nodes will need to be rebooted in order to pick up the configuration changes and new keystore.

Choose the node on which you will perform the import and browse to the node.properties files on that machine. The node.properties file can be found here (appropriate substitute <your-cluster-role-server>):

\AUTOFORM DM\Server_x.x-<your-cluster-role-server>\wildfly-x.x.x.Final\domain\configuration\

For example:

C:\Program Files\Formpipe Software\Autoform DM\Server_x.x-<your-cluster-role-server>\wildfly-x.x.x.Final\domain\configuration\

Unlike the node.properties file for a standalone server, the clustered version only covers the configuration for a manually specified keystore.

You will need to set the path to the keystore. The path must be reachable by the Autoform DM node you are currently on, otherwise the import will fail. You will also need to set the Alias for the key in the keystore you wish to use.

Note

The alias must be exactly 8 characters long.

#
# Document Encryption (DM Node)

[...]
#efs.encryption.keystore.initial=

[...]
#efs.encryption.keystore.alias=

Example Completed node.properties File For a Manually Configured Encryption Keystore

[...]
efs.encryption.keystore.initial=c:/secure/data/keystore

[...]
efs.encryption.keystore.alias=myalias1

When this is done, save the node.properties file, then return to the Wildfly Management Console and start the specific Autoform DM node you have updated. Once it has started, we recommend logging in and navigating to the encryption screen to confirm encryption is correctly enabled. After this is done any other Autoform DM application nodes in the cluster can also then be started.

If everything is configured correctly, encryption will now be enabled for your cluster.