Skip to content

Secrets

Some secrets have to be stored by the application and read back later. A typical case: your application lets each customer connect their own S3 bucket, so the customer enters an access key and a secret key that you have to save in the database and use on every upload. Unlike a password, such a value cannot be hashed, because the application needs the original to talk to S3.

ZubZet encrypts these values at rest with a key from z_config/z_settings.ini. The database only ever holds the encrypted value, so a leaked dump or backup alone does not reveal the customers' credentials. The application decrypts a value right before using it.

Setting the key

Encryption needs PHP's OpenSSL extension, which the framework declares as a requirement in its composer.json.

Add an encryption_key of at least 32 bytes to z_config/z_settings.ini. The length is counted in bytes, so a key of plain ASCII characters, like the generated one below, needs 32 characters:

encryption_key = 2f6c1d9e8a7b4c3d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5

Generate a random one, for example with:

php -r 'echo bin2hex(random_bytes(32)), PHP_EOL;'

Wrap a key that contains = or !, such as a base64 one, in double quotes, otherwise z_settings.ini cannot be parsed:

encryption_key = "0WLTPAWOP15mDT/gBrdw/RMbctM7TFVXaPViz3y8AtA="

Keep the key out of the repository and never lose it

Anyone with the key and the database can decrypt every value, so provide it through the environment (CONFIG_ENCRYPTION_KEY with allow_env_config = true, see Installation) instead of committing it. Environment variables only override settings that exist in z_settings.ini, so keep an empty encryption_key = line there; without it CONFIG_ENCRYPTION_KEY is ignored. Values encrypted with a key cannot be decrypted without it: changing or losing the key makes every stored value unreadable.

Storing a secret

The global helpers encryptSecret() and decryptSecret() cover the usual case. Encrypt the value before it reaches the model, and decrypt it only where it is used:

// Saving the bucket credentials a customer entered
model("Bucket")->saveCredentials(
    $companyId,
    $req->getPost("accessKey"),
    encryptSecret($req->getPost("secretKey")),
);

// Using them for an upload
$bucket = model("Bucket")->getByCompany($companyId);
$secretKey = decryptSecret($bucket["secret_key"]);

The same methods are available on the ZubZet\Framework\Security\Secrets\Encryption class:

use ZubZet\Framework\Security\Secrets\Encryption;

$encrypted = Encryption::encryptSecret($secretKey);
$secretKey = Encryption::decryptSecret($encrypted);

Every call to encryptSecret() uses a fresh random IV, so encrypting the same value twice gives two different results. Compare decrypted values, never encrypted ones, and do not search or index the encrypted column.

Detecting a wrong key

Values are encrypted with AES-256-GCM, which authenticates the ciphertext. Decryption therefore never returns garbage: when the key is wrong, or the stored value was modified, truncated or is not an encrypted value at all, decryptSecret() throws a ZubZet\Framework\Security\Secrets\DecryptionException.

use ZubZet\Framework\Security\Secrets\DecryptionException;

try {
    $secretKey = decryptSecret($bucket["secret_key"]);
} catch(DecryptionException $e) {
    // Wrong encryption_key, or the stored value is damaged
}

A missing encryption_key, or one shorter than 32 bytes, throws a RuntimeException, so a misconfiguration is noticed before anything is stored. Decryption checks the value first: a value that is not in the encrypted format throws the DecryptionException even when the key is missing.

Stack traces

PHP copies the first 15 bytes of every argument into an exception's stack trace, which the framework logs. From PHP 8.2 on, #[\SensitiveParameter] hides the secret and the key there. On PHP 8.0 and 8.1 set zend.exception_ignore_args = On in php.ini.

Storage format

An encrypted value is plain text of the form zenc:aes-256-gcm: followed by base64url. Encrypting the 40 character S3 secret key wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY stores this in the database:

zenc:aes-256-gcm:ydhF8rgskJ4UnMKoACkDLA2jApTRBmneKl8pqgVYTBb2QOiipP6hs7KLeNTy1JEWkeW2FWxaulfmY_H4PNn46oyTAh4

zenc marks the value as encrypted, aes-256-gcm names the cipher, and the rest holds the random IV, the authentication tag and the ciphertext. The value only contains A-Z, a-z, 0-9, -, _ and :, so it can be stored in a VARCHAR or TEXT column and passed through URLs, JSON or environment variables without escaping. It is about (length × 4 / 3) + 55 characters long, 108 for the key above; a TEXT column avoids having to size it.

Any string can be encrypted, including binary data. To store several values together, encrypt them as JSON:

$stored = encryptSecret(json_encode(["accessKey" => $accessKey, "secretKey" => $secretKey]));
$credentials = json_decode(decryptSecret($stored), true);

The cipher key is derived from encryption_key with HKDF-SHA256, so the setting may be any sufficiently long random string, in double quotes if it contains = or !.

Changing the algorithm

Every value names the cipher it was encrypted with, so the framework can switch to a different algorithm without breaking stored values. A cipher is a class implementing ZubZet\Framework\Security\Secrets\Cipher\Cipher, registered under a fixed identifier in Encryption::CIPHERS. A new default only affects values encrypted from then on; existing values keep decrypting with the cipher they name, as long as it stays registered. Only authenticated ciphers qualify, otherwise a wrong key could no longer be detected.