Keyring.php

<?php
/*
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at https://mozilla.org/MPL/2.0/.
 */
/**
 * Italix Crypto - Keyring
 *
 * @package Italix\Crypto
 */

declare(strict_types=1);

namespace Italix\Crypto;

/**
 * The keys, and the fact that there can be more than one.
 *
 * Rotation is the reason this class exists rather than a `string $key`
 * parameter. A key can only be replaced if the old one keeps *verifying* for as
 * long as anything signed with it is still valid — a password-reset link mailed
 * five minutes before the rotation has to keep working. So: **sign with the
 * primary, verify against all**.
 *
 * Each key carries a short id which is written into the token, so verification
 * tries the right key first instead of all of them, and so an operator can tell
 * from a token which key produced it.
 *
 *     APP_KEY=base64:xxxxxxxx…              # primary
 *     APP_KEY_PREVIOUS=base64:yyyyyyyy…     # accepted during the rotation window
 *
 * Keys are 32 bytes. Accepted as `base64:…`, `hex:…`, or 64 hex characters
 * with no prefix.
 */
final class Keyring
{
    public const KEY_BYTES = 32;

    /** @var array<string, string> key id => raw 32-byte key, primary first */
    private array $keys = [];

    /**
     * @param string[] $keys Encoded keys, primary first
     */
    public function __construct(array $keys)
    {
        foreach ($keys as $encoded) {
            $encoded = trim((string) $encoded);

            if ($encoded === '') {
                continue;
            }

            $raw = self::decode($encoded);
            $this->keys[self::id_of($raw)] = $raw;
        }

        if ($this->keys === []) {
            throw new CryptoException(
                'A Keyring needs at least one key. Generate one with: '
                . 'php -r \'echo "base64:", base64_encode(random_bytes(32)), "\n";\''
            );
        }
    }

    /**
     * Build from environment variables.
     *
     * @param string[] $names in precedence order; the first present is primary
     */
    public static function from_env(array $names = ['APP_KEY', 'APP_KEY_PREVIOUS']): self
    {
        $keys = [];

        foreach ($names as $name) {
            $value = $_ENV[$name] ?? getenv($name);

            if (is_string($value) && trim($value) !== '') {
                $keys[] = $value;
            }
        }

        if ($keys === []) {
            throw new CryptoException(
                'No application key: set ' . reset($names) . ' in .env. Generate one with: '
                . 'php bin/ix crypto:key'
            );
        }

        return new self($keys);
    }

    /**
     * A fresh key in the encoded form the environment expects.
     */
    public static function generate(): string
    {
        return 'base64:' . base64_encode(random_bytes(self::KEY_BYTES));
    }

    public function primary_id(): string
    {
        return (string) array_key_first($this->keys);
    }

    public function primary(): string
    {
        return $this->keys[$this->primary_id()];
    }

    /**
     * The key with this id, or null. Never throws: the id comes off the wire.
     */
    public function by_id(string $key_id): ?string
    {
        return $this->keys[$key_id] ?? null;
    }

    /**
     * Every key, primary first — the verification order when a token carries no
     * usable id.
     *
     * @return array<string, string>
     */
    public function all(): array
    {
        return $this->keys;
    }

    public function count(): int
    {
        return count($this->keys);
    }

    // -------------------------------------------------------------------------
    // Internals
    // -------------------------------------------------------------------------

    /**
     * A short, non-secret identifier for a key.
     *
     * Derived by HMAC rather than by hashing the key directly, and truncated to
     * 8 hex characters: it appears in every token, so it must reveal nothing
     * useful about the key itself.
     */
    private static function id_of(string $raw_key): string
    {
        return substr(hash_hmac('sha256', 'italix.keyring.id', $raw_key), 0, 8);
    }

    private static function decode(string $encoded): string
    {
        if (strncmp($encoded, 'base64:', 7) === 0) {
            $raw = base64_decode(substr($encoded, 7), true);
        } elseif (strncmp($encoded, 'hex:', 4) === 0) {
            $raw = @hex2bin(substr($encoded, 4));
        } elseif (preg_match('/^[0-9a-fA-F]{64}$/', $encoded) === 1) {
            $raw = @hex2bin($encoded);
        } else {
            $raw = false;
        }

        if (!is_string($raw)) {
            throw new CryptoException(
                'Malformed application key: expected "base64:…", "hex:…" or 64 hex characters.'
            );
        }

        if (strlen($raw) !== self::KEY_BYTES) {
            throw new CryptoException(sprintf(
                'Application key must be %d bytes, got %d. Generate one with: php bin/ix crypto:key',
                self::KEY_BYTES,
                strlen($raw)
            ));
        }

        return $raw;
    }
}