AES-256 usually fails at the seams, not in the algorithm. In PHP, the hard part is rarely calling openssl_encrypt(). The hard part is deciding how the key enters the application, how the IV is generated and packaged, how malformed payloads are rejected, and how you prove the workflow still works after a rotation or refactor.
Most developers who search for an encrypt/decrypt starter kit are really asking four narrower questions. Which AES mode is the reasonable default? Where should the key live? How do I package IV, ciphertext, and tag without creating parsing bugs? What tests catch mistakes before production does? Security is one of those domains where boring structure is a feature, not a lack of imagination.
The problem is significant because PHP makes encryption available, but availability is not the same thing as a safe workflow. The PHP manual for openssl_encrypt() and openssl_decrypt() explains the API surface, while the OWASP Cryptographic Storage Cheat Sheet and OWASP Key Management Cheat Sheet frame the operational decisions around storage, rotation, and secret handling.
By the end of this guide, you will have a practical workflow for encrypt -> package -> store -> parse -> decrypt -> test, plus a shortlist of failure modes worth checking before you call the implementation finished. If you need adjacent site references while planning, the home page, blog index, Sources/Functions…, Reports & Tracking, and Support sections are the natural companions.
What an encryption workflow means in PHP
Think in terms of inputs and boundaries, not just functions. A usable PHP encryption workflow has six parts:
- Plaintext input: the value your application must later recover.
- Key material: a 32-byte secret for AES-256, loaded from a managed source.
- IV or nonce: generated per encryption operation.
- Cipher mode: ideally one that provides confidentiality and authenticity together.
- Output format: a versioned transport-safe string or object that includes the metadata decryption needs.
- Validation path: strict parsing rules before any decrypt call runs.
The question is not “can PHP encrypt this value?” The better question is “can the next deploy, the next key rotation, and the next incident review still understand this payload without guesswork?” If the answer is no, the implementation is only halfway built.
| Workflow part | Reasonable default | Watch for |
|---|---|---|
| Key source | Environment variable or secret manager | Hard-coded secrets and copied test keys |
| IV/nonce | random_bytes(openssl_cipher_iv_length(...)) |
Reusing one IV across records |
| Mode | AES-256-GCM when available | Using CBC without separate authentication |
| Packaging | Version + key ID + base64url fields | Undocumented delimiter choices and silent parser drift |
| Testing | Known vector + round-trip + tamper cases | Happy-path-only tests |
AES-256 basics for developers: pick the mode before you write helpers
AES-256 describes the key size, not the full operating behavior. In PHP you still need to choose the mode, and that choice changes the rest of the workflow.
AES-256-GCM is the reasonable default for new application-level encryption in PHP when your OpenSSL build supports it. GCM is an authenticated encryption mode, which means it protects confidentiality and also gives you an authentication tag that helps detect tampering. NIST’s SP 800-38D guidance on GCM is worth keeping in your reference set because it frames why IV handling and tag verification matter.
AES-256-CBC can still appear in legacy code and integration constraints, but it requires more discipline. If you use CBC, you need a separate integrity mechanism such as an HMAC, and you must verify that integrity before you trust decrypted data. That is exactly why many teams prefer GCM for new work: it reduces the number of moving parts you have to remember under deadline pressure.
| Mode | Best fit | Operational note |
|---|---|---|
| AES-256-GCM | New PHP application workflows | Includes an auth tag; do not ignore it on decrypt |
| AES-256-CBC | Compatibility work and older integrations | Needs separate authentication; more failure modes |
If you need a plain decision rule, use this one: for new code, start with GCM; for inherited CBC, contain it and document the migration path. The safest reasonable default is usually the correct one.
Key handling checklist: where keys live and what rotation really changes
Most application failures come from key handling, not from AES itself. A well-structured encryption helper with weak key management is still weak. That is the part teams often discover after the feature ships.
Use this checklist before writing the first production record:
- Keep the encryption key outside the repository. Environment-backed secrets, deployment secrets, or a managed secret store are the normal options.
- Store a binary-safe key, not a memorable phrase. In practice, teams often keep a base64-encoded 32-byte key in an environment variable and decode it at runtime.
- Validate the decoded key length explicitly. Do not assume the environment is correct because the variable exists.
- Assign a key ID. New writes should know which key version they used.
- Plan for read compatibility during rotation. Rotation means “new key for new writes, old keys still available for old reads” until migration is complete.
Hard-coded secrets are not a shortcut; they are deferred maintenance with extra blast radius. The PHP OpenSSL APIs will accept values that are the wrong shape unless you validate them yourself. That is one reason a small wrapper class is better than scattering crypto calls across controllers and utility files.
Rotation deserves a concrete mental model. Suppose the current key is k1 and you promote k2. The application should start encrypting new values with k2, continue decrypting old payloads marked k1, and optionally re-encrypt old records to k2 in background batches. Rotation is a compatibility exercise first, a cleanup exercise second.
If your team is building an internal dashboard to review secret versions, migration counts, or safe decrypt jobs, a neutral third-party web app generator can help with scaffolding the interface. It does not replace the ownership model, but it can reduce boilerplate around internal operations tooling.
IV and nonce strategy: generate per message, store with ciphertext
An IV or nonce is not optional metadata. It is part of the cryptographic construction. The practical rule is simple: generate a fresh IV or nonce for every encryption operation and package it with the ciphertext.
For GCM in common PHP/OpenSSL builds, openssl_cipher_iv_length('aes-256-gcm') typically returns 12 bytes. For CBC, the IV length is commonly 16 bytes. Do not hard-code these values when the runtime can tell you the correct length. That keeps the code honest and avoids subtle breakage if the chosen cipher changes.
What you should not do:
- Reuse one IV from a config file.
- Derive IVs from usernames, timestamps, or counters unless the construction explicitly calls for it and you have reviewed the implications.
- Hide the IV as though it were the secret.
The IV travels with the ciphertext because decryption needs it. The key stays separate because compromise of the key breaks confidentiality; visibility of the IV does not. That distinction saves a surprising amount of confusion during code review.
Output formatting: package for transport, then parse back strictly
Binary ciphertext is awkward in URLs, JSON payloads, and common database fields. That is why many PHP teams package the raw binary outputs into base64 or base64url strings. The important distinction is that base64 is a transport format, not a protection layer.
A practical payload format can be plain text and still be durable:
v1.k1.aes-256-gcm.<base64url-iv>.<base64url-ciphertext>.<base64url-tag>This gives you enough structure to answer the questions that matter during decryption:
- What format version is this?
- Which key ID should I load?
- Which algorithm or mode is expected?
- Where are the IV, ciphertext, and tag fields?
Version the format on day one. Even if you only support one format today, versioning makes later changes survivable. Future you may want a different key ID scheme, a different delimiter, a different mode, or a migration from CBC to GCM. A leading version marker is cheap insurance.
On the parse path, be strict. Split on the expected delimiter. Require the exact number of segments. Base64-decode with strict mode. Reject empty or malformed binary fields before calling decrypt. If the payload shape is wrong, fail early and return a generic application-level error. Not every mistake needs a dramatic stack trace.
Decryption safety: validate first, then fail quietly
The decrypt function should be one of the last steps in the process, not the first. Good decryption hygiene starts with input validation.
A safe sequence looks like this:
- Check that the payload matches the expected version and segment count.
- Look up the key by key ID and confirm it exists.
- Base64url-decode IV, ciphertext, and tag with strict parsing.
- Validate IV and tag lengths for the selected mode.
- Call
openssl_decrypt(). - Reject
falseor empty-invalid results according to your application rules.
Avoid detailed error leakage in user-facing responses. The caller usually needs “could not decrypt value” rather than “tag length invalid after parsing segment 6.” Save detailed diagnostics for protected logs, and even there avoid logging plaintext, full keys, or full payloads when a request fails.
This is also where application behavior matters. Decide whether decrypt failures should bubble up as exceptions, nulls, or a specific domain error object. Pick one behavior and document it. Chaotic error handling around encryption becomes a reliability problem long before it becomes a security postmortem.
Minimal end-to-end example structure
The example below keeps the workflow intentionally narrow: one loader for the key, one encrypt function, one decrypt function, and versioned packaging. It is not a complete library, but it is a good shape for application code.
<?php
final class AesGcmBox
{
private const CIPHER = 'aes-256-gcm';
private const VERSION = 'v1';
public static function loadKeyFromEnv(string $name): string
{
$encoded = getenv($name);
if (!is_string($encoded) || $encoded === '') {
throw new RuntimeException('Missing encryption key.');
}
$key = base64_decode($encoded, true);
if ($key === false || strlen($key) !== 32) {
throw new RuntimeException('Encryption key must decode to 32 bytes.');
}
return $key;
}
public static function encrypt(string $plaintext, string $key, string $keyId = 'k1'): string
{
$iv = random_bytes(openssl_cipher_iv_length(self::CIPHER));
$tag = '';
$ciphertext = openssl_encrypt(
$plaintext,
self::CIPHER,
$key,
OPENSSL_RAW_DATA,
$iv,
$tag,
'',
16
);
if ($ciphertext === false) {
throw new RuntimeException('Encryption failed.');
}
return implode('.', [
self::VERSION,
$keyId,
self::CIPHER,
self::b64url($iv),
self::b64url($ciphertext),
self::b64url($tag),
]);
}
public static function decrypt(string $payload, array $keysById): string
{
$parts = explode('.', $payload);
if (count($parts) !== 6 || $parts[0] !== self::VERSION || $parts[2] !== self::CIPHER) {
throw new RuntimeException('Malformed encrypted payload.');
}
[$version, $keyId, $cipher, $ivPart, $ciphertextPart, $tagPart] = $parts;
if (!isset($keysById[$keyId])) {
throw new RuntimeException('Unknown key ID.');
}
$iv = self::b64urlDecode($ivPart);
$ciphertext = self::b64urlDecode($ciphertextPart);
$tag = self::b64urlDecode($tagPart);
if ($iv === false || $ciphertext === false || $tag === false) {
throw new RuntimeException('Malformed base64 payload.');
}
if (strlen($iv) !== openssl_cipher_iv_length(self::CIPHER) || strlen($tag) !== 16) {
throw new RuntimeException('Invalid IV or tag length.');
}
$plaintext = openssl_decrypt(
$ciphertext,
self::CIPHER,
$keysById[$keyId],
OPENSSL_RAW_DATA,
$iv,
$tag
);
if ($plaintext === false) {
throw new RuntimeException('Decryption failed.');
}
return $plaintext;
}
private static function b64url(string $binary): string
{
return rtrim(strtr(base64_encode($binary), '+/', '-_'), '=');
}
private static function b64urlDecode(string $text): string|false
{
$pad = (4 - strlen($text) % 4) % 4;
return base64_decode(strtr($text . str_repeat('=', $pad), '-_', '+/'), true);
}
}
The point of the example is not novelty. The point is to keep the sensitive logic centralized so validation, rotation, and testing happen in one place. That is the best fit for most teams.
How to test correctness: published vectors and round-trip tests do different jobs
Round-trip tests are necessary, but they are not sufficient. If your code encrypts and then decrypts its own output, you have only proved that the same implementation can talk to itself. That catches many bugs, but not all of them.
Use both of these test families:
| Test type | What it proves | Typical input |
|---|---|---|
| Known test vector | Your implementation matches a published expected output | Fixed key, IV, plaintext, ciphertext, and tag |
| Round-trip test | Your packaging and parse logic work end to end | Application-specific values and payload fixtures |
| Tamper test | Modified payloads fail instead of decrypting silently | Changed IV, ciphertext byte, or auth tag |
Known vectors are your interoperability check. Use them when you first build the helper and whenever you change the packaging or cipher parameters. NIST publications and vetted library test suites are the usual sources. Round-trip tests are your application regression check. Use them to cover empty strings, Unicode, long text, JSON blobs, and real payload shapes from your own system.
A practical test plan usually includes:
- One published AES-GCM vector with fixed expected outputs.
- One payload fixture for each format version you support.
- Two encryptions of the same plaintext proving the IV strategy creates different packaged outputs.
- One tampered payload that must fail.
- One old-key fixture proving rotation did not break reads.
If you are under time pressure, keep one principle anyway: save stable fixtures before refactors and before key-rotation code lands. Without fixtures, teams often “test” by creating fresh encrypted values after the change, which quietly skips the backward-compatibility question.
Common failure modes and quick fixes
| Failure mode | Symptom | Quick fix |
|---|---|---|
| Wrong key length | Decrypt fails or data becomes unreadable across environments | Base64-decode the env value and enforce 32 bytes for AES-256 |
| IV missing from payload | Stored ciphertext cannot be decrypted later | Package IV with ciphertext every time |
| Mode mismatch | Values encrypted in one environment fail in another | Store a version or mode marker in the payload |
| Encoding mix-up | Binary data is mangled in JSON or the database | Use base64url for transport and strict decode on read |
| Ignored auth tag | Tampered ciphertext appears to “decrypt strangely” | For GCM, require the tag and fail if it is missing or the wrong length |
| Hard-coded key in app code | Deployment convenience, then long-term incident risk | Move the key to environment or secret management and assign ownership |
There is a pattern here: most failures are packaging and process errors. They look like crypto problems from a distance, but they are usually state-management problems, validation problems, or migration problems. That is good news, because process is easier to improve than mathematics.
The safest reasonable default
If you need a short decision path, use this one:
- Use encryption only when the application must recover the original value later.
- For new PHP work, prefer AES-256-GCM if your runtime supports it.
- Load a 32-byte key from an external secret source, not from code.
- Generate a fresh IV per message and store it with the ciphertext.
- Package version, key ID, mode, IV, ciphertext, and tag into a strict base64url-safe format.
- Test with both a published vector and your own round-trip fixtures.
That is the best fit for most teams because it balances security properties with operational clarity. Decide on the workflow once, document it, and keep the implementation small enough to review properly. In encryption work, disciplined simplicity tends to age better than cleverness.