vdhicts/laravel-csr-generator

PHP offers several methods to help generate a CSR and private key. Unfortunately, some CSR parts (i.e. subject alternative names) are not easily usable. This Laravel package aims to make the procedure easier within your Laravel application.

Requirements#

This Laravel package requires PHP 8.1 or higher, Laravel 9+ and you will need the openssl extension as that's required for the openssl_* php functions used by this package.

Installation#

This package can be used in any Laravel project.

You can install the package via composer:

composer require vdhicts/laravel-csr-generator

Usage#

This package is an easy-to-use wrapper around the PHP functions.

Getting started#

All steps can be performed individually to suit all your needs.

// Generate the private key
$privateKey = (new PrivateKeyGenerator())->generate();

// Collect the subject fields
$subjectFields = new SubjectFields(
    'example.com',
    'security@example.com',
    'NL',
    'Zuid-Holland',
    'Den Haag',
    'Example',
    'DevOps',
    ['www.example.com']
);

// Generate the csr
$csr = (new CsrGenerator($subjectFields, $privateKey))->generate();
$csrContent = $csr->export();

Generate private key#

The private key can be generated with the PrivateKeyGenerator. It's possible to manually determine the key bits and type. Additional options can be provided too. The generator will return null when failed or an instance of PrivateKey.

$privateKey = (new PrivateKeyGenerator())
    ->setPrivateKeyBits(8196)
    ->setPrivateKeyType(OPENSSL_KEYTYPE_RSA)
    ->setAdditionalOptions(['config' => 'your-config-file'])
    ->generate();

You can access the OpenSSLAsymmetricKey as a property.

Export private key as string#

To convert the private key to a string, use the export method on the PrivateKey object or cast the object to a string:

Encrypted key#

$privateKeyContent = $privateKey
    ->setPassPhrase('test-1234!')
    //->setAdditionalOptions(['config' => 'path-to-your-config-file'])
    ->export();

Unencrypted key#

$privateKeyContent = $privateKey
    ->setPassPhrase(null)
    //->setAdditionalOptions(['config' => 'path-to-your-config-file'])
    ->export();

When you don't set the passphrase or set it to null, the key won't be encrypted.

Generate CSR#

To generate the CSR, generate the private key and create the subject fields first. The generator will return null when failed or an instance of Csr.

$subjectFields = new SubjectFields(
    'example.com',
    'security@example.com',
    'NL',
    'Zuid-Holland',
    'Den Haag',
    'Example',
    'DevOps',
    ['www.example.com']
);
$csr = (new CsrGenerator($subjectFields, $privateKey))
    ->setAdditionalOptions(['config' => 'path-to-your-config-file'])
    ->generate();

You can access the OpenSSLCertificateSigningRequest as a property.

Subject alternative names & your own config#

When providing subject alternative names, the config file from the additional options will be overwritten. This is required to provide the subject alternative names as those can't be provided directly to the openssl_ functions built in PHP. If you need to provide subject alternative names and a custom config, leave the subject alternative names in the SubjectFields empty and provide your config with the SAN section:

$subjectFields = new SubjectFields(
    'example.com',
    'security@example.com',
    'NL',
    'Zuid-Holland',
    'Den Haag',
    'Example',
    'DevOps' // so not providing the subject alternative names here
);

// Create your config file with the subject alternative names
..

// Provide your config file to the generator
$csr = (new CsrGenerator($subjectFields, $privateKey))
    ->setAdditionalOptions(['config' => 'path-to-your-config-file'])
    ->generate();

To help you create the config file, it's possible to publish the view for the config file. This view is used by default for generating the config with the subject alternative names.

php artisan vendor:publish --provider="Vdhicts\CsrGenerator\CsrGeneratorServiceProvider" --tag=csr-generator-views

Export CSR as string#

To convert the CSR to a string, use the export method on the Csr object or cast the object to a string:

$csrContent = $csr->export();

Custom configuration#

Some defaults are set which are used by the generators. To change those defaults, publish the configuration file with:

php artisan vendor:publish --provider="Vdhicts\CsrGenerator\CsrGeneratorServiceProvider" --tag=csr-generator-config

Tests#

Unit tests are available in the tests folder. Run with:

composer test

When you want a code coverage report which will be generated in the build/report folder. Run with:

composer test-coverage

Contribution#

Any contribution is welcome, see the Contributing guidelines.

Security#

If you discover any security-related issues in this or other packages of Vdhicts, please email security@vdhicts.nl instead of using the issue tracker.

License#

This package is open-sourced software licensed under the MIT license.