Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Initial commit
  • Loading branch information
paragonie-security committed Oct 22, 2017
0 parents commit 9e5bdf6
Show file tree
Hide file tree
Showing 18 changed files with 16,235 additions and 0 deletions.
3 changes: 3 additions & 0 deletions .gitignore
@@ -0,0 +1,3 @@
/local
/composer.lock
/vendor
18 changes: 18 additions & 0 deletions LICENSE
@@ -0,0 +1,18 @@
/*
* ISC License
*
* Copyright (c) 2017
* Paragon Initiative Enterprises <security at paragonie dot com>
*
* Permission to use, copy, modify, and/or distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/
66 changes: 66 additions & 0 deletions README.md
@@ -0,0 +1,66 @@
# Certainty - CA-Cert Automation for PHP Projects

[![Build Status](https://travis-ci.org/paragonie/certainty.svg?branch=master)](https://travis-ci.org/paragonie/certainty)
[![Latest Stable Version](https://poser.pugx.org/paragonie/certainty/v/stable)](https://packagist.org/packages/paragonie/certainty)
[![Latest Unstable Version](https://poser.pugx.org/paragonie/certainty/v/unstable)](https://packagist.org/packages/paragonie/certainty)
[![License](https://poser.pugx.org/paragonie/certainty/license)](https://packagist.org/packages/paragonie/certainty)
[![Downloads](https://img.shields.io/packagist/dt/paragonie/certainty.svg)](https://packagist.org/packages/paragonie/certainty)

Automate your PHP projects' cacert.pem management.

**Requires PHP 5.6 or newer.**

### 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 are (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:

```bash
composer require paragonie/certainty:dev-master
```

Due to the nature of CA Certificates, you want to use `dev-master`. If a major CA gets compromised and
their certificates are revoked, you don't want to continue trusting these certificates.

## What Certainty Does

Certainty maintains a repository of all the `cacert.pem` files, along with a

## Using Certainty

### Create Symlink to Latest CACert

After running `composer update`, simply run a script that excecutes the following.

```php
<?php
(new \ParagonIE\Certainty\Fetch())
->getLatestBundle()
->createSymlink('/path/to/cacert.pem');
```

Then, make sure your HTTP library is using the cacert path provided. For example, using cURL:

```php
<?php

$ch = curl_init();
// ... snip ...
curl_setopt($ch, CURLOPT_CAINFO, '/path/to/cacert.perm');
```

27 changes: 27 additions & 0 deletions composer.json
@@ -0,0 +1,27 @@
{
"name": "paragonie/certainty",
"description": "Up-to-date, verifiable repository for Certificate Authorities",
"keywords": ["CA", "Certificate Authority", "CA-Cert", "CACert", "cacert.pem", "ca-cert.pem", "PKI", "TLS", "SSL", "Public-Key Infractructure", "Ed25519"],
"license": "ISC",
"authors": [
{
"name": "Paragon Initiative Enterprises",
"email": "security@paragonie.com",
"homepage": "https://paragonie.com"
}
],
"autoload": {
"psr-4": {
"ParagonIE\\Certainty\\": "src/"
}
},
"require": {
"php": "^5.6|^7",
"paragonie/constant_time_encoding": "^1|^2",
"paragonie/sodium_compat": "^1.3"
},
"require-dev": {
"phpunit/phpunit": "^6",
"vimeo/psalm": "^0|^1"
}
}
26 changes: 26 additions & 0 deletions data/ca-certs.json
@@ -0,0 +1,26 @@
[
{
"date": "2017-09-20",
"file": "cacert-2017-09-20.pem",
"sha256": "435ac8e816f5c10eaaf228d618445811c16a5e842e461cb087642b6265a36856",
"signature": "9007f7f0411d6d1f1f5136b247375e614a24216e4fc6c9d6d12642f986f3d45cea3daa2a19705579845a37488ce679f78a1b890d24da6157a2e9894d351fa70a"
},
{
"date": "2017-06-07",
"file": "cacert-2017-06-07.pem",
"sha256": "e78c8ab7b4432bd466e64bb942d988f6c0ac91cd785017e465bdc96d42fe9dd0",
"signature": "ed1fc6af6827cac04da6caf40deffeadc2a19feba5281d7cf92d1563ad9af49b8d25bf459e5d5acec0fe723394f88f240d4b716e52f3835f9ab3caa3cc85380e"
},
{
"date": "2017-01-18",
"file": "cacert-2017-01-18.pem",
"sha256": "e62a07e61e5870effa81b430e1900778943c228bd7da1259dd6a955ee2262b47",
"signature": "0f217f29c9711cd74ed60f0f6da886c166969945546a6e75e6fa8cf5ea87387f5fce1e1ced71af46095d2dd411a3676ec1aa40927cc0d47a91adaeef965b240b"
},
{
"date": "2016-11-02",
"file": "cacert-2016-11-02.pem",
"sha256": "cc7c9e2d259e20b72634371b146faec98df150d18dd9da9ad6ef0b2deac2a9d3",
"signature": "59687e4a471591fd09f2e9d84a595fd37618eadf0c4a3eef56feaca10100a175da520dbd068473189af3775ca91e1f48eb55155accb9d5c6137d25b6a9e93103"
}
]

0 comments on commit 9e5bdf6

Please sign in to comment.