Lockbox

Lockbox is a simple, tiered system for working with cryptographic keys and
encrypted data. It provides a set of easy-to-use interfaces that encourage
a “secure by default” design.

There are three primary concepts to Lockbox: Keys, secrets and vaults.
Keys are used for encryption or decryption of data. Secrets are data values
that can be read or written using multiple keys. A vault is one way to store
a collection of secrets, that also comes with some built-in key management
tools.

Interesting fact: The classes here were originally designed to support
responsible handling of authentication tokens for server applications, to
ensure that the various passwords and API keys for production servers weren’t
just dumped in plain text into the file system. This is particularly important
for cloud servers, where access to the disk images is entirely out of the
so-called “site owner’s” control.

Quick-Start

Manual Install

Grab all the files from the src/ directory here and stick them somewhere.
Arrange to autoload them. If you instead want to require() them, this is the
block you’ll need:

require_once "CryptoCore.php";
require_once "CryptoCoreLoader.php";
require_once "CryptoCoreFailed.php";
require_once "CryptoCoreBuiltin.php";
require_once "CryptoCoreOpenssl.php";
require_once "Crypto.php";
require_once "CryptoKey.php";
require_once "Secret.php";
require_once "Vault.php";

Composer Install

See https://packagist.org/packages/starekrow/lockbox. Greetz to @KJLJon.

Using Lockbox

Suck the classes you’ll be using into your namespace (or don’t, but you’ll be
typing “starekrow” a lot).

use starekrow\Lockbox\CryptoKey;
use starekrow\Lockbox\Secret;
use starekrow\Lockbox\Vault;

To encrypt some data:

// CryptoKey defaults to AES-128-CBC encryption with a random key
$key = new CryptoKey();
$message = "You can't see me.";
$ciphertext = $key->Lock( $message );
file_put_contents( "key.txt", $key->Export() );
file_put_contents( "cipher.txt", $ciphertext );

To decrypt some encrypted data:

$key = CryptoKey::Import( file_get_contents( "key.txt" ) );
$ciphertext = file_get_contents( "cipher.txt" );
$message = $key->Unlock( $ciphertext );
echo $message;             // "You can't see me."

To use a specified key and a different cipher:

$key = new CryptoKey( "ILikeCheese", null, "AES-256-ECB" );
$no_see_um = $key->Lock( "This text is safe." );
$see_um = $key->Unlock( $no_see_um );

Note that if your key is not the expected length for the given cipher, PHP’s
openssl extension will apply some default padding or cropping to your key
data. For interoperability with non-PHP crypto systems, be sure to specify the
key at the proper length for your chosen cipher.

To encrypt some data (even structured data) so that it can be decrypted with
more than one key:

$s = new Secret( [ "my stuff" => "Sooper seekrit" ] );
$k = new CryptoKey( "correcthorsebatterystaple" );
$k2 = new CryptoKey( "ILikeCheese" );
$s->AddLockbox( $k );
$s->AddLockbox( $k2 );
file_put_contents( "secret.txt", $s->Export() );
file_put_contents( "key.txt", $k->Export() );
file_put_contents( "key2.txt", $k2->Export() );

To get that data back:

$s = Secret::Import( file_get_contents( "secret.txt" ) );
$k = CryptoKey::Import( file_get_contents( "key.txt" ) );
$s->Unlock( $k );
$val = $s->Read();
echo $val["my stuff"];                 // "Sooper seekrit"

Interestingly, secret.txt contains something like:

{
    "locks": {
    "17e9c178-7a99-47ac-a422-5ec9a9e0a6e8": "2W2ElRE4S7xu93xxcvIF7dubb+46YhgZKDS3Lnztc7YDL+Had4nNIRqZ03jzW8w1IaZtMAudFTQFLejVYMwDeHnpHotBR5UBo0TZq4jgW2hetGbahLOpni3hhwbU9at8By34Dj53UfK84pXyOe2RH90+b/vL9OLAD51hupsbI2TlKPjCsys8V3EhaIz0a57yCKhAyMarZkyklRKvFYvbKw==",
    "0188b485-0937-4695-a0d6-5f968b286fc9": "Ugq4MuwOfvyKlREhVJDFLuRR8U7O6y0e3KYD2Gllk4QC0EaC2MJDtJ9yCkePF49zsukgmjSpHvhAjg1ZN3yWEOR8DE3kDY8rai9RC1LRRC0iK2nTg7DqCsvUV57nY1mG5MVpW8LXAirjRtCasj2yJu1D1JY0U06hXpSDoVzaLSFqPoRoSAI231SwISgnqhLCUEt7L7LGwIt3voMehH6wxg=="
    },
    "data": "+2uEgQ52VGOVvGu41umPhjurmqhoXHMqhbzoFeQuWs63rFQNVW9HK3dlEddEyZfoe+lXT2M5MElUfdXF1vWZ8mLiorVkN8N+Waz6YeyZ3CePpYPNsZT9yMCWAQNwnTjU"
}

And key.txt contains:

k0|17e9c178-7a99-47ac-a422-5ec9a9e0a6e8|QUVTLTEyOC1DQkM=|Y29ycmVjdGhvcnNlYmF0dGVyeXN0YXBsZQ==

Create a vault and put a value into it:

$v = new Vault( "./secrets" );
$v->CreateVault( "CorrectHorseBatteryStaple" );
$v->Put( "test1", "This is a test." );
$v->Close();

Open an existing vault and read a value from it:

