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