stored key doc

R/stored_key.R

@@ -1,3 +1,91 @@
+#' Encryption key object
+#'
+#' This class represents an encryption keys stored in a vault. It provides methods for carrying out operations, including encryption and decryption, signing and verification, and wrapping and unwrapping.
+#'
+#' @docType class
+#'
+#' @section Methods:
+#' This class provides the following methods:
+#' ```
+#' encrypt(plaintext, algorithm=c("RSA-OAEP", "RSA-OAEP-256", "RSA1_5"))
+#' decrypt(ciphertext, algorithm=c("RSA-OAEP", "RSA-OAEP-256", "RSA1_5"), as_raw=TRUE)
+#' sign(digest,
+#'      algorithm=c("PS256", "PS384", "PS512", "RS256", "RS384", "RS512",
+#'                  "ES256", "ES256K", "ES384", "ES512"))
+#' verify(signature, digest,
+#'        algorithm=c("PS256", "PS384", "PS512", "RS256", "RS384", "RS512",
+#'                    "ES256", "ES256K", "ES384", "ES512"))
+#' wrap(value, algorithm=c("RSA-OAEP", "RSA-OAEP-256", "RSA1_5"))
+#' unwrap(value, algorithm=c("RSA-OAEP", "RSA-OAEP-256", "RSA1_5"), as_raw=TRUE)
+#'
+#' update_attributes(attributes=vault_object_attrs(), ...)
+#' list_versions()
+#' set_version(version=NULL)
+#' delete(confirm=TRUE)
+#' ```
+#' @section Arguments:
+#' - `plaintext`: For `encrypt`, the plaintext to encrypt.
+#' - `ciphertext`: For `decrypt`, the ciphertext to decrypt.
+#' - `digest`: For `sign`, a generated hash to sign. For `verify`, the digest to verify for authenticity.
+#' - `signature`: For `verify`, a signature to verify for authenticity.
+#' - `value`: For `wrap`, a symmetric key to be wrapped; for `unwrap`, the value to be unwrapped to obtain the symmetric key.
+#' - `as_raw`: For `decrypt` and `unwrap`, whether to return a character vector or a raw vector (the default).
+#' - `algorithm`: The algorithm to use for each operation. Note that the operation must be compatible with the key type.
+#' - `attributes`: For `update_attributes`, the new attributes for the object, such as the expiry date and activation date. A convenient way to provide this is via the [vault_object_attrs] helper function.
+#' - `...`: For `update_attributes`, additional key-specific properties to update. See [keys].
+#' - `version`: For `set_version`, the version ID or NULL for the current version.
+#' - `confirm`: For `delete`, whether to ask for confirmation before deleting the key.
+#'
+#' @section Details:
+#' The operations supported by a key will be those given by the `key_ops` argument when the key was created. By default, a new key supports all the operations listed above: encrypt/decrypt, sign/verify, and wrap/unwrap.
+#'
+#' A key can have multiple _versions_, which are automatically generated when a key is created with the same name as an existing key. By default, the most recent (current) version is used for key operations; use `list_versions` and `set_version` to change the version.
+#'
+#' @section Value:
+#' For the key operations, a raw vector (for `decrypt` and `unwrap`, if `as_raw=TRUE`) or character vector.
+#'
+#' For `list`, a vector of key version IDs.
+#'
+#' For `set_version`, the key object with the updated version.
+#'
+#' @seealso
+#' [keys]
+#'
+#' [Azure Key Vault documentation](https://docs.microsoft.com/en-us/azure/key-vault/),
+#' [Azure Key Vault API reference](https://docs.microsoft.com/en-us/rest/api/keyvault)
+#'
+#' @examples
+#' \dontrun{
+#'
+#' vault <- key_vault$new("mykeyvault")
+#'
+#' vault$keys$create("mynewkey")
+#' # new version of an existing key
+#' vault$keys$create("mynewkey", key_properties(type="RSA", rsa_key_size=4096))
+#'
+#' key <- vault$keys$get("mynewkey")
+#' vers <- key$list_versions()
+#' key$set_version(vers[2])
+#'
+#' plaintext <- "some secret text"
+#'
+#' ciphertext <- key$encrypt(plaintext)
+#' decrypted <- key$decrypt(ciphertext, as_raw=FALSE)
+#' decrypted == plaintext  # TRUE
+#'
+#' dig <- digest::digest(plaintext, "sha256", raw=TRUE)
+#' sig <- key$sign(dig)
+#' key$verify(sig, dig)  # TRUE
+#' 
+#' wraptext <- key$wrap(plaintext)
+#' unwrap_text <- key$unwrap(wraptext, as_raw=FALSE)
+#' plaintext == unwrap_text  # TRUE
+#'
+#' }
+#' @name keys
+#' @rdname keys
+NULL
+
 stored_key <- R6::R6Class("stored_key", inherit=stored_object,
 
 public=list(

man/keys.Rd

@@ -1,11 +1,13 @@
 % Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/keys.R
+% Please edit documentation in R/keys.R, R/stored_key.R
 \docType{class}
 \name{keys}
 \alias{keys}
 \title{Encryption keys in Key Vault}
 \description{
 This class represents the collection of encryption keys stored in a vault. It provides methods for managing keys, including creating, importing and deleting keys, and doing backups and restores. For operations with a specific key, see \link{key}.
+
+This class represents an encryption keys stored in a vault. It provides methods for carrying out operations, including encryption and decryption, signing and verification, and wrapping and unwrapping.
 }
 \section{Methods}{
 
@@ -19,6 +21,24 @@ list()
 backup(name)
 restore(backup)
 }
+
+
+This class provides the following methods:\preformatted{encrypt(plaintext, algorithm=c("RSA-OAEP", "RSA-OAEP-256", "RSA1_5"))
+decrypt(ciphertext, algorithm=c("RSA-OAEP", "RSA-OAEP-256", "RSA1_5"), as_raw=TRUE)
+sign(digest,
+     algorithm=c("PS256", "PS384", "PS512", "RS256", "RS384", "RS512",
+                 "ES256", "ES256K", "ES384", "ES512"))
+verify(signature, digest,
+       algorithm=c("PS256", "PS384", "PS512", "RS256", "RS384", "RS512",
+                   "ES256", "ES256K", "ES384", "ES512"))
+wrap(value, algorithm=c("RSA-OAEP", "RSA-OAEP-256", "RSA1_5"))
+unwrap(value, algorithm=c("RSA-OAEP", "RSA-OAEP-256", "RSA1_5"), as_raw=TRUE)
+
+update_attributes(attributes=vault_object_attrs(), ...)
+list_versions()
+set_version(version=NULL)
+delete(confirm=TRUE)
+}
 }
 
 \section{Arguments}{
@@ -33,6 +53,21 @@ restore(backup)
 \item \code{...}: For \code{create} and \code{import}, other named arguments which will be treated as tags.
 \item \code{backup}: For \code{restore}, a string representing the backup blob for a key.
 }
+
+
+\itemize{
+\item \code{plaintext}: For \code{encrypt}, the plaintext to encrypt.
+\item \code{ciphertext}: For \code{decrypt}, the ciphertext to decrypt.
+\item \code{digest}: For \code{sign}, a generated hash to sign. For \code{verify}, the digest to verify for authenticity.
+\item \code{signature}: For \code{verify}, a signature to verify for authenticity.
+\item \code{value}: For \code{wrap}, a symmetric key to be wrapped; for \code{unwrap}, the value to be unwrapped to obtain the symmetric key.
+\item \code{as_raw}: For \code{decrypt} and \code{unwrap}, whether to return a character vector or a raw vector (the default).
+\item \code{algorithm}: The algorithm to use for each operation. Note that the operation must be compatible with the key type.
+\item \code{attributes}: For \code{update_attributes}, the new attributes for the object, such as the expiry date and activation date. A convenient way to provide this is via the \link{vault_object_attrs} helper function.
+\item \code{...}: For \code{update_attributes}, additional key-specific properties to update. See \link{keys}.
+\item \code{version}: For \code{set_version}, the version ID or NULL for the current version.
+\item \code{confirm}: For \code{delete}, whether to ask for confirmation before deleting the key.
+}
 }
 
 \section{Value}{
@@ -42,6 +77,20 @@ For \code{get}, \code{create} and \code{import}, an object of class \code{stored
 For \code{list}, a vector of key names.
 
 For \code{backup}, a string representing the backup blob for a key. If the key has multiple versions, the blob will contain all versions.
+
+
+For the key operations, a raw vector (for \code{decrypt} and \code{unwrap}, if \code{as_raw=TRUE}) or character vector.
+
+For \code{list}, a vector of key version IDs.
+
+For \code{set_version}, the key object with the updated version.
+}
+
+\section{Details}{
+
+The operations supported by a key will be those given by the \code{key_ops} argument when the key was created. By default, a new key supports all the operations listed above: encrypt/decrypt, sign/verify, and wrap/unwrap.
+
+A key can have multiple \emph{versions}, which are automatically generated when a key is created with the same name as an existing key. By default, the most recent (current) version is used for key operations; use \code{list_versions} and \code{set_version} to change the version.
 }
 
 \examples{
@@ -79,11 +128,43 @@ bak <- vault$keys$backup("mynewkey")
 vault$keys$delete("mynewkey", confirm=FALSE)
 vault$keys$restore(bak)
 
+}
+\dontrun{
+
+vault <- key_vault$new("mykeyvault")
+
+vault$keys$create("mynewkey")
+# new version of an existing key
+vault$keys$create("mynewkey", key_properties(type="RSA", rsa_key_size=4096))
+
+key <- vault$keys$get("mynewkey")
+vers <- key$list_versions()
+key$set_version(vers[2])
+
+plaintext <- "some secret text"
+
+ciphertext <- key$encrypt(plaintext)
+decrypted <- key$decrypt(ciphertext, as_raw=FALSE)
+decrypted == plaintext  # TRUE
+
+dig <- digest::digest(plaintext, "sha256", raw=TRUE)
+sig <- key$sign(dig)
+key$verify(sig, dig)  # TRUE
+
+wraptext <- key$wrap(plaintext)
+unwrap_text <- key$unwrap(wraptext, as_raw=FALSE)
+plaintext == unwrap_text  # TRUE
+
 }
 }
 \seealso{
 \link{key}, \link{key_properties}, \link{vault_object_attrs}
 
+\href{https://docs.microsoft.com/en-us/azure/key-vault/}{Azure Key Vault documentation},
+\href{https://docs.microsoft.com/en-us/rest/api/keyvault}{Azure Key Vault API reference}
+
+\link{keys}
+
 \href{https://docs.microsoft.com/en-us/azure/key-vault/}{Azure Key Vault documentation},
 \href{https://docs.microsoft.com/en-us/rest/api/keyvault}{Azure Key Vault API reference}
 }