.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "AWS::Signature4 3pm"
.TH AWS::Signature4 3pm "2017-11-11" "perl v5.26.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
AWS::Signature4 \- Create a version4 signature for Amazon Web Services
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\& use AWS::Signature4;
\& use HTTP::Request::Common;
\& use LWP;
\&
\& my $signer = AWS::Signature4\->new(\-access_key => \*(AqAKIDEXAMPLE\*(Aq,
\&                                   \-secret_key => \*(AqwJalrXUtnFEMI/K7MDENG+bPxRfiCYEXAMPLEKEY\*(Aq);
\& my $ua     = LWP::UserAgent\->new();
\&
\& # Example POST request
\& my $request = POST(\*(Aqhttps://iam.amazonaws.com\*(Aq,
\&                    [Action=>\*(AqListUsers\*(Aq,
\&                     Version=>\*(Aq2010\-05\-08\*(Aq]);
\& $signer\->sign($request);
\& my $response = $ua\->request($request);
\&
\& # Example GET request
\& my $uri     = URI\->new(\*(Aqhttps://iam.amazonaws.com\*(Aq);
\& $uri\->query_form(Action=>\*(AqListUsers\*(Aq,
\&                  Version=>\*(Aq2010\-05\-08\*(Aq);
\&
\& my $url = $signer\->signed_url($uri); # This gives a signed URL that can be fetched by a browser
\& my $response = $ua\->get($url);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module implement's Amazon Web Service's Signature version 4
(http://docs.aws.amazon.com/general/latest/gr/signature\-version\-4.html).
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP "$signer = AWS::Signature4\->new(\-access_key => $account_id,\-secret_key => $private_key);" 4
.el .IP "\f(CW$signer\fR = AWS::Signature4\->new(\-access_key => \f(CW$account_id\fR,\-secret_key => \f(CW$private_key\fR);" 4
.IX Item "$signer = AWS::Signature4->new(-access_key => $account_id,-secret_key => $private_key);"
Create a signing object using your \s-1AWS\s0 account \s-1ID\s0 and secret key. You
may also use the temporary security tokens received from Amazon's \s-1STS\s0
service, either by passing the access and secret keys derived from the
token, or by passing a VM::EC2::Security::Token produced by the
\&\s-1VM::EC2\s0 module.
.Sp
Arguments:
.Sp
.Vb 3
\& Argument name       Argument Value
\& \-\-\-\-\-\-\-\-\-\-\-\-\-       \-\-\-\-\-\-\-\-\-\-\-\-\-\-
\& \-access_key         An AWS access key (account ID)
\&
\& \-secret_key         An AWS secret key
\&
\& \-security_token     A VM::EC2::Security::Token object
.Ve
.Sp
If a security token is provided, it overrides any values given for
\&\-access_key or \-secret_key.
.Sp
If the environment variables \s-1EC2_ACCESS_KEY\s0 and/or \s-1EC2_SECRET_KEY\s0 are
set, their contents are used as defaults for \-access_key and
\&\-secret_key.
.ie n .IP "$signer\->sign($request [,$region] [,$payload_sha256_hex])" 4
.el .IP "\f(CW$signer\fR\->sign($request [,$region] [,$payload_sha256_hex])" 4
.IX Item "$signer->sign($request [,$region] [,$payload_sha256_hex])"
Given an HTTP::Request object, add the headers required by \s-1AWS\s0 and
then sign it with a version 4 signature by adding an \*(L"Authorization\*(R"
header.
.Sp
The request must include a \s-1URL\s0 from which the \s-1AWS\s0 endpoint and service
can be derived, such as \*(L"ec2.us\-east\-1.amazonaws.com.\*(R" In some cases
(e.g. S3 bucket operations) the endpoint does not indicate the
region. In this case, the region can be forced by passing a defined
value for \f(CW$region\fR. The current date and time will be added to the
request using an \*(L"X\-Amz-Date header.\*(R" To force the date and time to a
fixed value, include the \*(L"Date\*(R" header in the request.
.Sp
The request content, or \*(L"payload\*(R" is retrieved from the HTTP::Request
object by calling its \fIcontent()\fR method.. Under some circumstances the
payload is not included directly in the request, but is in an external
file that will be uploaded as the request is executed. In this case,
you must pass a second argument containing the results of running
\&\fIsha256_hex()\fR (from the Digest::SHA module) on the content.
.Sp
The method returns a true value if successful. On errors, it will
throw an exception.
.ie n .IP "$url = $signer\->signed_url($request)" 4
.el .IP "\f(CW$url\fR = \f(CW$signer\fR\->signed_url($request)" 4
.IX Item "$url = $signer->signed_url($request)"
This method will generate a signed \s-1GET URL\s0 for the request. The \s-1URL\s0
will include everything needed to perform the request.
.ie n .IP "my $url $signer\->signed_url($request_or_uri [,$expires])" 4
.el .IP "my \f(CW$url\fR \f(CW$signer\fR\->signed_url($request_or_uri [,$expires])" 4
.IX Item "my $url $signer->signed_url($request_or_uri [,$expires])"
Pass an HTTP::Request, a \s-1URI\s0 object, or just a plain \s-1URL\s0 string
containing the proper endpoint and parameters needed for an \s-1AWS REST
API\s0 Call. This method will return an appropriately signed request as a
\&\s-1URI\s0 object, which can be shared with non-AWS users for the purpose of,
e.g., accessing an object in a private S3 bucket.
.Sp
Pass an optional \f(CW$expires\fR argument to indicate that the \s-1URL\s0 will only
be valid for a finite period of time. The value of the argument is in
seconds.
.ie n .IP "$signing_key = AWS::Signature4\->signing_key($secret_access_key,$service_name,$region,$date)" 4
.el .IP "\f(CW$signing_key\fR = AWS::Signature4\->signing_key($secret_access_key,$service_name,$region,$date)" 4
.IX Item "$signing_key = AWS::Signature4->signing_key($secret_access_key,$service_name,$region,$date)"
Return just the signing key in the event you wish to roll your own signature.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1VM::EC2\s0
.SH "AUTHOR"
.IX Header "AUTHOR"
Lincoln Stein <lincoln.stein@gmail.com>.
.PP
Copyright (c) 2014 Ontario Institute for Cancer Research
.PP
This package and its accompanying libraries is free software; you can
redistribute it and/or modify it under the terms of the \s-1GPL\s0 (either
version 1, or at your option, any later version) or the Artistic
License 2.0.  Refer to \s-1LICENSE\s0 for the full license text. In addition,
please see \s-1DISCLAIMER\s0.txt for disclaimers of warranty.