/ 
URL-Signature-0.03
River stage zero No dependents
/ URL::Signature::Query

NAME

URL::Signature::Query - Sign your URL with a query parameter

SYNOPSIS

use URL::Signature::Query;
my $signer = URL::Signature::Query->new( key => 'my-secret-key' );

my $url = $signer->sign('/some/path');

or, from within URL::Signature:

use URL::Signature;
my $signer = URL::Signature->new(
  key    => 'my-secret-key',
  format => 'query',
  as     => 'k',
);

DESCRIPTION

This module provides query signature for URLs. It is a subset of URL::Signature but can also be used as a stand-alone module if you don't care as much about signature flexibility.

METHODS

new( %attributes )

Instantiates a new object. You can set the same attributes as URL::Signatures, but it will force 'format' to be 'query'. The following extra parameters are also available:

  • as - This option specifies the variable (query parameter) name in which to inject/extract the authentication code. This option defaults to k, so when you say something like:

    my $signer = URL::Signature::Query->new( key => 'my-secret-key' );

$signer->validate( 'www.example.com/foo/bar?k=1234' );

    it will look for the available query parameters and see if the one labelled 'k' has the appropriate key for the remaining URL.

    Similarly, if you say:

    my $url = $signer->sign( 'www.example.com/foo/bar' );

    it will place the signature as the 'k' query parameter, so $url will stringify to 'www.example.com/foo/bar?k=CODE', where CODE is the calculated signature for that path.

    Note that 'k' is just the default, it will use whichever name you set in the 'as' attribute:

    my $signer = URL::Signature::Query->new(
      key => 'my-secret-key',
      as  => 'Signature',
);

my $url = $signer->sign( '/foo/bar?someKey=someValue&answer=42' );

print "$url";
# => /foo/bar?answer=42&someKey=someValue&Signature=68bPh9H8gsqT6I5TM4J3E7xqrfw

    Note that the order of the query parameters might change. This won't matter to the signature itself, and it shouldn't matter to the URL as well.

sign( $url_string )

(Inherited from URL::Signature)

Receives a string containing the URL to be signed. Returns a URI object with the original URL modified to contain the authentication code as a query parameter.

validate( $url_string )

(Inherited from URL::Signature)

Receives a string containing the URL to be validated. Returns false if the URL's auth code is not a match, otherwise returns an URI object containing the original URL minus the authentication code query parameter.

Convenience Methods

Aside from sign() and validate(), there are a few other methods you may find useful:

code_for_uri( $uri_object )

Receives a URI object and returns a string containing the authentication code necessary for that object.

extract( $uri_object )

my ($code, $new_uri) = $obj->extract( $original_uri );

Receives a URI object and returns two elements:

  • the extracted signature from the given URI

  • a new URI object just like the original minus the signature query parameter

In URL::Signature::Query, it will assume the original uri contains the signature in the query parameter label specified by the 'as' parameter set in the constructor. The returned uri will be the same except the signature itself will be removed. For instance:

my $path = URI->new( 'example.com/some/path?foo=bar&k=12345' );
my ($code, $uri) = $obj->extract( $path );

print $code;  # '12345'
print "$uri"; # 'example.com/some/path?foo=bar'

append

my $new_uri = $obj->append( $original_uri, $code );

Receives a URI object and the authentication code to be inserted. Returns a new URI object with the auth code properly appended, according to the query parameter name specified by the 'as' parameter set in the constructor. For example:

my $original_uri = URI->new( 'example.com/some/path?foo=bar' );
my $signed_uri   = $obj->append( $original_uri, '1234' );

print "$signed_uri";  # 'example.com/some/path?foo=bar&k=12345'

SEE ALSO

URL::Signature