bytesfield/key-manager

Api Key Management for generating public and private key pairs storing and retrieving the master encryption key.

v1.0.2 2021-05-24 22:05 UTC

Requires

• php: >=7.4
• paragonie/ciphersweet: ^2

Requires (Dev)

• nunomaduro/collision: 9999999-dev
• orchestra/testbench: ^6.x-dev
• phpunit/phpunit: 9.5.x-dev

MIT

• Abraham Udele

• manager
• encryption
• private
• public
• key

README

Key Manager

Key Manager is a Laravel Package for generating public and private key pairs storing, retrieving and authenticating requests using the private key value.

Installation

PHP 7.4+ and Composer are required.

To get the latest version of Key Manager, simply require it

composer require bytesfield/key-manager

Or add the following line to the require block of your composer.json file.

"bytesfield/key-manager": "1.0.*"

You'll then need to run composer install or composer update to download it and have the autoloader updated.

Once KeyManager is installed, you need to register the service provider. Open up config/app.php and add the following to the providers key.

'providers' => [
    ...
    Bytesfield\KeyManager\KeyManagerServiceProvider::class,
    ...
]

If you use Laravel >= 5.5 you can skip this step and go to configuration

• Bytesfield\KeyManager\KeyManagerServiceProvider::class,

Also, register the Facade like so:

'aliases' => [
    ...
    'KeyManager' => Bytesfield\KeyManager\Facades\KeyManager::class,
    ...
]

Configuration

You can publish the configuration file using this command:

php artisan key-manager:install

This publishes a configuration-file named keymanager.php with some sensible defaults will be placed in your config directory and two migration files create_key_clients_table and create_key_api_credentials_table placed in your database\migrations directory:

<?php

return [

    /**
     * Generated API Encryption Key
     *
     */
    'api_encryption_key' => env('API_ENCRYPTION_KEY'),

];

Then run this command to migrate your database

php artisan migrate

Usage

Generate API Encryption Key by running this command on your terminal

php artisan encryption:generate

This will generate an encryption key in your .env:

API_ENCRYPTION_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

If you are using a hosting service like heroku, ensure to add the above details to your configuration variables.

Using KeyManager Facade

Import the KeyManager Facade

use Bytesfield\KeyManager\Facades\KeyManager;

Create a Key Client

KeyManager::createClient(string $name, string $type);
// Optional
KeyManager::createClient(string $name, string $type, string $status);

This creates a client with public and private keys pairs

Note : $status param can either be active or suspended while $type is dependent on what you want e.g user or admin.

Get Private Key

KeyManager::getPrivateKey(int $clientId);

Change Key Pairs

KeyManager::changeKeys(int $clientId);

Suspend a client

KeyManager::suspendClient(int $clientId);

Activate a Client

KeyManager::activateClient(int $clientId);

Suspend an API Credential

KeyManager::suspendApiCredential(int $clientId);

Activate an API Credential

KeyManager::activateApiCredential(int $clientId);

Injecting KeyManager or KeyManagerInterface in a constructor

Import the KeyManager or KeyManagerInterface

use Bytesfield\KeyManager\KeyManager;

public function __construct(KeyManager $keyManager)
{
    $this->keyManager = $keyManager;
}

Or

use Bytesfield\KeyManager\KeyManagerInterface;

public function __construct(KeyManagerInterface $keyManager)
{
    $this->keyManager = $keyManager;
}

Create a Key Client

$this->keyManager->createClient(string $name, string $type);
// Optional
$this->keyManager->createClient(string $name, string $type, string $status);

This creates a client with public and private keys pairs

Note : $status param can either be active or suspended while $type is dependent on what you want e.g user or admin.

Get Private Key

$this->keyManager->getPrivateKey(int $clientId);

Change Key Pairs

$this->keyManager->changeKeys(int $clientId);

Suspend a Client

$this->keyManager->suspendClient(int $clientId);

Activate a Client

$this->keyManager->activateClient(int $clientId);

Suspend an API Credential

$this->keyManager->suspendApiCredential(int $clientId);

Activate an API Credential

$this->keyManager->activateApiCredential(int $clientId);

Using Commands

You can use commands to perform these actions too.

Create a Key Client

client:create {name} {type}

Or

client:create {name} {type} {status=active}

This creates a client with public and private keys pairs

Note : $status param can either be active or suspended while $type is dependent on what you want e.g user or admin.

Get Private Key

client:getkey {clientId}

Change Key Pairs

client:changekey {clientId}

Suspend a client

client:suspend {clientId}

Activate a Client

client:activate {clientId}

Suspend an API Credential

client:suspend-key {clientId}

Activate an API Credential

client:activate-key {clientId}

Using the middleware to protect your routes.

In your route add auth.client middleware

Route::get('test', function(){
    return "Hello world";
})->middleware('auth.client');

Or

In your controller add auth.client

public function __construct(){
    $this->middleware('auth.client');
}

This Middleware Authenticates a client's request with a valid private key value api-auth-key which is to be passed to the request header.

Testing

composer test

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email abrahamudele@gmail instead of using the issue tracker.

Credits

• Abraham Udele
  Find me on Twitter. Linkedin.

License

The MIT License (MIT). Please see License File for more information.