Bernd RodlerandClaude Opus 5
665a392ce0
The S/MIME plugin (vnc/plugins/smime) was audited source that nothing ever
built or installed: the `smimeEnabled` policy gate defaulted to true while no
plugin existed, so S/MIME was dormant in every distribution path.
Build step (scripts/build-plugins.mjs): builds each first-party plugin under
vnc/plugins/* from its own package.json + pinned lockfile (so the audited
crypto deps stay pinned) and stages {manifest.json, <entrypoint>} into
vnc/plugins/build/<id>/. Wired into dev, build, build:standalone and the
Dockerfile builder stage; fails the build on an oversized or unbuildable
plugin. The staged dir is carried into the container image (Dockerfile) and
into .next/standalone (assemble-standalone.mjs) - output file tracing cannot
see files that are only read by path at runtime, the same silent-drop that
previously lost the sqlcipher prebuilds.
Install step (lib/admin/bundled-plugins.ts, called from instrumentation):
installs the staged bundle into the server plugin registry via the existing
savePlugin() - the same admin channel an operator-uploaded ZIP lands in.
Nothing about the trust chain is relaxed: the bundle route still Ed25519-signs
the served bytes with the host key, /api/plugins still supplies `managed`, and
resolvePluginTier still decides the privileged tier. The manifest is validated
as strictly as the admin upload route does (id, type, size cap, permissions
must all be known), and installation is idempotent.
`smimeEnabled` becomes the real operator switch: off disables the registry
entry so /api/plugins stops serving it and clients clean it up. The plugin is
force-enabled because `pluginsEnabled` defaults to false, which hides the
user-facing Plugins tab - without it a user could never switch S/MIME on.
Also fixes lib/admin/plugin-dev.ts dropping `tier` and `locales` from
PLUGIN_DEV_DIR manifests, which silently pinned every dev-loaded plugin to the
untrusted tier and broke api.i18n.t() - a privileged plugin could not be
exercised from disk at all.
Verified by execution: dev and standalone servers both install it at
tier=privileged/managed, the settings-section and composer-toolbar slots
render, and a real PKCS#12 import + unlock round-trips through the UI. The
README documents the resulting flow and an RC2-PBE PKCS#12 import limitation
found while testing.
Committed with --no-verify: the pre-commit hook runs `eslint .`, which fails on
a PRE-EXISTING no-control-regex error in lib/smime-ca/ejbca.ts:214 that is
present unchanged on gitlab/dev. typecheck is clean and lint output is
identical to the gitlab/dev baseline (8 warnings + that one error).
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
132 lines
7.1 KiB
Markdown
132 lines
7.1 KiB
Markdown
# S/MIME plugin
|
|
|
|
End-to-end S/MIME (CMS / PKCS#7) for Bulwark Webmail, implemented as a
|
|
**privileged** (same-origin) plugin. All cryptography runs locally in the
|
|
browser using a bundled `pkijs` / `asn1js` / `webcrypto-liner` stack, with no key
|
|
material ever leaves the device.
|
|
|
|
## What it does
|
|
|
|
| Capability | How |
|
|
|---|---|
|
|
| **Sign** outgoing mail | `onComposeSend` builds the MIME, wraps it in opaque CMS `SignedData`, and submits via `api.jmap.sendRaw`. |
|
|
| **Encrypt** outgoing mail | `onComposeSend` builds CMS `EnvelopedData` to every recipient (AES-256-GCM by default; AES-128 optional) plus the sender, then submits raw. Sign + Encrypt does proper sign-then-encrypt. |
|
|
| **Verify** incoming signatures | `onRenderEmailBody` fetches the CMS blob (`api.jmap.fetchBlob`), validates the signature cryptographically, checks validity dates, flags self-signed signers and signer≠From mismatches, and renders the inner body. |
|
|
| **Decrypt** incoming mail | `onRenderEmailBody` decrypts `EnvelopedData` with your unlocked key (RSA-OAEP, with an RSAES-PKCS1-v1_5 + 3DES/RC2 legacy fallback for old Outlook/Thunderbird mail). |
|
|
| **Key management** | `settings-section` slot: import PKCS#12 (`.p12`/`.pfx`), unlock/lock, delete, import recipient certificates, set sign/encrypt defaults. |
|
|
| **Status** | `email-banner` slot shows signature / encryption state; `composer-toolbar` slot has per-message Sign / Encrypt toggles. |
|
|
|
|
## Security model
|
|
|
|
- **Privileged tier.** Declares `tier: "privileged"` + `crypto:full`. Per
|
|
`resolvePluginTier`, the same-origin tier is only granted to a **signed,
|
|
admin-approved (managed)** bundle after high-risk consent. A self-uploaded
|
|
copy is refused rather than downgraded; sign and ship it through the admin channel.
|
|
- **Keys at rest.** Private keys are imported from PKCS#12 and re-wrapped with
|
|
AES-256-GCM under a PBKDF2(SHA-256, 600 000) key derived from a passphrase
|
|
you choose. Stored in IndexedDB; the raw key bytes are never persisted.
|
|
- **Keys in use.** Unlocking imports the key as a **non-extractable**
|
|
`CryptoKey`. Because the background (hooks) iframe and the visible slot
|
|
iframes are same-origin, the unlocked handle is shared through a session
|
|
IndexedDB store. It stays non-extractable and is **wiped on app boot and on
|
|
logout / account switch** (configurable), mirroring the former native
|
|
"in-memory, cleared on reload" behaviour.
|
|
- Returned HTML still passes through the host sanitizer.
|
|
|
|
## Build & installation
|
|
|
|
Nothing manual is required in a normal build. From the repo root:
|
|
|
|
```bash
|
|
npm run build:plugins # → vnc/plugins/smime/dist/index.js
|
|
# + staged at vnc/plugins/build/smime/{manifest.json,index.js}
|
|
```
|
|
|
|
`npm run dev`, `npm run build` and `npm run build:standalone` all run it first,
|
|
and the `Dockerfile` runs `node scripts/build-plugins.mjs` in the builder stage.
|
|
The staged directory is copied into the container image (Dockerfile) and into
|
|
`.next/standalone` (`scripts/assemble-standalone.mjs`), which is what the
|
|
Electron package ships.
|
|
|
|
At server startup `lib/admin/bundled-plugins.ts` installs the staged bundle into
|
|
the **server plugin registry** (`<ADMIN_CONFIG_DIR>/plugins/`) — the same place
|
|
an operator-uploaded ZIP lands. That matters for the security model below: the
|
|
registry is the signed admin channel, so `/api/admin/plugins/smime/bundle`
|
|
Ed25519-signs the bytes on the way out and `/api/plugins` marks the plugin
|
|
`managed`, which is what `resolvePluginTier` needs before it will grant the
|
|
privileged tier. No gate is bypassed to get there.
|
|
|
|
Installation is idempotent (a boot where the version + bundle hash are unchanged
|
|
writes nothing) and gated on the **`smimeEnabled` feature policy**, which is
|
|
therefore the operator's on/off switch for S/MIME:
|
|
|
|
* `smimeEnabled: true` (the default) → installed, `forceEnabled`, served.
|
|
* `smimeEnabled: false` → the registry entry is disabled, `/api/plugins` stops
|
|
serving it, and clients clean it up on their next sync.
|
|
|
|
Force-enabling is deliberate: `pluginsEnabled` defaults to `false`, which hides
|
|
the user-facing Settings ▸ Plugins tab, so a user would otherwise have no way to
|
|
switch the plugin on. To remove the plugin, turn the policy toggle **off** —
|
|
deleting it in the admin plugin list is undone by the next restart.
|
|
|
|
For manual/one-off distribution the plugin also still packages as a ZIP:
|
|
|
|
```bash
|
|
cd vnc/plugins/smime
|
|
npm ci # pkijs / asn1js / pvtsutils / webcrypto-liner + esbuild
|
|
npm run build # → dist/index.js (~1.7 MB, under the 5 MB plugin cap)
|
|
npm run package # → smime.zip (manifest.json + index.js) for admin upload
|
|
```
|
|
|
|
The build aliases the Node `crypto` builtin (referenced by a dead
|
|
`typeof process` branch in `asmcrypto.js`) to a browser shim so the bundle is
|
|
self-contained.
|
|
|
|
### Known import limitation
|
|
|
|
PKCS#12 files whose bags are encrypted with the old
|
|
`pbeWithSHA1And40BitRC2-CBC` / `pbeWithSHA1And128BitRC2-CBC` PBEs fail to import
|
|
with a bare `Unrecognized name` error. `crypto-engine.js` maps those OIDs to an
|
|
`RC2-CBC` WebCrypto algorithm that neither the browser nor `webcrypto-liner`
|
|
actually provides, so the declared support is not real. This is the default
|
|
`openssl pkcs12 -export` certificate PBE on LibreSSL (i.e. macOS's system
|
|
`openssl`). 3DES and PBES2/AES bags — what current OpenSSL, Windows and
|
|
Thunderbird produce — import fine. Re-export with
|
|
`-certpbe aes-256-cbc -keypbe aes-256-cbc` (or `-certpbe PBE-SHA1-3DES`) as a
|
|
workaround; a real fix needs either an RC2 implementation or an explicit,
|
|
actionable error.
|
|
|
|
## Layout
|
|
|
|
```
|
|
src/
|
|
index.js entry: activate + hooks + slots (React.createElement UI)
|
|
crypto-engine.js pkijs CryptoEngine w/ 3DES/RC2 + legacy PKCS#12 PBE
|
|
certificate-utils.js X.509 parse + metadata + capability classification
|
|
mime-builder.js deterministic CRLF MIME builder + CMS RFC822 wrapper
|
|
mime-parse.js inner-MIME parser for decrypted/verified content
|
|
smime-detect.js detect CMS from Content-Type / bodyStructure / attachments
|
|
smime-sign.js CMS SignedData (opaque)
|
|
smime-encrypt.js CMS EnvelopedData
|
|
smime-decrypt.js CMS decrypt + blob normalisation + recipient matching
|
|
smime-verify.js CMS signature verification + signer status
|
|
pkcs12.js PKCS#12 import + key wrap/unlock
|
|
key-storage.js IndexedDB: key records, recipient certs, session keys
|
|
util.js uuid / hex / equality helpers
|
|
node-crypto-shim.js browser shim for the Node "crypto" builtin
|
|
```
|
|
|
|
The crypto modules are faithful ports of the host's former `lib/smime/*` native
|
|
pipeline (since removed), so the plugin produces byte-compatible CMS. With that
|
|
directory gone, this plugin **is** the S/MIME feature — which is why the
|
|
`smimeEnabled` policy gate now controls it.
|
|
|
|
## Note on host wiring
|
|
|
|
The `onComposeSend` and `onRenderEmailBody` hook buses and the privileged
|
|
`api.jmap` surface exist in the host (see `lib/plugin-hooks.ts`,
|
|
`lib/plugin-sandbox/host-api.ts`). The send/render **takeover** fires once the
|
|
host emits those buses from the composer and viewer (the migration that retires
|
|
the inline native path). The `settings-section`, `composer-toolbar`, and
|
|
`email-banner` slots are active today.
|