Sodium Compat Laravel Package

Getting Started

1. Install via Composer: composer require paragonie/sodium_compat. No configuration needed—just require_once 'vendor/autoload.php';.
2. First use case: Securely store user passwords using sodium_crypto_pwhash() (Argon2id), even on shared hosting where ext/sodium isn’t available:

   $passwordHash = sodium_crypto_pwhash(
       64, // hash length
       'user_password_here',
       sodium_randombytes_buf(SODIUM_CRYPTO_PWHASH_SALTBYTES),
       SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE,
       SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE,
       SODIUM_CRYPTO_PWHASH_ALG_ARGON2ID13
   );
   

3. Check compatibility: Call Sodium\Library::versionString() to confirm the polyfill is active. No native extension required.

Implementation Patterns

• Uniform crypto calls: Use sodium_*() functions throughout your codebase—code works identically in environments with or without ext/sodium.
• Key management patterns:
  • Generate ephemeral keys for file encryption:

    $key = sodium_crypto_secretbox_keygen();
    $nonce = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
    $ciphertext = sodium_crypto_secretbox($plaintext, $nonce, $key);
    

  • Derive keys from passwords (e.g., for API tokens):

    $derivedKey = sodium_crypto_pwhash(
        32,
        $userPassword,
        $salt,
        SODIUM_CRYPTO_PWHASH_OPSLIMIT_MODERATE,
        SODIUM_CRYPTO_PWHASH_MEMLIMIT_MODERATE
    );
    

• Hybrid deployment strategy: Deploy without native libsodium in staging/dev, then auto-upgrade to ext/sodium in production—no code changes needed.

Gotchas and Tips

• Performance trap: Pure-PHP crypto is ~10–100× slower than ext/sodium. Benchmark sodium_crypto_secretbox() for your payload sizes—avoid on high-throughput crypto-heavy endpoints.
• Constant availability: SODIUM_CRYPTO_* constants are auto-exported—no need to use them. Avoid hardcoding magic numbers (e.g., 32 for key length); prefer SODIUM_CRYPTO_SECRETBOX_KEYBYTES.
• Testing gotcha: Unit tests often run in CLI (where ext/sodium might be installed). Use if (!extension_loaded('sodium')) { sodium_compat_init(); } in test bootstrap to force polyfill consistency.
• Extension priority: If both polyfill and ext/sodium are loaded, ext/sodium wins—verify with function_exists('sodium_crypto_box_keypair').
• Upgrade path: Once ext/sodium is installed, remove the polyfill from composer.json— Laravel’s auto-discovery and native bindings will take over seamlessly.
• Critical tip: Always use random_bytes() (not mt_rand()) for nonces/secrets. The polyfill adds a CSPRNG fallback if unavailable.