Constant Time Encoding Laravel Package

Getting Started

Start by installing the package via Composer:

composer require paragonie/constant_time_encoding

Then, import the relevant encoder classes directly—no configuration or service setup required. The most common first use case is securely encoding/decoding sensitive values like tokens or keys without leaking timing information. For example, to safely encode a secret token for URL-safe transmission:

use ParagonIE\ConstantTime\Base64Url;

$token = random_bytes(32);
$encoded = Base64Url::encode($token); // Constant-time, URL-safe Base64

Check the src/ directory in the repository for a complete list of available codecs (Base64, Base64Url, Hex, Base32, Base32Hex), and consult test/ for real-world examples.

Implementation Patterns

• Secure Token Handling: Use Base64Url::encode() for JWT header/payload encoding or session tokens where URL compatibility and timing safety are both critical.
• Secret Decoding with Validation: Always use the library’s decode methods instead of manual base64_decode()—they enforce strict character-set validation and throw exceptions on malformed input, avoiding silent failures that could leak side-channel information.

  try {
      $secret = Base64Url::decode($userInput);
  } catch (\TypeError $e) {
      // Invalid encoding—treat as untrusted
  }
  

• Key Derivation Interop: Integrate with libs like paragonie/sodium_compat or defuse/php-encryption where constant-time operations chain (e.g., decoding a key before use in sodium_crypto_secretbox()).
• HTTP Header Sanitization: Safely decode Authorization tokens (e.g., Bearer with Base64-encoded credentials) without exposing timing differences between valid/invalid payloads.

Gotchas and Tips

• No autoloading guarantees for legacy PHP: While PHP 7.4+ is well-supported, avoid using this on PHP <7.2—though technically possible, the library is not tested there.
• Case sensitivity matters for Base32/Hex: Base32::decode() rejects uppercase letters (per RFC 4648), and Hex::decode() expects lowercase only—validate user input before passing it or use strict encoders for output to avoid mismatches.
• Avoid manual base64_encode/decode elsewhere: Even if you use constant_time_encoding for decoding, using PHP’s native base64_encode() in parallel (e.g., for logging) can reintroduce timing leaks. Standardize on this library for all secret-related encoding/decoding.
• Extension hook: custom codecs: While not officially supported, you can subclass Encoder and Decoder traits to add bespoke codecs—but double-check constant-time guarantees using tools like Tock.
• Debugging timing leaks: If you suspect a timing vulnerability despite using this library, verify you’re not using strcmp() or === on decoded values in other layers—this library only secures the encoding/decoding step itself.