view release on metacpan or  search on metacpan

lib/AWS/Signature/V4/Credentials.pod  view on Meta::CPAN

=pod

=for vim
   vim: tw=72 ts=3 sts=3 sw=3 et ai :

=encoding utf8

=head1 NAME

AWS::Signature::V4::Credentials - The credentials-based variant of AWS Signature V4


=head1 VERSION

This module is part of the L<AWS::Signature::V4> distribution and shares
its version.


=head1 SYNOPSIS

   # you do not create it: AWS::Signature::V4 does, from "credentials"
   use AWS::Signature::V4;

   my $s = AWS::Signature::V4->new(
      service => 'iam', region => 'us-east-1',
      credentials => {
         access_key_id     => $id,
         secret_access_key => $secret,
         session_token     => $token,    # optional
      },
   );


=head1 DESCRIPTION

This class implements the traditional variant of the algorithm
(C<AWS4-HMAC-SHA256>), where the signature is an HMAC computed with a key
derived from the secret access key.

B<You are not supposed to use this module directly.>
L<AWS::Signature::V4> creates an object when it is given the
C<credentials> option, using the same keys, and calls the methods below.
The class is documented for those who work on the distribution, or want
to know how the two variants are kept apart, not as a public interface.

The constructor complains with an L<Ouch> exception (code C<400>) if the
access key or the secret are missing or empty; the session token is
optional, and an empty one is like a missing one.


=head1 THE INTERFACE OF A VARIANT

L<AWS::Signature::V4> talks to the variant in use, this class or its
sibling, through the same few methods, so that it does not need to know
which one it is dealing with. The scope is what appears in the
C<Credential> and in the string to sign, like
C<20150830/us-east-1/iam/aws4_request>.

=head1 INTERFACE

=head2 algorithm

   my $name = $variant->algorithm;    # AWS4-HMAC-SHA256

=head2 credential_id

   my $id = $variant->credential_id;

The access key id.

=head2 signature

   my $hex = $variant->signature($scope, $string_to_sign);

The hexadecimal HMAC-SHA256 of the string to sign, computed with the
signing key for the scope.

=head2 signing_key

   my $bytes = $variant->signing_key($scope);

The key derived from the secret for the date, region and service in the
scope (the raw bytes, not hexadecimal). It is also what signs the chunks of
a streaming upload.

=head2 can_sign_chunks

True: chunks of streaming uploads can be signed, because there is a
derived key.

=head2 extra_fields

   my @pairs = $variant->extra_fields;

What goes with the request besides the signature, as a list of
C<< name => value >> pairs, named as query parameters (the caller
lowercases them to make headers): here the session token, as
C<X-Amz-Security-Token>, if there is one.


=head1 AUTHOR