ManualWorks can encrypt the names and email addresses in the user (R_USER) table and the authors in the document (R_BOOK) and chapter (R_CHAPTER) tables with the AES-256/GCM algorithm. When this feature is on, these values are encrypted when saved and decrypted automatically when read.

Turning On User Information Encryption

User information encryption is turned on and off with a startup script option. Add the following option to the startup script options, and restart ManualWorks. This setting alone does not encrypt user information or document and chapter authors that are already stored, so also run the user information migration below.

3rabbitz.enable_user_encryption=true

Key File

The encryption key is stored in the .key.json file in the Data Directory.

• If there is no key file, a 32-byte AES key is generated automatically and .key.json is created the first time data is encrypted or the migration page is opened.

• Because the key file is stored in the data directory, in a redundant server environment all nodes that use the same data directory on the NAS share the same key file.

• If you lose the key file or change it by mistake, user names and email addresses cannot be decrypted. Keep it in a safe place.

The key file uses the following JSON format.

{
    "active": "k1",
    "keys": {
        "k1": "Base64-encoded 32-byte key"
    }
}

• active: The ID of the key currently in use. New data is encrypted with this key.

• keys: The list of available keys. Pair each key ID with its Base64-encoded 32-byte key value.

Rules for Key IDs and Values

Key IDs follow these rules.

• plain is reserved and cannot be used as a key ID.

• A key ID cannot contain the } character.

• A key value must be 32 bytes (AES-256) of Base64-encoded data.

You can create a key with the generate-key command in the Console.

generate-key

Format of Encrypted Values

Encrypted values have a prefix in the following format.

{v:KEY_ID}Base64-encoded IV + ciphertext

For example, a value encrypted with the k1 key starts as follows.

{v:k1}fI3YfyWSJ+...

Plain Mode

To store user information as plain text without encryption, set the active value in the key file to plain.

{
    "active": "plain",
    "keys": {
        "k1": "Base64-encoded 32-byte key"
    }
}

In plain mode, ManualWorks works as follows.

• New data is stored as plain text without encryption.

• Existing encrypted data (values with the {v:KEY_ID} prefix) is decrypted with the keys registered in keys and shown.

• Running the migration stores all encrypted data again as plain text.

Key Rotation

To rotate keys, add a new key and change the active value to the new key ID.

{
    "active": "k2",
    "keys": {
        "k1": "previous key",
        "k2": "new key"
    }
}

• New data is encrypted with the k2 key.

• Data encrypted with the old k1 key is identified by its prefix ({v:k1}) and decrypted with the k1 key.

• Running the migration re-encrypts all data encrypted with the old k1 key with the k2 key.

User Information Migration

After you turn on user information encryption for the first time or rotate keys, run the migration to store all user information again with the current active key. The authors of documents and chapters are processed at the same time.

Run the migration as follows.

1. Log in as an administrator.

2. Go to the 1User Encryption Migration page (/#/r/user_encryption).

3. Check the active key ID shown at the top of the page (for example, key: k1).

4. Click the 2 Start button. If the 3rabbitz.enable_user_encryption option is not set, the Start button is disabled.

5. In the “Are you sure you want to execute?” dialog, click the OK button.

6. Watch the progress and wait until all users are processed.

7. When the migration finishes, the message Completed. appears.

• Only document and chapter authors that are not yet encrypted are processed, so it is safe to run the migration more than once.

• Only the author column is updated, so the modification date and modifier of documents do not change.

Operational Considerations

Keep the following in mind when you operate user information encryption.

• Back up the key file: If the .key.json file is lost, encrypted user information and the API keys of AI providers cannot be decrypted. The key file is not included in ManualWorks backups, so when you back up the database, also back up the key file to a safe place.

• Restrict access to the key file: Restrict access at the operating system level so that only the ManualWorks process can read the key file.

• Cluster synchronization: Make sure all nodes in the cluster share the same data directory on the NAS.

• Consistent settings: Set the 3rabbitz.enable_user_encryption property to the same value on all nodes in the cluster.

Limitations

• In the <Admin | Users | Users> menu, searching by name and sorting by name or email are not supported.

• In the document list, searching by author is not supported. Searching by title, subtitle, and edition still works.