Generates version 2 and version 4 request signatures for Amazon Web Services ('AWS') < https://aws.amazon.com/> Application Programming Interfaces ('APIs') and provides a mechanism for retrieving credentials from environment variables, 'AWS' credentials files, and 'EC2' instance metadata. For use on 'EC2' instances, users will need to install the suggested package 'aws.ec2metadata' < https://cran.r-project.org/package=aws.ec2metadata>.
aws.signature is a package for creating request signatures for Amazon Web Services (AWS) APIs. It supports both the current Signature Version 4 and the legacy Signature Version 2. The former is used by most services. The high-level functions signature_v4_auth()
and signature_v2_auth()
translate request parameters into appropriate HTTP Authorization headers to pass to the APIs.
To use the package, you will need an AWS account and to enter your credentials into R. Your keypair can be generated on the IAM Management Console under the heading Access Keys. Note that you only have access to your secret key once. After it is generated, you need to save it in a secure location. New keypairs can be generated at any time if yours has been lost, stolen, or forgotten. The aws.iam package profiles tools for working with IAM, including creating roles, users, groups, and credentials programmatically; it is not needed to use IAM credentials.
By default, when loaded the package checks for environment variables. If absent, it checks for a default credentials file and loads credentials from it into environment variables; the profile used from that file can be regulated by setting the AWS_PROFILE
environment variable before loading this package (the `"default" profile is assumed if none is specified). This means the package and any dependencies should just work without needing to explicitly set or pass credentials within R code.
Regardless of this initial configuration, all awspack packages allow the use of credentials specified in a number of ways, in the following priority order:
User-supplied values passed directly to functions.
Environment variables, which can alternatively be set on the command line prior to starting R or via an Renviron.site
or .Renviron
file, which are used to set environment variables in R during startup (see ? Startup
). Or they can be set within R:
Sys.setenv("AWS_ACCESS_KEY_ID" = "mykey", "AWS_SECRET_ACCESS_KEY" = "mysecretkey", "AWS_DEFAULT_REGION" = "us-east-1", "AWS_SESSION_TOKEN" = "mytoken")
If R is running on an EC2 instance, the role profile credentials provided by aws.ec2metadata, if the aws.ec2metadata package is installed.
If R is running on an ECS task, the role profile credentials provided by aws.ec2metadata, if the aws.ec2metadata package is installed.
Profiles saved in a /.aws/credentials
"dot file" in the current working directory. The profile used can be regulated by the AWS_PROFILE
environment variable, otherwise the `"default" profile is assumed if none is specified or the specified profile is missing.
A centralized credentials file, containing credentials for multiple accounts. The location of this file is given by the AWS_SHARED_CREDENTIALS_FILE
environment variable or, if that is missing, by ~/.aws/credentials
(or an OS-specific equivalent). The profile used from that file can be regulated by the AWS_PROFILE
environment variable, otherwise the `"default" profile is assumed if none is specified or the specified profile is missing.
Because all functions requesting a signature walk this entire list of potential credentials sources, it typically makes sense to set environment variables otherwise a potentially large performance penalty can be paid. For this reason, it is usually better to explicitly invoke a profiles stored in a local or centralized (e.g., ~/.aws/credentials
) credentials file using:
# use your 'default' account credentialsuse_credentials() # use an alternative credentials profileuse_credentials(profile = "bob")
For purposes of debugging, it can be useful to set the verbose = TRUE
argument (or globally set options(verbose = TRUE)
) in order to see what values are being used for signing requests.
Temporary session tokens are stored in environment variable AWS_SESSION_TOKEN
(and will be stored there by the use_credentials()
function). The aws.iam package provides an R interface to IAM roles and the generation of temporary session tokens via the security token service (STS). On EC2 instances or ECS tasks, the aws.ec2metadata package should be installed so that signatures are signed with appropriate, dynamically updated credentials.
As a fail safe the us-east-1
region is used whenever a region is not found.
To install the latest package version, it is recommended to install from the cloudyr drat repository:
# latest stable versioninstall.packages("aws.signature", repos = c(cloudyr = "http://cloudyr.github.io/drat", getOption("repos")))
Or, to pull a potentially unstable version directly from GitHub:
if (!require("remotes")) { install.packages("remotes")}remotes::install_github("cloudyr/aws.signature")
To install the latest version from CRAN, simply use install.packages("aws.signature")
.
locate_credentials()
call from internal signature_v4()
function. (#33)signature_v4_auth()
and signature_v2_auth()
gain a force_credentials
argument. If force_credentials = TRUE
, user-supplied values are used and no call to locate_credentials()
is made. (#33)AWS_SHARED_CREDENTIALS_FILE
and AWS_PROFILE
into code as appropriate and tweaked locate_credentials()
accordingly.signature_v4_auth()
and signature_v2_auth()
now returns all inputs to facilitate using the return value in constructing an HTTP request.datetime
argument in several functions. (#28, h/t @yansonz)read_credentials()
now trims excess whitespace from profile names. (#22, h/t Paul Ingles)locate_credentials()
returns region = default_region
even when no other credentials are found.canonical_request()
now correctly trims whitespace.use_credentials()
(with defaults) to that behavior is more similar to other AWS client libraries. (https://github.com/cloudyr/aws.s3/pull/184, h/t Dan Tenenbaum)profile
argument of use_credentials()
now defaults to Sys.getenv("AWS_PROFILE", "default")
for consistency with other AWS client libraries.locate_credentials()
now attempts to look in instance metadata for a region, when called from an EC2 instance. (see https://github.com/cloudyr/aws.s3/issues/151)region
have been standardized and documented for locate_credentials()
.signature_v4_auth()
and signature_v2_auth()
now both return a Region
value in their response list, as identified by locate_credentials()
.locate_credentials()
caused by trying to retrieve EC2 instance metadata from a non-EC2 machine on which the aws.ec2metadata package was installed.locate_credentials()
behavior.locate_credentials()
function to walk through a hierarchy of possible credential locations, beginning with user-supplied values, then environment variables, local then global credentials ".aws/credentials" files, and finally (if applicable) an EC2 role for the currently running instance. (#11)read_credentials()
to allow key-value pairs of any form: KEY=VALUE
, KEY = VALUE
, KEY= VALUE
, KEY =VALUE
. (#15, h/t David Severski)signature_v2_auth()
.read_credentials()
now looks for the credentials file in a more reasonable location on Windows (#12/#13, h/t user:kadrach)read_credentials()
and use_credentials()
to access AWS access credentials stored in .aws/credentials
files.canonical_request()
now sets C collate order to properly order query argument and header names across platforms.URLencode()
. (#5)signature_v4_auth
.utils::URLencode
that correctly encodes URLs per RFC 3986.