Download the PHP package laravel-chronicle/kms-aws without Composer

laravel-chronicle/kms-aws

AWS KMS custody for the Chronicle audit ledger.

Keeps Chronicle's cryptographic key material inside AWS KMS instead of on the application server. The package provides two independent providers:

• Signing (AwsKmsSigningProvider) - signs checkpoints and exports via KMS (ECDSA P-256). Verification is always offline, using a cached public key, so no AWS call is needed to verify.
• KEK custody (KmsKeyEncryptionProvider) - holds the Key Encryption Key for Chronicle's crypto-shredding, wrapping and unwrapping per-subject DEKs through KMS Encrypt/Decrypt so the KEK never leaves the HSM.

Use either or both. The signing setup is covered first; KEK custody has its own section below.

Installation

The package auto-discovers its service provider via Laravel's package discovery.

Requirements

• PHP 8.2+
• ext-openssl
• laravel-chronicle/core ^1.10
• AWS SDK for PHP ^3.0

AWS Setup

This section sets up the signing provider. If you also want KEK custody for crypto-shredding, you'll need a separate symmetric key - see KEK encryption provider below. The two providers use different key types and are configured independently.

Create a KMS key (signing)

Create an asymmetric KMS key with:

• Key type: Asymmetric
• Key spec: ECC_NIST_P256
• Key usage: SIGN_VERIFY

Required IAM actions

Attach the following IAM policy to the role that runs your application:

kms:GetPublicKey is not required at runtime - the public key is cached in your application config and never fetched from KMS during verification.

Retrieve and cache the public key

Retrieve your KMS key's public key once and store it in your config:

This outputs a PEM string like:

Store this as the public_key in your Chronicle signing config (see below).

Configuration

Register the KMS key in config/chronicle.php under signing.keys:

Set the corresponding environment variables:

How it works

The private key never leaves AWS KMS. Verification is offline and instant.

Key rotation

Chronicle's key rotation works identically for KMS-backed keys. Retire the old key by keeping only its public_key in the ring (omit key_arn), then add the new KMS key as active. Historic checkpoints and exports continue to verify offline against the retained public key.

Example two-key ring after rotation:

Note: AwsKmsSigningProvider requires key_arn at construction - it cannot be used as a verify-only provider. For retired KMS keys, switch the entry to Chronicle\Signing\EcdsaSigningProvider (from core) with only public_key set, as shown above. Core's EcdsaSigningProvider handles the local-verify-only case.

KEK encryption provider (crypto-shredding)

Chronicle v1.12 can encrypt PII payload fields under a per-subject DEK, wrapping those DEKs under a Key Encryption Key (KEK). This package can hold the KEK in AWS KMS so wrapped DEKs are protected outside the application.

Point chronicle.encryption.kek at the KMS provider:

Required IAM actions on the KEK: kms:Encrypt, kms:Decrypt. The KmsClient is resolved from the container (region from AWS_DEFAULT_REGION), so no extra wiring is needed beyond installing this package.

KmsClient options

The KmsClient singleton is shaped from config/chronicle-kms.php. All keys have sensible defaults - set nothing, and you get a standard region-derived client.

Credentials are never read from this config - they flow through the standard AWS credential chain (env vars, IAM roles, etc.). For anything these keys don't cover - a custom credential provider, or a fully custom client - re-bind Aws\Kms\KmsClient in your application's AppServiceProvider; that binding wins over this provider's default.

License

MIT