/ 
Mojo-UserAgent-Role-AWSSignature4-0.01
/ Mojo::UserAgent::Role::AWSSignature4

NAME

Mojo::UserAgent::Role::AWSSignature4 - Add AWS Signature Version 4 to Mojo::UserAgent requests

VERSION

0.01

SYNOPSIS

use Mojo::Base -strict;
use Mojo::UserAgent;
my $ua = Mojo::UserAgent->with_roles('+AWSSignature4')->new;
my $url = 'https://my-bucket.s3.us-east-1.amazonaws.com/my-object.txt';
$ua->put($url => awssig4 => {service => 's3'})->result;

DESCRIPTION

This role adds AWS Signature Version 4 capabilities to Mojo::UserAgent HTTP requests. It signs requests using the AWS Signature Version 4 signing process, which is required for authenticating requests to AWS services. It supports setting various parameters such as access key, secret key, region, service, and expiration time. Additionally, it can handle unsigned payloads and debug mode for troubleshooting.

This role is useful for developers who need to interact with AWS services using Mojolicious and want to ensure their requests are properly signed according to AWS security standards.

Note that this module can be used with any service that requires AWS Signature Version 4 signing, not just AWS services.

A Mojo::UserAgent::Transactor generator named awssig4 is added to handle the signing process. To use it, simply specify awssig4 as a generator when making requests with the user agent and specify the required configuration options as a hash reference.

GENERATORS

These content generators are available by default.

awssig4

$t->tx(POST => $url => awssig4 => {service => 's3'});

Generate AWS Signature Version 4 signed content. See ATTRIBUTES for options. service is the only required option.

The following request headers are added, in order, during signing:

- Host: Transaction request URL host, or 'localhost' if not present

- X-Amz-Date: The date and time of the request, in compact ISO 8601 format with UTC timezone

- X-Amz-Content-Sha256: Hashed payload of the content being sent, or UNSIGNED-PAYLOAD if unsigned_payload is set

- X-Amz-Expires: Expiration time in seconds (if expires is set)

- Authorization: AWS Signature Version 4 authorization (see authorization method)

ATTRIBUTES

Mojo::UserAgent::Role::AWSSignature4 adds the following attributes:

access_key

The AWS access key ID used for signing requests.

Defaults to $ENV{AWS_ACCESS_KEY}.

aws_algorithm

The AWS signing algorithm used.

Defaults to 'AWS4-HMAC-SHA256'.

content

Path to a file containing the request payload to be signed. Will be read and used as the request body during signing.

The value is provided as the "path" in Mojo::Asset::File attribute to create a Mojo::Asset::File object and set as the "asset" in Mojo::Content::Single.

No default value (i.e. undef).

debug

Enables debug mode for signing process.

Defaults to 0.

expires

The expiration time for the signed request in seconds.

Defaults to 86_400 (24 hours).

region

The AWS region for the request.

Defaults to 'us-east-1'.

secret_key

The AWS secret access key used for signing requests.

Defaults to $ENV{AWS_SECRET_KEY}.

service

The AWS service name for the request.

Has no default value and must be provided; dies if not set.

session_token

The AWS session token for temporary credentials.

Defaults to $ENV{AWS_SESSION_TOKEN}.

unsigned_payload

Indicates whether to use an unsigned payload.

Defaults to 0.

METHODS

Mojo::UserAgent::Transactor inherits all methods from Mojo::Base and implements the following new ones.

authorization

AWS Signature Version 4 authorization header value, in the format:

AWS4-HMAC-SHA256 Credential=ACCESS_KEY/DATE/REGION/SERVICE/aws4_request, SignedHeaders=SIGNED_HEADER_LIST, Signature=SIGNATURE

canonical_headers

AWS Signature Version 4 canonical sorted headers string, in the format:

header1:value1\nheader2:value2\n...

canonical_qstring

Adds the X-Amz-Signature parameter to the query string.

canonical_request

AWS Signature Version 4 canonical request string, in the format:

HTTP_METHOD\nCANONICAL_URI\nCANONICAL_QUERY_STRING\nCANONICAL_HEADERS\nSIGNED_HEADER_LIST\nHASHED_PAYLOAD

Will warn debug information if debug is enabled.

credential_scope

AWS Signature Version 4 credential scope string, in the format:

DATE/REGION/SERVICE/aws4_request

date

Returns the current date in YYYYMMDD format.

date_timestamp

Returns the current date and time in YYYYMMDD'T'HHMMSS'Z' format.

hashed_payload

Returns the SHA256 hash of the request payload, or UNSIGNED-PAYLOAD if unsigned_payload is set.

header_list

Returns a sorted array reference of the request header names.

signature

Calculates and returns the AWS Signature Version 4 signature.

signed_header_list

Returns a semicolon-separated list of signed header names.

signed_qstring

Adds the X-Amz-Signature parameter to the query string.

signing_key

Calculates and returns the AWS Signature Version 4 signing key.

string_to_sign

AWS Signature Version 4 string to sign, in the format:

AWS4-HMAC-SHA256\nDATE_TIMESTAMP\nCREDENTIAL_SCOPE\nHASHED_CANONICAL_REQUEST

Will warn debug information if debug is enabled.

time

Returns the current time as a Time::Piece object in UTC.

SEE ALSO

Mojolicious::UserAgent, Mojolicious, Mojolicious::Guides, https://mojolicious.org.

AUTHOR

Stefan Adams <sadams@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2025+ by Stefan Adams <sadams@cpan.org>. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.