update documentation

web/messages/en/docs/backup-restore/destinations/pbs.json

@@ -50,6 +50,7 @@
   },
   "encryption": {
     "heading": "Client-side encryption",
+    "glossaryHint": "This section uses the terms <em>keyfile</em>, <em>passphrase</em> and <em>recovery envelope</em>. If it ever gets hard to keep them apart, the <glosarioLink>glossary</glosarioLink> summarises the differences in one sentence per term.",
     "intro": "PBS client-side keyfile encryption encrypts chunks on the source host before upload. ProxMenux enables the feature with one added constraint: a recovery passphrase is mandatory when encryption is enabled. The passphrase does not protect the local keyfile; it protects the escrow copy of the keyfile that ProxMenux uploads to PBS for disaster recovery.",
     "keyfileTitle": "Keyfile",
     "keyfileBody": "The encryption prompt is a two-step yes/no. Step one asks whether to encrypt the backup: <em>No</em> continues without encryption; <em>Yes</em> moves to step two. Step two depends on whether a keyfile is already installed at <code>/usr/local/share/proxmenux/pbs-key.conf</code>. If it is, the installed keyfile is reused silently and the backup proceeds. If it is not, a two-option menu asks how to set one up. <em>Generate a new keyfile</em> runs <code>proxmox-backup-client key create --kdf none</code> — the resulting keyfile has no passphrase, so the scheduled runner can use it under systemd without any interactive prompt. <em>Import an existing keyfile</em> takes a path the operator supplies and copies it into place with <code>chmod 600</code>; ProxMenux does not inspect the contents (any keyfile the operator accepts as valid on their PBS is accepted here, including scrypt-encoded keyfiles that could not be validated non-interactively). When importing, the flow also asks for the keyfile's own passphrase — the one that <code>proxmox-backup-client key create --kdf scrypt</code> asked for at creation. That passphrase is persisted at <code>/usr/local/share/proxmenux/pbs-key.pass</code> (chmod 600) and reused by every encrypted job on this host as <code>PBS_ENCRYPTION_PASSWORD</code>. Leaving it blank means the keyfile is <code>--kdf none</code> (no passphrase). Both branches run only after the recovery passphrase has been confirmed — cancelling any dialog before that point leaves the disk unchanged.",
@@ -62,9 +63,11 @@
     "recoveryTitle": "Recovery passphrase and escrow blob",
     "recoveryBody": "The recovery passphrase is asked BEFORE any keyfile is written to disk. ProxMenux prompts twice with match validation; then, only if the operator confirms, the keyfile is created (or imported) and <code>openssl</code> produces <code>pbs-key.recovery.enc</code> — the keyfile encrypted with the passphrase. A copy is written to <code>/root/pbs-key.recovery-HOSTNAME-YYYYMMDD.enc</code> for offsite storage. Cancelling the passphrase dialog leaves the disk untouched — no keyfile is created and no cleanup is needed.",
     "blobUploadTitle": "Paired backup group on PBS",
-    "blobUploadBody1": "After a PBS backup that used the keyfile, the escrow blob is uploaded as a second backup group: <code>host/hostcfg-HOSTNAME-keyrecovery/BACKUP-TIME</code>. The shared <code>hostcfg-HOSTNAME</code> prefix places both groups adjacent in the PBS UI; the <code>-keyrecovery</code> suffix labels the relationship. The upload runs without <code>--keyfile</code> (the blob is already passphrase-protected by openssl) and only when the current backup used the keyfile.",
-    "blobUploadConstraintTitle": "Why two groups",
-    "blobUploadConstraintBody": "<code>--keyfile</code> is a per-invocation flag in <code>proxmox-backup-client backup</code>: all archives in a single invocation are encrypted with the keyfile or none are. <code>hostcfg.pxar</code> requires encryption; <code>keyrecovery.conf</code> cannot be encrypted with the same keyfile (fresh-install recovery would then require the keyfile it is meant to recover). Two invocations, two backup IDs.",
+    "blobUploadBody1": "After a backup that used the keyfile, ProxMenux uploads the recovery envelope to PBS as a second, paired backup group with the same name as the host group but ending in <code>-keyrecovery</code>. The two groups sit next to each other in the datastore listing — one for host backups, one for recovery envelopes. <strong>The envelope never leaves the host in plaintext</strong>: before upload, ProxMenux encrypts it on the host itself with AES-256-CBC, using a key derived from the recovery passphrase via PBKDF2 with 600 000 iterations and a random salt (<code>openssl enc -aes-256-cbc -pbkdf2 -iter 600000 -salt</code>). PBS receives only the already-encrypted envelope, and the upload happens only when the main backup was encrypted.",
+    "envelopeSecurityTitle": "Is uploading the keyrecovery file to PBS a security risk?",
+    "envelopeSecurityBody": "The keyrecovery file is encrypted in transit and at rest. The recovery passphrase never leaves the host: encryption happens locally before the upload, and PBS only ever sees the already-encrypted result. A PBS administrator — or anyone with access to the datastore — can download the keyrecovery file, but without the recovery passphrase they cannot read the keyfile inside: it is opaque ciphertext. Reconstructing the keyfile requires both pieces at once, the keyrecovery file and the passphrase, and only the operator holds both.",
+    "blobUploadConstraintTitle": "Why two groups instead of a single encrypted one",
+    "blobUploadConstraintBody": "A single <code>proxmox-backup-client backup</code> invocation encrypts every one of its archives with the same keyfile, or none at all — there is no in-between. The host backup has to be encrypted with the host keyfile, but the recovery envelope cannot ride along in that same upload, because it would end up encrypted with the very keyfile it contains: on a freshly reinstalled host there would be no way to open it (you would need the keyfile to decrypt the keyfile). That is why the two artefacts are uploaded independently and appear as two separate groups: the host backup is encrypted by PBS with the keyfile, and the recovery envelope is encrypted by ProxMenux with the passphrase before upload. Two different encryption layers protecting two different assets.",
     "blobUploadImageAlt": "PBS UI showing the hostcfg-HOSTNAME and hostcfg-HOSTNAME-keyrecovery backup groups adjacent in the datastore listing.",
     "blobUploadImageCaption": "PBS UI — the paired backup groups. The main group holds the host backups; the -keyrecovery group holds the escrow blob.",
     "recoverTitle": "Fresh-install recovery",