PHP Luminova: Helper Class to Handle Private and Plublic Keys

Luminova Encryption Key

Class Definition

• Full namespace: \Luminova\Security\Encryption\Key
• This class is marked as final and can't be subclassed
• This class is a Final class

Constants

Properties

ciphers

Supported AES encryption methods with their corresponding key sizes.

public static array<string,array> $ciphers = [
  'AES-128-CBC' => ['size' => 16],
  'AES-192-CBC' => ['size' => 24],
  // ...
]

Each cipher entry specifies the size of the encryption key in bytes.

• AES-128-CBC - 128-bit key (16 bytes)
• AES-192-CBC - 192-bit key (24 bytes)
• AES-256-CBC - 256-bit key (32 bytes)
• AES-128-CBC-HMAC-SHA1 - 128-bit key (16 bytes)
• AES-256-CBC-HMAC-SHA1 - 256-bit key (32 bytes)
• AES-128-CBC-HMAC-SHA256 - 128-bit key (16 bytes)
• AES-256-CBC-HMAC-SHA256 - 256-bit key (32 bytes)
• AES-128-CFB - 128-bit key (16 bytes)
• AES-192-CFB - 192-bit key (24 bytes)
• AES-256-CFB - 256-bit key (32 bytes)
• AES-128-CFB1 - 128-bit key (16 bytes)
• AES-192-CFB1 - 192-bit key (24 bytes)
• AES-256-CFB1 - 256-bit key (32 bytes)
• AES-128-CFB8 - 128-bit key (16 bytes)
• AES-192-CFB8 - 192-bit key (24 bytes)
• AES-256-CFB8 - 256-bit key (32 bytes)
• AES-128-CTR - 128-bit key (16 bytes)
• AES-192-CTR - 192-bit key (24 bytes)
• AES-256-CTR - 256-bit key (32 bytes)
• AES-128-ECB - 128-bit key (16 bytes)
• AES-192-ECB - 192-bit key (24 bytes)
• AES-256-ECB - 256-bit key (32 bytes)
• AES-128-OFB - 128-bit key (16 bytes)
• AES-192-OFB - 192-bit key (24 bytes)
• AES-256-OFB - 256-bit key (32 bytes)
• AES-128-XTS - 128-bit key (16 bytes)
• AES-256-XTS - 256-bit key (32 bytes)

Methods

constructor

Key generator for public, private, or random keys.

The constructor creates a key based on the given type:

• Key::TYPE_PUBLIC: Generates a public key from an existing private key, or creates a new key pair.
• Key::TYPE_PRIVATE: Generates a new private key.
• Key::TYPE_PAIR: Generates a key-pair (private and public key).
• Key::TYPE_RANDOM: Generates a random key string.

public __construct(
    string $type = Key::TYPE_PUBLIC,
    ?string $handler = null,
    ?string $passphrase = null,
    array<string,mixed> $options = []
): mixed

Parameters:

Key Type Options:

• For random type:

  • length: Key length in bytes (default: cipher size).
  • handler: The key handler lowercased (openssl or sodium).

• For public type:

  • private_key: Use this private key to derive the public key or provide optional private key options to generate new private key.

• For private type:

  • private_key_bits: Bit length for new private key (default: 2048).
  • private_key_type: Key type (default: OPENSSL_KEYTYPE_RSA).

See reference for more information https://php.net/manual/en/function.openssl-pkey-new.php

Examples:

Generate a random key string:

$key = new Key(Key::TYPE_RANDOM, [
  'length' => 32, 
  'handler' => 'openssl'
]);

echo $key->getRandom();
// Or $key->getResult()

Generate a private key:

$key = new Key(Key::TYPE_PRIVATE, [
  'private_key_bits' => 2048,
  'private_key_type' => OPENSSL_KEYTYPE_RSA
]);

echo $key->getPrivate();
// Or $key->getResult()

Generate a public key from an existing private key:

// Get private key from file.
$private = \Luminova\Funcs\get_content('/path/to/private.pem');

$key = new Key(Key::TYPE_PUBLIC, ['private_key' => $private]);

echo $key->getPrivate();
echo $key->getPublic();

// Or $key->getResult()

getResult

Get the generated key value.

public getResult(): string|array|null

Return Value:

string|array|null - Return key detail, or null if not available.

getPublic

Get the generated public key.

public getPublic(): ?string

Return Value:

string|null - Public key string, or null if not available.

getPrivate

Get the generated private key.

public getPrivate(): ?string

Return Value:

string|null - Private key string (PEM format), or null if not available.

getRandom

Get the generated random key.

public getRandom(bool $toHex = true): ?string

Parameters:

Return Value:

string|null - Random key string in hex or raw bytes, or null if not available.

size

Retrieve the key size based on cipher method.

public static size(?string $method = null): int

