TOPIC
Signing and Execution Policies
SHORT DESCRIPTION
Understanding the Microsoft Shell (MSH) execution policies, and how to use them.
LONG DESCRIPTION
MSH supports a concept called "execution policies" in order to help
deliver a more secure command line administration experience.
Execution policies define the restrictions under which MSH loads files
for execution and configuration. The four execution policies are
Restricted, AllSigned, RemoteSigned, and Unrestricted.
MSH is configured to run in its most secure mode by default. This
mode is the "Restricted" execution policy, in which MSH operates as
an interactive shell only. This mode may not be suitable for your
needs, so the following chart gives a progressive overview of the
alternatives, along with the trade-offs they require. See the
detailed descriptions below for more information.
Restricted
- Default execution policy.
- Does not run scripts.
- Interactive only.
AllSigned
- Runs scripts.
- All scripts and configuration files must be signed by a
publisher that you trust.
- Opens you to the risk of running signed (but malicious) scripts,
after confirming that you trust the publisher.
RemoteSigned
- Runs scripts.
- All scripts and configuration files downloaded from
communication applications such as Microsoft Outlook, Internet
Explorer, Outlook Express and Windows Messenger must be signed
by a publisher that you trust.
- Opens you to the risk of running malicious scripts not
downloaded from these applications, without prompting.
Unrestricted
- Runs scripts.
- All scripts and configuration files downloaded from
communication applications such as Microsoft Outlook, Internet
Explorer, Outlook Express and Windows Messenger run after
confirming that you understand the file originated from the
internet. No digital signature is required.
- Opens you to the risk of running unsigned, malicious scripts
downloaded from these applications.
Changing Your Execution Policy
------------------------------
To change your execution policy, first decide which of the execution
policies most securely meets your needs. Then, run the following
command from an MSH prompt. Using "RemoteSigned" as an example,
set-property `
HKLM:\SOFTWARE\Microsoft\Msh\Microsoft.Management.Automation.msh `
-property ExecutionPolicy -value RemoteSigned
Press enter on a blank line to complete the command. This command
requires administrator privileges.
Alternatively, you may use the Registry Editor to change the execution
policy. To do this, open HKEY_LOCAL_MACHINE and navigate to
SOFTWARE\Microsoft\Msh\Microsoft.Management.Automation.msh.
Then, change the "ExecutionPolicy" value to "RemoteSigned" and close
the Registry Editor.
MSH recognizes changes to your execution policy immediately. If it
does not change as you expect it to, ensure that the execution policy
is spelled correctly, and is one of the four listed above. If it is
spelled incorrectly, MSH reverts to the default execution policy.
Restricted Execution Policy
------------------------------
If you're reading this for the first time, MSH may have just displayed
the error message as you tried to run a script:
The file C:\my_script.msh cannot be loaded. The execution of scripts
is disabled on this system. Please see "get-help about_signing" for
more details.
The default execution policy of MSH is called "Restricted." In this
mode, MSH operates as an interactive shell only. It does not run
scripts, and loads only configuration files signed by a publisher that
you trust.
AllSigned Execution Policy
------------------------------
The AllSigned execution policy helps make the execution environment
more secure by requiring digital signatures on all scripts and
configuration files -- not just those that originate from the
internet. This includes scripts that you write. If you want to
enable the AllSigned execution policy and still write your own
scripts, you can add a digital signature to your scripts after you
write them.
For further details about how to sign a file, enter the
following at the MSH command prompt:
get-help set-authenticodeSignature
Adding a digital signature to a script requires that you sign it with
a code signing certificate. Two types of certificates are suitable
for signing a script file: those created by a certificate authority
(such as Verisign or Thawte, etc.,) and those created by you.
The first type (the kind created by a public, trusted, certificate
authority) is the most common. For a fee, the certificate authority
verifies your identity and provides you with a code signing
certificate. When you purchase your certificate from reputable
certificate authority, you will be able to share your script with
users on other computers. This is because those other computers trust
the certificate authority to faithfully validate the identities of
applicants.
The second type (the kind created by you) is known as a "self-signed
certificate." For this type, your computer is the authority that
creates the certificate. This has both benefits and drawbacks as
compared to one created by a public and trusted certificate authority.
The benefit of this type of certificate is that it costs nothing, and
enables you to write, sign, and run scripts on your computer. The
drawback is that other computers do not trust your computer (as the
certificate authority) to faithfully validate the identity of
applicants. Because they do not trust your computer, they will not
validate your self-signed signature.
To create a self-signed certificate, you will require a program from
either the Microsoft .NET Framework SDK or Microsoft Windows Platform
SDK called 'makecert.exe.'
With that program installed, run the following two commands. The
first creates a local certificate authority for your computer, and the
second generates a personal certificate from that certificate
authority:
makecert -n "CN=Monad Local Certificate Root" -a sha1 `
-eku 1.3.6.1.5.5.7.3.3 -r -sv root.pvk root.cer `
-ss Root -sr localMachine
makecert -pe -n "CN=Monad User" -ss MY -a sha1 `
-eku 1.3.6.1.5.5.7.3.3 -iv root.pvk -ic root.cer
After these steps, you can verify that the certificate was generated
correctly:
MSH:1 C:\ > dir cert:\CurrentUser\My -codesign
Subject : CN=Monad User
Issuer : CN=Monad Local Certificate Root
Thumbprint : 03D1706CF9925083CC0D9ABA0D3C07B69433EFB4
FriendlyName :
NotBefore : 8/23/2005 2:36:55 PM
NotAfter : 12/31/2039 3:59:59 PM
Extensions : {System.Security.Cryptography.Oid,
System.Security.Cryptography.Oid}
The command generated two temporary files (root.pvk and root.cer)
that you can delete. Now that you have your own self-signed
certificate, you can sign and run scripts your computer. The
following sample script file (once
signed) makes the process quite simple:
## sign-file.msh
## Sign a file
param([string] $file=$(throw "Please specify a filename."))
$cert = @(get-childitem cert:\CurrentUser\My -codesigning)[0]
set-authenticodeSignature $file $cert
To sign sign-file.msh in AllSigned mode, run the final two commands
manually, replacing "$file" with "sign-file.msh".
However, be aware that MSH will be unable to validate your script on
any other computers. Users that try will receive the following error
message:
MSH:1 C:\ > .\remote_file.msh
The file C:\remote_file.msh cannot be loaded. The signature of the
certificate can not be verified.
At line:1 char:15
+ .\ remote_file.msh <<<<
If you receive this error message when trying to run a script that you
did not write, treat the file as though you would treat an unsigned
script. If you review it, and trust it, you may sign it and run it.
One important point about the self-signing approach is that malicious
applications could potentially sign scripts on your behalf, allowing
MSH to execute them. To prevent automated signing on your behalf, use
Windows' certificate manager to export your signing certificate to a
.pfx file. When given the option, include the private key. Once
you've done that, re-import it using the option to "enable strong
private key protection." Strong private key protection prompts you
whenever an application tries to access your signing key.
RemoteSigned Execution Policy
------------------------------
In this execution policy, MSH helps protect you from malicious email
attachments and downloaded scripts by requiring that they contain a
digital signature. In addition, the digital signature on this file
must be from a publisher that you trust. Scripts created on the
current system do not require this digital signature in order for you
to run them.
If you have already set your execution policy to "RemoteSigned," some
scripts may still give an error message:
The file C:\remote.msh cannot be loaded. The file C:\remote.msh is not
digitally signed. The script will not execute on the system. Please
see "get-help about_signing" for more details.
In the RemoteSigned execution policy, MSH provides this error message
when you download an unsigned script from a communication application
such as Microsoft Outlook, Internet Explorer, Outlook Express and
Windows Messenger. To run the script, first review it to ensure that
you trust it to run on your computer. Be aware that a script has the
same power as any other executable program. In order to run this
script, open Windows Explorer and locate the file. Right-click on the
file, select "Properties," and then click the "Unblock" button at the
bottom right of the properties dialog that opens. Restart your MSH
shell, and the script will execute.
Alternately, you may see the following prompt:
Do you want to run software from this untrusted publisher?
The file C:\remote_file.msh is published by CN=Script Publisher. This
publisher is not trusted on your system. Only run scripts from trusted
publishers.
[V] Never run [D] Do not run [R] Run once [A] Always run
[?] Help (default is "D"):
MSH provides this prompt (in the RemoteSigned execution policy) when
you run a script from the internet that is digitally signed, but you
have not yet chosen to trust its publisher. In this case, the script
was signed by "Script Publisher."
One very important fact of digital signatures is that they do NOT
guarantee that the file is safe for you to run. They guarantee only
that the file has not changed since the publisher signed it, and that
a public Certificate Authority (CA) such as Verisign has verified the
identity of the publisher.
If you trust the publisher to run scripts on your system, select
either "Run once" or "Always run." If you do not trust the publisher
to run scripts on your system, select either "Never run," or "Do not
run." If you select either of the permanent options ("Never run" or
"Always run,") MSH will not prompt you again for this publisher.
In addition to the Restricted and RemoteSigned execution policies, MSH
offers two others: AllSigned, and Unrestricted.
Unrestricted Execution Policy
------------------------------
The final execution policy is called "Unrestricted." This policy
removes most of the restrictions under which MSH loads script and
configuration files. Local files run without prompting. Remote files
run based on your response to the following prompt:
MSH:1 C:\ > .\remote_file.msh
Security Warning
While scripts from the Internet can be useful, this script can
potentially harm your computer. Only run scripts that you trust.
Do you want to run C:\remote_file.msh?
[D] Do not run [R] Run once [S] Suspend [?] Help (default is "D"):
However, if the remote file is signed by a publisher that you already
trust, it runs without prompting.
SEE ALSO
For information about Code Signing, search Microsoft Developer
Network (MSDN) reference at http://msdn.microsoft.com/ for
"Introduction to Code Signing."
For information about the set-authenticodeSignature command, enter the
following at the MSH command prompt:
help set-authenticodeSignature