about Signing - PowerShell (2024)

Short description

Explains how to sign scripts so that they comply with the PowerShell executionpolicies.

Long description

This information only applies to PowerShell running on Windows.

The Restricted execution policy doesn't permit any scripts to run. TheAllSigned and RemoteSigned execution policies prevent PowerShell fromrunning scripts that don't have a digital signature.

This topic explains how to run selected scripts that aren't signed, even whilethe execution policy is RemoteSigned, and how to sign scripts for your ownuse.

For more information about PowerShell execution policies, seeabout_Execution_Policies.

To permit signed scripts to run

When you start PowerShell on a computer for the first time, the Restrictedexecution policy, which is the default, is likely to be in effect.

The Restricted policy doesn't permit any scripts to run.

To find the effective execution policy on your computer, type:

Get-ExecutionPolicy

To run unsigned scripts that you write on your local computer and signedscripts from other users, start PowerShell with the Run as Administratoroption and then use the following command to change the execution policy on thecomputer to RemoteSigned:

Set-ExecutionPolicy RemoteSigned

For more information, see the help topic for the Set-ExecutionPolicy cmdlet.

Running unsigned scripts using the RemoteSigned execution policy

If your PowerShell execution policy is RemoteSigned, PowerShell won't rununsigned scripts that are downloaded from the internet, including unsignedscripts you receive through email and instant messaging programs.

If you try to run a downloaded script, PowerShell displays the following errormessage:

The file <file-name> cannot be loaded. The file <file-name> is notdigitally signed. The script will not execute on the system. Please see"Get-Help about_Signing" for more details.

Before you run the script, review the code to be sure that you trust it.Scripts have the same effect as any executable program.

To run an unsigned script, use the Unblock-File cmdlet or use the followingprocedure.

1. Save the script file on your computer.
2. Click Start, click My Computer, and locate the saved script file.
3. Right-click the script file, and then click Properties.
4. Click Unblock.

If a script that was downloaded from the internet is digitally signed, but youhaven't yet chosen to trust its publisher, PowerShell displays the followingmessage:

Do you want to run software from this untrusted publisher?The file <file-name> is published by CN=<publisher-name>. Thispublisher is not trusted on your system. Only run scriptsfrom trusted publishers.[V] Never run [D] Do not run [R] Run once [A] Always run[?] Help (default is "D"):

If you trust the publisher, select Run once or Always run. If you don'ttrust the publisher, select either Never run or Do not run. If youselect Never run or Always run, PowerShell won't prompt you again forthis publisher.

Methods of signing scripts

You can sign the scripts that you write and the scripts that you get from othersources. Before you sign any script, examine each command to verify that it'ssafe to run.

For best practices about code signing, see Code-Signing Best Practices.

For more information about how to sign a script file, seeSet-AuthenticodeSignature.

The New-SelfSignedCertificate cmdlet, introduced in the PKI module inPowerShell 3.0, creates a self-signed certificate that's appropriate fortesting. For more information, see the help topic for theNew-SelfSignedCertificate cmdlet.

To add a digital signature to a script, you must sign it with a code signingcertificate. Two types of certificates are suitable for signing a script file:

• Certificates that are created by a certification authority: For a fee, apublic certification authority verifies your identity and gives you a codesigning certificate. When you purchase your certificate from a reputablecertification authority, you are able to share your script with users onother computers that are running Windows because those other computers trustthe certification authority.

• Certificates that you create: You can create a self-signed certificate forwhich your computer is the authority that creates the certificate. Thiscertificate is free of charge and enables you to write, sign, and run scriptson your computer. However, a script signed by a self-signed certificate willnot run on other computers.

Typically, you would use a self-signed certificate only to sign scripts thatyou write for your own use and to sign scripts that you get from other sourcesthat you have verified to be safe. It isn't appropriate for scripts that willbe shared, even within an enterprise.

If you create a self-signed certificate, be sure to enable strong private keyprotection on your certificate. This prevents malicious programs from signingscripts on your behalf. The instructions are included at the end of thistopic.

Create a self-signed certificate

To create a self-signed certificate, use the New-SelfSignedCertificatecmdlet in the PKI module. This module is introduced in PowerShell 3.0 and isincluded in Windows 8 and Windows Server 2012. For more information, see thehelp topic for the New-SelfSignedCertificate cmdlet.

$params = @{ Subject = 'CN=PowerShell Code Signing Cert' Type = 'CodeSigning' CertStoreLocation = 'Cert:\CurrentUser\My' HashAlgorithm = 'sha256'}$cert = New-SelfSignedCertificate @params

Using Makecert.exe