Parameters:

Return Value:

int - Return the key size in bytes.

cipher

Retrieve cipher information by method.

public static cipher(?string $method = null): ?array

Parameters:

Return Value:

array{size: int}|null - Cipher properties or null if unsupported.

method

Retrieve encryption method from default configuration.

public static method(string $default = 'AES-128-CBC'): string

Parameters:

Return Value:

string - Return the cipher method or default.

handler

Determine the application encryption handler from configuration.

Checks if the required PHP extension is loaded and optionally asserts that the handler is valid, throwing exceptions if not.

public static handler(bool $assert = false): string|false

Parameters:

Return Value:

string|false - Return handler name (Key::OPENSSL or Key::SODIUM) or false if unavailable.

Throws:

• \Luminova\Exceptions\EncryptionException - If $assert is true and the handler is invalid or unsupported.

isSupported

Verify that the given key length matches the expected size for the cipher method.

If no cipher method is provided, the default from App\Config\Encryption->methodwill be used.

public static isSupported(string $key, ?string $method = null): bool

Parameters:

Return Value:

bool - Return true if the key length is valid for the cipher, false otherwise.

isPrivate

Validate if a given key is private.

public static isPrivate(
    \OpenSSLAsymmetricKey|\OpenSSLCertificate|array|string $key, 
    ?string $passphrase = null, 
    ?string $handler = null
): bool

Parameters:

Return Value:

bool - Return true if valid private key, false otherwise.

isPublic

Validate if a given key is public.

public static isPublic(
    \OpenSSLAsymmetricKey|\OpenSSLCertificate|array|string $key, 
    ?string $handler = null
): bool

Parameters:

Return Value:

bool - Return true if valid public key, false otherwise.

isMatch

Validate whether a private and public key pair match.

public static isMatch(
    \OpenSSLAsymmetricKey|\OpenSSLCertificate|array|string $privateKey,
    \OpenSSLAsymmetricKey|\OpenSSLCertificate|array|string $publicKey,
    int $algo = OPENSSL_ALGO_SHA256,
    ?string $data = null,
    ?string $passphrase = null,
    ?string $handler = null
): bool

Parameters:

Return Value:

bool - Return true if keys match, false otherwise.

newPublic

Generate a public key from an existing private key, or create a new key pair.

If a private key is provided, the public key will be derived from it.If not, a new private/public key pair will be generated using Openssl.

Derive or generate a public key using the chosen crypto handler.

• For OpenSSL:If a private key is provided, the public key is derived from it.If not, a new private key is created and its public key is extracted.

• For Sodium:If a secret (private) key is provided, the corresponding public key is derived.If not, a new key-pair is generated and the public key is returned.

public static newPublic(
    ?string $handler = null, 
    ?string $passphrase = null, 
    array<string,mixed> $options = []
): string|false

Parameters:

Return Value:

string|false - Return the generated/derived public key (PEM for OpenSSL, base64 for Sodium),or false on failure.

newPrivate

Generate a new private key.

Creates a private key using OpenSSL asymmetric encryption. If no options are given, a default 2048-bit RSA key is generated.

Creates a private key using the given handler.

• Openssl: generates a PEM-encoded RSA key (default 2048-bit).
• Sodium: generates an Ed25519 private key (Base64-encoded).

public static newPrivate(
    ?string $handler = null, 
    ?string $passphrase = null, 
    ?array<string,mixed> $options = []
): string|false

Parameters:

Return Value:

string|false - Return a private key string (PEM or Base64) or false on failure.

Note:

• If an empty options array is passed, the options default to:

  • private_key_bits: Number of bits (default: 2048).
  • private_key_type: Key type (default: OPENSSL_KEYTYPE_RSA).
• Pass null to fall back to the Openssl default configuration.

newKeyPair

Generate a new private/public key pair using the chosen crypto handler.

• For OpenSSL:A PEM-encoded private key is generated (optionally protected with a passphrase),and the corresponding public key is extracted.

• For Sodium:A new key-pair is created, and both keys are returned as base64 strings.

public static newKeyPair(
    ?string $handler = null, 
    ?string $passphrase = null, 
    array<string,mixed> $options = []
): array|false

Parameters:

Return Value:

array{private: string, public: string}|false - Return an array with both private and public keys (PEM for OpenSSL, base64 for Sodium),or false on failure.

newRandom

Generate a random encryption key.

This method creates a random key using the selected encryption handler. If no handler or key length is provided, it falls back to the application’s default handler and cipher size.

Uses the specified handler:

• Sodium: generates a secretbox key (32 bytes).
• OpenSSL: generates pseudo-random bytes (default: cipher size).

public static newRandom(?string $handler = null, ?int $length = null, bool $toHex = true): string

Parameters:

Return Value:

string - Return random key string (hex or raw).