Weave Code
Halite Laravel Package
paragonie/halite
Halite is a high-level PHP cryptography library from Paragon Initiative Enterprises, built on libsodium. It provides safer, opinionated APIs for encryption, authentication, key management, and password hashing, helping you use modern crypto correctly with minimal foot-guns.
High-level cryptography interface powered by libsodium
Frequently asked questions about Halite
- Can I use Halite for encrypting sensitive Laravel model attributes like passwords or SSNs?
- Yes, Halite is ideal for encrypting sensitive fields in Laravel models. Use it with Eloquent accessors or a custom `EncryptedAttribute` trait to seal/unseal data before/after database operations. For passwords, however, stick with Laravel’s built-in `Hash` facade—Halite is better suited for bulk data or API payloads requiring authenticated encryption.
- How do I install Halite in a Laravel project, and what PHP version is required?
- Install via Composer: `composer require paragonie/halite`. Halite requires PHP 8.1+ and the `libsodium` extension (enabled by default in PHP 8.1+). For older PHP versions, manually enable the extension via `pecl install libsodium` or use a Docker image with libsodium pre-installed.
- Does Halite integrate with Laravel’s encryption config (e.g., `config/encryption.php`)?
- No, Halite doesn’t natively integrate with Laravel’s encryption config. You’ll need to create a custom wrapper to bridge Halite’s `KeyFactory` with your key storage (e.g., environment variables, AWS KMS, or a dedicated `config/halite.php`). Example: Store keys in `.env` and load them via a service provider.
- Is Halite suitable for encrypting API request/response payloads in Laravel?
- Absolutely. Halite’s `seal()` and `open()` methods are perfect for encrypting API payloads with authenticated encryption (AES-256-GCM + HMAC). Use middleware to encrypt outgoing responses or decrypt incoming requests, ensuring end-to-end security without modifying the database.
- How do I handle key rotation in Laravel with Halite?
- Halite’s `KeyFactory` supports programmatic key rotation. Store multiple keys in your config and use `Halite::setKey()` to switch between them. For Laravel, create a console command to generate new keys, update the config, and re-encrypt data with the old key before switching. Avoid downtime by keeping both keys active temporarily.
- What’s the performance impact of Halite’s Argon2id key derivation in production?
- Argon2id is CPU-intensive but secure. For high-throughput Laravel apps, adjust the `memory_cost` and `time_cost` parameters in `KeyFactory` to balance security and performance. Benchmark with tools like Blackfire to optimize for your workload. If latency is critical, consider pre-generating keys offline.
- Can I use Halite for database-level encryption (e.g., encrypting entire columns in MySQL)?
- Halite is designed for application-level encryption, not database-level. Encrypting columns directly in MySQL adds overhead and complicates queries. Instead, use Laravel’s attribute casting or accessors to encrypt/decrypt data on-the-fly. Avoid encrypting indexed or searchable fields—Halite’s deterministic encryption isn’t suitable for this.
- What alternatives to Halite exist for Laravel encryption, and when should I choose them?
- For simple hashing (e.g., passwords), use Laravel’s built-in `Hash` facade. For basic encryption, consider `defuse/php-encryption` (AES-256-CBC). Choose Halite only if you need authenticated encryption (AES-256-GCM + HMAC), key derivation (Argon2id), or libsodium’s modern crypto. Halite is overkill for non-sensitive data.
- How do I log failed decryption attempts in Laravel for audit purposes?
- Wrap Halite operations in a try-catch block and dispatch Laravel events (e.g., `DecryptionFailed`) or log to a monitor like Sentry. Example: `try { $data = Halite::open($encrypted); } catch (Exception $e) { event(new DecryptionFailed($e, $encrypted)); }`. Integrate with Laravel’s logging channels for compliance.
- What should I do if libsodium isn’t available on my shared hosting environment?
- Check if your host supports PHP 8.1+ (libsodium is bundled). If not, document the requirement in your `README` or use a Docker container with libsodium pre-installed. As a fallback, consider `defuse/php-encryption` (though it lacks authenticated encryption) or upgrade your hosting. Avoid rolling your own crypto.
Weaver
How can I help you explore Laravel packages today?