README

Key pair management for Craft CMS.

KeyChain stores X.509 certificates and their private keys so other plugins can use them for signing and encryption. It is used by SAML SP and SAML IdP.

• Generate self-signed OpenSSL key pairs from the control panel
• Bring your own key pair (BYOK)
• Encrypt keys at rest with Craft's security key
• Validates that a key and certificate belong together

Requirements

• Craft CMS 5
• PHP 8.2+ with the OpenSSL extension

Installation

composer require flipboxfactory/keychain
php craft plugin/install keychain

Key pairs are managed under KeyChain in the control panel.

Private keys aren't shown when you edit a key pair. Leave the field blank to keep the current key, paste a new one to replace it, or click Reveal current key (admins only, after re-entering your password) to see it.

Usage

use flipbox\keychain\KeyChain;

$service = KeyChain::getInstance()->getService();

// Generate and save a key pair, using the plugin's OpenSSL defaults
$keyPair = $service->generateOpenssl(['pluginHandle' => 'my-plugin']);

// Key pairs belonging to a plugin
$keyPairs = $service->findByPlugin($myPlugin)->all();

// PEM strings, decrypted if stored encrypted
$keyPair->getDecryptedKey();
$keyPair->getDecryptedCertificate();

Settings

Override the defaults in config/keychain.php:

return [
    'encryptByDefault' => true,
    'opensslDefaults' => [
        'digestAlgorithm' => 'sha256',
        'keyBits' => 2048,
        'daysExpiry' => 730,
        'commonName' => 'example.com',
        // countryName, stateOrProvinceName, localityName, organizationName,
        // organizationalUnitName, emailAddress, description
    ],
];

Development

Checks follow Craft's coding guidelines: craftcms/ecs and craftcms/phpstan. Tests use Codeception with Craft's test module and need a MySQL database:

docker run -d --rm --name keychain-test-mysql -e MYSQL_ROOT_PASSWORD=password \
  -e MYSQL_DATABASE=keychain_test -p 127.0.0.1:3306:3306 mysql:8.0
cp tests/.env.example tests/.env   # adjust CRAFT_DB_* if needed

composer check      # check-cs + phpstan + test
composer fix-cs     # auto-fix coding standards

CI runs the same checks on every push and pull request.

Contributing

See CONTRIBUTING.

License

MIT. See LICENSE.