From d92a186f07af03f0a43abbb2028cffa390e5b182 Mon Sep 17 00:00:00 2001
From: Hong Ooi <hongooi@microsoft.com>
Date: Thu, 25 Apr 2019 19:43:59 +1000
Subject: [PATCH] add cert issuer methods

---
 R/certificates.R    | 52 ++++++++++++++++++++++++++++++++++++++++++---
 man/certificates.Rd | 28 +++++++++++++++++++++---
 2 files changed, 74 insertions(+), 6 deletions(-)

diff --git a/R/certificates.R b/R/certificates.R
index c63e9f1..3e90ec1 100644
--- a/R/certificates.R
+++ b/R/certificates.R
@@ -22,6 +22,10 @@
 #' restore(backup)
 #' get_contacts()
 #' set_contacts(email)
+#' add_issuer(issuer, provider, credentials=NULL, details=NULL)
+#' remove_issuer(issuer)
+#' get_issuer(issuer)
+#' list_issuers()
 #' ```
 #' @section Arguments:
 #' - `name`: The name of the certificate.
@@ -38,12 +42,18 @@
 #' - `wait`: For `create` and `import`, whether to wait until the certificate has been created before returning. If FALSE, you can check on the status of the certificate via the returned object's `sync` method.
 #' - `backup`: For `restore`, a string representing the backup blob for a key.
 #' - `email`: For `set_contacts`, the email addresses of the contacts.
+#' - `issuer`: For the issuer methods, the name by which to refer to an issuer.
+#' - `provider`: For `add_issuer`, the provider name as a string.
+#' - `credentials`: For `add_issuer`, the credentials for the issuer, if required. Should be a list containing the components `account_id` and `password`.
+#' - `details`: For `add_issuer`, the organisation details, if required. See the [Azure docs](https://docs.microsoft.com/en-us/rest/api/keyvault/setcertificateissuer/setcertificateissuer#administratordetails) for more information.
 #'
 #' @section Value:
 #' For `get`, `create` and `import`, an object of class `stored_certificate`, representing the certificate itself.
 #'
 #' For `list`, a vector of key names.
 #'
+#' For `add_issuer` and `get_issuer`, an object representing an issuer. For `list_issuers`, a list of such objects.
+#'
 #' For `backup`, a string representing the backup blob for a certificate. If the certificate has multiple versions, the blob will contain all versions.
 #'
 #' @seealso
@@ -57,15 +67,20 @@
 #'
 #' vault <- key_vault$new("mykeyvault")
 #'
-#' vault$certificates$create("mynewcert", wait=TRUE)
+#' vault$certificates$create("mynewcert", "CN=mydomain.com")
 #' vault$certificates$list()
 #' vault$certificates$get("mynewcert")
 #'
+#' # specifying some domain names
+#' vault$certificates$create("mynewcert", "CN=mydomain.com",
+#'     x509=cert_x509_properties(dns_names=c("mydomain.com", "otherdomain.com")))
+#'
 #' # specifying a validity period of 2 years (24 months)
-#' vault$certificates$create("mynewcert", x509=cert_x509_properties(valid=24))
+#' vault$certificates$create("mynewcert", "CN=mydomain.com",
+#'     x509=cert_x509_properties(valid=24))
 #'
 #' # setting management tags
-#' vault$certificates$create("mynewcert", tag1="a value", othertag="another value")
+#' vault$certificates$create("mynewcert", "CN=mydomain.com", tag1="a value", othertag="another value")
 #'
 #' # importing a cert from a PFX file
 #' vault$certificates$import("importedcert", "mycert.pfx")
@@ -79,6 +94,13 @@
 #' vault$certificates$set_contacts("username@mydomain.com")
 #' vault$certificates$get_contacts()
 #' 
+#' # add an issuer and then obtain a cert
+#' # this can take a long time, so set wait=FALSE to return immediately
+#' vault$certificates$add_issuer("newissuer", provider="OneCert")
+#' vault$certificates$create("issuedcert", "CN=mydomain.com",
+#'     issuer=cert_issuer_properties("newissuer"),
+#'     wait=FALSE)
+#'
 #' }
 #' @name certificates
 #' @aliases certificates certs
@@ -201,6 +223,30 @@ public=list(
         self$do_operation("contacts", http_verb="DELETE")
     },
 
