Click the Castor logo or press Ctrl Alt T to change theme.
# Error handling Castor Crypto reports cryptographic failures with `Castor\Crypto\CryptoError`. You will see it when encoded input is invalid, key material has the wrong shape, decryption authentication fails, or libsodium rejects an operation. ## Treat decryption failure as authentication failure Authenticated encryption does not produce partial plaintext. If decryption fails, discard the ciphertext and return a generic application error. ```php <?php use Castor\Crypto\CryptoError; try { $secret = $key->decrypt($ciphertext, aad: $context); } catch (CryptoError) { // Wrong key, wrong context, tampered ciphertext, or corrupted storage. throw new RuntimeException('Could not read encrypted value.'); } ``` Do not tell an attacker whether the key, ciphertext, signature, or context was the part that failed. ## Signatures usually return true or false Signature verification returns a boolean: ```php if (!$verificationKey->verify($message, $signature)) { // Reject the payload. } ``` Invalid encodings can still throw before verification. Decode untrusted input inside a try/catch and respond with the same generic failure you use for a bad signature. ## Password verification is a normal branch A wrong password is not exceptional. `verify()` returns `false` for a mismatch: ```php if (!$hash->verify($submitted)) { // Invalid credentials. } ``` Keep login responses generic so attackers cannot enumerate accounts or learn which part of the credential pair was wrong. ## Logging safely It is usually safe to log stable metadata: user id, key id, record id, algorithm version, or an internal request id. Avoid logging plaintext, submitted passwords, secret keys, derived keys, or full ciphertexts unless you have a specific incident-response reason and a safe log pipeline. A good production error message helps operators find the failing record without giving attackers a cryptographic oracle.
Castor ecosystem