Oihana PHP

openssl

Table of Contents

Namespaces

enums

Classes

OpenSSLFileEncryption
File-level symmetric encryption powered by OpenSSL.

Functions

deriveKey()  : string
Derives a 32-byte symmetric encryption key from a passphrase using a slow KDF.
bestAvailableKdf()  : int
Returns the strongest KDF algorithm available in the current PHP environment.
isAeadCipher()  : bool
Determines whether an OpenSSL cipher name designates an AEAD mode.

Functions

deriveKey()

Derives a 32-byte symmetric encryption key from a passphrase using a slow KDF.

deriveKey(string $passphrase, string $salt, int $algorithm) : string

Why a KDF ? A passphrase like 'chocolat' has roughly 8 bytes of entropy. Using it directly as an AES-256 key (zero-padded to 32 bytes) makes brute-force trivial. A KDF deliberately slows the key derivation down (hundreds of thousands of iterations or memory-hard computation) so that an attacker who tries 1 million passphrases must do 1 million × N work — increasing brute-force cost by orders of magnitude.

Supported algorithms (passed via $algorithm):

Use bestAvailableKdf() to pick the strongest algorithm available in the current PHP environment.

The chosen algorithm is explicit so that the encrypted file can carry it and any reader (even on a different PHP build) can reproduce the derivation.

Security boundary: this function protects the cost of brute-forcing the passphrase. It does not protect against:

  • a leaked salt + ciphertext + passphrase (anyone with all three can decrypt) ;
  • a passphrase observable by an attacker (e.g. typed in front of a camera) ;
  • side-channel attacks on the host (memory dump while passphrase is in RAM).
Parameters
$passphrase : string

The user-provided passphrase. Must be non-empty.

$salt : string

A per-file random salt of EncryptionFormat::SALT_LENGTH bytes.

$algorithm : int

One of EncryptionFormat::KDF_ARGON2ID or EncryptionFormat::KDF_PBKDF2_SHA256.

Tags
throws
RuntimeException

If the passphrase is empty, the salt has wrong length, the algorithm is unknown, or Argon2id is requested but the sodium extension is not loaded.

example 
use function oihana\files\openssl\{ deriveKey , bestAvailableKdf } ;
use oihana\files\openssl\enums\EncryptionFormat;

$salt = random_bytes( EncryptionFormat::SALT_LENGTH ) ;
$algo = bestAvailableKdf() ;
$key  = deriveKey( 'my passphrase' , $salt , $algo ) ;
author

Marc Alcaraz (ekameleon)

since
1.0.0
Return values
string —

A 32-byte raw binary key.

bestAvailableKdf()

Returns the strongest KDF algorithm available in the current PHP environment.

bestAvailableKdf() : int

Use this when writing new encrypted files; for reading, the algorithm is dictated by the file header.

Tags
example 
use function oihana\files\openssl\bestAvailableKdf;

$kdf = bestAvailableKdf() ;
// → KDF_ARGON2ID on PHP 8.4 with sodium (the usual case)
// → KDF_PBKDF2_SHA256 on stripped-down builds
author

Marc Alcaraz (ekameleon)

since
1.0.0
Return values
int —

One of EncryptionFormat::KDF_ARGON2ID or EncryptionFormat::KDF_PBKDF2_SHA256.

isAeadCipher()

Determines whether an OpenSSL cipher name designates an AEAD mode.

isAeadCipher(string $cipher) : bool

AEAD (Authenticated Encryption with Associated Data) ciphers compute an authentication tag in addition to the ciphertext. PHP's openssl_encrypt() / openssl_decrypt() API requires the &$tag parameter for these ciphers; without it, integrity is not protected.

Currently recognised modes:

  • GCM (Galois/Counter Mode) — preferred for general use.
  • CCM (Counter with CBC-MAC).
  • OCB (Offset Codebook) — modern, less ubiquitous.

The check is purely textual on the cipher name (case-insensitive).

Parameters
$cipher : string

Cipher name as returned by openssl_get_cipher_methods(), e.g. 'aes-256-gcm', 'aes-128-ccm', 'aes-256-cbc'.

Tags
example 
use function oihana\files\openssl\isAeadCipher;

isAeadCipher('aes-256-gcm') ;  // true
isAeadCipher('aes-128-ccm') ;  // true
isAeadCipher('aes-256-cbc') ;  // false
isAeadCipher('chacha20-poly1305') ; // false — handled separately by sodium
author

Marc Alcaraz (ekameleon)

since
1.0.0
Return values
bool —

True if the cipher operates in an AEAD mode.

On this page

Search results