New-DbaComputerCertificate, New-DbaComputerCertificateSigningRequest - Add -Provider to create the private key in a Key Storage Provider (#10722)

Author: andreasjordan

public/New-DbaComputerCertificate.ps1

@@ -6,7 +6,8 @@ function New-DbaComputerCertificate {
     .DESCRIPTION
         Creates a new computer certificate - self-signed or signed by an Active Directory CA, using the Web Server certificate.
 
-        By default, a key with a length of 2048 bits and a friendly name of "SQL Server" is generated.
+        By default, a key with a length of 2048 bits and a friendly name of "SQL Server" is generated. The private key
+        is created by the legacy Microsoft RSA SChannel Cryptographic Provider unless -Provider asks for a Key Storage Provider.
 
         This command was originally intended to help automate the process so that SSL certificates can be available for enforcing encryption on connections.
 
@@ -62,6 +63,12 @@ function New-DbaComputerCertificate {
         Defaults to 2048 bits which meets current industry security standards for production environments.
         4096 bits can be used for high-security environments, though it may slightly impact performance during SSL handshakes.
 
+    .PARAMETER Provider
+        Specifies the cryptographic provider that generates and holds the private key.
+        Defaults to "Microsoft RSA SChannel Cryptographic Provider", a legacy Cryptographic Service Provider (CSP) that creates the key with KeySpec AT_KEYEXCHANGE, which is what the Microsoft certificate requirements for SQL Server name.
+        Use "Microsoft Software Key Storage Provider" for a Cryptography Next Generation (CNG) key. SQL Server 2019 and later load such a key as well, and Set-DbaNetworkCertificate and Test-DbaNetworkCertificate handle both key types.
+        The key is generated on the machine that runs the command and travels with the PFX to a remote computer, so the provider is the same on the target.
+
     .PARAMETER Store
         Specifies the certificate store location where the certificate will be installed.
         Defaults to "LocalMachine" which makes certificates available to services like SQL Server.
@@ -213,6 +220,8 @@ function New-DbaComputerCertificate {
         [string]$FriendlyName = "SQL Server",
         [string]$CertificateTemplate = "WebServer",
         [int]$KeyLength = 2048,
+        [ValidateSet("Microsoft RSA SChannel Cryptographic Provider", "Microsoft Software Key Storage Provider")]
+        [string]$Provider = "Microsoft RSA SChannel Cryptographic Provider",
         [string]$Store = "LocalMachine",
         [string]$Folder = "My",
         [ValidateSet("EphemeralKeySet", "Exportable", "PersistKeySet", "UserProtected", "NonExportable")]
@@ -400,7 +409,10 @@ function New-DbaComputerCertificate {
                 Add-Content $certCfg 'Signature="$Windows NT$"'
                 Add-Content $certCfg "[NewRequest]"
                 Add-Content $certCfg "Subject = ""CN=$fqdn"""
-                Add-Content $certCfg "KeySpec = 1"
+                if ($Provider -eq "Microsoft RSA SChannel Cryptographic Provider") {
+                    # A legacy CSP key. KeySpec 1 is AT_KEYEXCHANGE, the KeySpec the Microsoft certificate requirements for SQL Server name.
+                    Add-Content $certCfg "KeySpec = 1"
+                }
                 Add-Content $certCfg "KeyLength = $KeyLength"
                 # Keep the source cert exportable whenever it must be copied to another host.
                 if ("NonExportable" -in $Flag -and -not $ClusterInstanceName -and $computer.IsLocalHost) {
@@ -414,8 +426,14 @@ function New-DbaComputerCertificate {
                 Add-Content $certCfg "PrivateKeyArchive = FALSE"
                 Add-Content $certCfg "UserProtected = FALSE"
                 Add-Content $certCfg "UseExistingKeySet = FALSE"
-                Add-Content $certCfg "ProviderName = ""Microsoft RSA SChannel Cryptographic Provider"""
-                Add-Content $certCfg "ProviderType = 12"
+                Add-Content $certCfg "ProviderName = ""$Provider"""
+                if ($Provider -eq "Microsoft RSA SChannel Cryptographic Provider") {
+                    # ProviderType 12 is PROV_RSA_SCHANNEL.
+                    Add-Content $certCfg "ProviderType = 12"
+                } else {
+                    # A Key Storage Provider has neither a provider type nor a KeySpec, it takes the key algorithm instead.
+                    Add-Content $certCfg "KeyAlgorithm = RSA"
+                }
                 if ($SelfSigned) {
                     Add-Content $certCfg "RequestType = Cert"
                     Add-Content $certCfg "NotBefore = $((Get-Date).ToShortDateString())"

public/New-DbaComputerCertificateSigningRequest.ps1

@@ -10,7 +10,7 @@ function New-DbaComputerCertificateSigningRequest {
 
         Supports both standalone SQL Server instances and cluster configurations, automatically resolving FQDNs and configuring appropriate DNS entries. The generated certificates work with SQL Server's encryption features including encrypted client connections, mirroring, and backup encryption scenarios.
 
-        By default, creates RSA certificates with 2048-bit keys, the minimum the dbatools network certificate commands accept as suitable for SQL Server, though this can be raised for stronger encryption requirements. All certificates are configured as machine certificates with the Microsoft RSA SChannel Cryptographic Provider for compatibility with SQL Server's encryption stack.
+        By default, creates RSA certificates with 2048-bit keys, the minimum the dbatools network certificate commands accept as suitable for SQL Server, though this can be raised for stronger encryption requirements. All certificates are configured as machine certificates, by default with the legacy Microsoft RSA SChannel Cryptographic Provider; -Provider switches the private key to the Microsoft Software Key Storage Provider.
 
     .PARAMETER ComputerName
         The target computer name hosting the SQL Server instance where the certificate will be installed. Accepts multiple computer names for batch processing.
@@ -35,6 +35,11 @@ function New-DbaComputerCertificateSigningRequest {
         Specifies the RSA key length in bits for the certificate. Defaults to 2048, the minimum key length Test-DbaNetworkCertificate accepts as suitable for SQL Server; 4096 is possible for stronger requirements.
         Higher key lengths provide stronger encryption but may impact SQL Server connection performance on older hardware.
 
+    .PARAMETER Provider
+        Specifies the cryptographic provider that generates and holds the private key of the request.
+        Defaults to "Microsoft RSA SChannel Cryptographic Provider", a legacy Cryptographic Service Provider (CSP) that creates the key with KeySpec AT_KEYEXCHANGE, which is what the Microsoft certificate requirements for SQL Server name.
+        Use "Microsoft Software Key Storage Provider" for a Cryptography Next Generation (CNG) key. SQL Server 2019 and later load such a key as well, and Set-DbaNetworkCertificate and Test-DbaNetworkCertificate handle both key types.
+
     .PARAMETER Dns
         Additional DNS names to include in the certificate's Subject Alternative Name (SAN) field. By default includes both short and FQDN names.
         Add extra DNS entries here if clients connect using aliases, load balancer names, or other DNS records that point to your SQL Server instance.
@@ -109,6 +114,8 @@ function New-DbaComputerCertificateSigningRequest {
         [string]$Path = (Get-DbatoolsConfigValue -FullName 'Path.DbatoolsExport'),
         [string]$FriendlyName = "SQL Server",
         [int]$KeyLength = 2048,
+        [ValidateSet("Microsoft RSA SChannel Cryptographic Provider", "Microsoft Software Key Storage Provider")]
+        [string]$Provider = "Microsoft RSA SChannel Cryptographic Provider",
         [string[]]$Dns,
         [switch]$EnableException
     )
@@ -228,7 +235,10 @@ function New-DbaComputerCertificateSigningRequest {
                 Add-Content $certCfg 'Signature="$Windows NT$"'
                 Add-Content $certCfg "[NewRequest]"
                 Add-Content $certCfg "Subject = ""CN=$fqdn"""
-                Add-Content $certCfg "KeySpec = 1"
+                if ($Provider -eq "Microsoft RSA SChannel Cryptographic Provider") {
+                    # A legacy CSP key. KeySpec 1 is AT_KEYEXCHANGE, the KeySpec the Microsoft certificate requirements for SQL Server name.
+                    Add-Content $certCfg "KeySpec = 1"
+                }
                 Add-Content $certCfg "KeyLength = $KeyLength"
                 Add-Content $certCfg "Exportable = TRUE"
                 Add-Content $certCfg "MachineKeySet = TRUE"
@@ -237,8 +247,14 @@ function New-DbaComputerCertificateSigningRequest {
                 Add-Content $certCfg "PrivateKeyArchive = FALSE"
                 Add-Content $certCfg "UserProtected = FALSE"
                 Add-Content $certCfg "UseExistingKeySet = FALSE"
-                Add-Content $certCfg "ProviderName = ""Microsoft RSA SChannel Cryptographic Provider"""
-                Add-Content $certCfg "ProviderType = 12"
+                Add-Content $certCfg "ProviderName = ""$Provider"""
+                if ($Provider -eq "Microsoft RSA SChannel Cryptographic Provider") {
+                    # ProviderType 12 is PROV_RSA_SCHANNEL.
+                    Add-Content $certCfg "ProviderType = 12"
+                } else {
+                    # A Key Storage Provider has neither a provider type nor a KeySpec, it takes the key algorithm instead.
+                    Add-Content $certCfg "KeyAlgorithm = RSA"
+                }
                 if ($SelfSigned) {
                     Add-Content $certCfg "RequestType = Cert"
                 } else {

tests/New-DbaComputerCertificate.Tests.ps1

@@ -20,6 +20,7 @@ Describe $CommandName -Tag UnitTests {
                 "FriendlyName",
                 "CertificateTemplate",
                 "KeyLength",
+                "Provider",
                 "Store",
                 "Folder",
                 "Flag",
@@ -87,11 +88,43 @@ Describe $CommandName -Tag UnitTests {
             $script:requestConfig | Should -Contain "Exportable = TRUE"
             $script:requestConfig | Should -Not -Contain "Exportable = FALSE"
         }
+
+        It "Writes a Key Storage Provider request when Provider asks for one" {
+            $splatKspCertificate = @{
+                ComputerName = "dbatools-review-remote"
+                CaServer     = "dbatools-ca"
+                CaName       = "dbatools-ca"
+                Provider     = "Microsoft Software Key Storage Provider"
+                WhatIf       = $true
+            }
+            $null = New-DbaComputerCertificate @splatKspCertificate
+
+            $script:requestConfig | Should -Contain "ProviderName = ""Microsoft Software Key Storage Provider"""
+            $script:requestConfig | Should -Contain "KeyAlgorithm = RSA"
+            $script:requestConfig | Should -Not -Contain "KeySpec = 1"
+            $script:requestConfig | Should -Not -Contain "ProviderType = 12"
+        }
+
+        It "Writes a legacy CSP request with KeySpec AT_KEYEXCHANGE by default" {
+            $splatDefaultCertificate = @{
+                ComputerName = "dbatools-review-remote"
+                CaServer     = "dbatools-ca"
+                CaName       = "dbatools-ca"
+                WhatIf       = $true
+            }
+            $null = New-DbaComputerCertificate @splatDefaultCertificate
+
+            $script:requestConfig | Should -Contain "ProviderName = ""Microsoft RSA SChannel Cryptographic Provider"""
+            $script:requestConfig | Should -Contain "ProviderType = 12"
+            $script:requestConfig | Should -Contain "KeySpec = 1"
+            $script:requestConfig | Should -Not -Contain "KeyAlgorithm = RSA"
+        }
     }
 }
 
-#Tests do not run in appveyor
-Describe $CommandName -Tag IntegrationTests -Skip:([bool]$env:appveyor) {
+# These tests used to be skipped when APPVEYOR is set, which the Azure lanes do as well. Creating a self-signed
+# certificate in LocalMachine\My works on the runners, so they run there now.
+Describe $CommandName -Tag IntegrationTests {
     Context "Can generate a new certificate with default settings" {
         BeforeAll {
             $defaultCert = New-DbaComputerCertificate -SelfSigned -EnableException
@@ -157,4 +190,62 @@ Describe $CommandName -Tag IntegrationTests -Skip:([bool]$env:appveyor) {
             "$($documentCert.EnhancedKeyUsageList)" -match "1\.3\.6\.1\.5\.5\.7\.3\.1" | Should -BeFalse
         }
     }
+
+    Context "Can generate a certificate with a Key Storage Provider key" {
+        BeforeAll {
+            $PSDefaultParameterValues["*-Dba*:EnableException"] = $true
+
+            # The command returns a copy of the certificate object without the key, so the private key is read from the store entry.
+            $kspCert = New-DbaComputerCertificate -SelfSigned -Provider "Microsoft Software Key Storage Provider"
+            $kspStoreCert = Get-ChildItem -Path "Cert:\LocalMachine\My\$($kspCert.Thumbprint)"
+            $kspKey = [System.Security.Cryptography.X509Certificates.RSACertificateExtensions]::GetRSAPrivateKey($kspStoreCert)
+
+            $cspCert = New-DbaComputerCertificate -SelfSigned
+            $cspStoreCert = Get-ChildItem -Path "Cert:\LocalMachine\My\$($cspCert.Thumbprint)"
+            $cspKey = [System.Security.Cryptography.X509Certificates.RSACertificateExtensions]::GetRSAPrivateKey($cspStoreCert)
+
+            # For a remote computer the command exports a PFX and imports it on the target. The provider has to survive that transfer.
+            # On CI the instance is local, so the transfer only happens against a lab whose instance runs on another computer.
+            $computerName = ([DbaInstanceParameter]$TestConfig.InstanceSingle).ComputerName
+            $remoteKspCert = New-DbaComputerCertificate -ComputerName $computerName -SelfSigned -Provider "Microsoft Software Key Storage Provider"
+            $readProvider = {
+                param ($Thumbprint)
+                $cert = Get-ChildItem -Path "Cert:\LocalMachine\My\$Thumbprint"
+                ([System.Security.Cryptography.X509Certificates.RSACertificateExtensions]::GetRSAPrivateKey($cert)).Key.Provider.Provider
+            }
+            $splatReadProvider = @{
+                ComputerName = $computerName
+                ScriptBlock  = $readProvider
+                ArgumentList = $remoteKspCert.Thumbprint
+                # Raw, because Invoke-Command2 otherwise wraps the string in an object that only has a Length.
+                Raw          = $true
+            }
+            $remoteProvider = Invoke-Command2 @splatReadProvider
+
+            $PSDefaultParameterValues.Remove("*-Dba*:EnableException")
+        }
+
+        AfterAll {
+            $PSDefaultParameterValues["*-Dba*:EnableException"] = $true
+            Remove-DbaComputerCertificate -Thumbprint $kspCert.Thumbprint, $cspCert.Thumbprint
+            Remove-DbaComputerCertificate -ComputerName $computerName -Thumbprint $remoteKspCert.Thumbprint
+            $PSDefaultParameterValues.Remove("*-Dba*:EnableException")
+        }
+
+        It "Holds the private key in the Key Storage Provider" {
+            $kspKey.Key.Provider.Provider | Should -Be "Microsoft Software Key Storage Provider"
+            Test-Path -Path "$env:ProgramData\Microsoft\Crypto\Keys\$($kspKey.Key.UniqueName)" -PathType Leaf | Should -BeTrue
+        }
+
+        It "Holds the private key in the legacy CSP with KeySpec AT_KEYEXCHANGE by default" {
+            $cspKey.Key.Provider.Provider | Should -Be "Microsoft RSA SChannel Cryptographic Provider"
+            # A legacy CSP key opened through CNG reports an AT_KEYEXCHANGE KeySpec as AllUsages, an AT_SIGNATURE one as Signing.
+            $cspKey.Key.KeyUsage | Should -Be "AllUsages"
+            Test-Path -Path "$env:ProgramData\Microsoft\Crypto\RSA\MachineKeys\$($cspKey.Key.UniqueName)" -PathType Leaf | Should -BeTrue
+        }
+
+        It "Keeps the Key Storage Provider key when the certificate is imported on a remote computer" {
+            $remoteProvider | Should -Be "Microsoft Software Key Storage Provider"
+        }
+    }
 }

tests/New-DbaComputerCertificateSigningRequest.Tests.ps1

@@ -17,6 +17,7 @@ Describe $CommandName -Tag UnitTests {
                 "Path",
                 "FriendlyName",
                 "KeyLength",
+                "Provider",
                 "Dns",
                 "EnableException"
             )
@@ -33,6 +34,7 @@ Describe $CommandName -Tag IntegrationTests {
         $requestPath = "$($TestConfig.Temp)\$CommandName-$(Get-Random)"
         $null = New-Item -Path $requestPath -ItemType Directory
         $requestFriendlyName = "dbatoolsci_csr_$(Get-Random)"
+        $kspRequestFriendlyName = "dbatoolsci_csr_ksp_$(Get-Random)"
 
         # We want to run all commands outside of the BeforeAll block without EnableException to be able to test for specific warnings.
         $PSDefaultParameterValues.Remove("*-Dba*:EnableException")
@@ -45,7 +47,7 @@ Describe $CommandName -Tag IntegrationTests {
         # certreq -new leaves the pending request with its private key in the REQUEST store of the local machine.
         $requestStore = New-Object System.Security.Cryptography.X509Certificates.X509Store("REQUEST", "LocalMachine")
         $requestStore.Open("ReadWrite")
-        foreach ($pendingRequest in ($requestStore.Certificates | Where-Object FriendlyName -eq $requestFriendlyName)) {
+        foreach ($pendingRequest in ($requestStore.Certificates | Where-Object FriendlyName -in $requestFriendlyName, $kspRequestFriendlyName)) {
             $requestStore.Remove($pendingRequest)
         }
         $requestStore.Close()
@@ -66,4 +68,20 @@ Describe $CommandName -Tag IntegrationTests {
         (certutil -dump $signingRequest.FullName) -join " " | Should -Match "Public Key Length: 2048 bits"
         $WarnVar | Should -BeNullOrEmpty
     }
+
+    It "Generates the key in the Key Storage Provider when Provider asks for it" {
+        # certreq keeps the key of a pending request with the request in LocalMachine\REQUEST, which is where the provider shows.
+        $splatKspRequest = @{
+            Path         = $requestPath
+            FriendlyName = $kspRequestFriendlyName
+            Provider     = "Microsoft Software Key Storage Provider"
+        }
+        $files = New-DbaComputerCertificateSigningRequest @splatKspRequest
+        $files.Count | Should -Be 2
+        $pendingRequest = Get-ChildItem -Path Cert:\LocalMachine\REQUEST | Where-Object FriendlyName -eq $kspRequestFriendlyName
+        $pendingRequest | Should -Not -BeNullOrEmpty
+        $privateKey = [System.Security.Cryptography.X509Certificates.RSACertificateExtensions]::GetRSAPrivateKey($pendingRequest)
+        $privateKey.Key.Provider.Provider | Should -Be "Microsoft Software Key Storage Provider"
+        $WarnVar | Should -BeNullOrEmpty
+    }
 }