Share via


Configure certificate signing of PowerShell serialization payloads in Exchange Server

APPLIES TO: yes-img-162016 yes-img-192019 yes-img-seSubscription Edition

Overview

Certificate-based signing of PowerShell serialization payloads is a defense-in-depth security feature to prevent malicious manipulation of serialized data to be exchanged via Exchange Management Shell (EMS) sessions. It's available on Exchange Server 2013, Exchange Server 2016 and Exchange Server 2019.

The feature was introduced with the January 2023 Exchange Server Security Update. It was shipped as disabled by default (opt-in), and needs to be enabled by the Exchange Server administrator. It can be enabled via a setting override (Exchange Server 2016 and Exchange Server 2019) or by the help of a registry value (Exchange Server 2013).

By installing the November 2023 (or later) Exchange Server Security Update, the feature is enabled by default (opt-out) on a per-server basis, and needs to be disabled by the Exchange Server administrator if you don't want to use it. Make sure that the prerequisites for enabling certificate signing of serialized data are fulfilled before installing the November 2023 (or later) Exchange Server Security Update. To disable the feature you need to create a new setting override that explicitly turns the feature off.

What is data serialization

Data serialization is the process of converting the state of an object into a form (stream of bytes) that can be persisted or transmitted to memory, a database, or a file. PowerShell, for example, uses serialization when passing .NET objects between sessions. After an object was submitted or stored, it can be reconstructed back to its previous format. This process is called deserialization.

If you want to learn more about data serialization in PowerShell, we recommend reading the How objects are sent to and from remote sessions blog post.

Prerequisites for enabling certificate signing of serialized data

There are some prerequisites that must be fulfilled prior certificate signing of PowerShell serialization payloads can be enabled without breaking connectivity between Exchange Servers:

  • All Exchange servers in your environment must run the January 2023 Exchange Server Security Update or a later one. If the feature is enabled in an environment that has Exchange servers, which don't support serialization signing, you might experience issues in server-to-server communication or when using the Exchange Management Shell.

  • All Exchange servers (except Edge Transport and Management Tools only servers) must have access to the Exchange Server Auth Certificate which must be valid and must not be expired.

    Tip

    You can use the MonitorExchangeAuthCertificate script to check if the Exchange Server Auth Certificate is valid. It can also be used to renew the OAuth certificate automatically or to replace it if it has already expired.

Validate that certificate signing of PowerShell serialization payloads is used

You can verify if certificate signing of PowerShell serialization payloads is enabled, by checking the DataSerialization log file, which is maintained by Exchange Server. You can find the log file in the following directory: <ExchangeInstallPath>\V15\Logging\Data\Serialization.

Exchange maintains one log file per process. If you open an Exchange Management Shell (EMS), a new log file is created. If you open a second EMS, another log file will be written. The log file naming syntax is DataSerialization<yyyyMMdd>-<N>.LOG. Each of the log files can be up to 10 MB in size. The maximum size of the serialization log directory is limited to 1 GB by default. Log files are deleted if they are older than 30 days.

The EventData column contains the process name and the indicator that shows, whether serialization signing is used or not.

Example of serialization signing in use:

"S:MSG=SerializationTypeConverter Initialized, Process Name = w3wp, SerializationSigningEnabled = True, IsCustomParserEnabled = True"

Example of serialization signing not in use:

"S:MSG=SerializationTypeConverter Initialized, Process Name = powershell, SerializationSigningEnabled = False, IsCustomParserEnabled = True"

Enable certificate signing of PowerShell serialization payloads

Important

It's not necessary to create the setting override when running the November 2023 (or later) Exchange Server Security Update. The certificate signing of PowerShell serialization payloads feature is enabled by default when running this build.

Enable when running Exchange Server 2016 and Exchange Server 2019

You must create a new setting override to enable certificate signing of PowerShell serialization payloads.

  1. Run the following command from an elevated Exchange Management Shell (EMS) on a server that's running Exchange Server in your environment:

    New-SettingOverride -Name "EnableSigningVerification" -Component Data -Section EnableSerializationDataSigning -Parameters @("Enabled=true") -Reason "Enabling Signing Verification"
    

    Note

    This command enables all servers that are running Exchange Server 2016 and Exchange Server 2019 in your environment for certificate signing of PowerShell serialization payloads. You don't need to run the command on every Exchange server.

  2. Refresh the VariantConfiguration argument by running the following command:

    Get-ExchangeDiagnosticInfo -Process Microsoft.Exchange.Directory.TopologyService -Component VariantConfiguration -Argument Refresh 
    
  3. It's required to restart the World Wide Web Publishing service and the Windows Process Activation Service on the Exchange server, on which the setting override was created. Run the following command from an elevated PowerShell window or restart the server:

    Restart-Service -Name W3SVC, WAS -Force 
    

Enable when running Exchange Server 2013

If you run Exchange Server 2013, certificate signing of PowerShell serialization payloads must be enabled by creating a registry value on each Exchange Server 2013.

  1. Create the registry value on an Exchange Server 2013 by running the following command:

    New-ItemProperty -Path HKLM:\SOFTWARE\Microsoft\ExchangeServer\v15\Diagnostics -Name "EnableSerializationDataSigning" -Value 1 -Type String
    
  2. It's required to restart the World Wide Web Publishing service and the Windows Process Activation Service on each Exchange 2013 server, on which the registry value was created. Run the following command from an elevated PowerShell window or restart the server:

    Restart-Service -Name W3SVC, WAS -Force 
    

