view release on metacpan or  search on metacpan

lib/AWS/Signature/V4.pod  view on Meta::CPAN

=item C<body>, C<body_fh>

the payload, as a byte string, a reference to one (which avoids copying
large data around) or an open filehandle. The filehandle is hashed
from its current position to its end, without loading it in memory, and
put back where it was: so it must be seekable (a file, not a pipe or a
socket) and binary, without layers like C<:encoding> or C<:crlf> that
change the bytes read. Only one of them can be used;

=item C<payload_hash>, C<unsigned_payload>

skip the calculation and use the provided SHA-256 in hex, or
C<UNSIGNED-PAYLOAD>. They take precedence over C<body> and C<body_fh>.
C<payload_hash> can also be a C<STREAMING-*> marker, anything else is an
error. When the payload hash is not a SHA-256, the
C<x-amz-content-sha256> header carries it, whatever the service;

=item C<signed_headers>

array reference of the names of the headers to sign. By default all the
headers are signed except a few that are commonly changed on the way
(e.g. C<user-agent>) or that are meant for a single hop (e.g.
C<keep-alive>). C<host> and all the C<x-amz-*> headers, including those
that C<sign> adds, are always signed, even if not in the list: AWS wants
them signed, and it binds the signature to the host, the date and the
session token. It is an error to name a missing header;

=item C<time>

the epoch to sign for, in seconds (a fractional part is dropped),
defaults to now;

=item C<streaming>, C<decoded_content_length>, C<checksum>, C<trailers>

chunked and streaming uploads, see below.

=back

The returned hash reference contains:

=over

=item C<headers>

the complete set of headers to send, with lowercase names. Beyond those
in input, they include C<host>, C<x-amz-date>, C<authorization> and,
depending on the case, C<x-amz-security-token>, C<x-amz-x509>,
C<x-amz-x509-chain>, C<x-amz-content-sha256>;

=item C<authorization>

the value of the C<Authorization> header;

=item C<signature>, C<signed_headers>, C<scope>

the signature in hex, the semicolon-separated list of signed headers,
and the credential scope;

=item C<canonical_request>, C<string_to_sign>

the intermediate values of the algorithm, handy for debugging;

=item C<chunker>

only when streaming: see below.

=back

=head3 Chunked and streaming uploads

C<streaming> enables the C<aws-chunked> encoding used for uploads to S3,
where the body is sent in chunks that are signed as they go. It can be
C<1> or C<signed> (each chunk is signed, credentials variant only) or
C<unsigned> (no chunk signatures, only the request headers are signed,
also OK with X.509). The C<decoded_content_length>, i.e. the size of
the data, is mandatory. C<sign> sets the payload hash to
C<STREAMING-AWS4-HMAC-SHA256-PAYLOAD> (or its variants below), adds
C<x-amz-decoded-content-length> and C<aws-chunked> to C<Content-Encoding>
(after any other encoding, e.g. C<gzip,aws-chunked>, as it is the one
applied last: S3 takes that token off the end and stores what is left,
here C<gzip>), all signed; the C<Content-Length> to provide is the size
of the encoded body, see L</encoded_length>. S3 wants all chunks but the last
one to be at least 8 KiB. C<body>, C<body_fh>, C<payload_hash> and
C<unsigned_payload> do not apply.

   my $length = AWS::Signature::V4->encoded_length($decoded_length, $chunk_size);
   my $r = $s->sign(
      method => 'PUT', url => $url,
      headers => { 'Content-Length' => $length },
      streaming => 1, decoded_content_length => $decoded_length,
   );
   # send $r->{headers}, then the body, made of encoded chunks:
   my $ck = $r->{chunker};
   print {$socket} $ck->chunk($_) for @chunks;
   print {$socket} $ck->finish;

Trailers, i.e. headers sent after the data, e.g. for a checksum that is
only known at the end, are declared with C<sign>, which adds the
C<x-amz-trailer> header (signed like the others):

=over

=item C<checksum>

the name of an algorithm that the chunker computes while the chunks go
through: C<crc32>, C<crc32c>, C<sha1> or C<sha256>. The trailer is
named after it (e.g. C<x-amz-checksum-crc32c>);

=item C<trailers>

array reference of names of trailers whose values you provide when
calling L</finish>, so that any other algorithm can be used, e.g.
C<x-amz-checksum-crc64nvme>.

=back

Unsigned streaming needs at least one trailer. The payload hash becomes
C<STREAMING-AWS4-HMAC-SHA256-PAYLOAD-TRAILER> or
C<STREAMING-UNSIGNED-PAYLOAD-TRAILER>, and with signed chunks the trailers
get their own signature.