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.