Click the Castor logo or press Ctrl Alt T to change theme.
# Getting started The safest way to use cryptography is to name the job before choosing the primitive. "I need encryption" is often too vague. Do you need to recover a secret later? Verify that a browser did not edit a link? Store a password? Let another service send you confidential data? Each of those has a different answer. This guide gives you the mental map. The recipe pages contain the full examples. ## Step 1: identify what must be protected Start by writing down the asset and the attacker. For example: - "If the database leaks, OAuth refresh tokens should not be readable." - "If a customer edits an invitation URL, they should not be able to change the email address." - "If uploaded files are moved between storage systems, we want to detect corruption." - "If passwords leak from the users table, attackers should still need to guess them one by one." This sentence matters because cryptographic primitives are narrow tools. A signature will not hide an OAuth token. Encryption will not tell you who wrote a message unless you choose an authenticated mode. A fast hash will not protect weak passwords from offline guessing. ## Step 2: pick the primitive by failure mode For database secrets, read [Symmetric encryption](symmetric-encryption.html). The main failure to prevent is disclosure after storage compromise, with tamper detection as a bonus. For passwords, read [Password hashing](password-hashing.html). The main failure to slow down is offline guessing after a database leak. For tamper-proof payloads, read [Signed data](signed-data.html). The main failure to prevent is forgery or modification while keeping the payload readable. For messages between independent systems, read [Public-key encryption](key-pairs.html). The main problem is key distribution: one side can publish a public key while keeping its secret key private. For fingerprints and integrity checks, read [Generic hashing](generic-hashing.html). The main goal is stable identification of bytes, not secrecy. ## Step 3: keep boundaries explicit Castor Crypto asks you to wrap sensitive input in `Secret`: ```php <?php use Castor\Crypto\Secret; $password = Secret::raw($_POST['password']); ``` That small ceremony is intentional. It marks the point where ordinary application data becomes sensitive cryptographic material. `Secret` values do not echo accidentally, do not dump their contents, and are wiped on destruction when PHP and libsodium allow it. Values that need to cross text boundaries, such as ciphertexts, keys, signatures, and hashes, use `SecretText` encoding helpers. Read [Secrets and text boundaries](secrets.html) before designing storage formats. ## Step 4: design storage before shipping Most production mistakes happen around the primitive, not inside it. Decide where keys live, how you rotate them, what context is authenticated, what errors are shown to users, and whether replay matters. A good implementation has an answer to these questions before the first encrypted value or signed token is created. The recipe pages call out those tradeoffs where they appear.
Castor ecosystem