العودة إلى User Guides
المحتويات
User Guides
771 كلمة
Nov 13, 2026

Heratio Help Center article. Category: Admin & Settings.

Data Encryption

User Guide

Protect sensitive data at rest with two-layer encryption for digital objects and database fields.

Overview

DATAENCRYPTIONLAYER1:FILEENCRYPTIONLAYER2:FIELDENCRYPTIONDigitalobjectsondiskDatabasecolumnsMastersderivativesContactinfo,financesUploadedfilesDonordata,notesXChaCha20-Poly1305XChaCha20-Poly1305ChunkedstreamingPer-valueencryption

Why Encrypt?

COMPLIANCEREQUIREMENTSPOPIA(SouthAfrica)-PersonalinformationprotectionGDPR(EU)-DataprotectionregulationCCPA(California)-ConsumerprivacyactNARSSA(SouthAfrica)-NationalarchivesrequirementsPAIA(SouthAfrica)-PromotionofaccesstoinfoPIPEDA(Canada)-PersonalinfoprotectionNDPA(Nigeria)-DataprotectionactIfyourserverdiskordatabaseiscompromised,encrypteddataremainsprotected.

How to Access

MainMenuAdminAHGSettingsEncryptionKeyStatus(viewkeyinfo)MasterToggle(enable/disable)FileOptions(derivativestoggle)FieldCategories(selectwhattoencrypt)

Initial Setup

Step 1: Generate Encryption Key

An administrator must generate the master encryption key via CLI:

php bin/atom encryption:key --generate
IMPORTANTThekeyisstoredat:/etc/atom/encryption.keyBACKUPTHISKEYSECURELY.Iflost,ALLencrypteddataispermanentlyunrecoverable.Storebackupcopiesin:-Secureoffsitelocation-Hardwaresecuritymodule(HSM)-EncryptedUSBdriveinsafe

Step 2: Verify Key

php bin/atom encryption:key --validate

Expected output:

  Key is valid.
    Path: /etc/atom/encryption.key
    Key ID: 1
    Algorithm: XChaCha20-Poly1305 (libsodium)
    Permissions: 0600
    Round-trip test: PASSED

Step 3: Enable Encryption in Settings

Go to Admin > AHG Settings > Encryption

Layer 1: File Encryption

Encrypts uploaded digital objects (images, documents, audio, video) on disk.

How It Works

UserHeratioDiskuploadsencryptsstoresfilein-placeencryptedUserHeratioDiskviewsdecryptsreadsfileon-the-flyencrypted

Enable File Encryption

  1. Go to Admin > AHG Settings > Encryption
  2. Set Enable File Encryption to Yes
  3. Set Encrypt Derivatives to Yes (recommended)
  4. Click Save

Encrypt Existing Files

New uploads are encrypted automatically. For files already on disk:

# Preview what would be encrypted
php bin/atom encryption:encrypt-files --dry-run

# Encrypt first 100 unencrypted files
php bin/atom encryption:encrypt-files --limit=100

# Encrypt a specific digital object
php bin/atom encryption:encrypt-files --id=123 --with-derivatives

# Encrypt all files (set high limit)
php bin/atom encryption:encrypt-files --limit=10000

User Experience

Encryption is transparent to users:

  • Viewing, downloading, and streaming work exactly as before
  • IIIF viewer, media player, and thumbnails function normally
  • No action required from regular users

Layer 2: Field Encryption

Encrypts sensitive database columns so raw SQL access shows encrypted blobs instead of personal data.

Available Categories

FIELDCATEGORIES[]ContactDetailsEmail,address,telephone,fax,contactperson[]FinancialDataAppraisalvalues[]DonorInformationActorhistory(fordonorrecords)[]PersonalNotesNotecontent[]AccessRestrictionsRightsnotes

Enable Field Encryption

  1. Go to Admin > AHG Settings > Encryption
  2. Check the categories you want to encrypt
  3. Click Save
  4. Run the encryption command:
# Encrypt specific category
php bin/atom encryption:encrypt-fields --category=contact_details

