Add DownloadCertificate method to get X509Certificate2 (Azure#16815)

* Add DownloadCertificate method to get X509Certificate2

Resolves Azure#12083

* Add sample for just pubkey certificate

* Resolve feedback

* Return Response<X509Certificate2>

Author: heaths

sdk/keyvault/Azure.Security.KeyVault.Certificates/CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## 4.2.0-beta.3 (Unreleased)
 
+### Added
+
+- Added `DownloadCertificate` and `DownloadCertificateAsync` methods to get `X509Certificate2` with private key if permitted ([#12083](https://github.com/Azure/azure-sdk-for-net/issues/12083))
 
 ## 4.2.0-beta.2 (2020-10-06)
 

sdk/keyvault/Azure.Security.KeyVault.Certificates/api/Azure.Security.KeyVault.Certificates.netstandard2.0.cs

@@ -22,6 +22,8 @@ public CertificateClient(System.Uri vaultUri, Azure.Core.TokenCredential credent
         public virtual System.Threading.Tasks.Task<Azure.Response<System.Collections.Generic.IList<Azure.Security.KeyVault.Certificates.CertificateContact>>> DeleteContactsAsync(System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
         public virtual Azure.Response<Azure.Security.KeyVault.Certificates.CertificateIssuer> DeleteIssuer(string issuerName, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
         public virtual System.Threading.Tasks.Task<Azure.Response<Azure.Security.KeyVault.Certificates.CertificateIssuer>> DeleteIssuerAsync(string issuerName, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
+        public virtual Azure.Response<System.Security.Cryptography.X509Certificates.X509Certificate2> DownloadCertificate(string certificateName, string version = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
+        public virtual System.Threading.Tasks.Task<Azure.Response<System.Security.Cryptography.X509Certificates.X509Certificate2>> DownloadCertificateAsync(string certificateName, string version = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
         public virtual Azure.Response<Azure.Security.KeyVault.Certificates.KeyVaultCertificateWithPolicy> GetCertificate(string certificateName, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
         public virtual System.Threading.Tasks.Task<Azure.Response<Azure.Security.KeyVault.Certificates.KeyVaultCertificateWithPolicy>> GetCertificateAsync(string certificateName, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
         public virtual Azure.Security.KeyVault.Certificates.CertificateOperation GetCertificateOperation(string certificateName, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }

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

@@ -1,9 +1,11 @@
-// Copyright (c) Microsoft Corporation. All rights reserved.
+// Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
 using System;
 using System.Collections.Generic;
 using System.Globalization;
+using System.Security.Cryptography;
+using System.Security.Cryptography.X509Certificates;
 using System.Threading;
 using System.Threading.Tasks;
 using Azure.Core;
@@ -152,6 +154,104 @@ public virtual async Task<CertificateOperation> StartCreateCertificateAsync(stri
             }
         }
 
+#pragma warning disable AZC0015 // Unexpected client method return type.
+        /// <summary>
+        /// Creates an <see cref="X509Certificate2"/> from the specified certificate.
+        /// </summary>
+        /// <remarks>
+        /// Because <see cref="KeyVaultCertificate.Cer"/> contains only the public key, this method attempts to download the managed secret
+        /// that contains the full certificate. If you do not have permissions to get the secret,
+        /// <see cref="RequestFailedException"/> will be thrown with an appropriate error response.
+        /// If you want an <see cref="X509Certificate2"/> with only the public key, instantiate it passing only the
+        /// <see cref="KeyVaultCertificate.Cer"/> property.
+        /// </remarks>
+        /// <param name="certificateName">The name of the certificate to download.</param>
+        /// <param name="version">Optional version of a certificate to download.</param>
+        /// <param name="cancellationToken">A <see cref="CancellationToken"/> controlling the request lifetime.</param>
+        /// <returns>An <see cref="X509Certificate2"/> from the specified certificate.</returns>
+        /// <exception cref="ArgumentException"><paramref name="certificateName"/> is empty.</exception>
+        /// <exception cref="ArgumentNullException"><paramref name="certificateName"/> is null.</exception>
+        /// <exception cref="InvalidOperationException">The managed secret did not contain a certificate.</exception>
+        /// <exception cref="RequestFailedException">The request failed. See <see cref="RequestFailedException.ErrorCode"/> and the exception message for details.</exception>
+        public virtual Response<X509Certificate2> DownloadCertificate(string certificateName, string version = null, CancellationToken cancellationToken = default)
+        {
+            Argument.AssertNotNullOrEmpty(certificateName, nameof(certificateName));
+
+            using DiagnosticScope scope = _pipeline.CreateScope($"{nameof(CertificateClient)}.{nameof(DownloadCertificate)}");
+            scope.AddAttribute("certificate", certificateName);
+            scope.Start();
+
+            try
+            {
+                KeyVaultCertificateWithPolicy certificate = _pipeline.SendRequest(RequestMethod.Get, () => new KeyVaultCertificateWithPolicy(), cancellationToken, CertificatesPath, certificateName, "/", version);
+                Response<KeyVaultSecret> secretResponse = _pipeline.SendRequest(RequestMethod.Get, () => new KeyVaultSecret(), certificate.SecretId, cancellationToken);
+
+                string value = secretResponse.Value.Value;
+                if (string.IsNullOrEmpty(value))
+                {
+                    throw new InvalidOperationException($"Secret {certificate.SecretId} contains no value");
+                }
+
+                byte[] rawData = Convert.FromBase64String(value);
+
+                return Response.FromValue(new X509Certificate2(rawData), secretResponse.GetRawResponse());
+            }
+            catch (Exception e)
+            {
+                scope.Failed(e);
+                throw;
+            }
+        }
+
+        /// <summary>
+        /// Creates an <see cref="X509Certificate2"/> from the specified certificate.
+        /// </summary>
+        /// <remarks>
+        /// Because <see cref="KeyVaultCertificate.Cer"/> contains only the public key, this method attempts to download the managed secret
+        /// that contains the full certificate. If you do not have permissions to get the secret,
+        /// <see cref="RequestFailedException"/> will be thrown with an appropriate error response.
+        /// If you want an <see cref="X509Certificate2"/> with only the public key, instantiate it passing only the
+        /// <see cref="KeyVaultCertificate.Cer"/> property.
+        /// </remarks>
+        /// <param name="certificateName">The name of the certificate to download.</param>
+        /// <param name="version">Optional version of a certificate to download.</param>
+        /// <param name="cancellationToken">A <see cref="CancellationToken"/> controlling the request lifetime.</param>
+        /// <returns>An <see cref="X509Certificate2"/> from the specified certificate.</returns>
+        /// <exception cref="ArgumentException"><paramref name="certificateName"/> is empty.</exception>
+        /// <exception cref="ArgumentNullException"><paramref name="certificateName"/> is null.</exception>
+        /// <exception cref="InvalidOperationException">The managed secret did not contain a certificate.</exception>
+        /// <exception cref="RequestFailedException">The request failed. See <see cref="RequestFailedException.ErrorCode"/> and the exception message for details.</exception>
+        public virtual async Task<Response<X509Certificate2>> DownloadCertificateAsync(string certificateName, string version = null, CancellationToken cancellationToken = default)
+        {
+            Argument.AssertNotNullOrEmpty(certificateName, nameof(certificateName));
+
+            using DiagnosticScope scope = _pipeline.CreateScope($"{nameof(CertificateClient)}.{nameof(DownloadCertificate)}");
+            scope.AddAttribute("certificate", certificateName);
+            scope.Start();
+
+            try
+            {
+                KeyVaultCertificateWithPolicy certificate = await _pipeline.SendRequestAsync(RequestMethod.Get, () => new KeyVaultCertificateWithPolicy(), cancellationToken, CertificatesPath, certificateName, "/", version).ConfigureAwait(false);
+                Response<KeyVaultSecret> secretResponse = await _pipeline.SendRequestAsync(RequestMethod.Get, () => new KeyVaultSecret(), certificate.SecretId, cancellationToken).ConfigureAwait(false);
+
+                string value = secretResponse.Value.Value;
+                if (string.IsNullOrEmpty(value))
+                {
+                    throw new InvalidOperationException($"Secret {certificate.SecretId} contains no value");
+                }
+
+                byte[] rawData = Convert.FromBase64String(value);
+
+                return Response.FromValue(new X509Certificate2(rawData), secretResponse.GetRawResponse());
+            }
+            catch (Exception e)
+            {
+                scope.Failed(e);
+                throw;
+            }
+        }
+#pragma warning restore AZC0015 // Unexpected client method return type.
+
         /// <summary>
         /// Returns the latest version of the <see cref="KeyVaultCertificate"/> along with its <see cref="CertificatePolicy"/>. This operation requires the certificates/get permission.
         /// </summary>

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

@@ -0,0 +1,36 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+using System.Text.Json;
+
+namespace Azure.Security.KeyVault.Certificates
+{
+    internal class KeyVaultSecret : IJsonDeserializable
+    {
+        private const string ValuePropertyName = "value";
+
+        internal KeyVaultSecret()
+        {
+        }
+
+        public string Value { get; internal set; }
+
+        internal virtual void ReadProperty(JsonProperty prop)
+        {
+            switch (prop.Name)
+            {
+                case ValuePropertyName:
+                    Value = prop.Value.GetString();
+                    break;
+            }
+        }
+
+        void IJsonDeserializable.ReadProperties(JsonElement json)
+        {
+            foreach (JsonProperty prop in json.EnumerateObject())
+            {
+                ReadProperty(prop);
+            }
+        }
+    }
+}

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

@@ -17,6 +17,7 @@
 using System.Collections.Generic;
 using System.IO;
 using System.Linq;
+using System.Security.Cryptography;
 using System.Security.Cryptography.X509Certificates;
 using System.Text;
 using System.Threading;
@@ -739,6 +740,101 @@ public async Task VerifyUpdateCertificatePolicy()
             Assert.AreEqual(certificatePolicy.KeySize, updatePolicy.KeySize);
         }
 
+        [Test]
+        public async Task DownloadLatestCertificate()
+        {
+            string name = Recording.GenerateId();
+            CertificatePolicy policy = new CertificatePolicy
+            {
+                IssuerName = WellKnownIssuerNames.Self,
+                Subject = "CN=default",
+                KeyType = CertificateKeyType.Rsa,
+                Exportable = true,
+                ReuseKey = false,
+                KeyUsage =
+                {
+                    CertificateKeyUsage.DataEncipherment,
+                    CertificateKeyUsage.DigitalSignature,
+                },
+                CertificateTransparency = false,
+                ContentType = CertificateContentType.Pkcs12,
+            };
+
+            CertificateOperation operation = await Client.StartCreateCertificateAsync(name, policy);
+            RegisterForCleanup(name);
+
+            await operation.WaitForCompletionAsync();
+
+            KeyVaultCertificate certificate = await Client.GetCertificateAsync(name);
+
+            using X509Certificate2 pub = new X509Certificate2(certificate.Cer);
+            using RSA pubkey = (RSA)pub.PublicKey.Key;
+
+            byte[] plaintext = Encoding.UTF8.GetBytes("Hello, world!");
+            byte[] ciphertext = pubkey.Encrypt(plaintext, RSAEncryptionPadding.Pkcs1);
+
+            using X509Certificate2 x509certificate = await Client.DownloadCertificateAsync(name);
+            Assert.IsTrue(x509certificate.HasPrivateKey);
+
+            using RSA rsa = (RSA)x509certificate.PrivateKey;
+            byte[] decrypted = rsa.Decrypt(ciphertext, RSAEncryptionPadding.Pkcs1);
+
+            CollectionAssert.AreEqual(plaintext, decrypted);
+        }
+
+        [Test]
+        public async Task DownloadVersionedCertificate()
+        {
+            string name = Recording.GenerateId();
+            CertificatePolicy policy = new CertificatePolicy
+            {
+                IssuerName = WellKnownIssuerNames.Self,
+                Subject = "CN=default",
+                KeyType = CertificateKeyType.Rsa,
+                Exportable = true,
+                ReuseKey = false,
+                KeyUsage =
+                {
+                    CertificateKeyUsage.DataEncipherment,
+                    CertificateKeyUsage.DigitalSignature,
+                },
+                CertificateTransparency = false,
+                ContentType = CertificateContentType.Pkcs12,
+            };
+
+            CertificateOperation operation = await Client.StartCreateCertificateAsync(name, policy);
+            RegisterForCleanup(name);
+
+            await operation.WaitForCompletionAsync();
+
+            KeyVaultCertificate certificate = await Client.GetCertificateAsync(name);
+            string version = certificate.Properties.Version;
+
+            using X509Certificate2 pub = new X509Certificate2(certificate.Cer);
+            using RSA pubkey = (RSA)pub.PublicKey.Key;
+
+            byte[] plaintext = Encoding.UTF8.GetBytes("Hello, world!");
+            byte[] ciphertext = pubkey.Encrypt(plaintext, RSAEncryptionPadding.Pkcs1);
+
+            // Create a new certificate version that is not exportable just to further prove we are not downloading it.
+            policy.Exportable = false;
+            operation = await Client.StartCreateCertificateAsync(name, policy);
+
+            await operation.WaitForCompletionAsync();
+
+            certificate = await Client.GetCertificateAsync(name);
+            Assert.AreNotEqual(version, certificate.Properties.Version);
+
+            // Now download the certificate and test decryption.
+            using X509Certificate2 x509certificate = await Client.DownloadCertificateAsync(name, version);
+            Assert.IsTrue(x509certificate.HasPrivateKey);
+
+            using RSA rsa = (RSA)x509certificate.PrivateKey;
+            byte[] decrypted = rsa.Decrypt(ciphertext, RSAEncryptionPadding.Pkcs1);
+
+            CollectionAssert.AreEqual(plaintext, decrypted);
+        }
+
         private static CertificatePolicy DefaultPolicy => new CertificatePolicy
         {
             IssuerName = WellKnownIssuerNames.Self,