To create a self-signed certificate in earlier versions of Windows, use theCertificate Creation tool MakeCert.exe. This tool is included in theMicrosoft .NET SDK (versions 1.1 and later) and in the Microsoft Windows SDK.

For more information about the syntax and the parameter descriptions of theMakeCert.exe tool, see Certificate Creation Tool (MakeCert.exe).

To use the MakeCert.exe tool to create a certificate, run the followingcommands in an SDK Command Prompt window.

makecert -n "CN=PowerShell Local Certificate Root" -a sha256 `-eku 1.3.6.1.5.5.7.3.3 -r -sv root.pvk root.cer `-ss Root -sr localMachinemakecert -pe -n "CN=PowerShell User" -ss MY -a sha256 `-eku 1.3.6.1.5.5.7.3.3 -iv root.pvk -ic root.cer

The MakeCert.exe tool prompts you for a private key password. The passwordensures that no one can use or access the certificate without your consent.Create and enter a password that you can remember. You'll use this passwordlater to retrieve the certificate.

To verify that the certificate generated correctly, use the following commandto get the certificate in the certificate store on the computer. You won't finda certificate file in the file system directory.

At the PowerShell prompt, type:

Get-ChildItem cert:\CurrentUser\my -codesigning

This command uses the PowerShell Certificate provider to view informationabout the certificate.

If the certificate was created, the output shows the thumbprint thatidentifies the certificate in a display that resembles the following:

Directory: Microsoft.PowerShell.Security\Certificate::CurrentUser\MyThumbprint Subject---------- -------4D4917CB140714BA5B81B96E0B18AAF2C4564FDF CN=PowerShell User ]

Sign a script

After you create a self-signed certificate, you can sign scripts. If you usethe AllSigned execution policy, signing a script permits you to run thescript on your computer.

The following sample script, Add-Signature.ps1, signs a script. However, ifyou are using the AllSigned execution policy, you must sign theAdd-Signature.ps1 script before you run it.

To use this script, copy the following text into a text file, and name itAdd-Signature.ps1.

## Signs a file[cmdletbinding()]param( [Parameter(Mandatory=$true)] [string] $File)$cert = Get-ChildItem Cert:\CurrentUser\My -CodeSigningCert | Select-Object -First 1Set-AuthenticodeSignature -FilePath $File -Certificate $cert

To sign the Add-Signature.ps1 script file, type the following commands at thePowerShell command prompt:

$cert = Get-ChildItem Cert:\CurrentUser\My -CodeSigningCert | Select-Object -First 1Set-AuthenticodeSignature add-signature.ps1 $cert

After you sign the script, you can run it on the local computer. However, thescript won't run on computers where the PowerShell execution policy requires adigital signature from a trusted authority. If you try, PowerShell displays thefollowing error message:

The file C:\remote_file.ps1 cannot be loaded. The signature of thecertificate cannot be verified.At line:1 char:15+ .\ remote_file.ps1 <<<<

If PowerShell displays this message when you run a script that you didn'twrite, treat the file as you would treat any unsigned script. Review the codeto determine whether you can trust the script.

Enable strong protection for your private key

If you have a private key and certificate on your computer, malicious programsmight be able to sign scripts on your behalf, which authorizes PowerShell torun them.

To prevent automated signing on your behalf, use Certificate ManagerCertmgr.exe to export your signing key and certificate to a .pfx file.Certificate Manager is included in the Microsoft .NET SDK, the MicrosoftWindows SDK, and in Internet Explorer.

To export the certificate:

1. Start Certificate Manager.
2. Select the certificate issued by PowerShell Local Certificate Root.
3. Click Export to start the Certificate Export Wizard.
4. Select Yes, export the private key, and then click Next.
5. Select Enable strong protection.
6. Type a password, and then type it again to confirm.
7. Type a filename that has the .pfx filename extension.
8. Click Finish.

To re-import the certificate:

1. Start Certificate Manager.
2. Click Import to start the Certificate Import Wizard.
3. Open to the location of the .pfx file that you created during the exportprocess.
4. On the Password page, select Enable strong private key protection, andthen enter the password that you assigned during the export process.
5. Select the Personal certificate store.
6. Click Finish.

Prevent the signature from expiring

The digital signature in a script is valid until the signing certificateexpires or as long as a timestamp server can verify that the script was signedwhile the signing certificate was valid.

Because most signing certificates are valid for one year only, using a timestamp server ensures that users can use your script for many years to come.

See also

• about_Execution_Policies
• about_Profiles
• Set-AuthenticodeSignature
• Get-ExecutionPolicy
• Set-ExecutionPolicy
• Introduction to Code Signing