gabbro-php/crypt

Encryption and Hash library

1.006466 2025-09-27 14:20 UTC

Requires

• php: >=8.0.0
• gabbro-php/base: >=1.006466

Suggests

• ext-php_openssl: Needed in order to use the SSL Cipher class
• ext-sodium: Needed in order to use the Sodium Digest and Cipher classes
• gabbro-php/http: Needed if you want to use SignedCookieRegistry (version 1.*)

MIT

• Daniel Bergløv

README

This library provides a unified abstraction layer for message digests and symmetric ciphers, built around two core interfaces:

• Digest — for hashing, HMACs, verification, and key derivation.
• Cipher — for symmetric encryption and decryption.

It includes implementations backed by both PHP’s native extensions (hash, OpenSSL) and libsodium, so you can pick the provider that best fits your environment.

✨ Features

Digest

• Unified interface for:
  • Hashing arbitrary data
  • Creating and verifying MACs
  • Deriving keys from global secrets + salt
• Configurable “levels” for computational cost:
  • Fast (low iterations)
  • Moderate (default for most apps)
  • Sensitive (high security, slow, suitable for offline tasks)
• Implementations:
  • HashDigest: Uses PHP’s hash_* and hash_pbkdf2
  • SodiumDigest: Uses libsodium’s crypto_pwhash, crypto_generichash, and crypto_auth

Cipher

• Unified interface for symmetric encryption/decryption
• Implementations:
  • SSLCipher: Wraps OpenSSL, supporting AES, Camellia, Aria, and many other algorithms/modes.
  • SodiumCipher: Wraps libsodium’s crypto_secretbox, providing authenticated encryption (confidentiality + integrity in one step).
• Automatic key and IV/nonce management, with helpers for generation and normalization.

🔑 Security Model

• OpenSSL ciphers: require explicit IVs and may require separate HMACs for authenticity (unless using AEAD modes like GCM).
• Sodium ciphers: always use authenticated encryption (via XSalsa20 + Poly1305). Any tampering with ciphertext is detected during decryption.

This library ensures correct handling of secrets, salts, IVs, and nonces to reduce cryptographic misuse.

📦 Requirements

• OpenSSL extension (for SSLCipher)
• Libsodium extension (for SodiumCipher / SodiumDigest)

🔐 Philosophy

The main goal is to make crypto easy to use correctly:

• Configure once (secret, salt, key size, cipher mode).
• Use everywhere without boilerplate.
• Provide safe defaults and abstract away low-level details.