# Encrypt all enabled categories
php bin/atom encryption:encrypt-fields --all

# List available categories
php bin/atom encryption:encrypt-fields --list

Decrypt Fields (Reversible)

Field encryption is reversible:

# Decrypt a specific category
php bin/atom encryption:encrypt-fields --category=contact_details --reverse

# Decrypt all categories
php bin/atom encryption:encrypt-fields --all --reverse

Important Notes

  • Encrypted fields are not searchable in the search bar or advanced search
  • Detail pages display decrypted values for authorized users
  • Direct database queries (MySQL) show encrypted blobs
  • Encryption/decryption requires CLI access

Status Dashboard

Check the overall encryption status at any time:

php bin/atom encryption:status

Example output:

=======================================
  Heratio Encryption Dashboard
=======================================

MASTER KEY
----------
  Path: /etc/atom/encryption.key
  Status: Valid
  Key ID: 1
  Algorithm: XChaCha20-Poly1305 (libsodium)
  Sodium: Available (v1.0.18)
  Subkeys: HKDF-SHA256 (file, field, hmac)
  Permissions: 0600

SETTINGS
--------
  [ON ] Master toggle
  [ON ] Encrypt derivatives
  [ON ] Field: Contact details
  [OFF] Field: Financial data
  [OFF] Field: Donor information
  [OFF] Field: Personal notes
  [OFF] Field: Access restrictions

FILE ENCRYPTION (Layer 1)
------------------------
  Total digital objects: 898
  Sample (50 files):
    Encrypted V2 (sodium): 3
    Encrypted V1 (legacy): 0
    Plaintext: 47
    Missing:   0
  Estimated encryption rate: 6%

FIELD ENCRYPTION (Layer 2)
-------------------------
  [ENC] contact_details: Encrypted (6 fields)
  [   ] financial_data: Plaintext (1 fields)
  [   ] donor_information: Plaintext (1 fields)
  [   ] personal_notes: Plaintext (1 fields)
  [   ] access_restrictions: Plaintext (1 fields)

AUDIT LOG
---------
  Total operations: 3
    encrypt: 3
  Last operation: encrypt (file) - success

CLI Command Reference

ENCRYPTIONCOMMANDSKEYMANAGEMENTphpbin/atomencryption:keygeneratephpbin/atomencryption:keyvalidatephpbin/atomencryption:keygenerateforceFILEENCRYPTIONphpbin/atomencryption:encrypt-fileslimit=100phpbin/atomencryption:encrypt-filesid=123phpbin/atomencryption:encrypt-filesdry-runphpbin/atomencryption:encrypt-filesupgrade-v2FIELDENCRYPTIONphpbin/atomencryption:encrypt-fieldslistphpbin/atomencryption:encrypt-fieldscategory=Xphpbin/atomencryption:encrypt-fieldsallphpbin/atomencryption:encrypt-fieldsreverseSTATUSphpbin/atomencryption:status

Frequently Asked Questions

What happens if I lose the encryption key?

All encrypted data becomes permanently unrecoverable. Always maintain secure backups of /etc/atom/encryption.key.

Can I change the encryption key?

Yes. Generate a new key with --force, then re-encrypt all data. The old data must be decrypted first with the old key, or the system handles V1/V2 transitions automatically.

Does encryption slow down the system?

No measurable impact. Files are encrypted/decrypted on demand using streaming (never loaded fully into memory). A 75MB file has only ~20KB of encryption overhead.

Can I encrypt only some file types?

Currently, encryption applies to all digital objects when enabled. Selective file-type encryption is planned for a future release.

What if sodium is not installed?

The system falls back to AES-256-GCM (V1). This is secure but loads entire files into memory. Install php-sodium for the recommended V2 behavior.

Are encrypted fields searchable?

No. When a field category is encrypted, those values are not indexed in Elasticsearch. Detail pages decrypt on the fly for authorized users.

Can I upgrade V1 encrypted files to V2?

Yes: php bin/atom encryption:encrypt-files --upgrade-v2