add force_credentials argument to signature_v4_auth() and signature_v…

…2_auth() (#33)

NEWS.md

@@ -1,7 +1,7 @@
 # aws.signature 0.4.5
 
 * 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
 

R/signature_v4.R

@@ -1,11 +1,11 @@
 #' @title Signature Version 4
 #' @description Generates AWS Signature Version 4
-#' @param secret An AWS Secret Access Key. If \code{NULL}, it is retrieved using \code{\link{locate_credentials}}.
+#' @template secret
 #' @param date A character string containing a date in the form of \dQuote{YYMMDD}. If missing, it is generated automatically using \code{\link[base]{Sys.time}}.
-#' @param region A character string containing the AWS region for the request. If \code{NULL}, it is retrieved using \code{\link{locate_credentials}} or \dQuote{us-east-1} is used.
+#' @template region
 #' @param service A character string containing the AWS service (e.g., \dQuote{iam}, \dQuote{host}, \dQuote{ec2}).
 #' @param string_to_sign A character string containing the \dQuote{String To Sign}, possibly returned by \code{\link{string_to_sign}}.
-#' @param verbose A logical indicating whether to be verbose.
+#' @template verbose
 #' @details This function generates an AWS Signature Version 4 for authorizing API requests from its pre-formatted components. Users probably only need to use the \code{\link{signature_v4_auth}} function to generate signatures.
 #' @author Thomas J. Leeper <thosjleeper@gmail.com>
 #' @references
@@ -49,12 +49,14 @@
 #' @importFrom digest digest hmac
 #' @export
 signature_v4 <- 
-function(secret = NULL,
-         date = format(Sys.time(), "%Y%m%d"),
-         region = NULL,
-         service,
-         string_to_sign,
-         verbose = FALSE) {
+function(
+  secret = NULL,
+  date = format(Sys.time(), "%Y%m%d"),
+  region = NULL,
+  service,
+  string_to_sign,
+  verbose = getOption("verbose", FALSE)
+) {
     kDate <- digest::hmac(paste0("AWS4", secret), date, "sha256", raw = TRUE)
     kRegion <- digest::hmac(kDate, region, "sha256", raw = TRUE)
     kService <- digest::hmac(kRegion, service, "sha256", raw = TRUE)

R/v2.R

@@ -5,9 +5,11 @@
 #' @param service A character string containing the full hostname of an AWS service (e.g., \dQuote{iam.amazonaws.com}, etc.)
 #' @param path A character string specify the path to the API endpoint.
 #' @param query_args A list containing named query arguments.
-#' @param key An AWS Access Key ID. If \code{NULL}, it is retrieved using \code{\link{locate_credentials}}.
-#' @param secret An AWS Secret Access Key. If \code{NULL}, it is retrieved using \code{\link{locate_credentials}}.
-#' @param verbose A logical indicating whether to be verbose.
+#' @template key
+#' @template secret
+#' @template region
+#' @template force_credentials
+#' @template verbose
 #' @details This function generates an AWS Signature Version 2 for authorizing API requests. The function returns both an updated set of query string parameters, containing the required signature-related entries, as well as a \code{Signature} field containing the Signature string itself. Version 2 is mostly deprecated and in most cases users should rely on \code{\link{signature_v4_auth}} for Version 4 signatures instead.
 #' @return A list.
 #' @author Thomas J. Leeper <thosjleeper@gmail.com>
@@ -68,12 +70,34 @@
 #' @importFrom base64enc base64encode
 #' @export
 signature_v2_auth <- 
-function(datetime = format(Sys.time(),"%Y-%m-%dT%H:%M:%S", tz = "UTC"),
-         verb, service, path, query_args = list(),
-         key = NULL,
-         secret = NULL,
-         verbose = FALSE) {
-    credentials <- locate_credentials(key = key, secret = secret, region = "us-east-1", verbose = verbose)
+function(
+  datetime = format(Sys.time(),"%Y-%m-%dT%H:%M:%S", tz = "UTC"),
+  verb,
+  service,
+  path,
+  query_args = list(),
+  key = NULL,
+  secret = NULL,
+  region = NULL,
+  force_credentials = FALSE,
+  verbose = getOption("verbose", FALSE)
+) {
+    if (isTRUE(force_credentials)) {
+        credentials <- list(key = key, secret = secret, region = region)
+        if (isTRUE(verbose)) {
+            if (!is.null(key)) {
+                message("Using user-supplied value for AWS Access Key ID")
+            }
+            if (!is.null(secret)) {
+                message("Using user-supplied value for AWS Secret Access Key")
+            }
+            if (!is.null(region)) {
+                message(sprintf("Using user-supplied value for AWS Region ('%s')", region))
+            }
+        }
+    } else {
+        credentials <- locate_credentials(key = key, secret = secret, region = region, verbose = verbose)
+    }
 
     # set sort locale
     lc <- Sys.getlocale(category = "LC_COLLATE")
@@ -117,5 +141,6 @@ function(datetime = format(Sys.time(),"%Y-%m-%dT%H:%M:%S", tz = "UTC"),
                    AccessKeyId = credentials[["key"]],
                    SecretAccessKey = credentials[["secret"]],
                    SessionToken = credentials[["session_token"]],
-                   Region = credentials[["region"]]), class = "aws_signature_v2")
+                   Region = credentials[["region"]]),
+              class = "aws_signature_v2")
 }

R/v4.R

@@ -1,19 +1,20 @@
 #' @title Signature Version 4
 #' @description AWS Signature Version 4 for use in query or header authorization
 #' @param datetime A character string containing a datetime in the form of \dQuote{YYYYMMDDTHHMMSSZ}. If missing, it is generated automatically using \code{\link[base]{Sys.time}}.
-#' @param region A character string containing the AWS region for the request. See \code{\link{locate_credentials}}.
+#' @template region
 #' @param service A character string containing the AWS service (e.g., \dQuote{iam}, \dQuote{host}, \dQuote{ec2}).
 #' @param verb A character string containing the HTTP verb being used in the request.
 #' @param action A character string containing the API endpoint used in the request.
 #' @param query_args A named list of character strings containing the query string values (if any) used in the API request, passed to \code{\link{canonical_request}}.
 #' @param canonical_headers A named list of character strings containing the headers used in the request.
 #' @param request_body The body of the HTTP request.
-#' @param key An AWS Access Key ID. See \code{\link{locate_credentials}}.
-#' @param secret An AWS Secret Access Key. See \code{\link{locate_credentials}}.
+#' @template key
+#' @template secret
 #' @param session_token Optionally, an AWS Security Token Service (STS) temporary Session Token. This is added automatically as a header to \code{canonical_headers}. See \code{\link{locate_credentials}}.
 #' @param query A logical. Currently ignored.
 #' @param algorithm A character string containing the hashing algorithm used in the request. Should only be \dQuote{SHA256}.
-#' @param verbose A logical indicating whether to be verbose.
+#' @template force_credentials
+#' @template verbose
 #' @details This function generates an AWS Signature Version 4 for authorizing API requests.
 #' @return A list of class \dQuote{aws_signature_v4}, containing the information needed to sign an AWS API request using either query string authentication or request header authentication. Specifically, the list contains:
 #' 
@@ -62,25 +63,45 @@
 #' @seealso \code{\link{signature_v2_auth}}, \code{\link{locate_credentials}}
 #' @export
 signature_v4_auth <- 
-function(datetime = format(Sys.time(),"%Y%m%dT%H%M%SZ", tz = "UTC"),
-         region = NULL,
-         service,
-         verb,
-         action,
-         query_args = list(),
-         canonical_headers, # named list
-         request_body,
-         key = NULL,
-         secret = NULL,
-         session_token = NULL,
-         query = FALSE,
-         algorithm = "AWS4-HMAC-SHA256",
-         verbose = FALSE){
-    credentials <- locate_credentials(key = key, secret = secret, session_token = session_token, region = region, verbose = verbose)
-    key <- credentials[["key"]]
-    secret <- credentials[["secret"]]
-    session_token <- credentials[["session_token"]]
-    region <- credentials[["region"]]
+function(
+  datetime = format(Sys.time(),"%Y%m%dT%H%M%SZ", tz = "UTC"),
+  region = NULL,
+  service,
+  verb,
+  action,
+  query_args = list(),
+  canonical_headers, # named list
+  request_body,
+  key = NULL,
+  secret = NULL,
+  session_token = NULL,
+  query = FALSE,
+  algorithm = "AWS4-HMAC-SHA256",
+  force_credentials = FALSE,
+  verbose = getOption("verbose", FALSE)
+){
+    if (isTRUE(force_credentials)) {
+        if (isTRUE(verbose)) {
+            if (!is.null(key)) {
+                message("Using user-supplied value for AWS Access Key ID")
+            }
+            if (!is.null(secret)) {
+                message("Using user-supplied value for AWS Secret Access Key")
+            }
+            if (!is.null(session_token)) {
+                message("Using user-supplied value for AWS Secret Access Key")
+            }
+            if (!is.null(region)) {
+                message(sprintf("Using user-supplied value for AWS Region ('%s')", region))
+            }
+        }
+    } else {
+        credentials <- locate_credentials(key = key, secret = secret, session_token = session_token, region = region, verbose = verbose)
+        key <- credentials[["key"]]
+        secret <- credentials[["secret"]]
+        session_token <- credentials[["session_token"]]
+        region <- credentials[["region"]]
+    }
 
     date <- substring(datetime,1,8)
 

man-roxygen/force_credentials.R

@@ -0,0 +1 @@
+#' @param force_credentials A logical indicating whether to force use of user-supplied credentials. If \code{FALSE} (the default), \code{\link{locate_credentials}} is used to find credentials. If \code{TRUE}, user-supplied values are used regardless of their validity.

man-roxygen/key.R

@@ -0,0 +1 @@
+#' @param key An AWS Access Key ID. If \code{NULL}, it is retrieved using \code{\link{locate_credentials}}.

man-roxygen/region.R

@@ -0,0 +1 @@
+#' @param region A character string containing the AWS region for the request. If missing, \dQuote{us-east-1} is assumed.

man-roxygen/secret.R

@@ -0,0 +1 @@
+#' @param secret An AWS Secret Access Key. If \code{NULL}, it is retrieved using \code{\link{locate_credentials}}.

man-roxygen/verbose.R

@@ -0,0 +1 @@
+#' @param verbose A logical indicating whether to be verbose.