+    add_issuer=function(issuer, provider, credentials=NULL, details=NULL)
+    {
+        op <- construct_path("issuers", issuer)
+        body <- list(provider=provider, credentials=credentials, org_details=details)
+        self$do_operation(op, body=body, encode="json", http_verb="PUT")
+    },
+
+    get_issuer=function(issuer)
+    {
+        op <- construct_path("issuers", issuer)
+        self$do_operation(op)
+    },
+
+    remove_issuer=function(issuer)
+    {
+        op <- construct_path("issuers", issuer)
+        self$do_operation(op, http_verb="DELETE")
+    },
+
+    list_issuers=function()
+    {
+        self$do_operation("issuers")
+    },
+
     do_operation=function(op="", ..., options=list())
     {
         url <- self$url
diff --git a/man/certificates.Rd b/man/certificates.Rd
index b2d04d1..df35832 100644
--- a/man/certificates.Rd
+++ b/man/certificates.Rd
@@ -25,6 +25,10 @@ backup(name)
 restore(backup)
 get_contacts()
 set_contacts(email)
+add_issuer(issuer, provider, credentials=NULL, details=NULL)
+remove_issuer(issuer)
+get_issuer(issuer)
+list_issuers()
 }
 }
 
@@ -45,6 +49,10 @@ set_contacts(email)
 \item \code{wait}: For \code{create} and \code{import}, whether to wait until the certificate has been created before returning. If FALSE, you can check on the status of the certificate via the returned object's \code{sync} method.
 \item \code{backup}: For \code{restore}, a string representing the backup blob for a key.
 \item \code{email}: For \code{set_contacts}, the email addresses of the contacts.
+\item \code{issuer}: For the issuer methods, the name by which to refer to an issuer.
+\item \code{provider}: For \code{add_issuer}, the provider name as a string.
+\item \code{credentials}: For \code{add_issuer}, the credentials for the issuer, if required. Should be a list containing the components \code{account_id} and \code{password}.
+\item \code{details}: For \code{add_issuer}, the organisation details, if required. See the \href{https://docs.microsoft.com/en-us/rest/api/keyvault/setcertificateissuer/setcertificateissuer#administratordetails}{Azure docs} for more information.
 }
 }
 
@@ -54,6 +62,8 @@ For \code{get}, \code{create} and \code{import}, an object of class \code{stored
 
 For \code{list}, a vector of key names.
 
+For \code{add_issuer} and \code{get_issuer}, an object representing an issuer. For \code{list_issuers}, a list of such objects.
+
 For \code{backup}, a string representing the backup blob for a certificate. If the certificate has multiple versions, the blob will contain all versions.
 }
 
@@ -62,15 +72,20 @@ For \code{backup}, a string representing the backup blob for a certificate. If t
 
 vault <- key_vault$new("mykeyvault")
 
-vault$certificates$create("mynewcert", wait=TRUE)
+vault$certificates$create("mynewcert", "CN=mydomain.com")
 vault$certificates$list()
 vault$certificates$get("mynewcert")
 
+# specifying some domain names
+vault$certificates$create("mynewcert", "CN=mydomain.com",
+    x509=cert_x509_properties(dns_names=c("mydomain.com", "otherdomain.com")))
+
 # specifying a validity period of 2 years (24 months)
-vault$certificates$create("mynewcert", x509=cert_x509_properties(valid=24))
+vault$certificates$create("mynewcert", "CN=mydomain.com",
+    x509=cert_x509_properties(valid=24))
 
 # setting management tags
-vault$certificates$create("mynewcert", tag1="a value", othertag="another value")
+vault$certificates$create("mynewcert", "CN=mydomain.com", tag1="a value", othertag="another value")
 
 # importing a cert from a PFX file
 vault$certificates$import("importedcert", "mycert.pfx")
@@ -84,6 +99,13 @@ vault$certificates$restore(bak)
 vault$certificates$set_contacts("username@mydomain.com")
 vault$certificates$get_contacts()
 
+# add an issuer and then obtain a cert
+# this can take a long time, so set wait=FALSE to return immediately
+vault$certificates$add_issuer("newissuer", provider="OneCert")
+vault$certificates$create("issuedcert", "CN=mydomain.com",
+    issuer=cert_issuer_properties("newissuer"),
+    wait=FALSE)
+
 }
 }
 \seealso{