view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

    default: s3.amazonaws.com

    Note that requests are made to domain buckets when possible.  You can
    prevent that behavior if either the bucket name does not conform to
    DNS bucket naming conventions or you preface the bucket name with '/'
    or explicitly turn off domain buckets by setting `dns_bucket_names`
    to false.

    If you set a region then the host name will be modified accordingly if
    it is an Amazon endpoint.

- region

    The AWS region you where your bucket is located.

    default: us-east-1

- buffer\_size

    The default buffer size when reading or writing files.

    default: 4096

## signer

Sets or retrieves the signer object. API calls must be signed using
your AWS credentials. By default, starting with version 0.54 the
module will use [Net::Amazon::Signature::V4](https://metacpan.org/pod/Net%3A%3AAmazon%3A%3ASignature%3A%3AV4) as the signer and
instantiate a signer object in the constructor. Note however, that
signers need your credentials and they _will_ get stored by that
class, making them susceptible to inadvertant exfiltration. You have a
few options here:

- 1. Use your own signer.

    You may have noticed that you can also provide your own credentials
    object forcing this module to use your object for retrieving
    credentials. Likewise, you can use your own signer so that this
    module's signer never sees or stores those credentials.

- 2. Pass the credentials object and set `cache_signer` to a
false value.

    If you pass a credentials object and set `cache_signer` to a false
    value, the module will use the credentials object to retrieve
    credentials and create a new signer each time an API call is made that
    requires signing. This prevents your credentials from being stored
    inside of the signer class.

    _Note that using your own credentials object that stores your
    credentials in plaintext is also going to expose your credentials when
    someone dumps the class._

- 3. Pass credentials, set `cache_signer` to a false value.

    Unfortunately, while this will prevent [Net::Amazon::Signature::V4](https://metacpan.org/pod/Net%3A%3AAmazon%3A%3ASignature%3A%3AV4)
    from hanging on to your credentials, you credentials will be stored in
    the `Amazon::S3` object.

    Starting with version 0.55 of this module, if you have installed
    [Crypt::CBC](https://metacpan.org/pod/Crypt%3A%3ACBC) and [Crypt::Blowfish](https://metacpan.org/pod/Crypt%3A%3ABlowfish), your credentials will be
    encrypted using a random key created when the class is
    instantiated. While this is more secure than leaving them in
    plaintext, if the key is discovered (the key however is not stored in
    the object's hash) and the object is dumped, your _encrypted_
    credentials can be exposed.

- 4. Use very granular credentials for bucket access only.

    Use credentials that only allow access to a bucket or portions of a
    bucket required for your application. This will at least limit the
    _blast radius_ of any potential security breach.

- 5. Do nothing...send the credentials, use the default signer.

    In this case, both the `Amazon::S3` class and the
    [Net::Amazon::Signature::V4](https://metacpan.org/pod/Net%3A%3AAmazon%3A%3ASignature%3A%3AV4) have your credentials. Caveat Emptor.

    See also [Amazon::Credentials](https://metacpan.org/pod/Amazon%3A%3ACredentials) for more information about safely
    storing your credentials and preventing exfiltration.

## region

Sets the region for the API calls. This will also be the
default when instantiating the bucket object unless you pass the
region parameter in the `bucket` method or use the `verify_region`
flag that will _always_ verify the region of the bucket using the
`get_location_constraint` method.

default: us-east-1

## buckets

    buckets([verify-region])

- verify-region (optional)

    `verify-region` is a boolean value that indicates if the
    bucket's region should be verified when the bucket object is
    instantiated.

    If set to true, this method will call the `bucket` method with
    `verify_region` set to true causing the constructor to call the
    `get_location_constraint` for each bucket to set the bucket's
    region. This will cause a significant decrease in the peformance of
    the `buckets()` method. Setting the region for each bucket is
    necessary since API operations on buckets require the region of the
    bucket when signing API requests. If all of your buckets are in the
    same region and you have passed a region parameter to your S3 object,
    then that region will be used when calling the constructor of your
    bucket objects.

    default: false

Returns a reference to a hash containing the metadata for all of the
buckets owned by the accout or (see below) or `undef` on error.

- owner\_id

    The owner ID of the bucket's owner.