Improve docs and add sample for cert import (Azure#16610)

Resolves Azure#13043

Author: heaths

sdk/keyvault/Azure.Security.KeyVault.Certificates/samples/README.md

@@ -13,3 +13,4 @@ description: Samples for the Azure.Security.KeyVault.Certificates client library
 
 - [Setting, getting, updating, and deleting certificates](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/keyvault/Azure.Security.KeyVault.Certificates/samples/Sample1_HelloWorld.md)
 - [Listing certificates, certificate versions, and deleted certificates](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/keyvault/Azure.Security.KeyVault.Certificates/samples/Sample2_GetCertificates.md)
+- [Importing PKCS#12 (PFX) and PEM-formatted certificates](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/keyvault/Azure.Security.KeyVault.Certificates/samples/Sample2_ImportCertificate.md)

sdk/keyvault/Azure.Security.KeyVault.Certificates/samples/Sample1_HelloWorld.md

@@ -11,7 +11,7 @@ You can use the [DefaultAzureCredential][DefaultAzureCredential] to try a number
 In the sample below, you can set `keyVaultUrl` based on an environment variable, configuration setting, or any way that works for your application.
 
 ```C# Snippet:CertificatesSample1CertificateClient
-var client = new CertificateClient(new Uri(keyVaultUrl), new DefaultAzureCredential());
+CertificateClient client = new CertificateClient(new Uri(keyVaultUrl), new DefaultAzureCredential());
 ```
 
 ## Creating a certificate
@@ -36,7 +36,8 @@ while (!certOp.HasCompleted)
 We can now get the created certificate along with its policy from the Azure Key Vault.
 
 ```C# Snippet:CertificatesSample1GetCertificateWithPolicy
-KeyVaultCertificateWithPolicy certificate = client.GetCertificate(certName);
+Response<KeyVaultCertificateWithPolicy> certificateResponse = client.GetCertificate(certName);
+KeyVaultCertificateWithPolicy certificate = certificateResponse.Value;
 
 Debug.WriteLine($"Certificate was returned with name {certificate.Name} which expires {certificate.Properties.ExpiresOn}");
 ```
@@ -49,8 +50,8 @@ We find that the certificate has been compromised and we want to disable it so a
 CertificateProperties certificateProperties = certificate.Properties;
 certificateProperties.Enabled = false;
 
-KeyVaultCertificate updatedCert = client.UpdateCertificateProperties(certificateProperties);
-Debug.WriteLine($"Certificate enabled set to '{updatedCert.Properties.Enabled}'");
+Response<KeyVaultCertificate> updatedCertResponse = client.UpdateCertificateProperties(certificateProperties);
+Debug.WriteLine($"Certificate enabled set to '{updatedCertResponse.Value.Properties.Enabled}'");
 ```
 
 ## Creating a certificate with a new version

sdk/keyvault/Azure.Security.KeyVault.Certificates/samples/Sample2_GetCertificates.md

@@ -11,7 +11,7 @@ You can use the [DefaultAzureCredential][DefaultAzureCredential] to try a number
 In the sample below, you can set `keyVaultUrl` based on an environment variable, configuration setting, or any way that works for your application.
 
 ```C# Snippet:CertificatesSample2CertificateClient
-var client = new CertificateClient(new Uri(keyVaultUrl), new DefaultAzureCredential());
+CertificateClient client = new CertificateClient(new Uri(keyVaultUrl), new DefaultAzureCredential());
 ```
 
 ## Creating certificates

sdk/keyvault/Azure.Security.KeyVault.Certificates/samples/Sample2_ImportCertificate.md

@@ -0,0 +1,72 @@
+# Importing PKCS#12 (PFX) and PEM-formatted certificates
+
+This sample demonstrates how to import both PKCS#12 (PFX) and PEM-formatted certificates into Azure Key Vault.
+To get started, you'll need a URI to an Azure Key Vault. See the [README](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/keyvault/Azure.Security.KeyVault.Certificates/README.md) for links and instructions.
+
+## Creating a CertificateClient
+
+To create a new `CertificateClient` to import certificates, you need the endpoint to an Azure Key Vault and credentials.
+You can use the [DefaultAzureCredential][DefaultAzureCredential] to try a number of common authentication methods optimized for both running as a service and development.
+
+In the sample below, you can set `keyVaultUrl` based on an environment variable, configuration setting, or any way that works for your application.
+
+```C# Snippet:CertificatesSample3CertificateClient
+CertificateClient client = new CertificateClient(new Uri(keyVaultUrl), new DefaultAzureCredential());
+```
+
+## Import a PFX certificate
+
+Assuming you already have a PFX containing your key pair, you can import it into Key Vault.
+You can do this without setting a policy, but the policy is needed if you want the private key to be exportable
+or to configure actions when a certificate is close to expiration:
+
+```C# Snippet:CertificatesSample3ImportPfxCertificate
+string name = $"cert-{Guid.NewGuid()}";
+byte[] pfx = File.ReadAllBytes("certificate.pfx");
+ImportCertificateOptions importOptions = new ImportCertificateOptions(name, pfx)
+{
+    Policy = new CertificatePolicy(WellKnownIssuerNames.Self, "CN=contoso.com")
+    {
+        // Required when setting a policy; if no policy required, Pfx is assumed.
+        ContentType = CertificateContentType.Pkcs12,
+
+        // Optionally mark the private key exportable.
+        Exportable = true
+    }
+};
+
+client.ImportCertificate(importOptions);
+```
+
+## Import a PEM-formatted certificate
+
+PEM-formatted certificates are more common when using tools like _openssl_. To import a PEM-formatted certificate,
+you must set a `CertificatePolicy` that sets the `ContentType` to `CertificateContentType.Pem` or the certificate
+will fail to import:
+
+```C# Snippet:CertificatesSample3ImportPemCertificate
+string name = $"cert-{Guid.NewGuid()}";
+byte[] pem = File.ReadAllBytes("certificate.cer");
+ImportCertificateOptions importOptions = new ImportCertificateOptions(name, pem)
+{
+    Policy = new CertificatePolicy(WellKnownIssuerNames.Self, "CN=contoso.com")
+    {
+        // Required when the certificate bytes are a PEM-formatted certificate.
+        ContentType = CertificateContentType.Pem,
+
+        // Optionally mark the private key exportable.
+        Exportable = true
+    }
+};
+
+client.ImportCertificate(importOptions);
+```
+
+## Source
+
+To see the full example source, see:
+
+* [Synchronous Sample3_ImportCertificate.cs](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/keyvault/Azure.Security.KeyVault.Certificates/tests/samples/Sample3_ImportCertificate.cs)
+* [Asynchronous Sample3_ImportCertificateAsync.cs](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/keyvault/Azure.Security.KeyVault.Certificates/tests/samples/Sample3_ImportCertificateAsync.cs)
+
+[DefaultAzureCredential]: https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/identity/Azure.Identity/README.md

sdk/keyvault/Azure.Security.KeyVault.Certificates/src/CertificateClient.cs

@@ -668,7 +668,7 @@ public virtual async Task<Response<KeyVaultCertificateWithPolicy>> RestoreCertif
         }
 
         /// <summary>
-        /// Imports a pre-existing certificate to the key vault. The specified certificate must be in PFX or ASCII PEM format, and must contain the private key as well as the X.509 certificates. This operation requires the
+        /// Imports a pre-existing certificate to the key vault. The specified certificate must be in PFX or ASCII PEM-format, and must contain the private key as well as the X.509 certificates. This operation requires the
         /// certificates/import permission.
         /// </summary>
         /// <param name="importCertificateOptions">The details of the certificate to import to the key vault.</param>
@@ -697,7 +697,7 @@ public virtual Response<KeyVaultCertificateWithPolicy> ImportCertificate(ImportC
         }
 
         /// <summary>
-        /// Imports a pre-existing certificate to the key vault. The specified certificate must be in PFX or ASCII PEM format, and must contain the private key as well as the X.509 certificates. This operation requires the
+        /// Imports a pre-existing certificate to the key vault. The specified certificate must be in PFX or ASCII PEM-format, and must contain the private key as well as the X.509 certificates. This operation requires the
         /// certificates/import permission.
         /// </summary>
         /// <param name="importCertificateOptions">The details of the certificate to import to the key vault.</param>

sdk/keyvault/Azure.Security.KeyVault.Certificates/src/CertificatePolicy.cs

@@ -172,8 +172,13 @@ public string IssuerName
         }
 
         /// <summary>
-        /// Gets or sets the <see cref="CertificateContentType"/> of the certificate when downloaded from GetSecret.
+        /// Gets or sets the <see cref="CertificateContentType"/> of the certificate.
         /// </summary>
+        /// <remarks>
+        /// Set to <see cref="CertificateContentType.Pkcs12"/> when <see cref="KeyVaultCertificate.Cer"/> contains your raw PKCS#12/PFX bytes,
+        /// or to <see cref="CertificateContentType.Pem"/> when <see cref="KeyVaultCertificate.Cer"/> contains your ASCII PEM-encoded bytes.
+        /// If not specified, <see cref="CertificateContentType.Pkcs12"/> is assumed.
+        /// </remarks>
         public CertificateContentType? ContentType { get; set; }
 
         /// <summary>

sdk/keyvault/Azure.Security.KeyVault.Certificates/src/ImportCertificateOptions.cs

@@ -28,7 +28,12 @@ public class ImportCertificateOptions : IJsonSerializable
         /// Initializes a new instance of the <see cref="ImportCertificateOptions"/> class.
         /// </summary>
         /// <param name="name">A name for the imported certificate.</param>
-        /// <param name="certificate">The PFX or ASCII PEM formatted value of the certificate containing both the X.509 certificates and the private key.</param>
+        /// <param name="certificate">The PFX or ASCII PEM-formatted value of the certificate containing both the X.509 certificates and the private key.</param>
+        /// <remarks>
+        /// If importing an ASCII PEM-formatted certificate, you must also create a <see cref="CertificatePolicy"/> with <see cref="CertificatePolicy.ContentType"/>
+        /// set to <see cref="CertificateContentType.Pem"/>, and set the <see cref="Policy"/> property. If the <see cref="Policy"/> property or
+        /// <see cref="CertificatePolicy.ContentType"/> property is not set, <see cref="CertificateContentType.Pkcs12"/> is assumed and the import will fail.
+        /// </remarks>
         /// <exception cref="ArgumentException"><paramref name="name"/> is empty.</exception>
         /// <exception cref="ArgumentNullException"><paramref name="name"/> or <paramref name="certificate"/> is null.</exception>
         public ImportCertificateOptions(string name, byte[] certificate)
@@ -46,13 +51,16 @@ public ImportCertificateOptions(string name, byte[] certificate)
         public string Name { get; }
 
         /// <summary>
-        /// Gets the PFX or PEM formatted value of the certificate containing both the X.509 certificates and the private key.
+        /// Gets the PFX or ASCII PEM-formatted value of the certificate containing both the X.509 certificates and the private key.
         /// </summary>
         public byte[] Certificate { get; }
 
         /// <summary>
-        /// Gets the policy which governs the lifecycle of the imported certificate and its properties when it is rotated.
+        /// Gets or sets the policy which governs the lifecycle of the imported certificate and its properties when it is rotated.
         /// </summary>
+        /// <remarks>
+        /// If setting the policy, <see cref="CertificatePolicy.ContentType"/> must be set to a valid <see cref="CertificateContentType"/> value.
+        /// </remarks>
         public CertificatePolicy Policy { get; set; }
 
         /// <summary>

sdk/keyvault/Azure.Security.KeyVault.Certificates/tests/SampleFixture.cs

@@ -23,6 +23,7 @@ public class SampleFixture: SamplesBase<KeyVaultTestEnvironment>
 #pragma warning disable SA1402 // File may only contain a single type
     public partial class HelloWorld : SampleFixture { }
     public partial class GetCertificates : SampleFixture { }
+    public partial class ImportCertificate : SampleFixture { }
     public partial class Snippets : SampleFixture { }
 #pragma warning restore SA1402 // File may only contain a single type
 }

sdk/keyvault/Azure.Security.KeyVault.Certificates/tests/samples/Sample1_HelloWorld.cs

@@ -6,7 +6,6 @@
 using System;
 using System.Diagnostics;
 using System.Threading;
-using Azure.Security.KeyVault.Tests;
 
 namespace Azure.Security.KeyVault.Certificates.Samples
 {
@@ -22,7 +21,7 @@ public void HelloWorldSync()
             string keyVaultUrl = TestEnvironment.KeyVaultUrl;
 
             #region Snippet:CertificatesSample1CertificateClient
-            var client = new CertificateClient(new Uri(keyVaultUrl), new DefaultAzureCredential());
+            CertificateClient client = new CertificateClient(new Uri(keyVaultUrl), new DefaultAzureCredential());
             #endregion
 
             #region Snippet:CertificatesSample1CreateCertificate
@@ -38,7 +37,8 @@ public void HelloWorldSync()
             #endregion
 
             #region Snippet:CertificatesSample1GetCertificateWithPolicy
-            KeyVaultCertificateWithPolicy certificate = client.GetCertificate(certName);
+            Response<KeyVaultCertificateWithPolicy> certificateResponse = client.GetCertificate(certName);
+            KeyVaultCertificateWithPolicy certificate = certificateResponse.Value;
 
             Debug.WriteLine($"Certificate was returned with name {certificate.Name} which expires {certificate.Properties.ExpiresOn}");
             #endregion
@@ -47,8 +47,8 @@ public void HelloWorldSync()
             CertificateProperties certificateProperties = certificate.Properties;
             certificateProperties.Enabled = false;
 
-            KeyVaultCertificate updatedCert = client.UpdateCertificateProperties(certificateProperties);
-            Debug.WriteLine($"Certificate enabled set to '{updatedCert.Properties.Enabled}'");
+            Response<KeyVaultCertificate> updatedCertResponse = client.UpdateCertificateProperties(certificateProperties);
+            Debug.WriteLine($"Certificate enabled set to '{updatedCertResponse.Value.Properties.Enabled}'");
             #endregion
 
             #region Snippet:CertificatesSample1CreateCertificateWithNewVersion

sdk/keyvault/Azure.Security.KeyVault.Certificates/tests/samples/Sample1_HelloWorldAsync.cs

@@ -6,7 +6,6 @@
 using System;
 using System.Diagnostics;
 using System.Threading.Tasks;
-using Azure.Security.KeyVault.Tests;
 
 namespace Azure.Security.KeyVault.Certificates.Samples
 {
@@ -24,7 +23,7 @@ public async Task HelloWorldAsync()
             // Instantiate a certificate client that will be used to call the service. Notice that the client is using
             // default Azure credentials. To make default credentials work, ensure that environment variables 'AZURE_CLIENT_ID',
             // 'AZURE_CLIENT_KEY' and 'AZURE_TENANT_ID' are set with the service principal credentials.
-            var client = new CertificateClient(new Uri(keyVaultUrl), new DefaultAzureCredential());
+            CertificateClient client = new CertificateClient(new Uri(keyVaultUrl), new DefaultAzureCredential());
 
             // Let's create a self-signed certificate using the default policy. If the certificate
             // already exists in the Key Vault, then a new version of the key is created.
@@ -36,7 +35,8 @@ public async Task HelloWorldAsync()
             // amount of time, so applications should only wait on the operation to complete in the case the issuance time is well
             // known and within the scope of the application lifetime. In this case we are creating a self-signed certificate which
             // should be issued in a relatively short amount of time.
-            KeyVaultCertificateWithPolicy certificate = await certOp.WaitForCompletionAsync();
+            Response<KeyVaultCertificateWithPolicy> certificateResponse = await certOp.WaitForCompletionAsync();
+            KeyVaultCertificateWithPolicy certificate = certificateResponse.Value;
 
             // At some time later we could get the created certificate along with its policy from the Key Vault.
             certificate = await client.GetCertificateAsync(certName);
@@ -48,9 +48,9 @@ public async Task HelloWorldAsync()
             CertificateProperties certificateProperties = certificate.Properties;
             certificateProperties.Enabled = false;
 
-            KeyVaultCertificate updatedCert = await client.UpdateCertificatePropertiesAsync(certificateProperties);
+            Response<KeyVaultCertificate> updatedCertResponse = await client.UpdateCertificatePropertiesAsync(certificateProperties);
 
-            Debug.WriteLine($"Certificate enabled set to '{updatedCert.Properties.Enabled}'");
+            Debug.WriteLine($"Certificate enabled set to '{updatedCertResponse.Value.Properties.Enabled}'");
 
             // We need to create a new version of the certificate that applications can use to replace the compromised certificate.
             // Creating a certificate with the same name and policy as the compromised certificate will create another version of the