novay/kunci is a core Laravel package that provides secure data encryption and decryption functionalities using OpenSSL. It offers a flexible architecture to manage encryption keys, including a default file-based driver, and serves as the foundation for integrating with various Cloud Key Management Services (KMS) via separate packages.
Add the Core Package to Your Project:
You can easily add novay/kunci to your Laravel project using Composer:
composer require novay/kunci
Run Composer Update (Optional): If you encounter any autoloading issues, you can try running:
composer dump-autoload
Publish the Configuration File (Optional):
To publish the kunci.php configuration file to your main application's config directory (so you can customize key paths and other settings):
php artisan vendor:publish --tag=kunci-config
novay/kunci comes with a file-based key driver as its default. For enhanced security and cloud integration, consider using dedicated Cloud KMS driver packages (see Cloud KMS Integration below).
For the file-based driver, you can create a new, secure 64-character (256-bit) encryption key using a dedicated Artisan command:
php artisan kunci:generate
By default, this command will create a .key file in storage/app/private/.
You can also specify a custom key file path:
php artisan kunci:generate --path=./path/to/your/secret.key
For the file-based driver, this package will look for the key file at storage/app/private/.key by default. You can change this path via the config/kunci.php configuration file (after you've published it) or through the KUNCI_KEY_FILE environment variable in your .env file:
# Your .env file
KUNCI_KEY_FILE=/absolute/path/to/your/custom/.key
After generating the key file, it is critically important to protect it with appropriate file system permissions:
www-data or nginx) can read the file.public_html or public/). The storage/app/ directory (or its subdirectories like storage/app/private/) is a recommended location.Example commands to set permissions (adjust to your web server's user/group):
chmod 600 storage/app/private/.key
chown www-data:www-data storage/app/private/.key # Replace www-data with the appropriate user/group
Not all drivers support deterministic encryption (encrypting data in a way that produces the same ciphertext for the same plaintext, useful for searchable encryption).
DeterministicKunciDriver which extends the base KunciDriver interface.encryptDeterministic() and decryptDeterministic() methods.Kunci will automatically check if the configured driver supports deterministic encryption before calling these methods.Currently, the default FileDriver implements deterministic encryption methods, but other drivers (e.g., Cloud KMS drivers) may or may not support it.
novay/kunci is designed to be extensible, allowing you to use various Cloud Key Management Services (KMS) as your encryption key source. This is achieved through separate, dedicated driver packages.
Currently, the following Cloud KMS drivers are planned (or could be developed):
novay/kunci-aws: Integration with AWS Key Management Service (KMS).novay/kunci-azure: Integration with Azure Key Vault.novay/kunci-gcp: Integration with Google Cloud Key Management Service (KMS).To use a specific Cloud KMS, you need to install its corresponding driver package in addition to novay/kunci. For example, to use AWS KMS:
composer require novay/kunci-aws
(This command will automatically pull in novay/kunci if it's not already installed).
After installing a KMS driver package, you need to configure novay/kunci to use it.
Set the Driver: In your config/kunci.php file (or via KUNCI_DRIVER environment variable), set the driver option to your desired KMS provider (e.g., 'aws-kms').
// config/kunci.php (after publishing)
return [
'driver' => env('KUNCI_DRIVER', 'file'), // Change 'file' to 'aws-kms', 'gcp-kms', or 'azure-kv'
...
];
The Kunci Facade provides a consistent interface regardless of the underlying key management driver configured.
When using a KMS driver, you don't explicitly "load" the key in the same way as the file-based driver. The Kunci Facade will automatically interact with the configured KMS service to perform cryptographic operations. You simply need to ensure your application has the correct permissions (IAM roles for AWS/GCP, Azure AD for Azure) to communicate with your KMS service.
You do not need to manually call Kunci::loadKeyFromFile() when using a KMS driver. The system handles the key's interaction with the KMS service internally.
Encrypting data remains simple, as the Facade abstracts the underlying key management:
use Novay\Kunci\Facades\Kunci; // Use the Facade
$dataToEncrypt = "This is highly sensitive information.";
try {
$encryptedData = Kunci::encrypt($dataToEncrypt); // No key parameter needed here, it's managed by the driver
echo "Original Data: " . $dataToEncrypt . "\n";
echo "Encrypted Data: " . $encryptedData . "\n";
} catch (\Exception $e) {
// Handle encryption errors (e.g., KMS connectivity issues, permissions)
die("Encryption Error: " . $e->getMessage());
}
Decrypting data also uses the same consistent Facade interface:
use Novay\Kunci\Facades\Kunci;
// Assume $encryptedData is a valid string encrypted by Kunci
try {
$decryptedData = Kunci::decrypt($encryptedData);
if ($decryptedData !== false) {
echo "Decrypted Data: " . $decryptedData . "\n";
} else {
echo "Failed to decrypt data. Key might be incorrect or encrypted data is corrupt.\n";
}
} catch (\Exception $e) {
// Handle decryption errors
die("Decryption Error: " . $e->getMessage());
}
To use deterministic encryption (if supported by your configured driver), you can call:
use Novay\Kunci\Facades\Kunci;
$data = "searchable data";
try {
// Encrypt deterministically
$encrypted = Kunci::encryptDeterministic($data);
// Later, decrypt deterministically
$decrypted = Kunci::decryptDeterministic($encrypted);
echo "Encrypted (deterministic): $encrypted\n";
echo "Decrypted: $decrypted\n";
} catch (\Exception $e) {
echo "Deterministic encryption is not supported by the current driver: " . $e->getMessage();
}
novay/kunci is open-source software licensed under the MIT License.
MIT License
Copyright (c) 2025 Novianto Rahmadi
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
How can I help you explore Laravel packages today?