Crypto
A well designed cryptographic library for php., (*1)
Install
composer require krak/crypto
Design
The Crypto Library has two main interfaces: Crypt and Pad., (*2)
A Crypt is what does the encryption and decryption., (*3)
A Pad is what does the padding and stripping., (*4)
Usage
<?php
use Krak\Crypto;
$key = random_bytes(16);
$hmac_key = random_bytes(16);
$crypt = new Crypto\OpenSSLCrypt($key);
$crypt = new Crypto\Base64Crypt(new Crypto\HmacCrypt($crypt, $hmac_key));
$encrypted = $crypt->encrypt('data');
echo $crypt->decrypt($encrypted);
// outputs: data
All Crypts implement the interface Krak\Crypto\Crypt, (*5)
You can also use any of the Krak\Crypto\Pad classes, (*6)
<?php
use Krak\Crypto;
$pad = new Crypto\Pkcs7Pad();
$padded = $pad->pad('abc');
echo $pad->strip($padded);
// outputs: abc
Crypt
The Crypt libraries are responsible for encrypting the data. There are crypt implementations that do encryption and others that are just decorators., (*7)
McryptCrypt and OpenSSLCrypt handle encryption. Each crypt uses the Krak\Crypto\pack_payload method to prepend the iv to the cipher text., (*8)
Note: Please be knowledgeable of the keys you pass in. The key size depends on the algorithm and typically ranges from 8, 16, 24, or 32 bytes., (*9)
Base64Crypt, HmacCrypt, and are decorators for providing base64 encoding and hmac signing/authentication for your messages., (*10)
GnuPGCliCrypt handles encrypting via the gpg cli utility., (*11)
<?php
$crypt = new Krak\Crypt\GnuPGCliCrypt('User Name', $passphrase = 'secret', $gpg_executable_path = 'gpg');
It will encrypt/decrypt data with the public and private keys for the given $username. Important: you need to make sure the keys are properly imported into your gpg cli tool. We use the --always-trust flag for encrypting, so make sure the keys you add are properly trusted., (*12)
This crypt also requires the symfony/process component to be installed., (*13)
NullCrypt is used more for testing or mocking. It just returns the data passed to it., (*14)
Pad Types
-
Krak\Crypto\Pkcs7Pad - pads via the pkcs7 algorithm
-
Krak\Crypto\NullBytePad - pads by appending null bytes.
-
Krak\Crypto\NoPad - doesn't apply any padding, just returns the string as is.
Iv Gen
The crypts take in a parameter for iv generation. There are three types:, (*15)
-
Krak\Crypto\mcrypt_iv_gen() - creates a mcrypt iv generator which uses
mcrypt_create_iv
-
Krak\Crypto\php_iv_gen() - creates an iv gen that uses
random_bytes. We use the paragonie/random_compat library to handle non php7 users
-
Krak\Crypto\static_iv_gen($iv) - creates an iv gen that takes an iv and always returns that iv for generation.
Streams
The crypt library has also created a concept called a Stream. Crypto streams works very similar to nodejs streams, where they are stream of buffers/content. Streams are very handy for encrypting large amounts of data because of how they efficiently pipe their information along. Here's an example of using streams to upper case content, encrypt, and then encode., (*16)
<?php
use Krak\Crypto;
$stream = Crypto\str_stream('this is some data'); // create a stream from raw string.
$stream = new Crypto\StreamPipe($stream);
$crypt_stream = new Crypto\Stream\CryptStream(new Crypto\OpenSSLCrypt($key), 16); // encrypt/decrypt 16 byte chunks at a time
$base64_stream = new Crypto\Stream\Base64Stream(64); // encode/decode 64 byte chunks at a time
$key = random_bytes(16);
$dst = fopen('php://stdout', 'w');
$stream->pipe(Crypto\map_stream('strtoupper'))
->pipe($crypt_stream->encrypt())
->pipe($base64_stream->encode())
->pipe(Crypt\write_stream($dst));
// at this point, stdout will have encrypted uppercased info.
Look at the API to see all of the different streams and how to use them., (*17)
API
Run make api to create the api documentation. Then open up docs/api/index.html to view the API docs., (*18)
Test
Run tests with peridot via, (*19)
make test
Wallogit.com
