README

An SSL/TLS service and facade for Laravel. Capture peer certificates using 'openssl' or 'stream' drivers, or create your own driver.

Driver	Description
openssl	Executes the openssl command
stream	PHP's `stream_*()` functions
file	Parses local certificate files

Installation

Install the package via composer:

composer require jinomial/laravel-ssl

The default configuration is to use the openssl driver.

'openssl' => [
    'driver' => 'openssl',
],

Publish the config file to change the default driver:

php artisan vendor:publish --provider="Jinomial\LaravelSsl\SslServiceProvider" --tag="laravel-ssl-config"

Usage

Capture the certificate of jinomial.com:443 using the default driver:

use Jinomial\LaravelSsl\Facades\Ssl;

// Returns a CertificateCollection
$certificates = Ssl::show('google.com');

$cert = $certificates->first();

echo $cert->getCommonName(); // "google.com"
echo $cert->isValid() ? 'Valid' : 'Expired/Invalid';
echo $cert->getValidTo()->diffForHumans(); // "in 3 months"

Certificate Helper Methods

The Certificate DTO provides several helpful methods:

Method	Description
`isValid()`	Returns true if the cert is not expired and verification passed
`isExpired()`	Returns true if the current time is past the `validTo` date
`getCommonName()`	Get the Common Name (CN) from the subject
`getIssuerCommonName()`	Get the Common Name (CN) from the issuer
`getValidFrom()`	Returns a `Carbon` instance for the start date
`getValidTo()`	Returns a `Carbon` instance for the expiration date
`getSubjectAlternativeNames()`	Returns an array of SANs
`getHost()` / `getPort()`	The connection details used for this certificate

Advanced Usage

Multiple lookups at once:

$results = Ssl::show([
    ['host' => 'google.com', 'port' => '443'],
    ['host' => 'github.com', 'port' => '443'],
]);

// Find a specific result
$githubCert = $results->where('host', 'github.com')->first();

Use a specific driver:

$response = Ssl::driver('stream')->show('google.com', '443', [
    // Get the certificate only without the CA Chain.
    \Jinomial\LaravelSsl\Drivers\Stream::OPTION_CHAIN => false,
]);

The openssl driver executes the openssl binary (must be in your $PATH) to retrieve the X509 certificate.

Each response is indexed.

certificate is the return value from openssl_x509_parse().

verification contains the verification code and verification message.

Local File Driver

You can also parse local certificate files using the file driver. This is useful for checking certificates stored on disk.

use Jinomial\LaravelSsl\Facades\Ssl;

// Provide a path to a certificate file
$certificates = Ssl::driver('file')->show('/path/to/certificate.crt');

The id-ad-caIssuers property can be followed to get the issuer certificate:

$response = Ssl::show(
    'http://cacerts.digicert.com/CloudflareIncECCCA-3.crt',
    443,
    ['id-ad-caIssuers' => true]
);

stream driver responses

The stream driver uses PHP's stream_* functions and SSL context to capture entire peer certificate chains.

Each response is indexed. The subindex is the chain sequence with 0 being the host, 1 being the issuer (if not self signed), etc. Results are the return value from openssl_x509_parse().

Artisan Commands

Show Certificate

Show details for a specific host:

php artisan ssl:show google.com

Bulk SSL Check

Monitor multiple hosts at once. This command can check hosts provided as arguments or those configured in config/ssl.php.

# Check specific hosts
php artisan ssl:check google.com github.com

# Check all hosts configured in ssl.monitored_hosts
php artisan ssl:check

The command will output a table showing the status, common name, and expiration time for each host.

Custom Drivers

Create a class that extends Jinomial\LaravelSsl\Drivers\Driver.

Implement public function show() according to the Jinomial\LaravelSsl\Contracts\Ssl\Driver contract.

    /**
     * Application service provider bootstrap for package services.
     *
     * \App\Ssl\Drivers\SslCapture is my custom driver class I made.
     * The SslManager needs to know how to construct it.
     */
    public function boot(): void
    {
        $sslLoader = $this->app->get(\Jinomial\LaravelSsl\SslManager::class);
        $driverName = 'my-custom-driver';
        $sslLoader->extend($driverName, function () use ($driverName) {
            return new \App\Ssl\Drivers\SslCapture($driverName);
        });
    }

Testing

Run all tests:

composer test

Test suites are separated into "unit" and "integration". Run each suite:

composer test:unit
composer test:integration

Tests are grouped into the following groups:

network
drivers
openssl
manager
facades
commands

Run tests for groups:

composer test -- --include=manager,facades

Network tests make remote calls that can take time or fail. Exclude them:

composer test:unit -- --exclude=network

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

Jason Schmedes

License

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

jinomial / laravel-ssl

Maintainers

Package info

Statistics

Security