doc tweaking

R/az_storage.R

@@ -7,8 +7,9 @@
 #' The following methods are available, in addition to those provided by the [AzureRMR::az_resource] class:
 #' - `new(...)`: Initialize a new storage object. See 'Initialization'.
 #' - `list_keys()`: Return the access keys for this account.
-#' - `get_account_sas(...)`: Return an account shared access signature (SAS). See 'Shared access signatures' below.
+#' - `get_account_sas(...)`: Return an account shared access signature (SAS). See 'Creating a shared access signature' below.
 #' - `get_user_delegation_key(...)`: Returns a key that can be used to construct a user delegation SAS.
+#' - `get_user_delegation_sas(...)`: Return a user delegation SAS.
 #' - `revoke_user_delegation_keys()`: Revokes all user delegation keys for the account. This also renders all SAS's obtained via such keys invalid.
 #' - `get_blob_endpoint(key, sas)`: Return the account's blob storage endpoint, along with an access key and/or a SAS. See 'Endpoints' for more details
 #' - `get_file_endpoint(key, sas)`: Return the account's file storage endpoint.
@@ -17,10 +18,10 @@
 #' @section Initialization:
 #' Initializing a new object of this class can either retrieve an existing storage account, or create a account on the host. Generally, the best way to initialize an object is via the `get_storage_account`, `create_storage_account` or `list_storage_accounts` methods of the [az_resource_group] class, which handle the details automatically.
 #'
-#' @section Shared access signatures:
-#' The simplest way for a user to access files and data in a storage account is to give them the account's access key. This gives them full control of the account, and so may be a security risk. An alternative is to provide the user with a _shared access signature_ (SAS), which limits access to specific resources and only for a set length of time.
+#' @section Creating a shared access signature:
+#' Note that you don't need to worry about this section if you have been _given_ a SAS, and only want to use it to access storage.
 #'
-#' AzureStor supports two kinds of SAS: account and user delegation, with the latter applying only to blob and ADLS2 storage. To create an account SAS, call the `get_account_sas()` method. This has the following signature:
+#' AzureStor supports generating two kinds of SAS: account and user delegation, with the latter applying only to blob and ADLS2 storage. To create an account SAS, call the `get_account_sas()` method. This has the following signature:
 #'
 #' ```
 #' get_account_sas(key=self$list_keys()[1], start=NULL, expiry=NULL, services="bqtf", permissions="rl",
@@ -40,7 +41,13 @@
 #'                         resource_types="c", ip=NULL, protocol=NULL, snapshot_time=NULL)
 #' ```
 #'
-#' See the [Shared access signatures][sas] page for more information about SAS.
+#' To invalidate all user delegation keys, as well as the SAS's generated with them, call the `revoke_user_delegation_keys()` method. This has the following signature:
+#'
+#' ```
+#' revoke_user_delegation_keys()
+#' ```
+#'
+#' See the [Shared access signatures][sas] page for more information about this topic.
 #'
 #' @section Endpoints:
 #' The client-side interaction with a storage account is via an _endpoint_. A storage account can have several endpoints, one for each type of storage supported: blob, file, queue and table.

R/sas.R

@@ -22,12 +22,14 @@
 #' @param ... Arguments passed to lower-level functions.
 #'
 #' @details
-#' An **account SAS** is secured with the storage account key. An account SAS delegates access to resources in one or more of the storage services. All of the operations available via a user delegation SAS are also available via an account SAS. You can also delegate access to read, write, and delete operations on blob containers, tables, queues, and file shares.
+#' An **account SAS** is secured with the storage account key. An account SAS delegates access to resources in one or more of the storage services. All of the operations available via a user delegation SAS are also available via an account SAS. You can also delegate access to read, write, and delete operations on blob containers, tables, queues, and file shares. To obtain an account SAS, call `get_account_sas`.
 #'
 #' A **user delegation SAS** is a SAS secured with Azure AD credentials. It's recommended that you use Azure AD credentials when possible as a security best practice, rather than using the account key, which can be more easily compromised. When your application design requires shared access signatures, use Azure AD credentials to create a user delegation SAS for superior security.
 #'
 #' Every SAS is signed with a key. To create a user delegation SAS, you must first request a **user delegation key**, which is then used to sign the SAS. The user delegation key is analogous to the account key used to sign a service SAS or an account SAS, except that it relies on your Azure AD credentials. To request the user delegation key, call `get_user_delegation_key`. With the user delegation key, you can then create the SAS with `get_user_delegation_sas`.
 #'
+#' To invalidate all user delegation keys, as well as the SAS's generated with them, call `revoke_user_delegation_keys`.
+#'
 #' See the examples and Microsoft Docs pages below for how to specify arguments like the services, permissions, and resource types. Also, while not explicitly mentioned in the documentation, ADLSgen2 storage can use any SAS that is valid for blob storage.
 #' @seealso
 #' [blob_endpoint], [file_endpoint],

man/az_storage.Rd

