AWS-Signature-V4
view release on metacpan or search on metacpan
lib/AWS/Signature/V4.pod view on Meta::CPAN
only for encrypted keys. Like C<private_key>, it is not kept once the key
is loaded;
=item C<signer>
alternative to the keys: a function that gets the bytes to sign and
returns the signature of their SHA-256, as raw bytes: PKCS#1 v1.5 for
RSA and DER for ECDSA (e.g. to delegate to an HSM or a KMS). Decode it
first if your HSM or KMS gives it in base64 or hex: the returned bytes are
put in the request as they are, hex-encoded, and AWS would just refuse a
signature in the wrong form. It takes precedence over
the keys. If it returns C<undef>, an empty string, a reference or a string
with wide characters, signing fails with an L<Ouch> exception with code
C<400>; if it dies, the error goes through as it is.
=back
=item C<double_encode>, C<normalize_path>, C<payload_header>
boolean overrides for what is decided from the service: encode the
path twice, remove empty, C<.> and C<..> segments from it, and always
add the C<x-amz-content-sha256> header. They default to true, true, false
for every service but S3, where they are false, false, true. S3 goes by
several names: C<s3>, C<s3-object-lambda>, C<s3-outposts> and
C<s3express>.
Again, setting an C<undef> value for these three arguments does I<NOT>
mean I<false> but I<default> instead (i.e. false, false, and true).
C<payload_header> also tells L</presign> what the service takes for
granted in a presigned URL: C<UNSIGNED-PAYLOAD> if true, as S3 does, the
hash of the body it gets otherwise.
=back
=head2 algorithm
my $name = $s->algorithm;
The name of the signing algorithm in use, e.g. C<AWS4-HMAC-SHA256>.
=head2 sign
my $r = $s->sign(%args);
my $r = $s->sign(\%args);
Sign a request. The arguments are name/value pairs or a hash reference;
an unknown name, or one that does not apply (e.g. C<expires>, which is
for L</presign>), is an error, and an C<undef> value is the same as a
missing argument. Named arguments:
=over
=item C<method>, C<url>
the HTTP method and the full URL (mandatory). The method must be an HTTP
token, and it is uppercased. The host, lowercased and without default
ports, provides the C<host> header unless it is given; user information
(C<user@host>) is an error, it is not stripped.
The URL can also be just a path, starting with C</>, if a C<Host> header
is given. See L</DESCRIPTION> and L</SECURITY CONSIDERATIONS> for what
the URL can hold; in particular, the query cannot hold C<+>, which some
read as a space and others as a plus sign: write C<%20> or C<%2B>;
=item C<headers>
the headers of the request, as a hash reference or an array reference of
pairs. A value is a byte string, or an array reference of them, and
repeated names are joined with a comma; C<undef> values are skipped.
Names must be HTTP tokens (RFC 9110: letters, digits and
C<!#$%&'*+-.^_`|~>) and values cannot hold CR, LF or NUL characters:
anything else is an error, as it could inject headers or change the
meaning of the canonical request. The same check applies to the values
that C<sign> adds, e.g. the session token, and to the ones that
L</presign> puts in the query string instead.
An C<X-Amz-Content-Sha256> header is taken as the payload hash; if the
payload hash also comes from the arguments below, the two must agree;
=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
( run in 0.710 second using v1.01-cache-2.11-cpan-234fa220139 )