blib/lib/AWS/Signature/V4.pm untested

filter: Statementstmt 0.0% 0 / 374 Branchbran 0.0% 0 / 196 Conditioncond 0.0% 0 / 197 MC/DCmcdc 0.0% 0 / 118 Subroutinesub 0.0% 0 / 53 Podpod 0.0% 0 / 40 totaltotal 0.0% 0 / 978 CC 99 SCAR 42.8
CC
99
Cov
0%
sign
272.0
encoded_length
210.0
_split_url
110.0
CRAP 72.4
1 package AWS::Signature::V4;
2 { our $VERSION = '0.003' }
3  
4 use v5.24;
5 use Moo;
6 use experimental qw< signatures >;
7 use Digest::SHA qw< sha256_hex >;
8 use POSIX qw< strftime >;
9 use Scalar::Util qw< openhandle >;
10  
11 use AWS::Signature::V4::Error qw< fail shown >;
12 use AWS::Signature::V4::Checksum ();
13 use AWS::Signature::V4::Chunker ();
14 use AWS::Signature::V4::Credentials ();
15 use AWS::Signature::V4::X509 ();
16  
17 use constant {
18  
19 # Headers that intermediaries commonly rewrite or that should never be
20 # signed
21 AUTH_PARAM => +{
22 map { lc($_) => $_ } qw<
23 X-Amz-Algorithm
24 X-Amz-Credential
25 X-Amz-Date
26 X-Amz-Expires
27 X-Amz-Security-Token
28 X-Amz-Signature
29 X-Amz-SignedHeaders
30 X-Amz-X509
31 X-Amz-X509-Chain
32 >
33 },
34  
35 # Headers that intermediaries commonly rewrite or that should never be
36 # signed
37 UNSIGNED => +{
38 map { lc($_) => 1 } qw<
39 Authorization
40 Connection
41 Expect
42 Keep-Alive
43 Proxy-Authenticate
44 Proxy-Authorization
45 Proxy-Connection
46 TE
47 Trailer
48 Transfer-Encoding
49 Upgrade
50 User-Agent
51 X-Amzn-Trace-Id
52 >
53 },
54  
55 # the arguments of some methods; anything else is an error
56 ALLOWED_ARGS => +{
57 encoded_length => +{
58 map { $_ => 1 } qw<
59 checksum
60 signed
61 trailers
62 >
63 },
64  
65 sign => +{
66 map { $_ => 1 } qw<
67 body
68 body_fh
69 checksum
70 decoded_content_length
71 headers
72 method
73 payload_hash
74 signed_headers
75 streaming
76 time
77 trailers
78 unsigned_payload
79 url
80 >
81 },
82  
83 presign => +{
84 map { $_ => 1 } qw<
85 body
86 body_fh
87 expires
88 headers
89 method
90 payload_hash
91 signed_headers
92 time
93 unsigned_payload
94 url
95 >
96 },
97  
98 payload => [ qw< body body_fh payload_hash unsigned_payload > ],
99 streaming => [ qw< decoded_content_length checksum trailers > ],
100 },
101  
102 MAX_EPOCH => 253402300799, # 9999-12-31T23:59:59Z
103 };
104  
105 sub _copy ($value) { ref $value eq 'HASH' ? {$value->%*} : $value }
106  
107 sub _hash_or_undef ($name, $value) {
108 fail 400, qq{"$name" must be a hash reference}
109 unless !defined $value || ref $value eq 'HASH';
110 }
111  
112 # arguments of sign/presign as a hash: name => value pairs or a hash
113 # reference; undefined values are like missing ones, unknown names an error
114 sub _args ($what, @args) {
115 @args = $args[0]->%* if @args == 1 && ref $args[0] eq 'HASH';
116 fail 400, "$what takes name => value pairs or a hash reference" if @args % 2;
117 my %args = @args;
118 defined $args{$_} or delete $args{$_} for keys %args;
119  
120 # go looking for argument names that are outside the allowed ones
121 my $allowed = ALLOWED_ARGS->{$what}
122 or die "ALLOWED_ARGS does not support <$what>";
123 if (my @l = grep { ! $allowed->{$_} } keys(%args)) {
124 fail 400, "unsupported for $what: " . _shown_list(@l);
125 }
126 return %args;
127 }
128  
129 sub _check_url ($url) {
130 defined $url or fail 400, 'missing parameter "url"';
131 fail 400, 'url must be a string' if ref $url;
132 fail 400, 'url must be ASCII: percent-encode non-ASCII characters'
133 if $url =~ m{[^\x00-\x7F]};
134 fail 400, 'url must not contain control characters: percent-encode them'
135 if $url =~ m{[\x00-\x1F\x7F]};
136 return $url;
137 }
138  
139 # an HTTP token (RFC 9110), like header names and methods
140 sub _is_token ($s) {
141 defined $s && !ref $s && $s =~ m{\A[!#\$%&'*+.^_`|~0-9A-Za-z-]+\z};
142 }
143  
144 sub _method ($method) {
145 fail 400, 'invalid method ' . shown($method) . ': it must be an HTTP token'
146 unless _is_token($method);
147 return uc $method;
148 }
149  
150 sub _is_count ($n) {
151 defined $n && !ref $n && $n =~ m{\A (?: 0 | [1-9][0-9]* ) \z}mxs;
152 }
153  
154 # headers as a hash or array of pairs, to a hash with lowercase names;
155 # undefined values are skipped, like missing headers
156 sub _headers_hash ($in) {
157 my @pairs;
158 if (ref $in eq 'HASH') {
159 @pairs = map { $_ => $in->{$_} } sort keys $in->%*; # repeatable order
160 }
161 elsif (ref $in eq 'ARRAY') {
162 fail 400, '"headers" as an array reference must hold name => value pairs'
163 if $in->@* % 2;
164 @pairs = $in->@*;
165 }
166 elsif (defined $in) {
167 fail 400, '"headers" must be a hash or array reference';
168 }
169 my %h;
170 while (my ($k, $v) = splice @pairs, 0, 2) {
171 _check_header_name($k);
172 my @values = grep { defined } ref $v eq 'ARRAY' ? $v->@* : $v;
173 _check_header_value($k, $_) for @values;
174 next unless @values;
175 $v = join ',', @values;
176 $k = lc $k;
177 $h{$k} = exists $h{$k} ? "$h{$k},$v" : $v;
178 }
179 return %h;
180 }
181  
182 # so that it cannot change the canonical request
183 sub _check_header_name ($name) {
184 fail 400, 'invalid header name ' . shown($name) unless _is_token($name);
185 }
186  
187 # what is wrong with a value that gets signed, if anything: CR, LF and NUL
188 # would forge lines in the canonical request, and a character beyond a byte
189 # cannot go on the wire (in a query string _uri_encode would turn it into an
190 # invalid percent escape, silently mangling e.g. a session token)
191 sub _bad_value ($value) {
192 return 'no CR, LF or NUL' if $value =~ m{[\r\n\0]};
193 return 'a byte string, encode characters first' if $value =~ m{[^\x00-\xFF]};
194 return undef;
195 }
196  
197 # so that it cannot inject headers or lines in the canonical request
198 sub _check_header_value ($name, $value) {
199 my $invalid = ref $value ? 'a string or an array reference of strings'
200 : _bad_value($value) // return;
201 fail 400, 'invalid value for header ' . shown($name) . ": $invalid";
202 }
203  
204 # the same, for what presign signs into the query string instead of headers
205 sub _check_query_values (@pairs) {
206 while (my ($name, $value) = splice @pairs, 0, 2) {
207 my $invalid = ref $value ? 'a string' : _bad_value($value // '') // next;
208 fail 400, 'invalid value for query parameter ' . shown($name) . ": $invalid";
209 }
210 }
211  
212 # all the headers to send, including those that the module adds itself
213 sub _check_header_values ($h) {
214 _check_header_value($_, $h->{$_}) for sort keys $h->%*;
215 }
216  
217 # sorted, lowercase names of the headers to sign. Always included: host, all
218 # the x-amz-* headers (AWS wants them signed) and the names in @also
219 sub _signed_headers ($h, $names, @also) {
220 fail 400, '"signed_headers" must be an array reference' unless ref $names eq 'ARRAY';
221 my %signed = map { $_ => 1 } 'host', @also, grep { m{\Ax-amz-} } keys $h->%*;
222 for my $name ($names->@*) {
223 _check_header_name($name);
224 $signed{lc $name} = 1;
225 }
226 for my $name (sort keys %signed) {
227 fail 400, 'cannot sign missing header ' . shown($name) unless exists $h->{$name};
228 }
229 return sort keys %signed;
230 }
231  
232 sub _is_sha256 ($hash) { $hash =~ m{\A[0-9a-f]{64}\z}mxs }
233  
234 # a hex SHA-256 (lowercased), UNSIGNED-PAYLOAD or a STREAMING-* marker
235 sub _check_payload_hash ($what, $value) {
236 if (!ref $value) {
237 return lc $value if $value =~ m{\A[0-9A-Fa-f]{64}\z};
238 return $value if $value =~ m{\A(?:UNSIGNED-PAYLOAD|STREAMING-[A-Z0-9-]+)\z};
239 }
240 fail 400, "$what must be a SHA-256 in hex, UNSIGNED-PAYLOAD or a STREAMING-* marker";
241 }
242  
243 # the payload hash in the x-amz-content-sha256 header provided by the
244 # caller, if any; it is put back later, when needed
245 sub _given_payload_hash ($h) {
246 my $given = delete $h->{'x-amz-content-sha256'} // return undef;
247 return _check_payload_hash('the x-amz-content-sha256 header', $given);
248 }
249  
250 # payload hash from the arguments, undef if they say nothing about it
251 sub _payload_hash ($args) {
252 return _check_payload_hash('"payload_hash"', $args->{payload_hash})
253 if defined $args->{payload_hash};
254 return 'UNSIGNED-PAYLOAD' if $args->{unsigned_payload};
255 return _body_hash($args);
256 }
257  
258 # the payload hash from the arguments and the one in the header must agree;
259 # the default applies if there is neither
260 sub _agree ($from_args, $given, $default) {
261 return $from_args // $default unless defined $given;
262 fail 400, 'the x-amz-content-sha256 header does not match the payload'
263 if defined $from_args && $from_args ne $given;
264 return $given;
265 }
266  
267 # hex SHA-256 of the "body" or "body_fh" argument, undef if none is given
268 sub _body_hash ($args) {
269 my $fh = $args->{body_fh};
270 fail 400, 'give either "body" or "body_fh", not both'
271 if defined $fh && defined $args->{body};
272 return _fh_hash($fh) if defined $fh;
273 return undef unless defined $args->{body};
274  
275 # the hash must match what goes on the wire, so no characters allowed;
276 # a copy is made only for internally-UTF-8 strings, never modify input
277 my $ref = _body_ref($args);
278 return sha256_hex($$ref // '') unless utf8::is_utf8($$ref);
279 my $copy = $$ref;
280 utf8::downgrade($copy, 1)
281 or fail 400, 'body must be a byte string: encode characters first';
282 return sha256_hex($copy);
283 }
284  
285 # the handle is hashed from where it is to its end, then put back there
286 sub _fh_hash ($fh) {
287 openhandle($fh) or fail 400, '"body_fh" must be an open filehandle';
288 fail 400, '"body_fh" must be a binary handle: binmode it'
289 if grep { m{\A(?:encoding|utf8|crlf)} } PerlIO::get_layers($fh);
290 my $pos = tell $fh;
291 fail 400, '"body_fh" must be seekable (a file, not a pipe or a socket)'
292 unless $pos >= 0 && seek $fh, $pos, 0;
293 my $sha = Digest::SHA->new(256);
294 eval { $sha->addfile($fh); 1 } or fail 400, qq{"body_fh" cannot be read: $!};
295 seek $fh, $pos, 0 or fail 400, qq{"body_fh" cannot be put back where it was: $!};
296 return $sha->hexdigest;
297 }
298  
299 # names of the trailers: built-in checksum first, then the declared ones
300 sub _trailer_names ($args) {
301 my @names;
302 if (defined(my $algo = $args->{checksum})) {
303 fail 400, 'unknown checksum ' . shown($algo) . ' (supported: '
304 . join(', ', AWS::Signature::V4::Checksum->supported_algorithms) . ')'
305 unless AWS::Signature::V4::Checksum->is_supported_algorithm($algo);
306 push @names, "x-amz-checksum-$algo";
307 }
308 my $trailers = $args->{trailers} // [];
309 fail 400, '"trailers" must be an array reference' unless ref $trailers eq 'ARRAY';
310 for my $name (map { lc($_ // '') } $trailers->@*) {
311 _check_trailer_name($name);
312 fail 400, "trailer '$name' declared twice" if grep { $_ eq $name } @names;
313 push @names, $name;
314 }
315 return @names;
316 }
317  
318 sub _check_trailer_name ($name) {
319 fail 400, 'invalid trailer name ' . shown($name) unless $name =~ m{\A[a-z0-9][a-z0-9-]*\z};
320 }
321  
322 sub _canonical_query ($query) {
323 return '' unless defined $query && length $query;
324 my @pairs = map {
325 my ($k, $v) = split /=/, $_, 2;
326 [_uri_encode(_uri_decode($k)), _uri_encode(_uri_decode($v // ''))];
327 } grep { length } split /&/, $query;
328 return join '&', map { "$_->[0]=$_->[1]" }
329 sort { $a->[0] cmp $b->[0] || $a->[1] cmp $b->[1] } @pairs;
330 }
331  
332 sub _uri_encode ($s) {
333 $s =~ s{([^A-Za-z0-9\-_.~])}{sprintf '%%%02X', ord $1}gmse;
334 return $s;
335 }
336  
337 sub _uri_decode ($s) {
338 $s =~ s{%([0-9A-Fa-f]{2})}{chr hex $1}gse;
339 return $s;
340 }
341  
342 # body is either a plain scalar or a reference to one; only in the latter
343 # case the caller's data is not copied at all
344 sub _body_ref ($args) {
345 my $body = $args->{body};
346 return \$args->{body} unless ref $body;
347 fail 400, 'body must be a scalar or a reference to a scalar'
348 unless ref($body) eq 'SCALAR';
349 return $body;
350 }
351  
352 # AWS trims and collapses spaces, so ASCII whitespace only (/a): with
353 # unicode_strings, \s would also take the bytes 0xA0 and 0x85 of UTF-8 text
354 sub _trim ($v) {
355 $v =~ s{\A\s+|\s+\z}{}gmxa; # remove leading/trailing whitespaces
356 $v =~ s{\s+}{ }gas; # normalize internal whitespaces
357 return $v;
358 }
359  
360 # (host, path, query) of a url; the host is lowercased and the port is
361 # removed if it is the default one, as user agents do before sending it
362 sub _split_url ($url) {
363 # every part is optional, so this always matches
364 my ($scheme, $auth, $path, $query) =
365 $url =~ m{\A (?: ([A-Za-z][A-Za-z0-9+.-]*) :// ([^/?\#]*) )?
366 ([^?\#]*) (?: \? ([^\#]*) )? }x;
367 fail 400, 'url path must start with "/": give an absolute url, or a path with a Host header'
368 if length $path && $path !~ m{\A/};
369 fail 400, 'url query must not contain "+": write %20 for a space, %2B for a plus sign'
370 if defined $query && $query =~ m{\+};
371 return (undef, $path, $query) unless defined $auth && length $auth;
372  
373 fail 400, 'url must not have user information (user@host)' if $auth =~ m{@};
374 my ($host, $port) = $auth =~ m{\A
375 (\[[0-9A-Fa-f:.]+\] | [A-Za-z0-9._~-]+) # host
376 (?: : ([0-9]*) )? # optional port
377 \z}x or fail 400, 'invalid url: ' . shown($auth);
378 $host = lc $host;
379 if (length($port // '')) {
380 $port += 0;
381 fail 400, "invalid port: $port" if $port < 1 || $port > 65535;
382 my $lcscheme = lc($scheme);
383 my $default = $lcscheme eq 'https' ? 443
384 : $lcscheme eq 'http' ? 80
385 : 0;
386 $host .= ':' . $port if $port != $default;
387 }
388 return ($host, $path, $query);
389 }
390  
391 sub _shown_list (@list) {
392 return join ', ',
393 map { join '', q{"}, shown($_), q{"} }
394 sort { $a cmp $b } @list;
395 }
396  
397  
398 use namespace::clean; # imported or plain functions must not become methods
399  
400  
401 has service => (is => 'ro');
402 has region => (is => 'ro');
403  
404 # credentials: {access_key_id, secret_access_key, session_token?}
405 has credentials => (is => 'ro', coerce => \&_copy, isa => sub { _hash_or_undef(credentials => @_) });
406  
407 # Certificate-based variant, as used by IAM Roles Anywhere.
408 # certificate / certificate_file: PEM or DER text, or path of a file with it
409 # chain / chain_files: optional arrayref of PEM/DER intermediate certificates,
410 # or of paths of files with them; a PEM item can be a bundle.
411 # chain can also be a plain string: a PEM-encoded bundle, and
412 # chain_files a plain string: the path of one file
413 # key_type: 'RSA' or 'ECDSA'
414 # signer: sub ($bytes_to_sign) -> signature (DER for ECDSA, PKCS#1 v1.5
415 # for RSA), computed with SHA-256; or, alternatively,
416 # private_key_file / private_key: PEM or DER key (path or content), signed
417 # with CryptX; private_key_password if it is encrypted
418 has x509 => (is => 'ro', coerce => \&_copy, isa => sub { _hash_or_undef(x509 => @_) });
419  
420 # S3 is the odd one out: this is the only place that knows how to tell. S3
421 # Object Lambda, S3 on Outposts and S3 Express sign with names of their own,
422 # under the same rules.
423 has _is_s3 => (is => 'lazy', init_arg => undef);
424 sub _build__is_s3 ($self) { $self->service =~ m{\As3(?:-object-lambda|-outposts|express)?\z} }
425  
426 has double_encode => (is => 'ro', lazy => 1, default => sub ($self) { !$self->_is_s3 });
427 has normalize_path => (is => 'ro', lazy => 1, default => sub ($self) { !$self->_is_s3 });
428 has payload_header => (is => 'ro', lazy => 1, default => sub ($self) { $self->_is_s3 });
429  
430 # FIXME review this decision: "undef" in Perl has a history of meaning
431 # "false" but here we're saying that it means "do the default".
432 # an undefined option is like a missing one: the default applies
433 around BUILDARGS => sub ($orig, $class, @args) {
434 my $args = $class->$orig(@args);
435 defined $args->{$_} or delete $args->{$_}
436 for qw< double_encode normalize_path payload_header >;
437 return $args;
438 };
439  
440 # The variant in use, credentials or x509, which knows how to sign and what
441 # goes with the request: see AWS::Signature::V4::Credentials and ::X509
442 has _auth => (is => 'lazy', init_arg => undef);
443  
444 sub BUILD ($self, $args) {
445 for my $name (qw< service region >) {
446 my $value = $self->$name;
447 defined($value) || fail 400, qq{missing parameter "$name"};
448 fail 400, qq{invalid "$name" } . shown($value)
449 . ': only letters, digits, ".", "_" and "-" are allowed'
450 unless $value =~ m{\A[-A-Za-z0-9._]+\z};
451 }
452  
453 # make sure the caller provides us *exactly* one of credentials/X509
454 my $x509_params = $self->x509;
455 my $credentials_params = $self->credentials;
456 fail 400, 'provide either "credentials" or "x509", not both'
457 if $credentials_params && $x509_params;
458 fail 400, 'provide (exactly) one of "credentials" or "x509"'
459 unless $credentials_params || $x509_params;
460  
461 $self->_auth; # force building and fail fast
462  
463 # after using the parameters, we get rid of sensitive data in the input
464 # hash for X509
465 delete($x509_params->{$_}) for qw< private_key private_key_password >;
466  
467 return;
468 }
469  
470 sub _build__auth ($self) {
471 return $self->credentials
472 ? AWS::Signature::V4::Credentials->new($self->credentials->%*)
473 : AWS::Signature::V4::X509->new($self->x509->%*);
474 }
475  
476 sub algorithm ($self) { $self->_auth->algorithm }
477  
478 # sign(method => ..., url => ..., headers => ..., body => ..., time => ...)
479 # Returns a hashref:
480 # headers: all headers to set on the request (name => value)
481 # including Authorization, X-Amz-Date, Host if missing...
482 # authorization: value of the Authorization header
483 # signature, canonical_request, string_to_sign, signed_headers, scope
484 sub sign ($self, @args) {
485 my %args = _args(sign => @args);
486  
487 # some arguments apply to the "payload" variant and some to the
488 # "streaming" variant only, we need some more input validation.
489 # $not_allowed below collects the name of the parameter that are not
490 # allowed for the variant that is requested.
491 my $streaming = $args{streaming};
492 my $not_allowed = ALLOWED_ARGS->{$streaming ? 'payload' : 'streaming'};
493 my @misplaced = grep { exists $args{$_} } $not_allowed->@*;
494 fail 400, qq{"$misplaced[0]" }
495 . ($streaming ? 'does not apply to streaming' : 'needs streaming')
496 if @misplaced;
497  
498 my $method = _method($args{method} // fail 400, 'missing parameter "method"');
499 my ($h, $path, $query, $amzdate, $scope) = $self->_request(\%args);
500 $h->{'x-amz-date'} = $amzdate;
501 my $given = _given_payload_hash($h);
502  
503 my ($unsigned_chunks, @trailer_names);
504 my $payload_hash;
505 if ($streaming) {
506 fail 400, 'streaming must be false, 1, "signed", or "unsigned"'
507 unless $streaming =~ m{\A(?:1|signed|unsigned)\z};
508 $unsigned_chunks = $streaming eq 'unsigned';
509 @trailer_names = _trailer_names(\%args);
510 fail 400, 'unsigned streaming needs "checksum" or "trailers"'
511 if $unsigned_chunks && !@trailer_names;
512 fail 400, 'signed streaming needs the credentials variant, not x509'
513 if !$unsigned_chunks && !$self->_auth->can_sign_chunks;
514 my $len = $args{decoded_content_length}
515 // fail 400, 'streaming needs "decoded_content_length"';
516 fail 400, 'decoded_content_length must be a non-negative integer'
517 unless $len =~ m{\A[0-9]+\z};
518 $payload_hash =
519 $unsigned_chunks ? 'STREAMING-UNSIGNED-PAYLOAD-TRAILER'
520 : @trailer_names ? 'STREAMING-AWS4-HMAC-SHA256-PAYLOAD-TRAILER'
521 : 'STREAMING-AWS4-HMAC-SHA256-PAYLOAD';
522 $h->{'x-amz-decoded-content-length'} = $len;
523 $h->{'x-amz-trailer'} = join ',', @trailer_names if @trailer_names;
524  
525 # whatever the caller has, e.g. gzip, then aws-chunked: RFC 9110 wants
526 # the encodings in the order they were applied, and this one is the
527 # outermost, applied to the already-gzipped data (as botocore does)
528 my @encodings = grep { length && lc($_) ne 'aws-chunked' }
529 map { _trim($_) } split m{,}, $h->{'content-encoding'} // '';
530 $h->{'content-encoding'} = join ',', @encodings, 'aws-chunked';
531 }
532 else {
533 $payload_hash = _payload_hash(\%args);
534 }
535 $payload_hash = _agree($payload_hash, $given, sha256_hex(''));
536 $h->{'x-amz-content-sha256'} = $payload_hash
537 if $self->payload_header || $streaming || defined $given || !_is_sha256($payload_hash);
538  
539 my %extra = $self->_auth->extra_fields;
540 $h->{lc $_} = $extra{$_} for keys %extra;
541 _check_header_values($h); # before they end up in the canonical request
542  
543 my @signed = _signed_headers($h, $args{signed_headers}
544 // [grep { ! UNSIGNED->{$_} } keys $h->%*], $streaming ? 'content-encoding' : ());
545 my $r = $self->_signed($method, $path, _canonical_query($query), $h,
546 \@signed, $payload_hash, $amzdate, $scope);
547  
548 my $credential = $self->_auth->credential_id . "/$scope";
549 $r->{authorization} = $self->algorithm . " Credential=$credential, "
550 . "SignedHeaders=$r->{signed_headers}, Signature=$r->{signature}";
551 _check_header_value(authorization => $r->{authorization});
552 $r->{headers} = {$h->%*, authorization => $r->{authorization}};
553  
554 $r->{chunker} = AWS::Signature::V4::Chunker->new(
555 ($unsigned_chunks ? () : (key => $self->_auth->signing_key($scope))),
556 signed => !$unsigned_chunks, amzdate => $amzdate,
557 scope => $scope, previous => $r->{signature},
558 expected => $args{decoded_content_length},
559 checksum => $args{checksum}, trailer_names => \@trailer_names,
560 ) if $streaming;
561 return $r;
562 }
563  
564 # presign(method => 'GET', url => ..., expires => 3600, time => ...)
565 # Returns a hashref:
566 # url: the URL, with the signature in its query string
567 # headers: headers that the client must send with it (Host, ...)
568 # signature, canonical_request, string_to_sign, signed_headers, scope
569 sub presign ($self, @args) {
570 my %args = _args(presign => @args);
571 my $method = _method($args{method} // 'GET');
572 my ($h, $path, $query, $amzdate, $scope) = $self->_request(\%args);
573  
574 my $expires = $args{expires} // 3600;
575 fail 400, 'expires must be an integer between 1 and 604800 seconds'
576 unless $expires =~ m{\A[0-9]+\z} && $expires >= 1 && $expires <= 604800;
577  
578 for my $pair (split m{&}, $query // '') {
579 my ($name) = split m{=}, $pair, 2;
580 my $known = AUTH_PARAM->{lc _uri_decode($name // '')} or next;
581 fail 400, "url already carries $known: presign adds it";
582 }
583  
584 # S3 takes UNSIGNED-PAYLOAD for granted in presigned URLs, the others the
585 # hash of the body they get: anything else needs the header, signed
586 my $given = _given_payload_hash($h);
587 my $payload_hash = _agree(_payload_hash(\%args), $given,
588 $self->payload_header ? 'UNSIGNED-PAYLOAD' : sha256_hex(''));
589 my $taken_for_granted = $self->payload_header
590 ? $payload_hash eq 'UNSIGNED-PAYLOAD' : _is_sha256($payload_hash);
591 $h->{'x-amz-content-sha256'} = $payload_hash
592 if defined $given || !$taken_for_granted;
593  
594 my @signed = _signed_headers($h, $args{signed_headers} // []);
595 _check_header_values($h);
596  
597 my @params = (
598 'X-Amz-Algorithm' => $self->algorithm,
599 'X-Amz-Credential' => $self->_auth->credential_id . "/$scope",
600 'X-Amz-Date' => $amzdate,
601 'X-Amz-Expires' => $expires,
602 'X-Amz-SignedHeaders' => join(';', @signed),
603 $self->_auth->extra_fields,
604 );
605 _check_query_values(@params);
606  
607 my @query = grep { length } $query // '';
608 while (my ($k, $v) = splice @params, 0, 2) {
609 push @query, _uri_encode($k) . '=' . _uri_encode($v);
610 }
611 my $canonical_query = _canonical_query(join '&', @query);
612  
613 my $r = $self->_signed($method, $path, $canonical_query, $h,
614 \@signed, $payload_hash, $amzdate, $scope);
615  
616 # whatever is not allowed in a URL path (e.g. a space) is percent-encoded
617 my ($prefix) = $args{url} =~ m{\A([^?\#]*)};
618 $prefix =~ s{([^A-Za-z0-9\-._~!\$&'()*+,;=:@/%\[\]])}{sprintf '%%%02X', ord $1}ge;
619 $r->{url} = "$prefix?$canonical_query&X-Amz-Signature=$r->{signature}";
620 $r->{headers} = $h;
621 return $r;
622 }
623  
624 # pieces of the request that sign and presign have in common: the headers
625 # (with host), the path and query from the url, the date and the scope
626 sub _request ($self, $args) {
627 my ($host, $path, $query) = _split_url(_check_url($args->{url}));
628 my %h = _headers_hash($args->{headers});
629 $h{host} //= $host;
630 length($h{host} // '')
631 or fail 400, 'url has no host: give an absolute url or a Host header';
632  
633 my $epoch = $args->{time} // time;
634 fail 400, 'time must be an epoch in seconds, e.g. from time()'
635 unless !ref $epoch && $epoch =~ m{\A[0-9]+(?:\.[0-9]*)?\z} && $epoch <= MAX_EPOCH;
636 my $amzdate = strftime('%Y%m%dT%H%M%SZ', gmtime int $epoch);
637 my $scope = join '/', substr($amzdate, 0, 8), $self->region, $self->service, 'aws4_request';
638 return (\%h, $path, $query, $amzdate, $scope);
639 }
640  
641 # canonical request, string to sign and signature, as returned to the caller
642 sub _signed ($self, $method, $path, $canonical_query, $h, $signed, $payload_hash, $amzdate, $scope) {
643 my $signed_headers = join ';', $signed->@*;
644 my $canonical_request = join "\n",
645 $method,
646 $self->_canonical_path($path),
647 $canonical_query,
648 join('', map { "$_:" . _trim($h->{$_}) . "\n" } $signed->@*), # ends with blank line
649 $signed_headers,
650 $payload_hash;
651 my $string_to_sign = join "\n",
652 $self->algorithm, $amzdate, $scope, sha256_hex($canonical_request);
653 return {
654 signature => $self->_auth->signature($scope, $string_to_sign),
655 signed_headers => $signed_headers,
656 scope => $scope,
657 canonical_request => $canonical_request,
658 string_to_sign => $string_to_sign,
659 };
660 }
661  
662 # size of an aws-chunked body: every chunk but the last one is $chunk_size
663 # signed => 1 (default) or 0, checksum => $algo, trailers => {name => length}
664 sub encoded_length ($class, $decoded, $chunk_size, @args) {
665 fail 400, 'the decoded size must be a non-negative integer'
666 unless _is_count($decoded);
667 fail 400, 'the chunk size must be a positive integer'
668 unless _is_count($chunk_size) && $chunk_size > 0;
669  
670 fail 400, 'encoded_length named options must be name => value pairs' if @args % 2;
671 my %opts = _args(encoded_length => @args);
672  
673 my $signed = exists($opts{signed}) ? ($opts{signed} || 0) : 1;
674 fail 400, 'signed must be false, 1, "signed", or "unsigned"'
675 if ref $signed || $signed !~ m{\A(?:1|0|signed|unsigned|)\z}mxs;
676 $signed = $signed eq '1' || $signed eq 'signed';
677  
678 my $trailer = 0; # sum of length of each trailer line "name:value\r\n"
679 my %seen; # catch duplicates
680 if (defined(my $algo = $opts{checksum})) {
681 my ($name) = _trailer_names({checksum => $algo});
682 $seen{$name} = 1;
683 $trailer += length($name) + 1 + AWS::Signature::V4::Checksum->encoded_size($algo) + 2;
684 }
685 my $declared = $opts{trailers} // {};
686 fail 400, '"trailers" must be a hash reference from names to lengths'
687 unless ref $declared eq 'HASH';
688 for my $given (sort keys $declared->%*) {
689 my $name = lc $given;
690 _check_trailer_name($name);
691 # sign() refuses the same repetition, so do not count a line twice
692 fail 400, "trailer '$name' declared twice" if $seen{$name}++;
693 fail 400, 'the length of trailer ' . shown($given) . ' must be a non-negative integer'
694 unless _is_count($declared->{$given});
695 $trailer += length($name) + 1 + $declared->{$given} + 2;
696 }
697  
698 my $chunk = sub ($size) { # everything around the data of a chunk
699 length(sprintf '%x', $size) + ($signed ? 17 + 64 : 0) + 2 + 2;
700 };
701 my $total = 0;
702 my $full = int($decoded / $chunk_size);
703 $total += $full * ($chunk->($chunk_size) + $chunk_size);
704 my $rest = $decoded - $full * $chunk_size;
705 $total += $chunk->($rest) + $rest if $rest;
706  
707 # final chunk: "0[;chunk-signature=..]\r\n", trailers, [signature line,] "\r\n"
708 $total += 1 + ($signed ? 17 + 64 : 0) + 2 + $trailer + 2;
709 $total += length('x-amz-trailer-signature') + 1 + 64 + 2 if $signed && $trailer;
710 return $total;
711 }
712  
713 # the path is empty or starts with "/", see _split_url
714 sub _canonical_path ($self, $path) {
715 $path = '/' unless length $path;
716 my $trailing = $path =~ m{/\z} && $path ne '/';
717 my @parts = split m{/}, $path, -1;
718 shift @parts; # leading empty item, before the first /
719 pop @parts if @parts && $parts[-1] eq ''; # trailing, re-added below
720  
721 if ($self->normalize_path) {
722 my @out;
723 for my $p (@parts) {
724 next if $p eq '' || $p eq '.';
725 if ($p eq '..') { pop @out; next }
726 # AWS might or might not take them as dot segments: refuse them
727 fail 400, 'url path has a percent-encoded dot segment ' . shown($p)
728 . ': write it as it is, or remove it'
729 if _uri_decode($p) =~ m{\A\.\.?\z};
730 push @out, $p;
731 }
732 @parts = @out;
733 }
734  
735 # incoming path is percent-encoded already: decode then encode once,
736 # and a second time for everything but S3
737 @parts = map {
738 my $e = _uri_encode(_uri_decode($_));
739 $e = _uri_encode($e) if $self->double_encode;
740 $e;
741 } @parts;
742 my $out = '/' . join '/', @parts;
743 $out .= '/' if $trailing && @parts;
744 return $out;
745 }
746  
747 1;