view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

Calculates and returns the AWS Signature Version 4 signing key through a series of HMAC-SHA256 operations.

### string_to_sign

Returns the AWS Signature Version 4 string to sign, in the format:

```
AWS4-HMAC-SHA256
DATE_TIMESTAMP
CREDENTIAL_SCOPE
HASHED_CANONICAL_REQUEST
```

Will warn debug information if `debug` is enabled.

### time

Returns the current time as a [Time::Piece](https://metacpan.org/pod/Time::Piece) object in UTC.

## Examples

### Basic S3 PUT Request

```perl
use Mojo::Base -strict;
use Mojo::UserAgent;

my $ua = Mojo::UserAgent->with_roles('+AWSSignature4')->new;

# With environment variables
$ENV{AWS_ACCESS_KEY} = 'your-access-key';
$ENV{AWS_SECRET_KEY} = 'your-secret-key';

my $url = 'https://my-bucket.s3.us-east-1.amazonaws.com/my-object.txt';
my $tx = $ua->put($url => awssig4 => {service => 's3'} => 'Hello World');
```

### Custom Region and Expires

```perl
my $tx = $ua->post(
  'https://dynamodb.eu-west-1.amazonaws.com/' => awssig4 => {
    service => 'dynamodb',
    region  => 'eu-west-1',
    expires => 3600,
  } => json => { TableName => 'MyTable' }
);
```

### With File Content

```perl
my $tx = $ua->put(
  'https://my-bucket.s3.amazonaws.com/large-file.bin' => awssig4 => {
    service => 's3',
    content => '/path/to/file',
  }
);
```

### Unsigned Payload (for streaming)

```perl
my $tx = $ua->post(
  'https://api.example.com/upload' => awssig4 => {
    service          => 'custom-service',
    unsigned_payload => 1,
    expires          => 900,
  }
);
```

### Debug Mode

```perl
my $tx = $ua->get(
  'https://my-bucket.s3.amazonaws.com/object' => awssig4 => {
    service => 's3',
    debug   => 1,  # Enables warnings for canonical request and string to sign
  }
);
```

## Supported Services

This role can be used with any AWS service or compatible service that requires AWS Signature Version 4 signing, including:

- S3 (Simple Storage Service)
- DynamoDB
- SQS (Simple Queue Service)
- SNS (Simple Notification Service)
- Lambda
- API Gateway
- CloudWatch
- And any other service using SigV4

## Requirements

- Perl 5.20.0 or higher
- [Mojolicious](https://metacpan.org/pod/Mojolicious) 9.38 or higher
- [Digest::SHA](https://metacpan.org/pod/Digest::SHA)
- [Time::Piece](https://metacpan.org/pod/Time::Piece)

## See Also

- [Mojolicious](https://mojolicious.org)
- [Mojo::UserAgent](https://metacpan.org/pod/Mojo::UserAgent)
- [AWS Signature Version 4 Signing Process](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html)
- [Mojo::UserAgent::Role::AWSSignature4 on MetaCPAN](https://metacpan.org/pod/Mojo::UserAgent::Role::AWSSignature4)

## Author

Stefan Adams <sadams@cpan.org>

## Copyright and License

This software is copyright (c) 2025+ by Stefan Adams <sadams@cpan.org>.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.