ross-kvit/php-mtls-hmac

mTLS + HMAC-signed GET client for testing

dev-main 2025-09-19 10:44 UTC

Requires

• php: >=8.0
• guzzlehttp/guzzle: ^7.0
• vlucas/phpdotenv: ^5.5

Requires (Dev)

• phpunit/phpunit: ^9.0

MIT

README

# PHP mTLS + HMAC client


Minimal Composer package demonstrating:


- mTLS client configuration using Guzzle
- HMAC-SHA256 signature computation over canonical query string
- PSR-4 autoloading, .env configuration via vlucas/phpdotenv
- Unit and integration tests (integration test uses badssl client endpoint)


## Setup


1. Copy files into a directory and run `composer install`.
2. Create a `.env` file (copy `.env.example`) and set the real paths/secrets.


Example `.env` for testing with badssl (download certs from https://badssl.com/download/):


```ini
MTLS_CLIENT_CERT=./certs/badssl.com-client-cert.pem
MTLS_CLIENT_KEY=./certs/badssl.com-client-key.pem
MTLS_CLIENT_KEY_PASSPHRASE=badssl.com
HMAC_SECRET=your_shared_hmac_secret
API_ENDPOINT=https://client.badssl.com/
```


3. Run unit tests: `./vendor/bin/phpunit --filter SignerTest`
4. Run integration test (if `.env` contains real cert/key/secret): `./vendor/bin/phpunit --filter IntegrationTest`


## Notes


- Guzzle options set `cert` and `ssl_key`. If your private key is encrypted, set `MTLS_CLIENT_KEY_PASSPHRASE`.
- `verify` defaults to system CA if `MTLS_CA_BUNDLE` not set. To force validation with a specific bundle, set `MTLS_CA_BUNDLE` to the path to your CA bundle.
- The Signer canonicalizes by sorting keys and building an RFC3986-encoded query string, then computing HMAC-SHA256.


## Final notes


This package is structured for testability: Signer is pure and unit-testable; Client depends on Config and Guzzle. The integration test is intentionally skipped unless environment variables are set so CI won't fail.