Kunci Laravel Package

Getting Started

Install the package via Composer:

composer require novay/kunci

Publish the configuration file (if needed) to customize encryption settings:

php artisan vendor:publish --provider="Novay\Kunci\KunciServiceProvider"

For basic encryption/decryption, use the Kunci facade:

use Novay\Kunci\Facades\Kunci;

// Encrypt
$encrypted = Kunci::encrypt('sensitive-data');

// Decrypt
$decrypted = Kunci::decrypt($encrypted);

First Use Case: Securely encrypting API tokens or user-sensitive data in a database column.

Implementation Patterns

Deterministic Encryption (New in 1.1)

Use deterministic encryption when the same plaintext must always produce the same ciphertext (e.g., indexing, sorting, or comparing encrypted values):

$deterministic = Kunci::deterministic()->encrypt('searchable-data');

Workflow:

1. Database Indexing: Encrypt fields like email or username deterministically to enable LIKE queries or sorting.
2. Comparison Logic: Compare encrypted values directly (e.g., if ($encryptedA === $encryptedB)).
3. Cache Keys: Use deterministic encryption for cache keys requiring consistency.

Non-Deterministic Encryption (Default)

For unique ciphertexts per encryption (e.g., passwords, tokens):

$randomized = Kunci::encrypt('unique-data');

Integration Tips

• Migrations: Use deterministic encryption for columns needing queries:

  Schema::table('users', function (Blueprint $table) {
      $table->string('encrypted_email')->unique();
  });
  

• Query Scopes: Combine with Laravel’s query builder for encrypted searches:

  public function scopeSearchByEmail($query, $email)
  {
      return $query->where('encrypted_email', Kunci::deterministic()->encrypt($email));
  }
  

• Model Attributes: Cast encrypted attributes in models:

  protected $casts = [
      'encrypted_email' => EncryptedAttribute::make('encrypted_email'),
  ];
  

Gotchas and Tips

Deterministic Encryption Caveats

1. Security Implications:

   • Deterministic encryption leaks patterns (e.g., identical emails produce identical ciphertexts). Use only for non-sensitive data requiring queryability.
   • Avoid for passwords or tokens where uniqueness is critical.

2. Key Rotation:

   • Re-encrypting deterministic data after key rotation requires a migration strategy (e.g., dual-write during transition).

3. Performance:

   • Deterministic mode is slightly faster but consumes more CPU/memory due to repeated encryption for comparisons.

General Tips

• Configuration:
  • Set deterministic_key in config/kunci.php if using custom keys for deterministic mode.
  • Example:

    'deterministic' => [
        'key' => env('DETERMINISTIC_KEY', 'default-key-here'),
    ],
    

• Debugging:
  • Use Kunci::getAlgorithm() to verify encryption mode (e.g., AES-256-CBC for non-deterministic, AES-256-ECB for deterministic).
  • Log decryption failures with:

    try {
        $decrypted = Kunci::decrypt($encrypted);
    } catch (\Novay\Kunci\Exceptions\DecryptException $e) {
        Log::error("Decryption failed: " . $e->getMessage());
    }
    

• Extension Points:
  • Override encryption logic via service provider bindings:

    $this->app->bind(\Novay\Kunci\Contracts\Encryptor::class, function () {
        return new CustomEncryptor();
    });
    

• Backup Keys:
  • Store deterministic keys securely (e.g., AWS KMS, HashiCorp Vault) if using custom keys.