Overview
Cipher is intentionally small. Rather than exposing a large encryption framework, it wraps one clear workflow around libsodium’s secretbox functions.
The main idea is simple:
- We start with a plain text message.
- We encrypt it using a shared secret key and an initialisation-vector (IV).
- We transmit the cipher text and IV.
- We reconstruct the encrypted message on the receiving side.
- We decrypt it using the same shared key.
The main objects
Key
Key holds the shared secret bytes. If we do not pass bytes into the constructor, a secure random key is generated for us.
Casting the object to a string gives us a base64 representation, which is convenient for storage or transport:
$key = new GT\Cipher\Key();
echo (string)$key;
That string form is for transport or display. The actual encryption methods use the raw bytes internally.
InitVector
Every message needs an IV. In this library, the InitVector is generated automatically when a message is constructed, unless we pass one in ourselves.
The IV is not secret, but it is still required for decryption. If we send cipher text to another system, we must send the IV alongside it.
[!NOTE] In cryptography, an Initialisation Vector is sometimes also known as a “nonce” See wikipedia’s page for more information.
PlainTextMessage
This is the object we construct when we have clear text data and want to encrypt it.
use GT\Cipher\Message\PlainTextMessage;
$message = new PlainTextMessage("Quarterly figures attached");
Calling encrypt() returns a CipherText object:
$cipherText = $message->encrypt($key);
CipherText
CipherText represents the encrypted bytes. Casting it to a string gives the base64 encoded cipher text that we would usually transmit to another system.
It also has getUri(), which appends the cipher text and IV to a URI as cipher and iv query string parameters.
EncryptedMessage
This is the receiving-side counterpart to PlainTextMessage. We construct it from the incoming cipher text and IV, then call decrypt() with the same key.
EncryptedUri
If the sender chose to transmit the encrypted message in a query string, EncryptedUri can read the URI, extract the cipher and iv values, and decrypt them in one step.
What Cipher does not try to do
This library does not handle:
- key exchange between systems
- public/private key cryptography
- long-term secret storage
- signing or authenticity checks beyond what
secretboxitself provides - message serialisation beyond strings and query string transport
That is deliberate. Cipher keeps one common secret-key message flow small, readable, and easy to reuse.
Choosing the right entry point
- Use
PlainTextMessageandEncryptedMessagewhen you are sending cipher text and IV separately. - Use
CipherText::getUri()andEncryptedUriwhen you are sending encrypted data through a link or redirect. - Use
Keydirectly when you need to generate, serialise, or reconstruct a shared key.
Now that the shape of the library is clear, move on to Getting started.