Applies to: Exchange Server 2013

Topic Last Modified: 2012-10-17

Script security in the Exchange Management Shell helps prevent harmful or otherwise unwanted scripts from running in your organization. Options are available to modify script security to meet the requirements of your organization.

You typically encounter scripts from several sources: yourself, another person in your organization, and script writers from outside your organization, such as the Internet. If you write a script, you trust the script to do what it's designed to do. If you share the script with other administrators in your organization, they too may trust the script because they trust you.

When scripts come from other sources, such as the Internet, script security is a concern. The only way that you can trust scripts from sources unknown to your organization is to inspect the script code directly and test it in an isolated lab environment. Although this process can be time consuming and tedious, we recommend this practice to prevent unintentional execution of malicious or destructive code.

The Shell supports the recommended use of digital signatures to make sure a script isn't altered after the script is created. For more information about digital signatures, see "Code-signing basics" later in this topic.

Script execution modes

Four modes of script execution in the Shell control how scripts are used, depending on how they are signed and if they are from known or unknown sources. The following table describes each script execution mode.

Important:
The remote Shell requires that the script execution mode be set to RemotedSigned or Unrestricted. For more information about the remote Shell, see Exchange Management Shell.

Script execution modes

Mode Description

Restricted mode

No scripts will run, even if they are signed by a trusted publisher. This is the default script execution mode.

AllSigned mode

All scripts must be digitally signed by a trusted publisher before they will run.

RemoteSigned mode

All scripts locally created will run. Scripts downloaded from remote locations, such as the Internet, that can't be trusted, won't run.

Unrestricted mode

All scripts, regardless of whether they are digitally signed or trusted, will run. We don't recommend the Unrestricted mode unless you're running the script in a controlled test environment and not in a production environment.

To change the script execution mode from the default Restricted script execution mode, use the Set-ExecutionPolicy cmdlet in the Shell. This example changes the execution policy to RemotedSigned mode.

Copy Code
Set-ExecutionPolicy RemotedSigned

The Shell recognizes the change to the policy immediately.

Note:
If you have user access control enabled, you must open the Shell with elevated permissions to set the execution policy. To open the Shell with elevated permissions, right-click the Shell icon and select Run as administrator.

Large organizations that want to set a consistent script execution mode for all computers running the Shell should apply the script execution mode setting by using an Active Directory Group Policy. You configure the Active Directory Group Policy to set the ExecutionPolicy value located under the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell registry key to the desired script execution mode.

Caution:
Incorrectly editing the registry can cause serious problems that may require you to reinstall your operating system. Problems resulting from editing the registry incorrectly may not be able to be resolved. Before editing the registry, back up any valuable data.

Code-signing basics

Digital signatures are created by using a public-key signature algorithm that uses two different cryptographic keys called a key pair: the public key and the private key. The private key is known only to its owner, and the public key is available to anyone. In digital signatures, the private key generates the signature, and the corresponding public key validates the signature.

A certificate is a digital document that's generally used for authentication and to help secure information on open networks. A certificate securely binds a public key to the entity that holds the corresponding private key. Certificates are digitally signed by the issuing certification authority (CA). By using a code-signing certificate, the author of the script adds a digital signature to the script file. During this process, a one-way hash of the script is created and encrypted by using the private key. The encrypted hash is a digital signature string that's added to the script file. This digital signature string is commented out so that it doesn't interfere with script functionality.

When this script is run in a Shell environment where code signing is required, a new one-way hash of the script file is produced. The one-way hash is compared to the encrypted hash included with the script file after it's decrypted by using the public key. If the script wasn't altered in any way after it was signed, the hashes will match. The computer then tries to verify that the signature is from a trusted publisher by building a certificate chain to a trusted CA. If the trust is verified, the script runs.

Whether a script is from a trusted source depends on the origin of the code-signing certificate used to digitally sign the script. There are generally two types of certificates:

  • Certificates issued by a trusted CA   The CA verifies the identity of the requestor before it issues a code-signing certificate. The issuing authority can be an external, public third party that sells certificates or an internal CA hosted by your organization. If you sign a script by using this kind of certificate, you can share the script with users on other computers that recognize and trust the CA that issued the certificate.

  • Self-signed certificates   For this kind of certificate, your computer is the authority that creates the certificate. The benefit of a self-signed certificate is you can write, sign, and run scripts on your computer. But you can't share your script to run on other computers because your computer isn't recognized as a trusted CA. If your computer isn't trusted, your self-signed signature can't be validated, and the script won't run.

Cmdlets for managing code signing

The Shell includes two cmdlets for managing code signing. The Set-AuthenticodeSignature cmdlet is used to add digital signatures to script files. The Set-AuthenticodeSignature cmdlet takes the name of the file to be signed as its first positional parameter. If the file isn't in the current working directory, you must provide the path of the file. The second input parameter for this cmdlet is the certificate used for signing. This certificate is stored in the local certificate store. You must provide this parameter in the form of a string that references the certificate. The certificate can be accessed through the Cert: drive.

The other cmdlet for managing code signing is the Get-AuthenticodeSignature cmdlet. Use the Get-AuthenticodeSignature cmdlet to check and confirm the current code-signing status for the file provided as a parameter input. If a problem occurs when you use a code-signed script, the output from the Get-AuthenticodeSignature cmdlet will provide useful troubleshooting information.

If you want to run scripts from outside sources, such as Microsoft, you must adapt the scripts according to the script execution mode of your environment. You can receive scripts as basic .txt files, rename them as .ps1 script files, and then after you apply any required signing, run these scripts as if you had written the scripts yourself.

For more information about digital signing and script execution policies, in the Shell, run the following command: Get-Help About_Signing. This command returns information that includes detailed instructions for digitally signing scripts.