NAME

URL::Signature::Path - Sign your URL's path

SYNOPSIS

stand-alone usage:

  use URL::Signature::Path;
  my $signer = URL::Signature::Path->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 => 'path',
    as     => 1,
  );

DESCRIPTION

This module provides path 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 'path'. The following extra parameters are also available:

• as - This option specifies the segment's position in which to inject/extract the authentication code. This option is 0-based, and defaults to 1, meaning the second segment of the provided path should contain the signature.

  So, when you say something like:

     my $signer = URL::Signature::Path->new( key => 'my-secret-key' );
     
     $signer->validate( 'www.example.com/1234/foo/bar' );

  it will split the URL into ('www.example.com', '1234', 'foo', 'bar'), and, since 'as' is set to 1, it will assume '1234' is the signature to be extracted.

  Similarly, if you say:

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

  then it will place the signature on the second segment of the provided path, so $url will stringify to 'www.example.com/CODE/foo/bar', where CODE is the calculated signature for that path.

  Similarly, if you omit the domain (and/or the root of your application) and instead provide just the relative path, it should also append the signature properly:

     my $url = $signer->sign( '/foo/bar' );

  And '$url' will stringify to '/CODE/foo/bar'.

  Note, however, that for this to work you must provide the path starting with a '/', otherwise it will take the first element of your path to be segment 0:

     $url = $signer->sign( 'foo/bar' );

  The code above will create your $uri object as 'foo/CODE/bar', which is probably NOT what you want.

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.

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.

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

In URL::Signature::Path, it will assume the original uri contains the signature in the position 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/12345/some/path' );
   my ($code, $uri) = $obj->extract( $path );

   print $code;  # '12345'
   print "$uri"; # 'example.com/some/path'

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 position specified by the 'as' parameter set in the constructor. For example:

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

    print "$signed_uri";  # 'example.com/1234/some/path'

SEE ALSO

URL::Signature

cpanm URL::Signature

perl -MCPAN -e shell
install URL::Signature