view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

        constructor determine the bucket's region for you by calling the
        `get_location_constraint()` method.

        When signing API calls, the region for the specific bucket will be
        used. For calls that are not regional (`buckets()`, e.g.) the default
        region ('us-east-1') will be used.

    - Signature Version 2

        [https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAuthentication.html)

- Multipart Upload Support

    There are some recently added unit tests for multipart uploads that
    seem to indicate this feature is working as expected.  Please report
    any deviation from expected results if you are using those methods.

    For more information regarding multipart uploads visit the link below.

    [https://docs.aws.amazon.com/AmazonS3/latest/API/API\_CreateMultipartUpload.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateMultipartUpload.html)

# METHODS AND SUBROUTINES

Unless otherwise noted methods will return an `undef` if an error
occurs.  You can get more information about the error by calling
`err()` and `errstr()`.

## new 

Create a new S3 client object. Takes some arguments:

- credentials (optional)

    Reference to a class (like `Amazon::Credentials`) that can provide
    credentials via the methods:

        get_aws_access_key_id()
        get_aws_secret_access_key()
        get_token()

    If you do not provide a credential class you must provide the keys
    when you instantiate the object. See below.

    _You are strongly encourage to use a class that provides getters. If
    you choose to provide your credentials to this class then they will be
    stored in this object. If you dump the class you will likely expose
    those credentials._

- aws\_access\_key\_id

    Use your Access Key ID as the value of the AWSAccessKeyId parameter
    in requests you send to Amazon Web Services (when required). Your
    Access Key ID identifies you as the party responsible for the
    request.

- aws\_secret\_access\_key 

    Since your Access Key ID is not encrypted in requests to AWS, it
    could be discovered and used by anyone. Services that are not free
    require you to provide additional information, a request signature,
    to verify that a request containing your unique Access Key ID could
    only have come from you.

    **DO NOT INCLUDE THIS IN SCRIPTS OR APPLICATIONS YOU
    DISTRIBUTE. YOU'LL BE SORRY.**

    _Consider using a credential class as described above to provide
    credentials, otherwise this class will store your credentials for
    signing the requests. If you dump this object to logs your credentials
    could be discovered._

- token

    An optional temporary token that will be inserted in the request along
    with your access and secret key.  A token is used in conjunction with
    temporary credentials when your EC2 instance has
    assumed a role and you've scraped the temporary credentials from
    _http://169.254.169.254/latest/meta-data/iam/security-credentials_

- secure

    Set this to a true value if you want to use SSL-encrypted connections
    when connecting to S3. Starting in version 0.49, the default is true.

    default: true

- timeout

    Defines the time, in seconds, your script should wait or a
    response before bailing.

    default: 30s

- retry

    Enables or disables the library to retry upon errors. This
    uses exponential backoff with retries after 1, 2, 4, 8, 16,
    32 seconds, as recommended by Amazon.

    default: off

- host

    Defines the S3 host endpoint to use.

    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

README.md  view on Meta::CPAN

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.

- owner\_display\_name

    The name of the owner account. 

- buckets

    An array of [Amazon::S3::Bucket](https://metacpan.org/pod/Amazon%3A%3AS3%3A%3ABucket) objects for the account. Returns
    `undef` if there are not buckets or an error occurs.

## add\_bucket

    add_bucket(bucket-configuration)

`bucket-configuration` is a reference to a hash with bucket
configuration parameters.

_Note that since April of 2023, new buckets are created that block
public access by default. If you attempt to set an ACL with public
permissions the create operation will fail. To create a public bucket
you must first create the bucket with private permissions, remove the
public block and subsequently apply public permissions._

See ["delete\_public\_access\_block"](#delete_public_access_block).

- bucket

    The name of the bucket. See [Bucket name
    rules](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucketnamingrules.html)
    for more details on bucket naming rules.

- acl\_short (optional)

    See the set\_acl subroutine for documenation on the acl\_short
    options. Note that starting in April of 2023 new buckets are
    configured to automatically block public access. Trying to create a
    bucket with public permissions will fail. In order to create a public
    bucket you must first create a private bucket, then call the
    DeletePublicAccessBlock API. You can then set public permissions for
    your bucket using ACLs or a bucket policy.

- location\_constraint
- region

    The region the bucket is to be created in.

- headers

    Additional headers to send with request.

Returns a [Amazon::S3::Bucket](https://metacpan.org/pod/Amazon%3A%3AS3%3A%3ABucket) object on success or `undef` on failure.

## bucket

    bucket(bucket, [region])

    bucket({ bucket => bucket-name, verify_region => boolean, region => region });

Takes a scalar argument or refernce to a hash of arguments.

You can pass the region or set `verify_region` indicating that
you want the bucket constructor to detemine the bucket region.

If you do not pass the region or set the `verify_region` value, the
region will be set to the default region set in your `Amazon::S3`
object.

See [Amazon::S3::Bucket](https://metacpan.org/pod/Amazon%3A%3AS3%3A%3ABucket) for a complete description of the `bucket`
method.

## delete\_bucket

Takes either a [Amazon::S3::Bucket](https://metacpan.org/pod/Amazon%3A%3AS3%3A%3ABucket) object or a reference to a hash
containing:

- bucket

    The name of the bucket to remove

- region

    Region the bucket is located in. If not provided, the method will
    determine the bucket's region by calling `get_bucket_location`.

Returns a boolean indicating the success or failure of the API
call. Check `err` or `errstr` for error messages.

Note from the [Amazon's documentation](https://docs.aws.amazon.com/AmazonS3/latest/userguide/BucketRestrictions.html)

> If a bucket is empty, you can delete it. After a bucket is deleted,
> the name becomes available for reuse. However, after you delete the
> bucket, you might not be able to reuse the name for various reasons.
>
> For example, when you delete the bucket and the name becomes available
> for reuse, another AWS account might create a bucket with that
> name. In addition, **some time might pass before you can reuse the name
> of a deleted bucket**. If you want to use the same bucket name, we
> recommend that you don't delete the bucket.

## delete\_public\_access\_block

    delete_public_access_block(bucket-obj)

Removes the public access block flag for the bucket.

## dns\_bucket\_names

Set or get a boolean that indicates whether to use DNS bucket
names.

default: true

## err

Returns the last error. Usually this is the error code returned from
an API call or a short message that the describes the error. Use
`errstr` for a more descriptive explanation of the error condition.

## errstr

Detailed error description.

## list\_bucket, list\_bucket\_v2