Disable certificate signing of PowerShell serialization payloads

Disable when running Exchange Server 2016 and Exchange Server 2019

To disable the feature on Exchange Server 2016 or Exchange Server 2019, the setting override must be deleted or explicitly set to disabled.

Warning

Disabling certificate signing of PowerShell serialization payloads makes your server vulnerable to known Exchange vulnerabilities and weakens protection against unknown threats. We recommend leaving this feature enabled.

  1. Delete the setting override or set it explicitly to Enabled=false:

    When running the January 2023 SU to October 2023 Exchange SU, the setting override must be deleted to disable the feature.

    Run the following command from an elevated Exchange Management Shell:

    Get-SettingOverride -Identity "EnableSigningVerification" | Remove-SettingOverride
    

    or

    When running the November 2023 or later Exchange SU, a setting override must be created to explicitly disable the feature.

    Run the following command from an elevated Exchange Management Shell:

    New-SettingOverride -Name "DisableSigningVerification" -Component Data -Section EnableSerializationDataSigning -Parameters @("Enabled=false") -Reason "Disable Signing Verification"
    
  2. Refresh the VariantConfiguration argument by running the following command:

    Get-ExchangeDiagnosticInfo -Process Microsoft.Exchange.Directory.TopologyService -Component VariantConfiguration -Argument Refresh 
    
  3. It's required to restart the World Wide Web Publishing service and the Windows Process Activation Service on the Exchange server, on which the setting override was deleted or updated. Run the following command from an elevated PowerShell window or restart the server:

    Restart-Service -Name W3SVC, WAS -Force 
    
  4. Close the Exchange Management Shell (EMS) that was used to run the commands mentioned in the previous steps. This is important to apply the configuration immediately.

Disable when running Exchange Server 2013

To disable the feature on Exchange Server 2013, the registry value must be deleted to explicitly set to 0.

  1. Set the registry value to 0 on Exchange Server 2013 by running the following command:

    Set-ItemProperty -Path HKLM:\SOFTWARE\Microsoft\ExchangeServer\v15\Diagnostics -Name "EnableSerializationDataSigning" -Value 0
    
  2. It's required to restart the World Wide Web Publishing service and the Windows Process Activation Service on each Exchange 2013 server, on which the registry value was changed. Run the following command from an elevated PowerShell window or restart the server:

    Restart-Service -Name W3SVC, WAS -Force 
    

Known issues with certificate signing of serialized data

Important

Ensure to always install the latest Exchange Server update, as it resolves some of the issues listed in this section. Issues addressed by the latest update are marked with a checkmark.

  • ❌ If signing of PowerShell serialization payloads is enabled, an expired Auth Certificate will prevent the Get-ExchangeCertificate cmdlet from returning certificate details.

  • ✅ If signing of PowerShell serialization payloads is enabled, the Get-ExchangeCertificate cmdlet doesn't return a visible value when executed on a computer with only the Exchange Management Tools installed, regardless of the validity of the Auth Certificate.

  • ❌ Certain scripts included with Exchange Server, such as RedistributeActiveDatabases.ps1, may not function as expected under the following conditions:

    • The feature for signing PowerShell Serialization payloads is enabled.
    • You aren't using the default security groups provided by Exchange RBAC.
    • The script is run by a user who is not a member of the Organization Management role group.
  • The following PowerShell scripts don't function properly when executed on a computer that has only the Exchange Management Tools installed, without any other Exchange Server role. To resolve this issue, run the script on an Exchange Server with the mailbox role, using an elevated Exchange Management Shell (EMS).

    • RedistributeActiveDatabases.ps1
    • StartDagServerMaintenance.ps1
    • Manage-MetaCacheDatabase.ps1
    • Move-PublicFolderBranch.ps1
  • ❌ Some piped PowerShell cmdlets might fail to run on a computer that has only the Exchange Management Tools installed and no other Exchange Server role. To resolve this issue, use ForEach-Object as demonstrated in the examples or run them on an Exchange server with the mailbox role installed. This affects various cmdlet combinations, such as:

    • Get-Mailbox | Get-CalendarDiagnosticLog

    • Get-Mailbox | Get-MailboxFolderPermission

    • Get-Mailbox | Get-MailboxFolderStatistics

    • Get-MailboxDatabase | Get-MailboxStatistics

    • Get-MailboxDatabase | Get-Mailbox

    • Get-MailboxDatabase | Test-ExchangeSearch

    • Get-PublicFolderClientPermission | Remove-PublicFolderClientPermission

      If you want to use them on an Exchange Management Tools server (without any other Exchange Server role installed), you can work around this issue as shown here:

      Get-Mailbox | ForEach-Object { Get-CalendarDiagnosticLog -Identity $_.Name }
      Get-Mailbox | ForEach-Object { Get-MailboxFolderPermission -Identity $_.Name }
      Get-Mailbox | ForEach-Object { Get-MailboxFolderStatistics -Identity $_.Name }
      Get-MailboxDatabase | ForEach-Object { Get-MailboxStatistics -Database $_.Name }
      Get-MailboxDatabase | ForEach-Object { Get-Mailbox -Database $_.Name }
      Get-MailboxDatabase | ForEach-Object { Test-ExchangeSearch -MailboxDatabase $_.Name }
      Get-PublicFolderClientPermission \pf1 | ForEach-Object { Remove-PublicFolderClientPermission -Identity $_.Identity.ToString() -User $_.User.ToString() }