Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/ap/uri-signature-tiny

Mint and verify server-signed URIs
https://github.com/ap/uri-signature-tiny

perl signed-url

Last synced: 10 days ago
JSON representation

Mint and verify server-signed URIs

Awesome Lists containing this project

README 

        
=pod



=encoding UTF-8



=for comment vim: et sw=2 ts=2 sts=2



=head1 NAME



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



=head1 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 );



=head1 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.



=head1 METHODS



=over 2



=item C



Construct and return an instance of this class.

Takes a list of key/value pairs specifying configuration options:



=over 2



=item C



A message authentication code (MAC) value,

which needs to have cryptographically sufficient entropy.



B.



=item C



A callback that defines how to incorporate the signature into a fresh URI.

See L> for details.



Defaults to a placeholder that croaks.



=item C



A callback that defines how to remove the signature from a signed URI.

See L> for details.



Defaults to a placeholder that croaks.



=item C



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



Defaults to true.



=item C



The function that will be called to compute the signature,

which should have the same signature as the HMAC functions from L:

the (normalised) URI and the secret will be its first and second arguments.



Defaults to

L|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 }



=item C



Whether to apply substitutions to turn the return value of the L>

from regular C encoding into C.



Defaults to true.



=back



=item C



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 L>.



=item C



Takes a fresh URI and returns the same URI with the signature added to it.

Specifically it returns whatever the L> callback returns,

which gets called with the fresh URI and its signature as arguments.



=item C



Takes a signed URI and checks whether it matches its signature.

It passes its arguments to the L> callback,

which must return two values:

the bare URI with the signature stripped off, and the signature.



Both the signature extracted by the L> callback

and the actual signature computed by the L> callback

must be defined for verification to pass.



=back



=head1 SEE ALSO



=over 2



=item *



L



=item *



L2104, I|https://tools.ietf.org/html/rfc2104>



=item *



L4648, I, section 5., I|https://tools.ietf.org/html/rfc4648#section-5>



=back



=cut