Installation

The installation of this library can be done with Composer:

composer require aplus/crypto

Getting Started

The Crypto library is built on top of Sodium, providing tools that simplify its use.

Box

The Box class allows communication with encrypted messages between two entities.

For this, both must have a public and a private key, generated by their own key pair.

Below we generate the key pair and keys for a user:

use Framework\Crypto\Box;

$user1KeyPair = Box::makeKeyPair(); // string
$user1PublicKey = Box::makePublicKey($user1KeyPair); // string
$user1SecretKey = Box::makeSecretKey($user1KeyPair); // string

Then we generate the key pair and another user's keys:

$user2KeyPair = Box::makeKeyPair(); // string
$user2PublicKey = Box::makePublicKey($user2KeyPair); // string
$user2SecretKey = Box::makeSecretKey($user2KeyPair); // string

Once that's done, let's create a box to encrypt messages from user 1 to user 2.

First, we create a nonce:

$nonce = Box::makeNonce(); // string

Next, we create the Box for user 1, using the secret key for user 1 and the public key for user 2:

$user1Box = new Box($user1SecretKey, $user2PublicKey, $nonce);

So we can encrypt a message with the encrypt method:

$messageFromUser1 = 'What is your name?';
$ciphertext1 = $user1Box->encrypt($messageFromUser1); // string

And it can already be decrypted by user 1, using the decrypt method:

$messageFromUser1 = $user1Box->decrypt($ciphertext1); // What is your name?

For the second user to be able to decrypt the message, it is necessary for him to create an instance of Box using his secret key, the public key of user 1 and the same nonce used in the message:

$user2Box = new Box($user2SecretKey, $user1PublicKey, $nonce);

With this, user 2 will be able to decrypt the ciphertext:

$messageFromUser1 = $user2Box->decrypt($ciphertext1); // What is your name?

To respond, user 2 can create an instance of Box, using user 1's public key:

$user2Box = new Box($user2SecretKey, $user1PublicKey, $nonce);

And then encrypt the message:

$messageFromUser2 = 'John';
$ciphertext2 = $user2Box->encrypt($messageFromUser2); // string

Then the ciphertext can be decrypted by user 1:

$messageFromUser2 = $user1Box->decrypt($ciphertext2); // John

And by user 2 himself:

$messageFromUser2 = $user2Box->decrypt($ciphertext2); // John

BoxSeal

BoxSeal allows you to encrypt a message so that only the recipient can decrypt it.

First of all, the recipient needs to have a keypair that can be generated by the makeKeyPair method:

use Framework\Crypto\BoxSeal;

$keyPair = BoxSeal::makeKeyPair(); // string

Then it generates a public key with the makePublicKey method:

$publicKey = BoxSeal::makePublicKey($keyPair); // string

And this public key will be given to whoever will encrypt the messages.

Below is a message being encrypted:

$message = 'Expect Us!';
$ciphertext = BoxSeal::encrypt($message, $publicKey); // string

Then, when the ciphertext is delivered to the recipient, he can decrypt the message using the $keyPair with the decrypt method:

$message = BoxSeal::decrypt($ciphertext, $keyPair); // Expect Us!

GenericHash

The GenericHash class allows verifying messages through signatures.

First, you must generate a key with the makeKey method:

use Framework\Crypto\GenericHash;

$key = GenericHash::makeKey(); // string

Once this is done, it is possible to generate signatures for messages. Let's look at the following example:

$genericHash = new GenericHash($key);

$message = 'Hello, friend';
$signature = $genericHash->signature($message); // string

And then you can perform the verification:

if ($genericHash->verify($message, $signature)) {
    echo 'Message is verified.';
} else {
    echo 'Error: Message is not verified.';
}

Password

With the Password class it is possible to generate hashes and verify passwords.

Let's see how to generate a hash:

use Framework\Crypto\Password;

$password = 'iloveyou';
$hash = Password::hash($password); // string

The hash can be saved for future verification with the user's password, it is 97 characters long.

To verify that the password is valid, comparing it with the saved hash, you can use the verify method:

Password::verify($password, $hash); // bool

If it returns true, the password is correct.

The hash method has two parameters for setting Limits:

$opslimit = Password::LIMIT_INTERACTIVE;
$memlimit = Password::LIMIT_MODERATE;
$hash = Password::hash($password, $opslimit, $memlimit); // string

When limits change, it may be necessary to recreate a valid hash to store.

To find out if you need to create a new hash, use the needsRehash method:

Password::needsRehash($hash); // bool

It also has parameters to pass the limits of operations and memory:

if (Password::needsRehash($hash, Password::LIMIT_MODERATE)) {
    $hash = Password::hash($password, Password::LIMIT_MODERATE);
}

Password::setOpsLimit(Password::LIMIT_SENSITIVE); // void
Password::setMemLimit(Password::LIMIT_MODERATE); // void

use Framework\Crypto\SecretBox;

$key = SecretBox::makeKey(); // string
$nonce = SecretBox::makeNonce(); // string

$secretBox = new SecretBox($key, $nonce);

$message = 'Hello, Sodium!';
$ciphertext = $secretBox->encrypt($message); // string

$message = $secretBox->decrypt($ciphertext); // string or false

use Framework\Crypto\Sign;

$keyPair = Sign::makeKeyPair(); // string

$secretKey = Sign::makeSecretKey($keyPair); // string

$publicKey = Sign::makePublicKey($keyPair); // string

$message = 'Ai, aiaiai quiri qui uai';
$signature = Sign::signature($message, $secretKey); // string

if (Sign::verify($message, $signature, $publicKey)) {
    echo 'Signature is verified!';
} else {
    echo 'Error: Signature is not verified!';
}

use Framework\Crypto\Utils;

$string = 'foo';
$hex = Utils::bin2hex($string); // string

$string = Utils::hex2bin($hex); // string

use Framework\Crypto\Utils;

$string = 'foo';
$base64 = Utils::bin2base64($string); // string

$string = Utils::base642bin($base64); // string