Click the Castor logo or press Ctrl Alt T to change theme.
# Public-key encryption between systems Public-key encryption helps when one system needs to send encrypted data to another without sharing the same long-term symmetric key. Each party has a key pair: the public key can be shared, the secret key stays private. Castor Crypto exposes libsodium `crypto_box` through `KeyPair`, `PublicKey`, and `SecretKey`. ## Anonymous inbox encryption Use a recipient's public key when anyone should be able to submit a confidential message, but the recipient does not need cryptographic proof of who sent it. ```php <?php use Castor\Crypto\Asymmetric\KeyPair; use Castor\Crypto\Secret; $recipient = KeyPair::generate(); $public = $recipient->getPublic(); $ciphertext = $public->encrypt(Secret::raw('security report contents')); // Only the recipient key pair can open it. $plaintext = $recipient->decrypt($ciphertext); ``` This is good for inbox-style flows: encrypted contact forms, client-side crash reports, or drop boxes. It gives confidentiality, but not sender identity. ## Authenticated encryption between Alice and Bob When both sides have key pairs, the sender combines their secret key with the recipient's public key. The recipient combines their secret key with the sender's public key. ```php <?php use Castor\Crypto\Asymmetric\KeyPair; use Castor\Crypto\Secret; $alice = KeyPair::generate(); $bob = KeyPair::generate(); $bobToAlice = KeyPair::fromParts($bob->getSecret(), $alice->getPublic()); $aliceFromBob = KeyPair::fromParts($alice->getSecret(), $bob->getPublic()); $ciphertext = $bobToAlice->encryptAuth(Secret::raw('Hello Alice')); $plaintext = $aliceFromBob->decryptAuth($ciphertext); ``` `encryptAuth()` generates and stores the nonce inside the returned ciphertext as `nonce || encrypted message`. If the ciphertext is modified or opened with the wrong key combination, `decryptAuth()` throws `CryptoError`. ## Store and exchange keys Keys extend `SecretText`, so they can be encoded for storage and transport: ```php $publicForApi = $alice->getPublic()->toBase64(); $secretForVault = $alice->getSecret()->toBase64(); ``` Public keys may be published. Secret keys should live in a secret manager, encrypted config store, or other protected location. A full `KeyPair` also contains secret material and must be protected. ## Authenticity still needs identity Authenticated encryption proves that a message was created by whoever controls the matching secret key. Your application still needs to know which public key belongs to which service, user, or tenant. Pin public keys in configuration, verify them through an account setup flow, or distribute them through an authenticated channel. If an attacker can replace Bob's public key during setup, Alice will encrypt to the attacker instead. ## Tradeoffs and attack vectors Public-key encryption is convenient for multi-party systems, but it does not remove key management. Secret-key compromise exposes future messages and may expose stored messages if old ciphertexts are still available. Anonymous sealed boxes hide the sender. That is useful for drop boxes, but wrong for audit trails. Use authenticated encryption or signatures when sender identity matters. Replay is still possible: a valid ciphertext can be sent twice. Include application-level message ids or timestamps when duplicates are dangerous.
Castor ecosystem