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 returned by the
VM::EC2::Security::Token->
credentials() method, which in turn is
generated by calls to VM::EC2->
get_federation_token() and
VM::EC2->
get_session_token(). The Credentials object contains
time-limited EC2 authentication information, including access key ID, secret
access key, and a temporary authentication session token.
A Credentials object can be passed to VM::EC2->
new() via the
-security_token parameter, in which case the -access_key and -secret_key
parameters can be omitted.
As Credentials typically need to be transmitted from a process being run by an
AWS account holder to a process being run by another user, the object provides
serialization methods that allow the object to be transmitted as a simple
string.
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.
As in all VM::EC2 classes,
mixedCase() and
broken_out_with_underscores() names may be used interchangeably.
SERIALIZATION METHODS¶
These two methods allow you to serialize the credentials into a string suitable
for sending via SSL, S/MIME or another secure channel, and then reconstructing
the object at the other end. For sending the credentials to a non-perl
process, you can simply retrieve each individual field (access key, etc) and
send them individually.
$serialized = $credentials-> serialize()¶
Return a serialized form of the object as a base64-encoded string. Note that the
serialized form contains the secret access key and session token in
unencrypted, but very slightly obfuscated, form.
$credentials = VM::EC2::Security::Credentials->new_from_serialized($serialized)¶
Given a previously-serialized Credentials object, unserialize it and return a
copy.
CONVENIENCE METHODS¶
These are convenience methods.
$ec2 = $credentials->new_ec2(@args)¶
Create a new VM::EC2 object which is authorized using the security token
contained in the credentials object. You may pass all the arguments, such as
-endpoint, that are accepted by VM::EC2->
new(), but -access_key and
-secret_access_key will be ignored.
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.