26

aws.signature

Amazon Web Services Request Signatures

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:

  1. User-supplied values passed directly to functions.

  2. 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")

  3. If R is running on an EC2 instance, the role profile credentials provided by aws.ec2metadata, if the aws.ec2metadata package is installed.

  4. If R is running on an ECS task, the role profile credentials provided by aws.ec2metadata, if the aws.ec2metadata package is installed.

  5. 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.

  6. 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 credentials
use_credentials()
 
# use an alternative credentials profile
use_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.

Installation

CRAN Downloads Build Status codecov.io

To install the latest package version, it is recommended to install from the cloudyr drat repository:

# latest stable version
install.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").

cloudyr project logo

News

aws.signature 0.5.0

  • New Maintainer: @jon-mago
  • Fix use of file system credentials (Thanks to @lgjohnson)
  • Fix use of ECS metadata (Requires aws.ec2metadata >= 0.1.6)
  • Rewrite some internals and tests
  • Removed 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.signature 0.4.4

  • Allow use of ECS metadata where available. (h/t @jon-mago #23, #30)

aws.signature 0.4.3

  • Incorporated standard environment variables 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.
  • Updated documentation.

aws.signature 0.4.2

  • Fixed a bug in the default datetime argument in several functions. (#28, h/t @yansonz)

aws.signature 0.4.1

  • Removed some tests from execution on CRAN.

aws.signature 0.4.0

  • 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.
  • The test suite was upbdated substantially, though not all tests run on CRAN.

aws.signature 0.3.7

  • On namespace load, the package now checks for the presence of environment variables and, if absent, attempts to call 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)
  • The profile argument of use_credentials() now defaults to Sys.getenv("AWS_PROFILE", "default") for consistency with other AWS client libraries.

aws.signature 0.3.6

  • 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)
  • The set of fall backs for values of region have been standardized and documented for locate_credentials().
  • Updated documentation to describe the need for aws.ec2metadata on EC2 instances.

aws.signature 0.3.5

  • signature_v4_auth() and signature_v2_auth() now both return a Region value in their response list, as identified by locate_credentials().

aws.signature 0.3.4

  • Fixed a bug related to extracting credentials from environment variables. (https://github.com/cloudyr/aws.s3/issues/142, https://github.com/cloudyr/aws.s3/issues/143)
  • Fixed a bug related to extracting credentials from EC2 instance metadata (https://github.com/cloudyr/aws.s3/issues/144, h/t Daniele Rapati, Will Bowditch)
  • Bumped aws.ec2metadata suggestion to 0.1.2.

aws.signature 0.3.3

  • Fixed a bug in locate_credentials() caused by trying to retrieve EC2 instance metadata from a non-EC2 machine on which the aws.ec2metadata package was installed.
  • Expanded test suite to cover more of locate_credentials() behavior.

aws.signature 0.3.2

  • CRAN Release.
  • Added some minor tests.

aws.signature 0.3.1

  • Changed the precedence of credential sources to: user-supplied values, EC2 instance metadata, environment variables, local credentials file, and global credentials file. (#11)

aws.signature 0.3.0

  • Added a 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)

aws.signature 0.2.9

  • Modified read_credentials() to allow key-value pairs of any form: KEY=VALUE, KEY = VALUE, KEY= VALUE, KEY =VALUE. (#15, h/t David Severski)

aws.signature 0.2.8

  • Corrected the default timestamp format in signature_v2_auth().

aws.signature 0.2.7

  • read_credentials() now looks for the credentials file in a more reasonable location on Windows (#12/#13, h/t user:kadrach)
  • roxygenized the documentation (and reorganized the source files slightly). (#9)

aws.signature 0.2.6

  • Added support for signing requests (using V4 signatures) with temporary security tokens.
  • Modified some default arguments to correct unintended behavior. These should not affect any previously correct signing code.

aws.signature 0.2.5

  • Added functions read_credentials() and use_credentials() to access AWS access credentials stored in .aws/credentials files.

aws.signature 0.2.4

  • Further fixes to the handling of default arguments from environment variables.

aws.signature 0.2.3

  • Fixed the handling of default arguments from environment variables.

aws.signature 0.2.2

  • Added support for (legacy) AWS Signature Version 2.

aws.signature 0.2.1

  • canonical_request() now sets C collate order to properly order query argument and header names across platforms.

aws.signature 0.1.4

  • Coerce query string arguments to character before passing to URLencode(). (#5)

aws.signature 0.1.3

aws.signature 0.1.2

  • Fix bug in request body hashing for non-character request bodies (#3).

aws.signature 0.1.1

  • Allow request body has to be generated from file without loading into memory.

aws.signature 0.1.0

  • Include patched version of utils::URLencode that correctly encodes URLs per RFC 3986.
  • Initial release.

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.
install.packages("aws.signature")

0.6.0 by Jonathan Stott, a year ago

https://github.com/cloudyr/aws.signature

Report a bug at https://github.com/cloudyr/aws.signature/issues

Browse source code at https://github.com/cran/aws.signature

Authors: Thomas J. Leeper [aut] , Jonathan Stott [cre, aut] , Mike Kaminsky [ctb]

Documentation:   PDF Manual  

Task views: Web Technologies and Services

GPL (>= 2) license

Imports digest, base64enc

Suggests testthat, aws.ec2metadata

Imported by aws.alexa, aws.comprehend, aws.ecx, aws.iam, aws.kms, aws.lambda, aws.polly, aws.s3, aws.transcribe, aws.translate, text2speech.

Suggested by gargle.

See at CRAN

R links

R homepage

Download R

Mailing lists

R documentation

R manuals

R FAQs

The R Journal

CRAN links

CRAN homepage

CRAN repository policy

Submit a package

METACRAN stuff

About METACRAN

At github

Report a bug