drupal / mutamad_crypto
Cryptography, key management and multi-factor authentication for Mutamad: authenticated AES-256 with keys held outside the database and the web root, and MFA with an authenticator app. Aligned to NCA ECC-2:2024 2-2-2 and the cryptography controls.
Package info
git.drupalcode.org/project/mutamad_crypto.git
Type:drupal-recipe
pkg:composer/drupal/mutamad_crypto
Requires
- drupal/core: ~11.4.0
- drupal/encrypt: ~3
- drupal/key: ~1
- drupal/real_aes: ~2
- drupal/tfa: ^2.0
Requires (Dev)
None
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is not auto-updated.
Last update: 2026-11-16 06:07:01 UTC
README
Mutamad Crypto
Cryptography, key management and multi-factor authentication for Mutamad: authenticated AES-256 (Real AES) with keys held outside the database and the web root, and MFA with an authenticator app whose secrets those keys protect.
Built and maintained by iSpectra.
Why a recipe of its own
So that "where are the keys, and what encrypts with them?" has one answer — together with MFA, the control built on them. Other Mutamad recipes use what this ships; none creates keys of its own.
| Key and profile | Encrypts |
|---|---|
mutamad_tfa | Each user's MFA (authenticator) secret |
Field encryption of classified content will be added here with a key of its own. Rotating or losing one key must never affect what another protects.
Multi-factor authentication (NCA ECC 2-2-2)
An authenticator app (TOTP — Google Authenticator, Microsoft Authenticator,
FreeOTP…) plus 10 one-time recovery codes. Required for content approvers,
site administrators and administrators; any other staff account may enrol.
Each secret is encrypted with the mutamad_tfa key.
The required roles are named by id: they come from
mutamad_roles, but this
recipe does not require it, and a role that does not exist yet simply has
nobody in it. Mutamad's site template applies both, and grants
site_admin the right to administer other users' MFA.
Enrolling, and getting back in
A user in a required role is sent to the setup page on login and has 3
logins to enrol. After that the account is refused with "Contact support to
reset your access". To give it its 3 logins back (drush tfa:reset-user clears
a user's MFA secrets, but not this count):
drush php:eval \
"\Drupal::service('user.data')->delete('tfa', UID, 'tfa_user_settings');"
Requirements
- Drupal core 11.4. Composer brings Key, Encrypt, Real AES (with the
defuse/php-encryptionlibrary) and TFA. TFA's alpha must be allowed. TFA 2 has no stable Drupal 11 release, and Composer honours stability flags only in the root
composer.json.drupal/mutamad_projectalready allows it; any other site runs:composer require 'drupal/tfa:^2.0@alpha'drupal.org security advisories do not cover alpha releases. Say so in your risk register until TFA 2 is stable.
- A private files directory (
file_private_path), because the key file lives in it. The Mutamad project template puts it outside the web root. - The key file itself — see below.
Apply it to an existing site
Create the key file first (next section), then:
composer require drupal/mutamad_crypto 'drupal/tfa:^2.0@alpha'
drush recipe ../recipes/mutamad_crypto
From then on, every user in a required role is sent to MFA setup at their next login, with 3 logins to enrol. Tell them before you apply it.
Keys are not configuration
A key entity only says where its key lives. The key itself — 32 random bytes,
base64 — is a secret, so no recipe ships it. The Mutamad installer generates
it into <private files>/mutamad-keys/, outside the web root and the
database, readable by the web server and its group only.
Applied to a site the installer did not build, create it first:
KEYS='<private files directory>/mutamad-keys'
mkdir -p "$KEYS"
head -c 32 /dev/urandom | base64 > "$KEYS/tfa.key"
chmod 640 "$KEYS/tfa.key"
Never replace an existing key file. Everything encrypted with it becomes
unreadable; for mutamad_tfa, every enrolled user is locked out of MFA. Back
key files up with the site's secrets, not with its database — a backup that
holds both the data and its key protects neither.
To keep a key elsewhere, a secrets mount for example, override its location in settings.local.php:
$config['key.key.mutamad_tfa']['key_provider_settings']['file_location']
= '/run/secrets/mutamad_tfa.key';
Who manages keys
Nobody but the break-glass administrator. administer keys and
administer encrypt are granted to no role: whoever can change a key can make
everything it protects unreadable.
Checked
ddev mutamad-verify (from drupal/mutamad_project) checks on the running
site that MFA is on, uses an authenticator app and is required for the
privileged roles; that the key is present and 256 bits, lives outside the web
root and actually encrypts and decrypts; and that no role but the administrator
can manage keys.
License
GPL-2.0-or-later.
Maintainers
Built and maintained by iSpectra (on drupal.org).
