AWS-Signature-V4
view release on metacpan or search on metacpan
the private key, either as the path of a file or as its content, in
PEM or DER format (as understood by CryptX). private_key wins if
both are given;
private_key_password
only for encrypted keys. Like private_key, it is not kept once the
key is loaded;
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 undef, an empty string, a
reference or a string with wide characters, signing fails with an
Ouch exception with code 400; if it dies, the error goes through as
it is.
double_encode, normalize_path, payload_header
boolean overrides for what is decided from the service: encode the
path twice, remove empty, . and .. segments from it, and always add
the 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: s3, s3-object-lambda, s3-outposts and s3express.
Again, setting an undef value for these three arguments does NOT mean
false but default instead (i.e. false, false, and true).
payload_header also tells "presign" what the service takes for
granted in a presigned URL: UNSIGNED-PAYLOAD if true, as S3 does, the
hash of the body it gets otherwise.
algorithm
my $name = $s->algorithm;
The name of the signing algorithm in use, e.g. AWS4-HMAC-SHA256.
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. expires, which is for
"presign"), is an error, and an undef value is the same as a missing
argument. Named arguments:
method, 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 host header unless it is given; user
information (user@host) is an error, it is not stripped. The URL can
also be just a path, starting with /, if a Host header is given. See
"DESCRIPTION" and "SECURITY CONSIDERATIONS" for what the URL can
hold; in particular, the query cannot hold +, which some read as a
space and others as a plus sign: write %20 or %2B;
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; undef values are skipped.
Names must be HTTP tokens (RFC 9110: letters, digits and
!#$%&'*+-.^_`|~) 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 sign adds, e.g. the session token, and to the ones that
"presign" puts in the query string instead.
An 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;
body, 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 :encoding or
:crlf that change the bytes read. Only one of them can be used;
payload_hash, unsigned_payload
skip the calculation and use the provided SHA-256 in hex, or
UNSIGNED-PAYLOAD. They take precedence over body and body_fh.
payload_hash can also be a STREAMING-* marker, anything else is an
error. When the payload hash is not a SHA-256, the
x-amz-content-sha256 header carries it, whatever the service;
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. user-agent) or that are meant for a single hop (e.g.
keep-alive). host and all the x-amz-* headers, including those that
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;
time
the epoch to sign for, in seconds (a fractional part is dropped),
defaults to now;
streaming, decoded_content_length, checksum, trailers
chunked and streaming uploads, see below.
The returned hash reference contains:
headers
the complete set of headers to send, with lowercase names. Beyond
( run in 0.605 second using v1.01-cache-2.11-cpan-234fa220139 )