Search by

drupal / mutamad_crypto

Drupal-Infrastructure

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

Homepage

Issues

Type:drupal-recipe

pkg:composer/drupal/mutamad_crypto

Statistics

Installs: 61

Dependents: 1

Suggesters: 0

1.0.x-dev 2026-11-12 17:39 UTC

This package is not auto-updated.

Last update: 2026-11-16 06:07:01 UTC


README

Mutamad Crypto — التشفير

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 profileEncrypts
mutamad_tfaEach 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-encryption library) 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_project already 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

iSpectra

Built and maintained by iSpectra (on drupal.org).