PHP Classes

Certainty: Manage SSL certificate authority file used by PHP

Recommend this page to a friend!
  Info   Documentation   View files Files   Install with Composer Install with Composer   Download Download   Reputation   Support forum   Blog    
Ratings Unique User Downloads Download Rankings
Not enough user ratingsTotal: 118 This week: 1All time: 9,530 This week: 41Up
Version License PHP version Categories
certainty 1.0.0Custom (specified...5HTTP, PHP 5, Files and Folders, Crypt..., V..., S..., C...
Description 

Author

This package can manage SSL certificate authority file used by PHP.

It can manage the cacert.pem file that is used by PHP to perform secure network data access with remote machines like for instance retrieving data via HTTP using TLS.

The package can retrieve and update the cacert.pem file, so the remote machine certificates can be verified to assure that they are valid and the connection can be fully secure.

Innovation Award
PHP Programming Innovation award nominee
January 2018
Number 8
This package can manage SSL certificate authority file used by PHP.

It can manage the cacert.pem file that is used by PHP to perform secure network data access with remote machines like for instance retrieving data via HTTP using TLS.

The package can retrieve and update the cacert.pem file, so the remote machine certificates can be verified to assure that they are valid and the connection can be fully secure.

Manuel Lemos
Picture of Scott Arciszewski
  Performance   Level  
Name: Scott Arciszewski <contact>
Classes: 37 packages by
Country: United States United States
Age: ???
All time rank: 1173170 in United States United States
Week rank: 21 Up2 in United States United States Up
Innovation award
Innovation award
Nominee: 28x

Winner: 1x

Documentation

Certainty Documentation

Before you begin, which problem are you trying to solve?

Troubleshooting

I'm Getting a File Permission Error When Trying to Use Certainty

Make sure the vendor/paragonie/certainty/data directory is writable. For example:

chown -R webuser:webuser vendor/paragonie/certainty/data
chmod 0775 vendor/paragonie/certainty/data
chmod 0664 vendor/paragonie/certainty/data/* 

Details

Certainty - CA-Cert Automation for PHP Projects

Build Status Latest Stable Version Latest Unstable Version License Downloads

Automate your PHP projects' cacert.pem management. Read the blog post introducing Certainty.

Requires PHP 5.6 or newer.

Who is Certainty meant for?

  • Open source developers with no control over where their code is deployed (e.g. Magento module developers).
  • People whose code might be deployed in weird environments with CACert bundles that are outdated or in unpredictable locations.
  • People who are generally forced between: 1. Disabling certificate validation entirely, or 2. Increasing their support burden to deal with corner-cases where suddenly HTTP requests are failing on weird systems

Certainty allows your software to "just work" (which is usually the motivation for disabling certificate validation) without being vulnerable to man-in-the-middle attacks.

Motivation

Many HTTP libraries require you to specify a file path to a cacert.pem file in order to use TLS correctly. Omitting this file means either disabling certificate validation entirely (which enables trivial man-in-the-middle exploits), connection failures, or hoping that your library falls back safely to the operating system's bundle.

In short, the possible outcomes (from best to worst) are as follows:

  1. Specify a cacert file, and you get to enjoy TLS as it was intended. (Secure.)
  2. Omit a cacert file, and the OS maybe bails you out. (Uncertain.)
  3. Omit a cacert file, and it fails closed. (Connection failed. Angry customers.)
  4. Omit a cacert file, and it fails open. (Data compromised. Hurt customers. Expensive legal proceedings.)

Obviously, the first outcome is optimal. So we built Certainty to make it easier to ensure open source projects do this.

Installing Certainty

From Composer:

composer require paragonie/certainty:^1

Certainty will keep certificates up to date via RemoteFetch, so you don't need to update Certainty library just to get fresh CA-Cert bundless. Update only for bugfixes (especially security fixes) and new features.

Non-Supported Use Case:

If you are not using RemoteFetch (which is strongly recommended that you do, and we only provide support for systems that do use RemoteFetch), then you want to use dev-master rather than a version constraint, due to the nature of CA Certificates.

If a major CA gets compromised and their certificates are revoked, you don't want to continue trusting these certificates.

Furthermore, in the event of avoiding RemoteFetch, you should be running composer update at least once per week to prevent stale CA-Cert files from causing issues.

Using Certainty

See the documentation.

What Certainty Does

Certainty maintains a repository of all the cacert.pem files since 2017, along with a sha256sum and Ed25519 signature of each file. When you request the latest bundle, Certainty will check both these values (the latter can only be signed by a key held by Paragon Initiative Enterprises, LLC) for each entry in the JSON value, and return the latest bundle that passes validation.

The cacert.pem files contained within are reproducible from Mozilla's bundle.

How is Certainty different from composer/ca-bundle?

The key differences are:

  • Certainty will keep the CA-Cert bundles on your system up-to-date even if you do not run `composer update`.
  • We sign our CA-Cert bundles using Ed25519, and check every update into the PHP community Chronicle.

  Files folder image Files (41)  
File Role Description
Files folder imagebin (1 file)
Files folder imagedata (5 files)
Files folder imagedocs (1 file, 1 directory)
Files folder imagelocal (3 files)
Files folder imagesrc (6 files, 1 directory)
Files folder imagetest (6 files, 1 directory)
Accessible without login Plain text file .travis.yml Data Auxiliary data
Accessible without login Plain text file composer.json Data Auxiliary data
Accessible without login Plain text file LICENSE Lic. License text
Accessible without login Plain text file phpunit.xml.dist Data Auxiliary data
Accessible without login Plain text file psalm.xml Data Auxiliary data
Accessible without login Plain text file README.md Doc. Documentation

  Files folder image Files (41)  /  bin  
File Role Description
  Accessible without login Plain text file certainty-cert-symlink Example Example script

  Files folder image Files (41)  /  data  
File Role Description
  Accessible without login Plain text file ca-certs.json Data Auxiliary data
  Accessible without login Plain text file cacert-2016-11-02.pem Data Auxiliary data
  Accessible without login Plain text file cacert-2017-01-18.pem Data Auxiliary data
  Accessible without login Plain text file cacert-2017-06-07.pem Data Auxiliary data
  Accessible without login Plain text file cacert-2017-09-20.pem Data Auxiliary data

  Files folder image Files (41)  /  docs  
File Role Description
Files folder imagefeatures (2 files)
  Accessible without login Plain text file README.md Doc. Documentation

  Files folder image Files (41)  /  docs  /  features  
File Role Description
  Accessible without login Plain text file LocalCACertBuilder.md Class Class source
  Accessible without login Plain text file RemoteFetch.md Example Example script

  Files folder image Files (41)  /  local  
File Role Description
  Accessible without login Plain text file keygen.php Aux. Auxiliary script
  Accessible without login Plain text file README.md Doc. Documentation
  Accessible without login Plain text file signer.php Aux. Auxiliary script

  Files folder image Files (41)  /  src  
File Role Description
Files folder imageException (7 files)
  Accessible without login Plain text file Bundle.php Class Class source
  Accessible without login Plain text file Certainty.php Class Class source
  Accessible without login Plain text file Fetch.php Class Class source
  Accessible without login Plain text file LocalCACertBuilder.php Class Class source
  Accessible without login Plain text file RemoteFetch.php Class Class source
  Accessible without login Plain text file Validator.php Class Class source

  Files folder image Files (41)  /  src  /  Exception  
File Role Description
  Accessible without login Plain text file BundleException.php Class Class source
  Accessible without login Plain text file CryptoException.php Class Class source
  Accessible without login Plain text file EncodingException.php Class Class source
  Accessible without login Plain text file FilesystemException.php Class Class source
  Accessible without login Plain text file InvalidResponseException.php Class Class source
  Accessible without login Plain text file NetworkException.php Class Class source
  Accessible without login Plain text file RemoteException.php Class Class source

  Files folder image Files (41)  /  test  
File Role Description
Files folder imagestatic (1 file, 2 directories)
  Accessible without login Plain text file BundleTest.php Class Class source
  Accessible without login Plain text file CustomCASupportTest.php Class Class source
  Accessible without login Plain text file CustomValidator.php Class Class source
  Accessible without login Plain text file FetchTest.php Class Class source
  Accessible without login Plain text file RemoteFetchTest.php Class Class source
  Accessible without login Plain text file ValidatorTest.php Class Class source

  Files folder image Files (41)  /  test  /  static  
File Role Description
Files folder imagedata-empty (1 file)
Files folder imagedata-invalid (2 files)
  Accessible without login Plain text file repeat-globalsign.pem Data Auxiliary data

  Files folder image Files (41)  /  test  /  static  /  data-empty  
File Role Description
  Accessible without login Plain text file ca-certs.json Data Auxiliary data

  Files folder image Files (41)  /  test  /  static  /  data-invalid  
File Role Description
  Accessible without login Plain text file ca-certs.json Data Auxiliary data
  Accessible without login Plain text file cacert-2017-09-20.pem Data Auxiliary data

The PHP Classes site has supported package installation using the Composer tool since 2013, as you may verify by reading this instructions page.
Install with Composer Install with Composer
 Version Control Unique User Downloads Download Rankings  
 100%
Total:118
This week:1
All time:9,530
This week:41Up