AWS::Signature4 - Create a version4 signature for Amazon Web Services

       Lincoln Stein <lincoln.stein@gmail.com>.

       Copyright (c) 2014 Ontario Institute for Cancer Research

       This package and its accompanying libraries is free software; you can redistribute it  and/or  modify  it
       under  the  terms  of  the  GPL  (either version 1, or at your option, any later version) or the Artistic
       License 2.0.  Refer to LICENSE for the full license text. In  addition,  please  see  DISCLAIMER.txt  for
       disclaimers of warranty.

perl v5.36.0                                       2022-10-13                               AWS::Signature4(3pm)

       This module implement's Amazon Web Service's Signature version 4
       (http://docs.aws.amazon.com/general/latest/gr/signature-version-4.html).

       $signer = AWS::Signature4->new(-access_key => $account_id,-secret_key => $private_key);
           Create  a  signing  object  using  your AWS account ID and secret key. You may also use the temporary
           security tokens received from Amazon's STS service, either by passing  the  access  and  secret  keys
           derived from the token, or by passing a VM::EC2::Security::Token produced by the VM::EC2 module.

           Arguments:

            Argument name       Argument Value
            -------------       --------------
            -access_key         An AWS access key (account ID)

            -secret_key         An AWS secret key

            -security_token     A VM::EC2::Security::Token object

           If a security token is provided, it overrides any values given for -access_key or -secret_key.

           If the environment variables EC2_ACCESS_KEY and/or EC2_SECRET_KEY are set, their contents are used as
           defaults for -access_key and -secret_key.

       $signer->sign($request [,$region] [,$payload_sha256_hex])
           Given  an  HTTP::Request  object,  add  the headers required by AWS and then sign it with a version 4
           signature by adding an "Authorization" header.

           The request must include a URL from which the AWS endpoint  and  service  can  be  derived,  such  as
           "ec2.us-east-1.amazonaws.com."  In  some  cases  (e.g.  S3  bucket  operations) the endpoint does not
           indicate the region. In this case, the region can be forced by passing a defined value  for  $region.
           The  current  date  and  time will be added to the request using an "X-Amz-Date header." To force the
           date and time to a fixed value, include the "Date" header in the request.

           The request content, or "payload" is retrieved from the HTTP::Request object by calling its content()
           method.. Under some circumstances the payload is not included directly in the request, but is  in  an
           external  file that will be uploaded as the request is executed. In this case, you must pass a second
           argument containing the results of running sha256_hex() (from the Digest::SHA module) on the content.

           The method returns a true value if successful. On errors, it will throw an exception.

       $url = $signer->signed_url($request)
           This method will generate a signed GET URL for the request. The URL will include everything needed to
           perform the request.

       my $url $signer->signed_url($request_or_uri [,$expires])
           Pass an HTTP::Request, a URI object, or just a plain URL string containing the  proper  endpoint  and
           parameters  needed  for an AWS REST API Call. This method will return an appropriately signed request
           as a URI object, which can be shared with non-AWS users for the purpose of, e.g., accessing an object
           in a private S3 bucket.

           Pass an optional $expires argument to indicate that the URL will only be valid for a finite period of
           time. The value of the argument is in seconds.

       $signing_key = AWS::Signature4->signing_key($secret_access_key,$service_name,$region,$date)
           Return just the signing key in the event you wish to roll your own signature.

       AWS::Signature4 - Create a version4 signature for Amazon Web Services

       VM::EC2

        use AWS::Signature4;
        use HTTP::Request::Common;
        use LWP;

        my $signer = AWS::Signature4->new(-access_key => 'AKIDEXAMPLE',
                                          -secret_key => 'wJalrXUtnFEMI/K7MDENG+bPxRfiCYEXAMPLEKEY');
        my $ua     = LWP::UserAgent->new();

        # Example POST request
        my $request = POST('https://iam.amazonaws.com',
                           [Action=>'ListUsers',
                            Version=>'2010-05-08']);
        $signer->sign($request);
        my $response = $ua->request($request);

        # Example GET request
        my $uri     = URI->new('https://iam.amazonaws.com');
        $uri->query_form(Action=>'ListUsers',
                         Version=>'2010-05-08');

        my $url = $signer->signed_url($uri); # This gives a signed URL that can be fetched by a browser
        my $response = $ua->get($url);