Add-DbaAgDatabase, New-DbaAvailabilityGroup - auto-copy TDE certificate to replicas (#10237)

Author: andreasjordan

public/Add-DbaAgDatabase.ps1

@@ -83,6 +83,12 @@ function Add-DbaAgDatabase {
         When enabled, Restore-DbaDatabase uses the replica's default data and log directories instead of attempting to replicate the primary's folder structure.
         This is automatically set to true when the primary and replica servers run on different operating system platforms (e.g., Windows primary with Linux replica).
 
+    .PARAMETER MasterKeySecurePassword
+        Password for creating or opening the database master key on secondary replicas when adding TDE-encrypted databases.
+        When a database is protected by Transparent Data Encryption (TDE), the certificate used to protect the Database Encryption Key must exist on every secondary replica.
+        Providing this parameter together with SharedPath allows the command to automatically copy the TDE certificate from the primary to each secondary replica.
+        If the secondary already has a master key, this password is used to create one if it is missing.
+
     .PARAMETER WhatIf
         Shows what would happen if the command were to run. No actions are actually performed.
 
@@ -242,6 +248,9 @@ function Add-DbaAgDatabase {
         [switch]$SkipReuseSourceFolderStructure,
         [Parameter(ParameterSetName = 'NonPipeline')]
         [Parameter(ParameterSetName = 'Pipeline')]
+        [Security.SecureString]$MasterKeySecurePassword,
+        [Parameter(ParameterSetName = 'NonPipeline')]
+        [Parameter(ParameterSetName = 'Pipeline')]
         [switch]$EnableException
     )
 
@@ -365,6 +374,49 @@ function Add-DbaAgDatabase {
                 }
             }
 
+            # For TDE-encrypted databases, the master certificate must exist on every secondary replica
+            # before a backup can be restored or automatic seeding can succeed.
+            if ($db.EncryptionEnabled -and $db.HasDatabaseEncryptionKey -and $db.DatabaseEncryptionKey.EncryptorType -eq "ServerCertificate") {
+                $encryptorName = $db.DatabaseEncryptionKey.EncryptorName
+                Write-Message -Level Verbose -Message "Database $($db.Name) is TDE-encrypted using certificate '$encryptorName'. Checking secondary replicas."
+                if ($SharedPath) {
+                    $failure = $false
+                    foreach ($replicaName in $replicaServerSMO.Keys) {
+                        $replicaServer = $replicaServerSMO[$replicaName]
+                        $existingCert = Get-DbaDbCertificate -SqlInstance $replicaServer -Database master -Certificate $encryptorName
+                        if (-not $existingCert) {
+                            if ($Pscmdlet.ShouldProcess($replicaServer, "Copy TDE certificate '$encryptorName' from primary to replica $replicaName")) {
+                                try {
+                                    Write-Message -Level Verbose -Message "TDE certificate '$encryptorName' not found on $replicaName. Copying from primary."
+                                    $splatTdeCert = @{
+                                        Source          = $server
+                                        Destination     = $replicaServer
+                                        Database        = "master"
+                                        Certificate     = $encryptorName
+                                        SharedPath      = $SharedPath
+                                        EnableException = $true
+                                    }
+                                    if ($MasterKeySecurePassword) {
+                                        $splatTdeCert.MasterKeyPassword = $MasterKeySecurePassword
+                                    }
+                                    $null = Copy-DbaDbCertificate @splatTdeCert
+                                } catch {
+                                    $failure = $true
+                                    Stop-Function -Message "Failed to copy TDE certificate '$encryptorName' to replica $replicaName." -ErrorRecord $_ -Continue
+                                }
+                            }
+                        } else {
+                            Write-Message -Level Verbose -Message "TDE certificate '$encryptorName' already exists on replica $replicaName."
+                        }
+                    }
+                    if ($failure) {
+                        Stop-Function -Message "Failed to copy TDE certificate to all replicas for database $($db.Name)." -Continue
+                    }
+                } else {
+                    Write-Message -Level Warning -Message "Database $($db.Name) is TDE-encrypted with certificate '$encryptorName', but no SharedPath was provided. The TDE certificate must exist on all secondary replicas before the database can be added. Use -SharedPath and optionally -MasterKeySecurePassword to enable automatic certificate copying."
+                }
+            }
+
             $progress['Status'] = "Step 2/5: Running backup and restore if needed"
             Write-Message -Level Verbose -Message $progress['Status']
             Write-Progress @progress

public/New-DbaAvailabilityGroup.ps1

@@ -172,6 +172,12 @@ function New-DbaAvailabilityGroup {
         Manual (default) uses backup/restore through shared storage, Automatic uses direct network streaming.
         Use Automatic for SQL Server 2016+ to simplify setup when network bandwidth is sufficient and shared storage is limited.
 
+    .PARAMETER MasterKeySecurePassword
+        Password for creating the database master key on secondary replicas when adding TDE-encrypted databases.
+        When databases protected by Transparent Data Encryption (TDE) are added to the availability group, the TDE certificate
+        in the primary's master database must be copied to each secondary. Providing this parameter alongside SharedPath enables
+        automatic certificate copying. If a secondary replica is missing a master key, this password is used to create one.
+
     .PARAMETER Certificate
         Specifies the certificate name for endpoint authentication instead of Windows authentication.
         Both endpoints must have matching certificates with corresponding public/private key pairs.
@@ -395,6 +401,7 @@ function New-DbaAvailabilityGroup {
         [int]$Port = 1433,
         [switch]$Dhcp,
         [string]$ClusterConnectionOption,
+        [Security.SecureString]$MasterKeySecurePassword,
         [switch]$EnableException
     )
     begin {
@@ -791,6 +798,7 @@ function New-DbaAvailabilityGroup {
                 }
                 if ($SeedingMode) { $addDatabaseParams['SeedingMode'] = $SeedingMode }
                 if ($SharedPath) { $addDatabaseParams['SharedPath'] = $SharedPath }
+                if ($MasterKeySecurePassword) { $addDatabaseParams['MasterKeySecurePassword'] = $MasterKeySecurePassword }
                 try {
                     $null = Add-DbaAgDatabase @addDatabaseParams
                 } catch {

tests/Add-DbaAgDatabase.Tests.ps1

@@ -24,6 +24,7 @@ Describe $CommandName -Tag UnitTests {
                 "AdvancedBackupParams",
                 "NoWait",
                 "SkipReuseSourceFolderStructure",
+                "MasterKeySecurePassword",
                 "EnableException"
             )
             Compare-Object -ReferenceObject $expectedParameters -DifferenceObject $hasParameters | Should -BeNullOrEmpty

tests/New-DbaAvailabilityGroup.Tests.ps1

@@ -45,6 +45,7 @@ Describe $CommandName -Tag UnitTests {
                 "Port",
                 "Dhcp",
                 "ClusterConnectionOption",
+                "MasterKeySecurePassword",
                 "EnableException"
             )
             Compare-Object -ReferenceObject $expectedParameters -DifferenceObject $hasParameters | Should -BeNullOrEmpty