Castor Crypto — castor/crypto

# Castor Crypto Castor Crypto is a small PHP library for using libsodium through explicit, typed objects. It is meant for application developers who need to protect real features: account passwords, database secrets, webhook payloads, user-visible tokens, uploaded files, and messages between services. This documentation is written around those jobs. Instead of starting with a class reference, it starts with the question you usually have in an application: "What am I trying to protect, and from whom?" Once that is clear, the primitive choice becomes much easier. ## Install Castor packages are published in the Castor Composer repository: ```bash composer config repositories.castor composer https://castor-labs.github.io/php-packages composer require castor/crypto ``` You need PHP 8.3 or newer and the `sodium` extension. ## Choose by security goal If you need to **store login passwords**, use [Password hashing](docs/password-hashing.html). Passwords are guessed by attackers after database leaks, so they need slow, memory-hard hashing. Encryption is the wrong model because there should be no key that can "decrypt" every user's password. If you need to **read a secret later**, use [Symmetric encryption](docs/symmetric-encryption.html). This is the common database-field encryption case: OAuth refresh tokens, API credentials, private integration settings, or private notes. Your application owns a secret key and uses it to encrypt and decrypt values. If you need to **prove data was created by your application**, use [Signed data](docs/signed-data.html). Signatures are for tamper-proof links, webhook bodies, manifests, queue messages, and public payloads. They do not hide the message; they make modification detectable. If you need to **receive encrypted messages from another party**, use [Public-key encryption](docs/key-pairs.html). Public keys let senders encrypt to you without first sharing a symmetric secret. Authenticated public-key encryption also lets the receiver know which key pair produced the message. If you need a **fingerprint**, use [Generic hashing](docs/generic-hashing.html). Hashes are useful for file integrity, cache keys, content addressing, and keyed internal identifiers. They are not password hashes and they are not encryption. ## The one habit that prevents many mistakes Treat cryptographic values according to what they are, not according to how they look. A Base64 key is still a key. A ciphertext can usually be stored, but the key that opens it must live somewhere else. A signature can be public, but the signing key must be guarded. A hash may be safe to display for a file fingerprint, but not if it is a fast hash of a predictable secret. Castor Crypto helps by wrapping sensitive bytes in `Secret` and encoded cryptographic bytes in `SecretText`. Those objects make accidental logging and string conversion harder, but they do not replace application design. The guides explain the design choices and the failure modes that matter for each primitive.

Next → Documentation