PHP Luminova: Encryption Driver for OpenSSL and Sodium

The Encryption Driver is the foundation of Luminova’s encryption system.It provides a clean and consistent API that abstracts away the complexity of working with different encryption libraries.

You can use either the OpenSSL or Sodium driver to handle encryption and decryption operations with ease. Both drivers support setting custom keys, methods, and key sizes, while following modern cryptographic best practices.

This makes it ideal for developers who want strong encryption without manually managing ciphers, padding, or key handling details.

For most applications, using the Crypter Class is recommended it automatically selects and configures the best available encryption driver and method.

Usages

Initialize based on application encryption configuration.

use Luminova\Security\Encryption\Driver\{Openssl, Sodium};
use Luminova\Security\Encryption\Key;

$handler = Key::handler(true);
$method  = Key::method();
$key     = 'mykey';

$crypto = match ($handler) {
  'openssl' => new Openssl($key, $method, Key::size($method)),
  'sodium'  => new Sodium($key),
  default   => throw new Error('Encryption handler not supported.'),
};

// Encrypt
$crypto->setNonce($nonce); // Optional
$crypto->setData('Plain text');
$hash = $crypto->encrypt();

// Decrypt
echo $crypto->setData($hash)->decrypt();

Recommendation

Use the Crypter Class for automatic driver selection (OpenSSL or Sodium), encryption method resolution, and key configuration.It provides a unified and secure interface without requiring manual setup.

Class Definition

• Openssl namespace: \Luminova\Security\Encryption\Driver\Openssl
• Sodium namespace: \Luminova\Security\Encryption\Driver\Sodium
• Implements:\Luminova\Interface\EncryptionInterface

Driver Constructors

OpenSSL Driver Constructor

Initializes a new OpenSSL encryption driver.

A key and cipher method may be provided at construction time, or configured later using setKey() and setMethod() before performing encryption or decryption.

public __construct(?string $key = null, ?string $method = null, int $size = 16): mixed

Parameters:

Throws:

• \Luminova\Exceptions\EncryptionException - When an invalid cipher method or block size is used.

Examples:

Using Openssl encryption handling.

use Luminova\Security\Encryption\Driver\Openssl;

$openssl = new Openssl(
  key: 'mykey',
  method: 'AES-128-CBC',
  size: 16
);

Sodium Driver Constructor

Initializes a new Sodium encryption driver.

A key may be provided at construction time, or set later using setKey() before performing encryption or decryption.

public __construct(?string $key = null): mixed

Parameters:

Throws:

• \Luminova\Exceptions\EncryptionException - When the provided key is invalid for Sodium.

Using Sodium encryption handling.

use Luminova\Security\Encryption\Driver\Sodium;

$sodium = new Sodium(
  key: 'mykey'
);

Methods

Both drivers share methods and implementation logic.

setData

Set the data to encrypt or decrypt.

This method allows you to specify encoded cipher message to decrypt or a plain text to encrypt.

public setData(string $data): EncryptionInterface

Parameters:

Return Value:

Luminova\Interface\EncryptionInterface - Return instance of encryption driver class.

setAssociatedData

Sets Additional Authenticated Data (AEAD).

This method allows you to include additional authentication data during encryption or decryption.

public setAssociatedData(array|string $aad): EncryptionInterface

Parameters:

Return Value:

Luminova\Interface\EncryptionInterface - Return instance of encryption driver class.

Throws:

• \Luminova\Exceptions\EncryptionException - If array and failed to encode.

Note:

Must be identical for encryption and decryption or authentication fails.

setKey

Set the encryption or decryption key.

public setKey(string $key, int $length = 0, ?string $salt = null): EncryptionInterface

Parameters:

Return Value:

Luminova\Interface\EncryptionInterface - Return instance of encryption driver class.

Throws:

• \Luminova\Exceptions\EncryptionException - If error while generating key.

setNonce

Set nonce for encryption, if null random nonce will be generated.

public setNonce(?string $nonce = null): EncryptionInterface

Parameters:

Return Value:

Luminova\Interface\EncryptionInterface - Return instance of encryption driver class.

setMethod

Set the encryption method and block size for openssl.

This method sets an encryption method and block size for openssl driver only.This method will be ignored on Sodium.

public setMethod(string $method, int $size = 16): EncryptionInterface

Parameters:

Return Value:

Luminova\Interface\EncryptionInterface - Return instance of encryption driver class.

Throws:

• \Luminova\Exceptions\EncryptionException - If the method or block size is invalid.

nonce

Generate a random nonce, or return from a string.

public static nonce(int $length, ?string $string = null): string

Parameters:

Return Value:

string - Return the generated encryption nonce string.

Throws:

• \Luminova\Exceptions\EncryptionException - If error while generating nonce.

encrypt

Encrypt data into an encoded message.

This method performs cryptography to generate an encryption hash from a plan text.

public encrypt(): string

Return Value:

string Return the encrypted cipher message data if encryption succeed.

Throws:

• \Luminova\Exceptions\EncryptionException - If encryption fails due to invalid parameters.

Note:Encrypted payload is encoded in base64 string.

decrypt

Decrypt an encoded cipher message.

This method performs cryptography to decipher an encrypted hash into a readable plan text.

public decrypt(): string

Return Value:

string - Return the decrypted plain-text content if decryption succeed.

Throws:

• \Luminova\Exceptions\EncryptionException - If decryption fails or invalid parameters.

free

Free up cryptography resources.

This will clear:

• key
• nonce
• message
• addition authentication data

public free(): bool

Return Value:

bool - Return true if freed, otherwise false.