The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.

NAME

Signer::AWSv4 - Implements the AWS v4 signature algorithm

DESCRIPTION

Yet Another module to sign requests to Amazon Web Services APIs with the AWSv4 signing algorithm. This module has a different twist. The rest of modules out there are tied to signing HTTP::Request objects, but AWS uses v4 signatures in other places: IAM user login to MySQL RDSs, EKS, S3 Presigned URLs, etc. When building authentication modules for these services, I've had to create artificial HTTP::Request objects, just for a signing module to sign them, and then retrieve the signature. This module solves that problem, not being tied to any specific object to sign.

Signer::AWSv4 is a base class that implements the main v4 Algorithm. You're supposed https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html to subclass and override attributes to adjust how you want the signature to be built.

It's attributes let you inspect the entire signing process (making the string to sign, the signature, etc available for inspection)

Specialized Signers

Signer::AWSv4::S3 - Build presigned S3 URLs

Signer::AWSv4::EKS - Login to EKS clusters

Signer::AWSv4::RDS - Login to MySQL RDS servers with IAM credentials

Request Attributes

access_key

Holds the AWS Access Key to sign with. Please don't hardcode your credentials. Get them from some AWS authentication readers like Net::Amazon::Config, Config::AWS, AWS::CLI::Config, One of Paws::Credential subclasses.

secret_key String

Holds the AWS Secret Key

session_token String

Optional. The session token when using STS temporary credentials. Some services may not support authenticating with temporary credentials.

method String

The method to sign with. This can be overwritten by subclasses to provide an appropiate default for a specific service.

uri String

The uri to sign with. This can be overwritten by subclasses to provide an appropiate default for a specific service

region String

The uri to sign with. This can be overwritten by subclasses to provide an appropiate default for a specific service

service String

The service to sign with. This can be overwritten by subclasses to provide an appropiate default for a specific service

expires Integer

The time for which the signature will be valid. This may be defaulted in subclasses so the user doesn't have to specify it.

params HashRef of Strings

The query parameters to sign. Subclasses must implement a build_params method that sets the query parameters to sign appropiately.

headers HashRef of Strings

The headers to sign. Subclasses must implement a build_headers method that sets the headers to sign appropiately.

content String

The content of the request to be signed.

unsigned_payload Bool

Indicates wheather the payload (content) should be signed or not.

Signature Attributes

Attributes for obtaining the final signature

signature

The final signature. Just a hexadecimal string with the result of signing the request

signed_qstring

The query string that should be added to a URL to obtain a signed URL (some subclasses use this signed query string internally)

Internal Attributes

The computation of the signature is heald in a series of attributes that are built for dumping, diagnosing and controlling the signature process

time

A Time::Piece object that holds the time for the signature. Defaulted to "now"

date, date_timestamp

Values used in intermediate parts of the signature process. Derived from time.

canonical_qstring

The Canonical Query String to be used in the signature process.

header_list

The list of headers to sign. Defaults to all headers in the headers attribute

canonical_headers

The cannonical list of headers to use in the signature process. Depends on header_list

hashed_payload

The hashed payload of the request

signed_header_list

The list of signed headers, ready for inclusion in the canonical request

canonical_request

The canonical request that will be signed. Brings together the method, uri, canonical_qstring, canonical_headers, signed_header_list and hashed_payload

credential_scope

The credential scope to be used to sign the request

aws_algorithm

The string that identifies the signing algorithm version. Defaults to AWS4-HMAC-SHA256

string_to_sign

The string to sign

signing_key

The signing key

These internal concepts can be found in https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html, that describes the signature process.

TODO

Implement a signer for the AWS ElasticSearch service

Implement a generic "sign an HTTP::Request" signer

Pass the same test suite that Net::Amazon::Signature::V4 has

SEE ALSO

AWS::Signature4

Net::Amazon::Signature::V4

WebService::Amazon::Signature::v4

https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html

CONTRIBUTIONS

manwar: specify missing prereqs

mschout: add version support to S3

lucas1: add overriding response headers

BUGS and SOURCE

The source code is located here: https://github.com/pplu/AWSv4Signer

Please report bugs to: https://github.com/pplu/AWSv4Signer/issues

AUTHOR

Jose Luis Martinez
pplusdomain@gmail.com

COPYRIGHT and LICENSE

Copyright (c) 2018 by Jose Luis Martinez

This code is distributed under the Apache 2 License. The full text of the license can be found in the LICENSE file included with this module.