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:

1. We start with a plain text message.
2. We encrypt it using a shared secret key and an initialisation-vector (IV).
3. We transmit the cipher text and IV.
4. We reconstruct the encrypted message on the receiving side.
5. 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 secretbox itself 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 PlainTextMessage and EncryptedMessage when you are sending cipher text and IV separately.
• Use CipherText::getUri() and EncryptedUri when you are sending encrypted data through a link or redirect.
• Use Key directly 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.