$v = new Vault( "./secrets" );
$v->Open( "CorrectHorseBatteryStaple" );
$got = $v->Get( "test1" );
echo $got;                        // prints "This is a test."

How it Works

Each tier of the interface adds capabilities:

• CryptoKey handles basic encryption and decryption, and packages both the
  keys and the ciphertext for output, verification and decryption.
• Secret is a managed, encrypted data value with lockbox-style key
  handling.
• A Vault is file-based storage for secrets, with a master key and some
  additional key management tools.
• Crypto is a low-level interface that provides hashing and encryption of
  raw data.

CryptoKey

All of the actual encryption and decryption is done with CryptoKey instances.
These bundle together the pieces - cipher type and key data, along with a
unique key identifier to help with higher-level management - needed to
successfully decrypt a previously encrypted message. They also produce
representations of themselves and of the encrypted messages in tidy,
ASCII-safe strings.

Think of a key as a complete encryption package: You use the key to lock
plaintext (producing ciphertext) and to unlock ciphertext (producing plaintext).

A CryptoKey can be built with an (optional) passphrase, an (optional) id
string and an (optional) cipher specifier. Any parameter that isn’t
specified is filled with a reasonable default: A 256-bit random key, a 128-bit
(well, 123-bit) random ID formatted as a GUID, and an AES-128-CBC cipher.

The output of a Lock() operation includes the IV used and an HMAC of the
ciphertext, as well as the ciphertext itself. Those are then concatenated and
base-64 encoded. The result can be easily verified and decrypted with
Unlock().

The keys themselves, along with the exact cipher used and the key identifier,
can be converted to a simple printable string representation with Export()
and read back in with Import().

Secret

The Secret class provides a more extensive interface to handling a value that
needs to be protected. Each secret consists of three parts:

• The value itself is a binary string. Serialization from and to other data
  types is automatic.
• A random 256-bit internal key is used to encrypt the value.
• One or more lockboxes is attached.

The secret is created with any value, and can be locked (or unlocked) with one
or more different keys, using a virtual lockbox model. In this model, the
secret’s value is encrypted with the internal key. However, the
internal key is never saved directly, but is itself encrypted by the various
lockbox keys you supply. This arrangement has the following interesting
properties:

• The value can be decrypted with multiple, independent passphrases.
• The value can be updated by anyone with a valid lockbox key. Other
  key-holders will then see the updated value.
• A lockbox can be removed without decrypting the value.
• A lockbox can only be added by a valid key-holder.
• A lockbox key cannot be used to learn anything about the other lockbox keys
  (except their public ID, which is in the clear anyway).

Like keys, secrets are rendered in an ASCII-safe printable package (in this
case, a JSON wrapper around some base-64 strings) with Export() and can be
reconstituted with Import(). AddLockbox() takes a key you supply and
encrypts the internal key with it, adding the resulting virtual lockbox to the
secret. Additional management can be done with RemoveLockbox(),
HasLockbox() and ListLockboxes().

Unlock() takes a key matching any lockbox and decrypts the internal key from
the lockbox. Lock() just discards any saved copies of the internal key and
decrypted value.

If the secret has been unlocked, you can use Read() to get the value out of
it, and Update() to change it.

Vault

A Vault uses the properties of the Secret class to provide an encrypted
key-value store on disk that is as robust to interruption as the underlying
file system.

You supply the name of a directory for the vault, and the secrets are stored in
individual files in that directory. A random
master key is generated and used to encrypt each one. That
master key is itself encrypted with a passphrase, an arrangement that allows the
passphrase to be changed without changing the master key, and allows the master
key itself to be rotated in stages, no matter the size of the vault.

When using a vault, all the key and secret management is handled for you. Use
CreateVault() to set up a new vault (this will fail if a vault already
exists in the chosen directory) or Open() to open an existing one.
VaultExists() and DestroyVault() round out the vault management suite.
Close() forgets all keys and cached secrets without affecting the vault
on disk.

Manage values within the vault with Put(), Get(), Has(), Remove() and
PerSecret().

You can change the passphrase used to encrypt the master key with
ChangePassphrase(). This is a comparatively fast and safe operation, affecting
only one file. Rotate the master key itself with RotateMasterKey().

Crypto

Crypto is a low-level encryption interface. It is designed as a
straightforward compatibility layer, to hide some of the differences between
the various available cryptography extensions (and PHP versions) from
CryptoKey.

You should only use Crypto directly if you have a pretty good idea of what
you’re doing.

Exposure Risks

This being PHP, there’s no way (barring extensions) to actually scrub the
contents of RAM. It might in fact not even be useful to do so anyway, due to
other information leaks (swap files) allowed by many OS configurations.
In-process damage (e.g. Heartbleed) might also defeat such measures. The
following steps are taken to try to minimize the exposure risk:

• Secrets can be loaded without supplying a key at all. This leaves just the
  encrypted text and the encrypted lockboxes in RAM. So you can prospectively
  load secrets and only decrypt them if needed. This also allows removing a
  lockbox from a secret without ever supplying the key.

• Unlocking a secret does not automatically decrypt the value. The internal
  key is, however, stored - in the clear - in RAM after unlocking. This
  provides for the case where you want to add a lockbox to a secret but do
  not want to needlessly expose the unencrypted value in RAM.

• Vaults only load secret values from disk as they are requested.

• The passphrase used to decrypt a Vault master key is not retained by
  the Vault instance. Though, again, the master key itself is stored
  in the clear.

• Both Secret and Vault provide a Close() method that immediately
  detaches stored keys and plaintext values. CryptoKey provides a Shred()
  method that detaches the key data and id.