# License management library

Create, encrypt, decrypt and transfer license code.


## Overview 

This library handles **generating** and **loading** an array of information which represents a *License*

 
## What is a License
 
 A `License` is an object that holds an array of data. How you use this data in your code is up to you.
 
 This library will help you to generate a license, to encrypt it and to transfer it safely over insecure network to target application
 
## Terminology
 
 - **Encrypting** is encrypting using symmetric `AES-256-CTR` algorithm.
 - **Sealing** is a method of encrypting the symmetric cipher with **private** key, this is used to transfer the license code securely to the app that has to decrypt it.
 - **Unsealing** is a method that decrypts symmetric cipher information using **public** key
 - **Decrypting** is performed once `License` has been unsealed

## Requirements 

- `openssl` extension
- 2048-bit `private` key.
 
Generate a keypair using:
 
```
openssl genrsa -des3 -out private.pem 2048
```

## Generating a new License

Generating a new license means that its symmetric cipher key will be created along with the rest of the data.


```php

use Buckhill\License\LicenseManager;

$license_data = [
    'license' => [
        'id' => '6E6F5965A10A11E6A1670800274509D8',
        'startsAt' => 1481730870,
        'endsAt' => 1513266900,
        'gracePeriod' => '+7 days',
        'allowedNumberOfUsers' => 10,
        'numberOfProcessingServers' => 2
    ],

    /**
     * List of domains where license will function. If license is used at the domain that's not in this list,
     * the middleware checking the license will return an error, thus disabling the software
     */
    'domain' => ['localhost', '127.0.0.1'],


    /**
     * Information about two factor authentication (MFAStack functionality)
     */
    'twoFactor' => [
        'enabled' => false,
        'numberOfKeys' => [
            'global' => 0,
            'perPerson' => 0
        ]
    ],

    /**
     * Information about product that's being licensed
     */
    'product' => [
        'id' => 1,
        'title' => 'AuthStack IAM',
        'url' => 'https://www.buckhill.co.uk/products/authstack'
    ],

    /**
     * Information about contact person
     */
    'contact' => [
        'person' => 'Nikola B.',
        'email' => 'nikola@buckhill.co.uk'
    ],

    /**
     * Information about notification E-mail
     */
    'notificationEmail' => 'nikola@buckhill.co.uk',
];

$license = $manager->generate($license_data, 'AES-256-CTR');

$license = License::generate($license_data, 'AES-256-CTR');


```
 
## Loading an existing License

Loading a license means that you have its metadata stored somewhere (a `JSON` column in MySQL for example) which **includes** symmetric cipher.

```php
<?php

use Buckhill\License\LicenseManager;

$license_data = [];

$manager = new LicenseManager();

$license = $license->load($license_data);

```
 
## Sealing the License for transfer

Sealing the `License` means that metadata about symmetric cipher gets encrypted using **private key**. 
 
Flow:
    - Load or generate the license 
    - Encrypt the license model (array of data)
    - Extract symmetric algorithm, key and IV and encrypt them using **private key**
    - Generate a digital signature using **public key**
    - `base64_encode` the given information, separate it with `.` character. It's now safe to be sent over the network / HTTP

```php
<?php

use Buckhill\License\LicenseManager;
use Buckhill\License\Model\Seal;

$license_data = [];

$manager = new LicenseManager();

$license = $license->load($license_data);

/**
 * @var $seal Seal
 */
$seal = $manager->seal($license);

$sealString = $seal->toString(); // Returns a string safe to send over the network / HTTP

```

 
## Unsealing the License

Unsealing the license means verifying the digital signature, decrypting symmetric cipher info and decrypting the license.

Flow:
    - Obtain the sealed license string
    - Run it through `new(LicenseManager())->unseal()`
    - On error an exception is thrown
    - On success instance of `License` is returned
    

```php
<?php

use Buckhill\License\LicenseManager;

$sealString = '0ljmNUvWAoNB2ANKl7OYSIXi1I07BwxzvLTyRcrc8vTEZCrjVyT9KzVxzuQaBWdYPMGnA7LyHWbz4+YSFiMp4DpbOQLxYmgUxqk/fPzOn9cDQCCF5JkOUNw5kMIy/Pm8lZjcO4nYpa0twYEFZR83PofD/OOAH9+gU4evAfbbRo4LNkpemIV3BTXu0KWniVliPre6DGBVK6u2yXmx56+CrBPDC8R1FNNBxh189eLZZRgJzqW3rDIg712xWh31AEaQy9hE4mRGHb05A8uc7eWweSp0x2zRC+q40ytcEtn9DnTgtXteMnavisV5WC7FuBYE/mfI2BZBmC1pLG6Ulenb6Q==. .iMtT2W62Btfa04dXcENwsZSlmmOoHRVE0xOkVAewggA'; 

$manager = new LicenseManager();

$license = $manager->unseal($sealString);
   
```   

## Running unit tests

Clone the project, in `ssh terminal` type `make test`

```
$ git clone git@git.buckhill.com.hr:buckhill/license.git
$ cd license
$ make test
```