Laravel General Hashing

Wrapper classes for common hashing functions

Laravel General Hashing

Introduction

Many web applications use some kind of cryptography, but most programmers do not know what algorithm to use.

There are a lot of choices, but most of them are terrible these days (Looking at MD4 and MD5). Most of the good functions have really confusing API (like libsodium), so I wanted a clean "Laravel Way" and OOP access to these API's. I chose to write Laravel library (because Laravel is most commonly used php framework) that will help programmers (especially new ones) when they need cryptography.

This library provides Hashing and Signature algorithms with easy to use API.

Getting started

Installing

$ composer require brossquad/laravel-crypto

Publishing config file

php artisan vendor:publish --provider="BrosSquad\LaravelCrypto\HashingServiceProvider"

Generating EdDSA private and public key

Artisan command will generate private and public key inside PUBLIC_CRYPTO_PRIVATE_KEY and PUBLIC_CRYPTO_PUBLIC_KEY environmental variables (defaults to storage_path('crypto_public|private.key'))

$ php artisan crypto:keys

Utilities

Encoding

Base64 Encoding

use BrosSquad\LaravelCrypto\Support\Base64;

$binaryData = random_bytes(32);

// STANDARD VERSION

// Standard encoding
$base64 = Base64::encode($binaryData);
 
// Url encoding
$base64 = Base64::urlEncode($binaryData);

// Standard decoding
$binary = Base64::decode($base64);

// Url decoding
$binary = Base64::urlDecode($base64);


// CONSTANT TIME ENCODING AND DECODING

// Standard encoding
$base64 = Base64::constantEncode($binaryData);

// Url encoding
$base64 = Base64::constantUrlEncode($binaryData);

// Url encoding with no padding (=)
$base64 = Base64::constantUrlEncodeNoPadding($binaryData);

// Standard decoding
$binary = Base64::constantDecode($base64);

// Url decoding
$binary = Base64::constantUrlDecode($base64);

// Url decoding with no padding
$binary = Base64::constantUrlDecodeNoPadding($base64);



// LENGTH CHECKING

// Get maximum length for the byte buffer from base64 encoded string 
$bufferLength = Base64::maxEncodedLengthToBytes($base64Length);

// Get exact length for byte buffer from base64 encoded
$bufferLength = Base64::encodedLengthToBytes($base64String);

// Get base64 string length from byte buffer length
$base64Length = Base64::encodedLength($bufferLength, $hasPadding);

Generating random data

use BrosSquad\LaravelCrypto\Support\Random;

// Generate random string
$randomString = Random::string(60); // Generates random string base64 url encoded with no padding 

// Generate random bytes
$randomBytes = Random::bytes(32); // Generates buffer filled with crypto secure random bytes

// Generate random int
$randomImt = Random::int($min, $max);

General Hashing

Laravel crypto library uses the latest and best hashing algorithms. (Blake2b)

Using facade

namespace App\Services;

use BrosSquad\LaravelCrypto\Facades\Hashing;

class Service 
{
    public function hashing(): void
    {
        $data = 'Hello World';
        $blake2bHash = Hashing::hash($data); // Base64 Encoded string
        $blake2HashBinary = Hashing::hashRaw($data); // Binary Data, outputs 64 bytes of Blake2 hash
        // To check the length of binary strings use mb_strlen($binary, '8bit') function
    }
    
    public function checkingHash(): void
    {
        $hash1 = Hashing::hash('String 1');
        $hash2 = Hashing::hash('String 2');
        // Uses constant time compare to check 
        // if two hashes are equal
        // !! It supports binary data !!
        if(Hashing::equals($hash1, $hash2)) {
            // Hashes are equal
        }
    }

    public function hashVerification(): void {
        $data = 'Hello World';
        $hash = Hashing::hash($data);
        
        // !! Does not support binary hash !!
        // !! For binary data use verifyRaw !!
        if(Hashing::verify($hash,$data)) {
            // When data is hashed, hashes are same
        }
    }
}

Using dependency injection

When you use dependency injection, it will always use best algorithm possible. It removes room for errors;

namespace App\Services;

use \BrosSquad\LaravelCrypto\Contracts\Hashing;

class Service 
{
    protected Hashing $hashing;

