AWS::Signature4(3pm)

✨ AWS::Signature4 ✨

okay bestie, so this is AWS::Signature4 — it's a Perl module from the User Contributed Perl Documentation, and it does exactly one iconic thing: it makes Signature Version 4 signatures for Amazon Web Services. yes. that thing every AWS SDK does for you but here you're doing it by hand like a crafting influencer 💅

---

💖 NAME 💖

AWS::Signature4 — create a version4 signature for Amazon Web Services. that's it, that's the whole job, and it eats every time 🔥

---

🎀 SYNOPSIS 🎀

here's the whole vibe in code, look at her:

use AWS::Signature4;
use HTTP::Request::Common;
use LWP;

my $signer = AWS::Signature4->new(-access_key => 'AKIDEXAMPLE',
                                  -secret_key => 'wJalrXUtnFEMI/K7MDENG+bPxRfiCYEXAMPLEKEY');
my $ua     = LWP::UserAgent->new();

# Example POST request
my $request = POST('https://iam.amazonaws.com',
                   [Action=>'ListUsers',
                    Version=>'2010-05-08']);
$signer->sign($request);
my $response = $ua->request($request);

# Example GET request
my $uri     = URI->new('https://iam.amazonaws.com');
$uri->query_form(Action=>'ListUsers',
                 Version=>'2010-05-08');

my $url = $signer->signed_url($uri); # This gives a signed URL that can be fetched by a browser
my $response = $ua->get($url);

like. a POST, a GET, both signed, both slaying. 🌸

---

🌈 DESCRIPTION 🌈

this module implements Amazon Web Service's Signature version 4 (http://docs.aws.amazon.com/general/latest/gr/signature-version-4.html). no cap, that's the entire concept. 💖

---

👑 METHODS 👑

🫶 $signer = AWS::Signature4->new(-access_key => $account_id,-secret_key => $private_key);

make yourself a signing object using your AWS account ID and your secret key. you can also roll with the temporary security tokens you get from Amazon's STS service — either by passing in the access key and secret key that came from that token, or by handing over a VM::EC2::Security::Token object that the VM::EC2 module produced. flexible queen energy ✨

Arguments, and bestie I need you to actually read these:

• -access_key — an AWS access key (your account ID)
• -secret_key — an AWS secret key
• -security_token — a VM::EC2::Security::Token object

🚨 IMPORTANT: if you pass a security token, it overrides whatever you gave for -access_key or -secret_key. it doesn't merge, it doesn't negotiate, it just wins. periodt.

and listen — if the environment variables EC2_ACCESS_KEY and/or EC2_SECRET_KEY are set, their contents get used as the defaults for -access_key and -secret_key. so like, ambient credentials, cute. 💜

---

🔥 $signer->sign($request [,$region] [,$payload_sha256_hex])

hand this method an HTTP::Request object and it will add all the headers AWS is asking for, then sign it with a version 4 signature by adding an "Authorization" header. she does the whole thing for you. 💅

the request must include a URL that the AWS endpoint and service can be derived from — something like "ec2.us-east-1.amazonaws.com." 🌐

but here's the tea 🍓: sometimes (hello, S3 bucket operations) the endpoint does not tell you the region. in that case you force it by passing a defined value for $region. the current date and time get added to the request via an "X-Amz-Date header." and if you want to freeze the date and time at a fixed value instead, just include the "Date" header yourself in the request.

the request content — aka the payload — gets pulled from the HTTP::Request object by calling its content() method. but 😭 under some circumstances the payload isn't sitting directly in the request at all, it's in an external file that gets uploaded when the request actually executes. in that specific case you must pass a second argument containing the results of running sha256_hex() (from the Digest::SHA module) on the content.

returns a true value if it worked ✅. on errors it throws an exception 💀. no silent failure, she's honest.

---

⭐ $url = $signer->signed_url($request)

this generates a signed GET URL for the request. the URL will include everything needed to actually perform the request. everything. she's not gatekeeping. 🎀

---

💖 my $url $signer->signed_url($request_or_uri [,$expires])

pass in an HTTP::Request, a URI object, or just a plain URL string that contains the proper endpoint and parameters for an AWS REST API Call. what comes back is an appropriately signed request as a URI object — which means you can literally share it with non-AWS users for stuff like accessing an object in a private S3 bucket. bestie-friendly URLs, we love to see it 🫶

and there's an optional $expires argument: pass it to say the URL is only valid for a finite period of time. the value is in seconds. ⏳

---

🌸 $signing_key = AWS::Signature4->signing_key($secret_access_key,$service_name,$region,$date)

returns just the signing key, in case you want to roll your own signature. main character DIY moment. you do you, queen 👑

---

🦋 SEE ALSO 🦋

• VM::EC2

go look at her, she's the sibling module 💜

---

💀 AUTHOR 💀

Lincoln Stein <lincoln.stein@gmail.com>.

Copyright (c) 2014 Ontario Institute for Cancer Research

This package and its accompanying libraries is free software; you can redistribute it and/or modify it under the terms of the GPL (either version 1, or at your option, any later version) or the Artistic License 2.0. Refer to LICENSE for the full license text. In addition, please see DISCLAIMER.txt for disclaimers of warranty. ⚖️

---

and that's the whole page, bestie, we're done here. this was perl v5.36.0, dated 2022-10-13 — shoutout to that build, and shoutout to AWS::Signature4(3pm) for never once making us sign anything by hand. mwah. 💋✨