Secrets Manager for PHP

1.3.2 2021-01-25 14:31 UTC

README

Latest Stable Version Total Downloads

Secrets are an important aspect of most applications you can build. How you store them, and keep them "secret" is a challenge. Luckily, there are tools you can use to keep them all safe.

Secretary is a tool to integrate your PHP application with these tools.

Table of Contents

  1. Installation
  2. Api Documentation
    1. Secretary\Manager
      1. Initializing
      2. getSecret
      3. putSecret
      4. deleteSecret
      5. getAdapter
    2. Secretary\Secret
      1. getKey
      2. getValue

Installation

$ composer require secretary/core

By itself, the core is useless. You will also need to add at least one adapter:

Storage Engine Badges
AWS Secrets Manager Latest Stable Version Total Downloads
HashiCorp Vault Latest Stable Version Total Downloads
JSON File Latest Stable Version Total Downloads

There are also miscellaneous packages that add on to Secretary

Package Purpose Badges
PSR-6 Cache Adapter Allows for caching secrets using a PSR-6 Cache Interface Latest Stable Version Total Downloads
PSR-16 Cache Adapter Allows for caching secrets using a PSR-16 Cache Interface Latest Stable Version Total Downloads
Secretary Bundle Allows for integrating with the Symfony Framework Latest Stable Version Total Downloads

Api Documentation

There's two classes you interface with in Secretary:

Secretary\Manager

Secretary\Manager->__construct(AdapterInterface $adapter)

Pass in your desired adapter.

<?php
use Secretary\Manager;
use Secretary\Adapter\AWS\SecretsManager\LocalJSONFileAdapter;

$manager = new Manager(
    new LocalJSONFileAdapter([
        'region'      => 'us-east-1',
        'credentials' => [
            'accessKeyId'     => 'myAccessKeyId',
            'secretAccessKey' => 'mySecretAccessKey'
        ]
    ])
);

Optionally, you may wrap your adapter, with one of the two cache adapters.

<?php
use Secretary\Manager;
use Secretary\Adapter\AWS\SecretsManager\LocalJSONFileAdapter;

use Secretary\Adapter\Cache\PSR6Cache\ChainAdapter;
use Cache\Adapter\Apc\ApcCachePool;

$manager = new Manager(
    new ChainAdapter(
        new LocalJSONFileAdapter([
            'region'      => 'us-east-1',
            'credentials' => [
                'accessKeyId'     => 'myAccessKeyId',
                'secretAccessKey' => 'mySecretAccessKey'
            ]
        ]),
        new ApcCachePool()
    )
);

For mor information on the arguments and options for the adapters, view their respective documentation.

Secretary\Manager->getSecret(string $key, ?array $options): Secret

Fetches a secret from the configured adapter. $key is the name of the secret (or path) you are trying to get.

Certain adapters will take custom options as well, like VersionId and VersionStage for the AWS SecretsManager Adapter

This will throw a Secretary\SecretNotFoundException if the secret cannot be found

$secret = $manager->getSecret('databases/redis/dsn');
/*
Secret {
    "path" = "databases/redis/dsn",
    "value" = "redis://localhost:6379"
}
*/

Some adapters also support storing a key/value map as a secret's value.

$secret = $manager->getSecret('databases/redis');
/*
Secret {
    "path" = "databases/redis",
    "value" = [
        "dsn" => "redis://localhost:6379",
        "password" => "my_super_strong_password" 
    ]
}
*/

Secretary\Manager->putSecret(string $key, string|array $value, ?array $options): void

Puts a secret with the given $value, into the storage engine, under the given $key.

If the current adapter doesn't support arrays, and you pass one it, it will throw a Secretary\ValueNotSupportedException.

Again, some adapters allow passing in custom options to send along with the request.

$manager->putSecret('database/redis', 'postgres://localhost:5432');

And for adapters that support a key/value map as a value:

$manager->putSecret('database/redis', ['dsn' => 'redis://localhost:6379', 'password' => 'my_super_strong_password']);

Secretary\Manager->deleteSecret(string $key, ?array $options): void

Deletes a secret from the storage engine using the given $key.

Again, some adapters allow passing in custom options to send along with the request.

$manager->deleteSecret('database/redis');

Secretary\Manager->getAdapter(): AdapterInterface

Will return the adapter that was passed to this manager during construction.

Secretary\Secret

This class implements ArrayAccess, so if your secret supports passing a key/value map, you can grab straight from the map:

Secrets are immutable, so attempting to change a value will throw an Exception.

$secret = $manager->getSecret('database/redis');

$dsn = $secret['dsn'];

Secretary\Secret->getKey(): string

Returns the key for the secret

$secret = $manager->getSecret('dabase/redis');

$secret->getKey() === 'database/redis'; // true

Secretary\Secret->getValue(): string | array

Returns the value for the secret. If the secret is a key/value map, its an array

$secret = $manager->getSecret('dabase/redis/dsn');

$secret->getValue() === 'redis://localhost:6379'; // true

// Or

$secret = $manager->getSecret('dabase/redis');

print_r($secret->getValue()); 
/*
[
    "dsn" => "redis://localhost:6379",
    "password" => "my_super_strong_password" 
]
*/