Click the Castor logo or press Ctrl Alt T to change theme.
# Secrets and text boundaries Most security bugs are not failures of the primitive. They are ordinary application mistakes: logging a token, dumping a password in an exception page, storing a key in the wrong place, or confusing encoded text with raw bytes. Castor Crypto uses `Secret` and `SecretText` to make those boundaries visible. ## Secret is for sensitive bytes ```php <?php use Castor\Crypto\Secret; $password = Secret::raw($_POST['password']); ``` A `Secret` refuses accidental string casting. `echo $password` throws `CryptoError`, debug output hides the value, and the object attempts to wipe its bytes when destroyed. When you intentionally need the plaintext, call `toString()` at the boundary where your application consumes it: ```php $plaintext = $decrypted->toString(); ``` Keep that boundary small. The moment you turn a `Secret` back into a PHP string, normal PHP logging and debugging risks apply again. ## SecretText is for bytes that may need encoding `SecretText` extends `Secret` with hex and Base64 helpers. Ciphertexts, hashes, keys, signatures, and public keys often need to cross text-only boundaries such as JSON, URLs, environment variables, or database text columns. ```php $encoded = $ciphertext->toBase64(); $restored = SecretText::fromBase64($encoded); ``` Encoding is not encryption. A Base64 secret key is still a secret key. A Base64 ciphertext is still ciphertext. A Base64 public key is safe to publish because the underlying value is public, not because Base64 made it safe. ## Compare wrapped values Use `equals()` for wrapped cryptographic values: ```php if ($expected->equals($actual)) { // Match. } ``` This delegates to libsodium comparison instead of ordinary PHP string comparison. ## Practical rule Wrap sensitive input as soon as it enters cryptographic code. Decode stored values into typed objects before use. Convert back to strings only when you store, transmit, or intentionally reveal a result.
Castor ecosystem