Shh Laravel Package

Technical Evaluation

Architecture Fit

• Use Case Alignment: The package excels in secret encryption/decryption (RSA-OAEP + AES-GCM) and key management, aligning well with Laravel’s need for secure secret storage (e.g., .env files, database secrets, or API keys). It’s particularly useful for:
  • Encrypting sensitive data (e.g., API tokens, PII) before storage/transit.
  • Rotating secrets without breaking existing encrypted payloads (via asymmetric key pairs).
  • Integrating with Laravel’s config, cache, or filesystem for secure storage.
• Laravel Synergy:
  • Complements Laravel’s built-in Encrypter (which uses AES) by adding asymmetric encryption (RSA) for key exchange or hybrid encryption schemes.
  • Can integrate with Laravel’s Vault (if using Laravel 10+) or custom secret managers.
  • Works alongside Laravel’s Hash facade for passphrase-based key derivation.

Integration Feasibility

• Low Coupling: The package is standalone (no Laravel-specific dependencies) and can be integrated incrementally:
  • Option 1: Replace manual openssl_* calls with Shh for consistency.
  • Option 2: Use as a hybrid encryption layer (e.g., encrypt secrets with Shh, then store in Laravel’s cache or database).
  • Option 3: Extend Laravel’s Encrypter to support RSA-wrapped keys (advanced).
• PHP Version: Requires PHP 7.4+ (compatible with Laravel 8+). No major version conflicts.

Technical Risk

• Key Management:
  • Risk: Private keys must be stored securely (e.g., Laravel’s Vault, AWS KMS, or encrypted filesystem). Loss of private keys = irreversible data loss.
  • Mitigation: Use Laravel’s filesystem with strict permissions or integrate with a secrets manager (e.g., HashiCorp Vault).
• Performance:
  • Risk: RSA operations (especially 4096-bit) are CPU-intensive. May impact latency for high-throughput systems.
  • Mitigation: Cache public keys in memory (e.g., Laravel’s cache facade) and use shorter keys (e.g., 2048-bit) where possible.
• Compatibility:
  • Risk: OpenSSL version mismatches (e.g., missing openssl_encrypt with OPENSSL_RAW_DATA flag).
  • Mitigation: Test on target PHP/OpenSSL versions (e.g., Laravel Forge/Plesk/Heroku).
• Deprecation:
  • Risk: Last release in 2021; no active maintenance. May miss PHP 8.2+ features or security updates.
  • Mitigation: Fork or wrap the package in a Laravel-specific service layer to isolate changes.

Key Questions

1. Security Requirements:
   • Are we encrypting data-at-rest (e.g., database secrets) or data-in-transit (e.g., API payloads)?
   • Do we need audit logs for key usage (e.g., who encrypted/decrypted a secret)?
2. Key Rotation:
   • How often will secrets be rotated? Will we need to support multiple key versions?
3. Performance:
   • What’s the expected throughput for encrypted operations? (Benchmark with 10K ops.)
4. Storage:
   • Where will private keys reside? (Laravel storage/, AWS Secrets Manager, etc.)
5. Fallback:
   • Should we maintain a dual-writing system (e.g., encrypt with Shh and Laravel’s Encrypter) during migration?

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • Encryption: Replace or supplement Laravel’s Encrypter (AES-256-CBC) with Shh for asymmetric use cases.
  • Storage:
    • Filesystem: Store encrypted secrets in storage/app/secrets/ (with filesystem disk).
    • Database: Use Laravel’s database connection to store encrypted blobs (e.g., encrypted_secrets table).
    • Cache: Cache public keys in cache:remember() or Redis.
  • Configuration: Bind Shh keys to Laravel’s config (e.g., config/shh.php).
• Dependencies:
  • Required: PHP 7.4+, OpenSSL extension.
  • Optional:
    • ramsey/uuid (if generating UUID-based key IDs).
    • spatie/laravel-encryption (for hybrid encryption patterns).

Migration Path

1. Phase 1: Proof of Concept (PoC)

   • Replace a single secret encryption use case (e.g., encrypting API tokens).
   • Compare performance vs. Laravel’s Encrypter (benchmark with microtime()).
   • Validate key storage (e.g., encrypted private key in storage/).

2. Phase 2: Hybrid Integration

   • Extend Laravel’s Encrypter to support RSA-wrapped keys:

     // app/Services/HybridEncrypter.php
     use BenTools\Shh\Shh;
     use Illuminate\Contracts\Encryption\Encrypter as LaravelEncrypter;
     
     class HybridEncrypter implements LaravelEncrypter {
         public function encrypt($value, $key = null): string {
             $rsaKey = Shh::encrypt($value, $publicKey);
             return LaravelEncrypter::encrypt($rsaKey);
         }
     }
     

   • Register as a Laravel service provider.

3. Phase 3: Full Adoption

   • Migrate all secrets to Shh-encrypted storage.
   • Implement key rotation logic (e.g., encrypt new secrets with both old/new keys).
   • Deprecate manual openssl_* usage in the codebase.

Compatibility

• Laravel Versions: Works with Laravel 8+ (PHP 7.4+). For Laravel 9/10, test with PHP 8.1+.
• OpenSSL Flags: Ensure OPENSSL_RAW_DATA and OPENSSL_PKCS1_OAEP_PADDING are supported.
• Key Formats: Private keys must be in PEM format (default for Shh).

Sequencing

1. Generate Keys:
   • Create a shh:generate Artisan command to output keys to storage/shh/.
   • Example:

     // app/Console/Commands/GenerateShhKeys.php
     use BenTools\Shh\Shh;
     use Illuminate\Console\Command;
     
     class GenerateShhKeys extends Command {
         public function handle() {
             [$publicKey, $privateKey] = Shh::generateKeyPair(
                 env('SHH_PASSPHRASE'),
                 ['private_key_bits' => 2048]
             );
             file_put_contents(storage_path('shh/public.key'), $publicKey);
             file_put_contents(storage_path('shh/private.key'), $privateKey);
         }
     }
     

2. Encrypt Secrets:
   • Replace direct openssl_encrypt() calls with Shh::encrypt().
   • Example:

     $encrypted = Shh::encrypt('sensitive-data', file_get_contents(storage_path('shh/public.key')));
     

3. Decrypt Secrets:
   • Use Shh::decrypt() with the private key (loaded securely).
   • Example:

     $decrypted = Shh::decrypt($encrypted, file_get_contents(storage_path('shh/private.key')));
     

Operational Impact

Maintenance

• Key Rotation:
  • Process: Generate new key pairs, re-encrypt all secrets with the new public key, then archive old private keys.
  • Tooling: Create an Artisan command to bulk-reencrypt secrets.
• Backup:
  • Critical: Private keys must be backed up offline (e.g., encrypted USB drive).
  • Automation: Use Laravel’s scheduler to backup keys to a secure location weekly.
• Monitoring:
  • Logs: Track Shh usage (e.g., which secrets are accessed/decrypted).
  • Alerts: Monitor for failed decryption (potential key corruption).

Support

• Troubleshooting:
  • Common Issues:
    • Key Corruption: Validate PEM files with openssl rsa -check.
    • Passphrase Errors: Ensure passphrases are stored in Laravel’s .env.
    • Performance Bottlenecks: Profile with Xdebug to identify slow RSA ops.
  • Debugging: Use Shh::getError() to catch OpenSSL errors.
• Documentation:
  • Internal Wiki: Document key storage locations, rotation procedures, and emergency recovery.
  • Error Handling: Add custom exceptions for Shh failures (e.g., ShhDecryptionFailedException).

**Scal