    public function __construct(Hashing $hashing) 
    {
        $this->hashing = $hashing;        
    }

    public function hashing(): void
    {
        $data = 'Hello World';
        $blake2bHash = $this->hashing->hash($data); // Base64 Encoded string
        $blake2HashBinary = $this->hashing->hashRaw($data); // Binary Data, outputs 64 bytes of Blake2 hash
        // To check the length of binary strings use mb_strlen($binary, '8bit') function
    }
    
    public function checkingHash(): void
    {
        $hash1 = $this->hashing->hash('String 1');
        $hash2 = $this->hashing->hash('String 2');
        // Uses constant time compare to check 
        // if two hashes are equal
        // !! It supports binary data !!
        if($this->hashing->equals($hash1, $hash2)) {
            // Hashes are equal
        }
    }

    public function hashVerification(): void {
        $data = 'Hello World';
        $hash = $this->hashing->hash($data);
        
        // !! Does not support binary hash !!
        // !! For binary data use verifyRaw !!
        if($this->hashing->verify($hash,$data)) {
            // When data is hashed, hashes are same
        }
    }
}

When ever possible use default hashing algorithm (BLAKE2B). It is the most secure hash now, and it is faster than any other currently is use in industry (Except BLAKE3 which is not implemented in libsodium yet).

Default hashing API is wrapper on libsodium function. It provides nice API to work with in Laravel projects.

These functions should not be used for password hashing. NEVER!! For password hashing use laravel default Hash facade or Hasher interface

Shared Key signatures

Shared key signatures are done using SHA512/256 HMAC. (Sha512/256 -> SHA512 is optimized for X86_64 architecture which most computers and servers run these day, but SHA512 is to long, so it's trimmed to 256bits (64 bytes) hence the name SHA512/256, offers same security as SHA512 but it's shorter)

Using Facade

namespace App\Service;

use BrosSquad\LaravelCrypto\Facades\Hmac;

class Service 
{
    public function createSignature()
    {
        $data = 'Hello World';

        $signature = Hmac::sign($data); // Base64 Encoded encoded signature

        $signature = Hmac::signRaw($data); // Raw bytes for signature
        
        // Rest of the code
    }

    public function verifySigunature(string $signature) 
    {
        $data = 'Hello World';
        
        if(Hmac::verify($data, $signature)) {
            // Signature is valid
        } else {
            // Signature is invalid
        }
    }
}

Using Dependency Injection

namespace App\Service;

use BrosSquad\LaravelCrypto\Contracts\Signing;

class Service 
{
    private Signing $hmac;

    public function __construct(Signing $hmac) 
    {
        $this->hmac = $hmac;
    }

    public function createSignature()
    {
        $data = 'Hello World';

        $signature = $this->hmac->sign($data); // Base64 Encoded encoded signature

        $signature = $this->hmac->signRaw($data); // Raw bytes for signature
        
        // Rest of the code
    }

    public function verifySigunature(string $signature) 
    {
        $data = 'Hello World';
        
        if($this->hmac->verify($data, $signature)) {
            // Signature is valid
        } else {
            // Signature is invalid
        }
    }
}

Public Key signatures

Public key signing uses state of the art in public key cryptography -> EdDSA or Ed25519 Algorithms developed by famous crytographer Daniel Bernstein. It is based on Edwards Curve, and it is much faster then RSA (many even more serure). Public and privete keys are short, this allows the algorithm to be much faster. When ever you can use EdDSA algorithm for public key signatures

Before you start using EdDSA, generate private and public keys with artisan console command $ php artisan crypto:keys

Using Facade

namespace App\Service;

use BrosSquad\LaravelCrypto\Facades\EdDSA;

class Service 
{
    public function createSignature()
    {
        $data = 'Hello World';

        $signature = EdDSA::sign($data); // Base64 Encoded encoded signature

        $signature = EdDSA::signRaw($data); // Raw bytes for signature
        
        // Rest of the code
    }

    public function verifySigunature(string $signature) 
    {
        $data = 'Hello World';
        
        if(EdDSA::verify($data, $signature)) {
            // Signature is valid
        } else {
            // Signature is invalid
        }
    }
}

Using Dependency Injection

namespace App\Service;

