Download the PHP package ivansostarko/otto-crypt-php without Composer

OTTO Crypt — Laravel Package

OTTO Crypt is a Laravel‑ready crypto package that provides end‑to‑end encryption (E2EE) and chunked streaming AEAD for large files (video/audio), while remaining simple to use in apps and Artisan CLI.

⚠️ Security notice: OTTO Crypt uses trusted primitives (AES‑256‑GCM, Argon2id, HKDF, X25519), but its composition ("OTTO‑256‑GCM‑HKDF‑SIV") is custom. Treat it as experimental until it undergoes an independent cryptographic review.

Table of contents

• Highlights
• Installation
• Quick start
  • CLI (Artisan)
  • Laravel API (Facade)
• Design & Format
  • Construction: OTTO‑256‑GCM‑HKDF‑SIV
  • Header layout
  • Streaming/chunk format
  • Key derivation
  • Nonce derivation (HKDF‑SIV style)
  • X25519 E2E mode
• Configuration
• Comparison with other schemes
• Threat model & security notes
• Performance
• Docker
• Examples
• Roadmap
• FAQ
• Contributing
• License
• Responsible disclosure

Highlights

• AES‑256‑GCM AEAD for authenticated encryption (16‑byte tags).
• HKDF‑SIV‑style nonces (misuse‑resistance against nonce reuse by deriving nonces deterministically per chunk).
• Streaming / chunked encryption for very large files (default chunk 1 MiB; configurable).
• E2E session keys via X25519 (ephemeral ECDH) or Argon2id password KDF, or direct 32‑byte raw keys.
• Associated Data = full header, binding ciphertext to algorithm, salts, KDF params, and sender ephemeral key.
• Laravel native: auto‑discovered Service Provider + Facade + Artisan commands.

Installation

Requirements: PHP 8.2+, ext-openssl, ext-sodium, Laravel 12.

Quick start

CLI (Artisan)

Encrypt with a password (Argon2id):

Decrypt with a password:

End‑to‑end: encrypt to a recipient’s X25519 public key (base64/hex/raw):

End‑to‑end: decrypt with your X25519 secret key:

Laravel API (Facade)

Key exchange helpers:

Design & Format

Construction: OTTO‑256‑GCM‑HKDF‑SIV

• Base AEAD: AES‑256‑GCM (OpenSSL). Tag length: 16 bytes.
• Master key sources: 1) Argon2id(password, pwSalt, opslimit, memlimit) → 32‑byte master key
  2) Raw key (exactly 32 bytes)
  3) X25519 ECDH (ephemeral sender key + recipient public key) = shared secret → HKDF → 32‑byte master
• From the master key and a per‑file file_salt, we derive:
  • enc_key = HKDF(master, len=32, info="OTTO-ENC-KEY", salt=file_salt)
  • nonce_key= HKDF(master, len=32, info="OTTO-NONCE-KEY", salt=file_salt)
• Nonces are not random. For each chunk i, we derive:
  • nonce_i = HKDF(nonce_key, len=12, info="OTTO-CHUNK-NONCE" || counter64be)
    This deterministic (SIV‑style) nonce avoids catastrophic failures if an app mistakenly reuses nonces.
• Associated Data (AD) for every encryption is the full header. Any change to header (algo ID, salts, KDF params, ephemeral key) invalidates decryption.

Header layout

Binary header (fixed + variable):

Streaming/chunk format

For each plaintext chunk:

Each chunk is independently AEAD‑protected with its own derived nonce and the header as AD.

Key derivation

• Argon2id defaults (moderate work/memory) are configurable. Use strong passwords or password managers.
• Raw 32‑byte keys are accepted for systems that perform KDF externally.
• X25519: ephemeral sender secret/public and recipient public → shared = scalarmult(sk_eph, pk_rcpt) → master = HKDF(shared, len=32, info="OTTO-E2E-MASTER", salt=file_salt).

Nonce derivation (HKDF‑SIV style)

This provides deterministic per‑chunk nonces without persisting counters externally and protects against app‑level nonce reuse mistakes.

X25519 E2E mode

• Sender: generates ephemeral 32‑byte secret and publishes the corresponding public key in the header’s HVAR.
• Recipient: uses their long‑term secret key with sender’s ephemeral public to derive the same ECDH shared secret and then the same master key → enc_key + nonce_key.
• This gives forward secrecy for sessions (compromise of long‑term keys later does not reveal past sessions if ephemeral keys were erased).

Configuration

config/otto-crypt.php (after publish):

Tune Argon2id for your hardware. Larger memory/time improves password resistance at a performance cost.

Comparison with other schemes

Why OTTO? You need:

• Laravel‑native streaming AEAD over AES‑GCM,
• Deterministic nonce derivation to reduce misuse risks, and
• Simple E2E with X25519 baked in.

If you do not need AES or Laravel integration, consider libsodium’s crypto_secretstream (widely reviewed).

Threat model & security notes

• Provides confidentiality + integrity (AEAD) for data at rest or in transit.
• Resists accidental nonce reuse (per‑chunk HKDF‑derived nonces).
• Does not protect against endpoint compromise (malware/infostealers).
• Password mode security depends on password strength and Argon2id parameters. Prefer E2E keys for messengers.
• Forward secrecy: E2E mode uses ephemeral sender keys per session. Ensure ephemeral secrets are destroyed after use.
• Randomness: uses PHP/OpenSSL and libsodium PRNGs. Ensure the OS has good entropy.
• Side‑channels: standard OpenSSL AES‑GCM; this library does not attempt to harden against all timing/memory side channels.
• Key erasure: sensitive material is zeroed where feasible (sodium_memzero) after use, but ephemeral copies may exist in PHP/OPcache/streams.
• Audit: get a professional review before production. Treat current version as pre‑audit.

Performance

• AES‑256‑GCM leverages AES‑NI when available (OpenSSL).
• HKDF and Argon2id add CPU cost at session setup; chunk encryption is dominated by AES‑GCM.
• Adjust chunk_size for throughput vs. memory usage (1–8 MiB is typical).

Roadmap

• Unit/integration tests and test vectors.
• Optional AEAD‑SIV (RFC 5297) backend for fully standardized misuse resistance.
• Multi‑recipient E2E (encrypt same key to several recipients).
• Format versioning & negotiation.
• PHP FFI bindings for hardware engines (where available).

FAQ

Q: Is OTTO Crypt FIPS compliant?
A: It uses OpenSSL’s AES‑GCM and HKDF, which may be FIPS‑validated depending on your OpenSSL build, but the overall construction is custom and not a NIST‑standard scheme.

Q: Can I rotate keys?
A: Yes. Re‑encrypt with a new recipient public key or password. The header binds parameters to ciphertext.

Q: Why not random nonces?
A: Random or monotonic nonces are fine if implemented perfectly. Deterministic HKDF‑derived nonces help avoid catastrophic accidental reuse in complex streaming/parallel code.

Q: Message vs file?
A: encryptString for small payloads; encryptFile for streaming large data (audio/video/files).

Q: Does this replace libsodium secretstream?
A: No. If you can use libsodium’s crypto_secretstream, it’s excellent. OTTO focuses on AES‑GCM, Laravel integration, and simple E2E helper flows.

Contributing

PRs welcome. Please include:

• Clear problem statement
• Tests (PHPUnit / Testbench)
• Security considerations for cryptographic changes

Before suggesting algorithmic changes, open an issue to discuss implications.

License

MIT © 2025 Ivan Sostarko

Responsible disclosure

If you discover a vulnerability, do not open a public issue. Email the maintainer privately (see composer.json author) with details and steps to reproduce. We’ll coordinate a fix and a responsible disclosure timeline.