ap / uri-signature-tiny

Mint and verify server-signed URIs

NAME

URI::Signature::Tiny - Mint and verify server-signed URIs

SYNOPSIS

use URI;
use URI::Signature::Tiny;

my $notary = URI::Signature::Tiny->new(
  secret     => $secret,
  after_sign => sub {
    my ( $uri, $sig ) = @_;
    $uri->query_form({ $uri->query_form, s => $sig });
    $uri;
  },
  before_verify => sub {
    my ( $uri ) = @_;
    my %f = $uri->query_form;
    my $sig = delete $f{'s'};
    $uri = $uri->clone; # important
    $uri->query_form( \%f );
    ( $uri, ref $sig ? '' : $sig );
  },
);

my $signed_uri = $notary->sign( URI->new( 'http://example.com/foo?bar=baz#pagetop' ) );

my $ok = $notary->verify( $signed_uri );

DESCRIPTION

This is a minimal helper to generate URLs that you can later verify to not have been modified, so that you can trust security-relevant values such as user IDs. This is useful e.g. for a passwort reset link that the user should not be able to edit to log in as someone else.

METHODS

new

Construct and return an instance of this class. Takes a list of key/value pairs specifying configuration options:

secret

A message authentication code (MAC) value, which needs to have cryptographically sufficient entropy.

Required.

after_sign

A callback that defines how to incorporate the signature into a fresh URI. See "sign" for details.

Defaults to a placeholder that croaks.

before_verify

A callback that defines how to remove the signature from a signed URI. See "verify" for details.

Defaults to a placeholder that croaks.

sort_params

Whether to sort query parameters (if any) before computing the signature.

Defaults to true.

function

The function that will be called to compute the signature, which should have the same signature as the HMAC functions from Digest::SHA: the (normalised) URI and the secret will be its first and second arguments.

Defaults to \&Digest::SHA::hmac_sha256_base64.

You might also use this just to post-process the HMAC value, any way you wish:

sub { substr &Digest::SHA::hmac_sha512224_base64, 0, 10 }

recode_base64

Whether to apply substitutions to turn the return value of the "function" from regular base64 encoding into base64url.

Defaults to true.

signature

Compute and return the signature for the URI which is passed as the only argument.

The only way that the URI value might be modified here is to sort the query parameters if requested by "sort_params".

sign

Takes a fresh URI and returns the same URI with the signature added to it. Specifically it returns whatever the "after_sign" callback returns, which gets called with the fresh URI and its signature as arguments.

verify

Takes a signed URI and checks whether it matches its signature. It passes its arguments to the "before_verify" callback, which must return two values: the bare URI with the signature stripped off, and the signature.

Both the signature extracted by the "before_verify" callback and the actual signature computed by the "function" callback must be defined for verification to pass.

SEE ALSO

• URL::Signature

• RFC 2104, HMAC: Keyed-Hashing for Message Authentication

• RFC 4648, The Base16, Base32, and Base64 Data Encodings, section 5., Base 64 Encoding with URL and Filename Safe Alphabet