/ 
Amazon-Signature4-Lite-1.0.6
/ Amazon::Signature4::Lite

NAME

Amazon::Signature4::Lite - Lightweight AWS Signature Version 4 signing

SYNOPSIS

use Amazon::Signature4::Lite;

my $signer = Amazon::Signature4::Lite->new(
  access_key    => $access_key_id,
  secret_key    => $secret_access_key,
  session_token => $session_token,   # optional, for STS/IAM roles
  region        => 'us-east-1',
  service       => 's3',             # default
);

my $signed = $signer->sign(
  method  => 'PUT',
  url     => 'https://s3.amazonaws.com/my-bucket/my-key',
  headers => { 'Content-Type' => 'application/gzip' },
  payload => $content,
);

# $signed is a hashref of headers ready for HTTP::Tiny:
# Authorization, x-amz-date, x-amz-content-sha256,
# x-amz-security-token (if session_token provided), host

# For streamed content, supply a precomputed SHA-256 hash instead of #
# passing the complete payload to the signer.

my $signed = $signer->sign(
  method       => 'PUT',
  url          => 'https://s3.amazonaws.com/my-bucket/my-key',
  headers      => { 'Content-Type' => 'application/octet-stream', 'Content-Length' => $content_length, },
  payload_hash => $payload_hash,
);

DESCRIPTION

A minimal, dependency-free AWS Signature Version 4 implementation for signing S3 and other AWS API requests. Unlike AWS::Signature4, this module does not depend on LWP or HTTP::Request - it works directly with the plain scalars and hashrefs that HTTP::Tiny uses.

For large or streamed request bodies, callers may provide a precomputed SHA-256 payload hash, allowing the request to be signed without holding the complete payload in memory.

METHODS

new(%args)

my $signer = Amazon::Signature4::Lite->new(
  access_key => $key,
  secret_key => $secret,
  region     => 'us-east-1',
);

Required: access_key, secret_key, region. Optional: session_token (for temporary credentials), service (defaults to s3).

sign(%args)

my $headers = $signer->sign(
  method  => 'GET',
  url     => $url,
  headers => %extra_headers,
  payload => $body,
);

Signs an AWS request and returns a hash reference containing the HTTP headers required for the request.

Arguments:

method

HTTP request method. Defaults to GET.

url

The complete request URL. Required.

headers

Optional hash reference containing additional request headers to include in the signature.

payload

The request body. The SHA-256 hash used in the canonical request is calculated from this value.

If neither payload nor payload_hash is supplied, the payload is treated as an empty string.

payload_hash

An optional precomputed SHA-256 hash of the request body.

When supplied, payload_hash is used directly in the canonical request and, by default, as the value of the x-amz-content-sha256 header. The payload value is not hashed.

This is useful when the request body will be streamed and holding the complete payload in memory solely for signing would be undesirable. The caller is responsible for ensuring that payload_hash corresponds exactly to the content that will be transmitted.

my $headers = $signer->sign( method => 'PUT', url => $url, headers => %extra_headers, payload_hash => $sha256, );

add_sha256_header

Controls whether x-amz-content-sha256 is included in the returned headers. Defaults to true.

time

Optional Unix timestamp used when generating the signing timestamp. When omitted, the current time is used. This is primarily useful for testing or applications that need to control the signing time.

The returned hash reference includes Authorization, x-amz-date, host, and, by default, x-amz-content-sha256. It also includes x-amz-security-token when the signer was constructed with a session token.

The returned hash reference can be passed directly as the headers for an HTTP::Tiny request.

parse_service_url(%args)

my ($host, $service, $region) = Amazon::Signature4::Lite->parse_service_url(
  host           => 's3.us-east-2.amazonaws.com',
  default_region => 'us-east-1',
);

Extracts service name and region from an AWS endpoint URL. Can be called as a class or instance method.

Note: The patterns used for parsing are S3/AWS endpoint focused, not a general URL parser.

DEPENDENCIES

All dependencies are Perl core modules (since 5.10) or already required by distributions in the Amazon::* toolchain:

SEE ALSO

AWS::Signature4, Signer::AWSv4, Amazon::S3::Lite