RemoteFetch.md

RemoteFetch

This downloads the latest CA certificates from our Github repository and caches them locally.

Basic Usage

Using the RemoteFetch class is rather straightforward.

Basic Usage with cURL

<?php
use ParagonIE\Certainty\RemoteFetch;

$fetcher = new RemoteFetch('/path/to/certainty/data');
$latestCACertBundle = $fetcher->getLatestBundle();

$ch = curl_init();
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 2);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
curl_setopt($ch, CURLOPT_CAINFO, $latestCACertBundle->getFilePath());

Basic Usage with Guzzle

<?php
use ParagonIE\Certainty\RemoteFetch;
use GuzzleHttp\Client;

$fetcher = new RemoteFetch('/path/to/certainty/data');
$latestCACertBundle = $fetcher->getLatestBundle();
$client = new Client();

$response = $client->request('POST', '/url', [
    'verify' => $latestCACertBundle->getFilePath() 
]);

Basic Usage with Streams

<?php
use ParagonIE\Certainty\RemoteFetch;

$fetcher = new RemoteFetch('/path/to/certainty/data');
$latestCACertBundle = $fetcher->getLatestBundle();

$context = stream_context_create([
    'ssl' => [
        'crypto_method' => STREAM_CRYPTO_METHOD_TLSv1_2_CLIENT,
        'verify_peer' => true,
        'cafile' => $latestCACertBundle->getFilePath(),
        'verify_depth' => 5
    ]
]);

$data = file_get_contents(
    'https://php-chronicle.pie-hosted.com/chronicle/lookup/HuICLQCF_DWnQGbosC6fK8PuifQgIrRi2WYshB2erZY=',
    false,
    $context
);

Composer Integration

Since version 2.2.0.

You can have Certainty request an up-to-date bundle at runtime by ensuring you add this entry to your composer.json file:

{
  "scripts": {
    "post-autoload-dump": [
      "ParagonIE\\Certainty\\Composer::postAutoloadDump"
    ]
  }
}

Then, you can simply use the local Fetch class instead of RemoteFetch in your application code. Every time you run composer update, it will fetch the latest bundles from Certainty.

This is a great way to reduce your runtime performance overhead while guaranteeing that you have the latest CACert bundle.

Changing the Path or URL

By default, Certainty's RemoteFetch feature pulls from Github and uses the most recent CA-Cert bundled with the source code to ensure Github is actually Github.

You can change the URL or local save directory either by passing string arguments to the constructor, like so:

<?php
use ParagonIE\Certainty\RemoteFetch;

// Custom local path and remote URL:
$fetcher = new RemoteFetch(
    '/var/www/common/certs',
    'https://raw.githubusercontent.com/your-organization/certainty-fork/master/data/'
);

Changing the Time Between Remote Fetches

By default, RemoteFetch will check for new certificates at most once per day. To change this timeout, you have two options: Pass a DateInterval to the constructor, or change it after the object has been created.

<?php
use ParagonIE\Certainty\RemoteFetch;

// Cleaner.
$fetcher = (new RemoteFetch('/path/to/certainty/data'))
    ->setCacheTimeout(new \DateInterval('PT06H'));

// Alternatively, the constructor approach:
$fetcher = new RemoteFetch(
    '/path/to/certainty/data',
    RemoteFetch::DEFAULT_URL,
    null, // automatically selects/configures Guzzle
    new \DateInterval('PT06H') // 6 hours
);

Symlinks

Being able to fetch the most recent CA-Cert bundle's file path at runtime is the preferred usage for Certainty, but some will prefer to create a symlink at a predictable location so they can use that path in their code.

Certainty supports this usage.

<?php
use ParagonIE\Certainty\RemoteFetch;

$latest = (new RemoteFetch('/path/to/certainty/data'))->getLatestBundle();

$latest->createSymlink('/path/to/cacert.pem', true);

The second argument, true, tells Certainty to remove the existing symlink if it already exists.

Using a Different Chronicle

To use a different Chronicle instance (i.e. a replica of the PHP Chronicle instead of the main instance), you can configure your RemoteFetch object by calling the setChronicle() method with a URL and a public key.

<?php
use ParagonIE\Certainty\RemoteFetch;
$remoteFetch = new RemoteFetch('/var/www/my-project/data/certs');
$remoteFetch->setChronicle(
    'https://php-chronicle-replica.pie-hosted.com/chronicle/replica/_vi6Mgw6KXBSuOFUwYA2H2GEPLawUmjqFJbCCuqtHzGZ',
    'MoavD16iqe9-QVhIy-ewD4DMp0QRH-drKfwhfeDAUG0='
);