99designs/http-signatures

Sign and verify HTTP messages

4.0.0 2017-05-04 01:36 UTC

Requires

• php: >=5.5
• paragonie/random_compat: ^1.0|^2.0
• psr/http-message: ^1.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^1.11
• guzzlehttp/psr7: ^1.2
• phpunit/phpunit: ~4.8
• symfony/http-foundation: ~2.8|~3.0
• symfony/psr-http-message-bridge: ^1.0
• zendframework/zend-diactoros: ^1.1

MIT

• Paul Annesley

• http
• https
• signature
• signing
• hmac
• signed

README

PHP implementation of HTTP Signatures draft specification; allowing cryptographic signing and verifying of PSR7 messages.

See also:

• https://github.com/99designs/http-signatures-guzzlehttp
• https://github.com/99designs/http-signatures-ruby

Usage

Add 99designs/http-signatures to your composer.json.

Configure a context with your algorithm, keys, headers to sign. This is best placed in an application startup file.

use HttpSignatures\Context;

$context = new Context([
  'keys' => ['examplekey' => 'secret-key-here'],
  'algorithm' => 'hmac-sha256',
  'headers' => ['(request-target)', 'Date', 'Accept'],
]);

If there's only one key in the keys hash, that will be used for signing. Otherwise, specify one via 'signingKeyId' => 'examplekey'.

Messages

A message is assumed to be a PSR-7 compatible request or response object.

Signing a message

$context->signer()->sign($message);

Now $message contains the signature headers:

$message->headers->get('Signature');
// keyId="examplekey",algorithm="hmac-sha256",headers="...",signature="..."

$message->headers->get('Authorization');
// Signature keyId="examplekey",algorithm="hmac-sha256",headers="...",signature="..."

Verifying a signed message

$context->verifier()->isValid($message); // true or false

Symfony compatibility

Symfony requests normalize query strings which means the resulting request target can be incorrect. See symfony/psr-http-message-bridge#30

When creating PSR-7 requests you use withRequestTarget to ensure the request target is correct. For example

use Symfony\Bridge\PsrHttpMessage\Factory\DiactorosFactory;
use Symfony\Component\HttpFoundation\Request;

$symfonyRequest = Request::create('/foo?b=1&a=2');
$psrRequest = (new DiactorosFactory())
	->createRequest($symfonyRequest)
	->withRequestTarget($symfonyRequest->getRequestUri());

Contributing

Pull Requests are welcome.

License

HTTP Signatures is licensed under The MIT License (MIT).