EncryptionService
in package
Core encryption service with dual V1/V2 algorithm support.
V1 (legacy): AES-256-GCM via OpenSSL — whole-file, raw master key V2 (current): XChaCha20-Poly1305 via libsodium — chunked streaming, HKDF-derived subkeys
String encryption: V1: [IV(12)] + [TAG(16)] + [ciphertext] V2: [AHG2(4)] + [KEY_ID(4)] + [NONCE(24)] + [ciphertext+tag]
File encryption: V1: [AHG-ENC-V1(10)] + [IV(12)] + [TAG(16)] + [ciphertext] V2: [AHG-ENC-V2(10)] + [KEY_ID(4)] + [CHUNK_SIZE(4)] + [STREAM_HEADER(24)] + [chunks...] Each chunk: plaintext_chunk_size + 17 bytes (ABYTES overhead) Last chunk tagged with SODIUM_CRYPTO_SECRETSTREAM_XCHACHA20POLY1305_TAG_FINAL
Table of Contents
Methods
- decrypt() : string
- Decrypt a string.
- decryptFile() : void
- Decrypt a file to another file.
- decryptFileStream() : Generator
- Streaming decryption via Generator.
- detectFileVersion() : int
- Detect the encryption version of a file by reading its header.
- encrypt() : string
- Encrypt a string.
- encryptFile() : void
- Encrypt a file.
- getFileHeader() : string
- Get the current file header version string.
- getKey() : string
- Get the raw master encryption key.
- isEncryptedFile() : bool
- Check if a file is encrypted (V1 or V2).
Methods
decrypt()
Decrypt a string.
public
static decrypt(string $ciphertext[, string|null $key = null ]) : string
Auto-detects V1 vs V2 format and uses the appropriate algorithm.
Parameters
- $ciphertext : string
-
Binary ciphertext (V1 or V2 format)
- $key : string|null = null
-
32-byte key (auto-selects appropriate key if null)
Return values
string —Decrypted plaintext
decryptFile()
Decrypt a file to another file.
public
static decryptFile(string $encryptedPath, string $outputPath[, string|null $key = null ]) : void
Auto-detects V1 vs V2 header and dispatches to the correct decryption path.
Parameters
- $encryptedPath : string
-
Source file (encrypted)
- $outputPath : string
-
Destination file (plaintext)
- $key : string|null = null
-
32-byte key (auto-selects if null)
decryptFileStream()
Streaming decryption via Generator.
public
static decryptFileStream(string $encryptedPath[, string|null $key = null ]) : Generator
V2: True streaming — reads and decrypts one chunk at a time, constant memory. V1: Loads full file, decrypts, then yields in chunks (legacy behavior).
Parameters
- $encryptedPath : string
-
Path to encrypted file
- $key : string|null = null
-
32-byte key (auto-selects if null)
Return values
Generator —yields plaintext string chunks
detectFileVersion()
Detect the encryption version of a file by reading its header.
public
static detectFileVersion(string $filePath) : int
Parameters
- $filePath : string
Return values
int —1 for V1, 2 for V2, 0 for unknown
encrypt()
Encrypt a string.
public
static encrypt(string $plaintext[, string|null $key = null ]) : string
Uses XChaCha20-Poly1305 (V2) when sodium is available, falls back to AES-256-GCM (V1).
Parameters
- $plaintext : string
-
Data to encrypt
- $key : string|null = null
-
32-byte key (defaults to HKDF-derived field subkey)
Return values
string —Binary ciphertext with version-specific format
encryptFile()
Encrypt a file.
public
static encryptFile(string $inputPath, string $outputPath[, string|null $key = null ]) : void
V2 (sodium): Chunked streaming via secretstream — never loads full file into memory. V1 (OpenSSL): Whole-file encryption as fallback.
Parameters
- $inputPath : string
-
Source file (plaintext)
- $outputPath : string
-
Destination file (encrypted)
- $key : string|null = null
-
32-byte key (defaults to HKDF-derived file subkey)
getFileHeader()
Get the current file header version string.
public
static getFileHeader() : string
Return values
stringgetKey()
Get the raw master encryption key.
public
static getKey() : string
Return values
stringisEncryptedFile()
Check if a file is encrypted (V1 or V2).
public
static isEncryptedFile(string $filePath) : bool
Parameters
- $filePath : string