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
