VM::EC...ntials(3pm)

💖 VM::EC2::Security::Credentials 💖

okay bestie so this is the manual page for VM::EC2::Security::Credentials, which lives in the VM::EC2::Security::Credentials family of Perl docs, and it's literally the whole vibe of "temporary security credentials for EC2." let's get into it 🦋

---

✨ NAME ✨

VM::EC2::Security::Credentials — Temporary security credentials for EC2 💅

---

🌸 SYNOPSIS 🌸

use VM::EC2;
use VM::EC2::Security::Policy

# under your account
$ec2 = VM::EC2->new(...);  # as usual
my $policy = VM::EC2::Security::Policy->new;
$policy->allow('DescribeImages','RunInstances');
my $token = $ec2->get_federation_token(-name     => 'TemporaryUser',
                                       -duration => 60*60*3, # 3 hrs, as seconds
                                       -policy   => $policy);
print $token->sessionToken,"\n";
print $token->accessKeyId,"\n";
print $token->secretAccessKey,"\n";
print $token->federatedUser,"\n";

my $serialized = $token->serialize;

# get the serialized token to the temporary user
send_data_to_user_somehow($serialized);

# under the temporary user's account
my $serialized = get_data_somehow();

# create a copy of the token from its serialized form
my $token = VM::EC2::Security::Credentials->new_from_serialized($serialized);

# create a copy of the token from its JSON representation (e.g. as returned
# from instance metadata of an instance that is assigned an IAM role
my $token = VM::EC2::Security::Credentials->new_from_json($json);

# open a new EC2 connection with this token. User will be
# able to run all the methods specified in the policy.
my $ec2   = VM::EC2->new(-security_token => $token);
print $ec2->describe_images(-owner=>'self');

# convenience routine; will return a VM::EC2 object authorized
# to use the current token
my $ec2   = $token->new_ec2;
print $ec2->describe_images(-owner=>'self');

---

👑 DESCRIPTION 👑

The VM::EC2::Security::Credentials object is what gets handed back to you by the VM::EC2::Security::Token->credentials() method — and that method is what gets generated when you call VM::EC2->get_federation_token() and VM::EC2->get_session_token(). no cap, it's all connected 🔥

So what's actually inside a Credentials object? Time-limited EC2 authentication info, periodt: your access key ID, your secret access key, and a temporary authentication session token. that's the whole squad right there ✨

You can pass a Credentials object straight into VM::EC2->new() via the -security_token parameter, and when you do that? You can just... not bother with -access_key and -secret_key. they can be omitted entirely, iconic behavior 💅

Now here's the thing — Credentials usually need to travel from a process run by an AWS account holder over to a process being run by another user. So the object comes with serialization methods that let it get transmitted as a simple string. like a little care package but make it auth 🎀

---

💜 DATA ACCESS METHODS 💜

accessKeyId()          -- The temporary access key ID
secretAccessKey()      -- The secret access key
sessionToken()         -- The temporary security token, as a long
                            opaque string
expiration()           -- The expiration time of these credentials, as a
                            DateTime string.

And listen — same as with every VM::EC2 class, mixedCase() and broken_out_with_underscores() names are interchangeable. use whichever one your brain vibes with 🧚

---

🦋 SERIALIZATION METHODS 🦋

These two methods let you serialize the credentials into a string that's suitable for sending over SSL, S/MIME, or honestly any other secure channel — and then reconstruct the object on the other end. 🫶

But what if you're sending credentials to a non-perl process? No stress, bestie — you can just grab each individual field (access key, etc.) and send them one by one.

$serialized = $credentials->serialize()

Returns a serialized form of the object as a base64-encoded string. ✨

⚠️ heads up though — the serialized form contains the secret access key and session token in unencrypted, but very slightly obfuscated, form. not encrypted. obfuscated. know the difference, bestie 😭

$credentials = VM::EC2::Security::Credentials->new_from_serialized($serialized)

Hand it a previously-serialized Credentials object and it'll unserialize it and return a copy. easy 💖

---

🎀 CONVENIENCE METHODS 🎀

These are convenience methods. (yes, that's the whole intro, they're literally just here to make your life easier 🌈)

$ec2 = $credentials->new_ec2(@args)

Creates a brand-new VM::EC2 object that's authorized using the security token sitting inside the credentials object. 🔥

You may pass all the arguments that VM::EC2->new() accepts — stuff like -endpoint — but -access_key and -secret_access_key will be ignored. periodt.

---

⭐ STRING OVERLOADING ⭐

When used in a string context, this object will interpolate the

---

🌈 SEE ALSO 🌈

• VM::EC2
• VM::EC2::Generic

---

💖 AUTHOR 💖

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

Copyright (c) 2011 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.

---

okay that's the whole page, bestie, you ate it 💅✨ this was perl v5.38.2, dated 2024-08-10, and it's giving VM::EC2::Security::Credentials energy forever and always 🦋👑💖