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.

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

AUTHOR

Aristotle Pagaltzis <pagaltzis@gmx.de>

COPYRIGHT AND LICENSE

This software is copyright (c) 2020 by Aristotle Pagaltzis.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.