@@ -13,8 +13,9 @@ The following methods are available, in addition to those provided by the \link[
 \itemize{
 \item \code{new(...)}: Initialize a new storage object. See 'Initialization'.
 \item \code{list_keys()}: Return the access keys for this account.
-\item \code{get_account_sas(...)}: Return an account shared access signature (SAS). See 'Shared access signatures' below.
+\item \code{get_account_sas(...)}: Return an account shared access signature (SAS). See 'Creating a shared access signature' below.
 \item \code{get_user_delegation_key(...)}: Returns a key that can be used to construct a user delegation SAS.
+\item \code{get_user_delegation_sas(...)}: Return a user delegation SAS.
 \item \code{revoke_user_delegation_keys()}: Revokes all user delegation keys for the account. This also renders all SAS's obtained via such keys invalid.
 \item \code{get_blob_endpoint(key, sas)}: Return the account's blob storage endpoint, along with an access key and/or a SAS. See 'Endpoints' for more details
 \item \code{get_file_endpoint(key, sas)}: Return the account's file storage endpoint.
@@ -27,11 +28,11 @@ The following methods are available, in addition to those provided by the \link[
 Initializing a new object of this class can either retrieve an existing storage account, or create a account on the host. Generally, the best way to initialize an object is via the \code{get_storage_account}, \code{create_storage_account} or \code{list_storage_accounts} methods of the \link{az_resource_group} class, which handle the details automatically.
 }
 
-\section{Shared access signatures}{
+\section{Creating a shared access signature}{
 
-The simplest way for a user to access files and data in a storage account is to give them the account's access key. This gives them full control of the account, and so may be a security risk. An alternative is to provide the user with a \emph{shared access signature} (SAS), which limits access to specific resources and only for a set length of time.
+Note that you don't need to worry about this section if you have been \emph{given} a SAS, and only want to use it to access storage.
 
-AzureStor supports two kinds of SAS: account and user delegation, with the latter applying only to blob and ADLS2 storage. To create an account SAS, call the \code{get_account_sas()} method. This has the following signature:\preformatted{get_account_sas(key=self$list_keys()[1], start=NULL, expiry=NULL, services="bqtf", permissions="rl",
+AzureStor supports generating two kinds of SAS: account and user delegation, with the latter applying only to blob and ADLS2 storage. To create an account SAS, call the \code{get_account_sas()} method. This has the following signature:\preformatted{get_account_sas(key=self$list_keys()[1], start=NULL, expiry=NULL, services="bqtf", permissions="rl",
                 resource_types="sco", ip=NULL, protocol=NULL)
 }
 
@@ -42,7 +43,10 @@ Once you have a user delegation key, you can use it to obtain a user delegation
                         resource_types="c", ip=NULL, protocol=NULL, snapshot_time=NULL)
 }
 
-See the \link[=sas]{Shared access signatures} page for more information about SAS.
+To invalidate all user delegation keys, as well as the SAS's generated with them, call the \code{revoke_user_delegation_keys()} method. This has the following signature:\preformatted{revoke_user_delegation_keys()
+}
+
+See the \link[=sas]{Shared access signatures} page for more information about this topic.
 }
 
 \section{Endpoints}{

man/sas.Rd

@@ -90,12 +90,14 @@ Listed here are S3 generics and methods to obtain a SAS for accessing storage; i
 
 Note that you don't need to worry about these methods if you have been \emph{given} a SAS, and only want to use it to access a storage account.
 
-An \strong{account SAS} is secured with the storage account key. An account SAS delegates access to resources in one or more of the storage services. All of the operations available via a user delegation SAS are also available via an account SAS. You can also delegate access to read, write, and delete operations on blob containers, tables, queues, and file shares.
+An \strong{account SAS} is secured with the storage account key. An account SAS delegates access to resources in one or more of the storage services. All of the operations available via a user delegation SAS are also available via an account SAS. You can also delegate access to read, write, and delete operations on blob containers, tables, queues, and file shares. To obtain an account SAS, call \code{get_account_sas}.
 
 A \strong{user delegation SAS} is a SAS secured with Azure AD credentials. It's recommended that you use Azure AD credentials when possible as a security best practice, rather than using the account key, which can be more easily compromised. When your application design requires shared access signatures, use Azure AD credentials to create a user delegation SAS for superior security.
 
 Every SAS is signed with a key. To create a user delegation SAS, you must first request a \strong{user delegation key}, which is then used to sign the SAS. The user delegation key is analogous to the account key used to sign a service SAS or an account SAS, except that it relies on your Azure AD credentials. To request the user delegation key, call \code{get_user_delegation_key}. With the user delegation key, you can then create the SAS with \code{get_user_delegation_sas}.
 
+To invalidate all user delegation keys, as well as the SAS's generated with them, call \code{revoke_user_delegation_keys}.
+
 See the examples and Microsoft Docs pages below for how to specify arguments like the services, permissions, and resource types. Also, while not explicitly mentioned in the documentation, ADLSgen2 storage can use any SAS that is valid for blob storage.
 }
 \examples{