view release on metacpan or  search on metacpan

lib/Amazon/Signature4/Lite.pm  view on Meta::CPAN

=head1 NAME

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

=head1 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,
  );

=head1 DESCRIPTION

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

=head1 METHODS

=head2 new(%args)

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

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

=head2 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:

=over 4

=item method

HTTP request method. Defaults to C<GET>.

=item url

The complete request URL. Required.

=item headers

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

=item payload

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

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

=item payload_hash

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

When supplied, C<payload_hash> is used directly in the canonical request
and, by default, as the value of the C<x-amz-content-sha256> header. The
C<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 C<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,
);

=item add_sha256_header