App Secret
Introduction
Every Windwalker application has one root secret, read from the APP_SECRET environment variable. The framework uses it as the input for keys that protect data, so one value in the environment controls every derived key. Keep it unique to each environment and out of the code.
This page covers the secret itself. For how environment files are loaded, see environment variables.
Minimal Setup
The framework generates APP_SECRET automatically when the application is first set up. You only need to generate a new value when you rotate the secret. Use the crypt:secret command with --replace to write the new value into .env without pasting it by hand:
php windwalker crypt:secret --replaceThe command prints a random value with the base64url: prefix. The prefix tells the framework how to decode it. Without --replace, add the printed output to your environment file:
# .env.local
APP_SECRET=base64url:...The application configuration reads the variable into app.secret:
// etc/conf/app.config.php
return [
'secret' => env('APP_SECRET'),
];INFO
crypt:secret --replace writes to .env by default, not .env.local. Use --output to write the value to a file of your choice.
If you run this command without --replace, the output is a plain random value, so you can also use it outside the application:
- Copy it by hand into a secret or key setting of another system.
- Change the encoding format with the command options when the target system expects a different format.
- Omit the prefix when the consumer does not expect
base64url:.
Run php windwalker crypt:secret --help to see the available options. Without --replace, the command works as a simple password or key generator.
A Complete Example
The following is a designed example, not a framework class. A service that signs download links asks SecretKeeperInterface for a key derived for that one purpose:
use Windwalker\Core\Application\SecretKeeperInterface;
class DownloadSigner
{
public function __construct(
protected SecretKeeperInterface $secrets,
) {}
public function sign(string $path, int $expires): string
{
$key = $this->secrets->getSecret('download-link');
return hash_hmac('sha256', "$path|$expires", $key);
}
}The service receives the keeper through its constructor, so the application container supplies it. The derived key differs from the root secret and from keys derived for other purposes.
getSecret() is also available on AppContext and ApplicationInterface. Inject SecretKeeperInterface when you do not want to depend on the whole application. The service then depends only on the secret.
A Complete Example
A service that signs download links should not use the master secret directly. It asks SecretKeeperInterface for a key that is derived for one purpose:
use Windwalker\Core\Application\SecretKeeperInterface;
class DownloadSigner
{
public function __construct(
protected SecretKeeperInterface $secrets,
) {}
public function sign(string $path, int $expires): string
{
$key = $this->secrets->getSecret('download-link');
return hash_hmac('sha256', "$path|$expires", $key);
}
}The derived key is different from the master secret and from the keys derived for other purposes. A leaked download link therefore does not reveal a key that is used for sessions or encryption.
Derived Keys
getSecret() takes an optional purpose name. With a name, it returns a 32-byte key derived with HKDF-SHA256. The name is the HKDF info string, and no salt is used. Use one name per purpose, kept in a constant so signing and verification use the same value (designed example):
final class KeyPurpose
{
public const DOWNLOAD_LINK = 'download-link';
}
$key = $secrets->getSecret(KeyPurpose::DOWNLOAD_LINK);Without a name, getSecret() returns the decoded root secret. Use that form only when a library needs the raw value.
TIP
Do not use the raw root secret directly, for any purpose. Derive a new key with a purpose name instead, so each use gets its own key.
The framework itself uses this pattern. TaskPayload signs task payloads with a key derived for the task.run purpose.
WARNING
A purpose name must match exactly. A changed or misspelled name derives a different key, so existing signatures stop verifying.
Empty Secret Behavior
If APP_SECRET is not set, env() returns null, and the keeper returns an empty string for the unnamed call. The named call fails:
getSecret()with no name returns''and raises no error.getSecret('name')throws aValueErrorfromhash_hkdf().- Task signing throws a
LogicException("An application secret is required") when the secret is empty.
WARNING
An unset secret does not stop unnamed calls. Check that APP_SECRET is set in every environment before you deploy.
Rotating the Secret
Changing APP_SECRET changes every key derived from it, so signatures and encrypted data made with the old value no longer verify. The source does not define a rotation procedure, so plan the migration yourself.
WARNING
Rotation invalidates data protected with the old secret. Re-encrypt stored data and reissue signed links before you retire the old value.
Storage and Safety
Keep a separate secret for each environment, and keep it out of the code.
WARNING
Never commit APP_SECRET to git. Do not print it in logs or error pages. Store it in .env.local or in the server environment.
Related Pages
- Encryption for protecting data at rest.
- Hashing for one-way hashes such as passwords.
- Crypt component for the standalone cryptography package.