use BrosSquad\LaravelCrypto\Contracts\PublicKeySigning;

class Service 
{
    private PublicKeySigning $signing;

    public function __construct(PublicKeySigning $signing) 
    {
        $this->signing = $signing;
    }

    public function createSignature()
    {
        $data = 'Hello World';

        $signature = $this->signing->sign($data); // Base64 Encoded encoded signature

        $signature = $this->hmac->signRaw($data); // Raw bytes for signature
        
        // Rest of the code
    }

    public function verifySigunature(string $signature) 
    {
        $data = 'Hello World';
        
        if($this->hmac->verify($data, $signature)) {
            // Signature is valid
        } else {
            // Signature is invalid
        }
    }
}

Advanced

Encryption

LaravelCrypto library provides 2 additional encryption algorithms. It uses default laravel Encrypter interface and key so it does not require any code change, exept in config file

Use this only in new applications.

Use in older applications

If you have application which uses laravel default encryption and you have stored encrypted data in database, you will need to reencrypt the data with new algorithm!

// app.cofig
return [
    // ...
    
    // XChaCha20Poly1305 Algorithm
    'cipher' => 'XChaCha20Poly1305',
    
    // AES 256 GCM
    //!! Make sure you have hardware acceleration for
    //  AES-256-GCM, it wont work if your sever does not support it !!
    'cipher' => 'AES-256-GCM',

    // .. 
]

Benchmakrs

Encryption

Subject	Description	Revs	Iterations	Memory Peak	Best Time	Average Time	Worst Time
benchLaravelEncryption	Default Laravel Encrypter (AES-256-CBC)	100	10	2,259,976b	952.012μs	957.365μs	974.771μs
benchXChaCha20Poly1305	XChaCha20Poly1305 Encryption	100	10	2,458,008b	265.780μs	267.313μs	270.197μs
benchAes256gcm	AES 256 GCM Encryption	100	10	2,457,984b	252.650μs	254.105μs	256.572μs

Decryption

Subject	Description	Revs	Iterations	Memory Peak	Best Time	Average Time	Worst Time
benchLaravelDecryption	Default Laravel Decrypter (AES-256-CBC)	100	10	2,508,208b	1,661.467μs	1,666.177μs	1,677.097μs
benchXChaCha20Poly1305Decryption	XChaCha20Poly1305 Decryption	100	10	2,529,600b	455.560μs	458.140μs	465.492μs
benchAes256gcmDecryption	AES 256 GCM Decryption	100	10	2,529,576b	447.280μs	449.552μs	453.438μs

Name		Name	Last commit message	Last commit date
Latest commit History 30 Commits
benchmarks		benchmarks
config		config
src		src
tests		tests
.gitignore		.gitignore
LICENCE		LICENCE
README.md		README.md
azure-pipelines.yml		azure-pipelines.yml
composer.json		composer.json
composer.lock		composer.lock
exec		exec
phpbench.json		phpbench.json
phpunit.xml		phpunit.xml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Laravel General Hashing

Introduction

Getting started

Installing

Publishing config file

Generating EdDSA private and public key

Utilities

Encoding

Base64 Encoding

Generating random data

General Hashing

Using facade

Using dependency injection

Shared Key signatures

Using Facade

Using Dependency Injection

Public Key signatures

Using Facade

Using Dependency Injection

Advanced

Encryption

Benchmakrs

Encryption

Decryption

SHA256

Using Hashing Facade

Using Dependency Injection

SHA512

Using Hashing Facade

Using Dependency Injection

About

Releases

Packages

Languages

License

BrosSquad/laravel-crypto

Folders and files

Latest commit

History

Repository files navigation

Laravel General Hashing

Introduction

Getting started

Installing

Publishing config file

Generating EdDSA private and public key

Utilities

Encoding

Base64 Encoding

Generating random data

General Hashing

Using facade

Using dependency injection

Shared Key signatures

Using Facade

Using Dependency Injection

Public Key signatures

Using Facade

Using Dependency Injection

Advanced

Encryption

Benchmakrs

Encryption

Decryption

SHA256

Using Hashing Facade

Using Dependency Injection

SHA512

Using Hashing Facade

Using Dependency Injection

About

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages