From 0dd4a0ee0d9ae4c1148aede3d9ce04e46a7c27d5 Mon Sep 17 00:00:00 2001
From: Jonathan Miller <1+jmiller@noreply.git.mokoconsulting.tech>
Date: Mon, 13 Jul 2026 01:04:07 +0000
Subject: [PATCH] docs: refresh for 02.61.0

---
 Encryption.md | 45 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)
 create mode 100644 Encryption.md

diff --git a/Encryption.md b/Encryption.md
new file mode 100644
index 0000000..d7a188b
--- /dev/null
+++ b/Encryption.md
@@ -0,0 +1,45 @@
+# Encryption
+
+MokoSuiteBackup can produce **AES-256 encrypted** archives so backups can be stored on untrusted or remote destinations without exposing site data. Encryption is per-profile and driven entirely by a single password.
+
+## Enabling encryption
+
+Encryption is controlled by the profile's **`encryption_password`** column (`#__mokosuitebackup_profiles.encryption_password`, VARCHAR(255)). A blank value means **no encryption**; any non-empty value turns AES-256 encryption on for that profile's archives.
+
+There is no separate on/off toggle — setting a password enables encryption, clearing it disables it.
+
+## Supported formats
+
+Encryption support depends on the profile's `archive_format`:
+
+| Format | Encryption | Mechanism |
+|---|---|---|
+| `zip` | AES-256 | Post-process the finished ZIP with `ZipArchive::setEncryptionName()` per entry (WinZip-compatible AES-256) |
+| `7z` | AES-256 | Native `7z` CLI encryption applied during archive creation (`-p<password>`), with header encryption (`-mhe=on`) |
+| `tar.gz` | **Not supported** | Encryption is skipped and a warning is logged |
+
+If `tar.gz` is selected together with a password, the backup still completes but the archive is **not** encrypted and the log records:
+`WARNING: AES-256 encryption only supported for ZIP and 7z archives — skipping encryption`.
+
+### ZIP encryption details
+
+After the ZIP is written and closed, `BackupEngine::encryptArchive()` reopens it, calls `setPassword()`, and marks every entry with `ZipArchive::EM_AES_256`. This requires **PHP 7.2+ built with libzip 1.2.0+**; if `ZipArchive::EM_AES_256` is unavailable the backup fails with a clear runtime error rather than silently producing an unencrypted archive. Header encryption is per-file, so filenames within the ZIP remain visible (only file contents are encrypted).
+
+### 7z encryption details
+
+For 7z, the password is passed to `SevenZipArchiver::setEncryptionPassword()` before the archive is built. The archiver invokes the `7z`/`7za` CLI with `-mhe=on` (encrypt archive headers, so **filenames are also hidden**) and `-p<password>`. This requires `p7zip-full` (Linux) or 7-Zip (Windows) to be installed on the server.
+
+## How the password is handled
+
+- The password is stored in the profile row (`encryption_password`). It is used directly to encrypt the archive; the extension does **not** derive or store a separate key — key derivation is performed by the underlying ZIP/7z encryption implementation.
+- The REST API **never** returns the password: the `GET /profiles` endpoint masks `encryption_password` (and all other credential fields) as `***`. See [REST API](REST-API).
+- If encryption is configured but the encryption step fails, `BackupEngine` **deletes the plaintext archive** and records the failure, so an un-encrypted copy is never left behind:
+  `Plaintext archive removed after encryption failure`.
+
+## Restoring an encrypted archive
+
+The password is required to extract the archive. It is not embedded in the backup, so it must be supplied at restore time (or kept in the profile for automated restores). Keep the password safe — **without it the backup cannot be decrypted or restored.**
+
+## Related sanitization
+
+Encryption protects the archive at rest; it is independent of the profile's data-sanitization options (`sanitize_passwords`, `sanitize_emails`, `sanitize_sessions`, `preserve_super_admin`), which strip or mask sensitive database contents inside the dump, and of the automatic `configuration.php` credential stripping (stored as `configuration.php.bak`). Use both together for the strongest protection when shipping backups off-site.