Chapter 10. Scripts

PowerShell scripts function like batch files in the traditional console: scripts are text files that can include any PowerShell code. If you run a PowerShell script, PowerShell will read the instructions in it, and then execute them. As a result, scripts are ideal for complex automation tasks. In this chapter, you'll learn how to create and execute scripts.

PowerShell makes certain requirements mandatory for their execution because scripts can contain potentially dangerous statements. Depending on the security setting and storage location, scripts must have a digital signature or be specified with their absolute or relative path names. These security aspects will also be covered in this chapter.

Topics Covered:

• Writing and Starting PowerShell Scripts
  • Using Redirection to Create Scripts
  • Creating Scripts with an Editor
  • Starting Scripts
    • Execution restrictions
      • Table 10.1: Execution policy setting options
    • Invoking Scripts like Commands
• Passing Arguments to Scripts
  • $args Returns All Arguments
  • $args is an Array
  • Accessing Separate Arguments in $args
  • Using Parameters in Scripts
    • Validating Parameters
  • Scopes: Ranges of Validity in Scripts
  • #requires: Script Requirements
• Making Scripts Understandable
  • Using Functions in Scripts
  • Separating Scripts into Work Scripts and Libraries
  • Library Scripts Central Directory
• Creating Pipeline Scripts
  • Slow Sequential Mode
  • Quicker Streaming Mode
  • Writing Pipeline Results
• Profile: Autostart Scripts
  • Four Different Profile Scripts
    • Table 10.2: PowerShell profiles
  • Creating Your Own Profile
  • Create a Global Profile for All Users
• Digital Signatures for Your Scripts
  • Finding an Appropriate Certificate
    • Figure 10.1: Using an option dialog to select a certificate
    • Creating a New Certificate
    • Creating Self-Signed Certificates
  • Examining the Code-Signing Certificate
  • Declaring a Certificate "Trusted"
    • Figure 10.2: Certificates must be declared trusted
    • Figure 10.3: The trusted certificate may now be used for signatures
  • Signing PowerShell Scripts
    • Using the First Available Certificate
    • Recursively Signing All PowerShell Scripts
    • Selecting Certificates Using the Dialog Box
  • Validating Signed PowerShell Scripts
    • Manual Validation
      • Table 10.3: Status reports of signature validation and their causes
    • Automatic Validation
  • Building a Miniature PKI
    • Creating a Root Certificate
    • Creating Staff Certificates
    • Creating a Backup
    • Installing Enterprise-Wide Root Certificates
• Summary

Writing and Starting PowerShell Scripts

A PowerShell script is nothing more than a text file containing PowerShell code. If the text file is executed, PowerShell steps through its statements and executes them. PowerShell scripts work very much like the batch files of older consoles: you can create PowerShell scripts with much the same simplicity you could using batch files.

Using Redirection to Create Scripts

If your script is short, you could create it directly from within the console by redirecting the script code to a file:

But because you must use quotation marks to enclose text, it can be confusing to use quotation marks inside the script code. Or you may like to specify multi-line text. So, using "here-strings" would work better in this example:

Here-strings always begin with @' and end with '@. Everything in between is stored as text, including all special characters and line breaks. If you use double instead of single quotation marks, PowerShell will expand all variables in your here-string.

Creating Scripts with an Editor

Considerably more convenient are genuine text editors, such as Notepad. Assign it the task of creating a new file:

Notepad will open and offer to create the myscript.ps1 file. Click Yes. Now you can write your script in Notepad. Just enter the same statements in Notepad that you would otherwise have typed interactively in the console:

Then use File/Save to save your script and close the Notepad.

Starting Scripts

While your script was created, it can't be started just like that. If you enter the file name of your script file, you'll get an error message:

It won't work until you specify at least the relative path name of the script, which is .\myscript.ps1:

Execution restrictions

PowerShell always initially prohibits scripts from running. Whether scripts can be started or not is determined by the execution policy:

Only an administrator can change this setting. The Get-ExecutionPolicy cmdlet will tell you the current setting of your execution policy:

If you want to run scripts, choose another setting from Table 10.1 for the execution policy and use Set-ExecutionPolicy to specify it. You just need to change this setting once. PowerShell will make a permanent note of it.

Usually, the best "liberal" setting is RemoteSigned because you can run your own locally stored scripts and potentially dangerous scripts downloaded from the Internet are not allowed:

Invoking Scripts like Commands

To actually invoke scripts just as easily as normal commands—without having to specify relative or absolute paths and the ".psl" file extension—you can employ two simple tricks. The simplest is alias names. You could define a new alias name for invoking a script:

You could immediately launch you script by entering the dosomething command:

However, this alias would only work in the same directory in which the script is stored because it uses a relative path name. If you store your scripts in fixed locations, you'd better specify an absolute path name or use environment variables. You could put your script in a central directory and in a profile for all users:

Then copy the script to this directory:

Now, specify a fixed destination path independently of the current directory:

Alternatively, you could declare the directory in which your scripts are stored as a trusted location: include this directory in the Windows Path environment variable. All PowerShell scripts in this directory will no longer require you to specify them by using relative or absolute path names. You no longer even have to append the "ps1" file extension in this connection. Try it out:

Passing Arguments to Scripts

You can write scripts that interact with the user, who can then pass arguments to a script. That works for scripts just as it does for the functions in the last chapter. Let's look at how you can modify your first simple script so that its output is not an unchangeable text, but a welcome text that a user can modify.

$args Returns All Arguments

Arguments that you pass to a function or a script are located in the $args variable. To get your script to output the text that the user specifies after the script name when the script is invoked, make the appropriate changes to your script. First, load it back in Notepad as in the following example:

Now, change your script in the Notepad and replace the lines in it with these:

Save the change and try out your modified script.

The script works, but no text in particular was output. That's obvious because you haven't specified any arguments yet. So, try out the script with an argument:

It works and everything that you specify after the script name will be passed as an argument to your script.

$args is an Array

The data you specify after your script when it is invoked are called arguments. PowerShell evaluates these arguments and uses spaces to separate each argument from the other, which explains why your script brings together several spaces in succession:

PowerShell has identified seven separate arguments from the data that follows your script. You'll find them all afterwards in $args, which is in reality an array. If you would like to use spaces in an argument, and avoid PowerShell interpreting them as separators, your argument must be enclosed in quotation marks:

Now all the spaces are output.

Accessing Separate Arguments in $args

Because $args is an array, you could also process each element of the array separately. In Chapter 4, you familiarized yourself with arrays so you know now that you can access elements in an array through an index. So, your script might look like this if you'd like to process the first argument:

However,$args[0] can no longer be simply integrated into the output text because PowerShell resolves only simple variables. The entire expression must be wrapped in a direct variable $(...). Save your script, and then look at how your script handles your arguments now:

Using Parameters in Scripts

While$args is a simple way to pass user data to a script, it's entirely up to you to find out which argument the user specified and in which order. If the user didn't enter his arguments in exactly the same order you anticipated, the script will get muddled and may not interpret his arguments correctly. In addition, the user won't get any feedback from the script telling him which arguments are permitted or required.

In older script languages, a lot of effort was required to validate passed arguments and to allocate them properly. But PowerShell has this option and it works very much like the parameters of the functions in the last chapter. For functions, parameters specified in parentheses after the function name:

This works exactly the same way for scripts, just that the question arises of where to put the parameters for a script. While functions are always located in a function Name(Parameter) {...} construct, such a framework isn't available for scripts. That's why scripts have to use the param statement.

Let's translate the function with the two parameters $path and $name into a script. Open your script again for processing in Notepad:

Now type this code:

Save your script and try it out:

It works: your script responds now just like the function and uses parameters instead of unnamed arguments. The data in parentheses after param exactly match the same data that you put after the function names in parentheses for functions.

Validating Parameters

After reading the last chapter, you should know how to formulate arguments so that PowerShell can verify that they were specified. The next script requires an argument called name and another called age. It establishes exactly which data type is necessary for each argument and also determines that an error message will be output if the argument is not specified:

Save this script and execute it. If you forget to specify one of the two arguments, or if you specify the parameter with an invalid value, PowerShell will automatically output an appropriate error message:

Scopes: Ranges of Validity in Scripts

To prevent scripts from having unintentional effects on other scripts or their interactive consoles, they are usually executed in isolation. Here, "isolation" means that all the variables and functions you create in a script are valid only inside the script. If you want to remove isolation, you can "dot source" scripts and functions when you invoke them: this just means putting a single dot or period in front of scripts and functions when you call them. If you want to define the scope of each variable or function separately, use the identifiers described in Chapter 3.

PowerShell stores all the variables in the interactive console in the global: area. All the variables that a script creates are stored in the script: area. When a script has completed its work, its script: area is deleted. That's how PowerShell removes only the variables that the script created. Variables that are already there remain untouched because of their location in the global: area.

This raises an interesting question of how scripts handle variables that have already been defined previously. If a variable doesn't exist in the current scope, PowerShell will try to find it in the parent scope. So, if you created a variable called $test in the console, your script would be able to read this variable. However, change is constant in the current scope: if you modify the contents of the $test variable inside your script, PowerShell would create a new variable called $test in the script: area. The result would be two variables: one in the global: area and one in the script: area. Your script would use the new variable because when you invoke $test inside the script, PowerShell will always look in the current scope first and will not proceed to the parent scope until it cannot locate the sought word. The script can read this variable since $test was created in the current scope. Here's a little test script:

Take a look at how the script handles the $test variable:

#requires: Script Requirements

Scripts may have certain requirements for their execution. Cmdlets are not necessarily limited to just the ones included in PowerShell. Third-party suppliers offer additional cmdlets. For example, if you're using Microsoft Exchange you'll have many additional special Exchange cmdlets at your disposal.

The cmdlets are part of an additional snap-in that Exchange includes. All additional snap-ins are loaded on the basis of an automatically starting profile script by using Add-PSSnapin. Get-PSSnapin can show you which snap-ins are currently in use by your PowerShell console:

If a script uses commands from an additional snap-in, it can indicate that by using the #requires statement. For example, specify a snap-in after #requires that is essential for the script. If the snap-in is missing, PowerShell won't start the script and will instead output an error message. This is how such a script might look:

While the first requirement appears to be met because this snap-in is part of the basic snap-ins, the second required snap-in is missing. If you try to run the script, you'll get an error message informing you why the script couldn't be started:

If you want to lock in a script to a particular version of PowerShell, use the -Version parameter. Scripts that use new V2-specific features will be able to use #requires -Version 2 to specify that they can't be run with the older version.

Note that you are able to use -ShellID to limit execution of scripts to particular PowerShell consoles. -ShellID is a PowerShell console identifier and is located in the $ShellID automatic variable. For the Microsoft console, the tag is Microsoft.PowerShell. Use #requires -ShellID Microsoft.PowerShell if you'd like to ensure that a script may be executed in Microsoft consoles only.

Making Scripts Understandable

Scripts may be as long as you'd like but typically the longer a script is, the harder it will be to read it. For this reason, lengthy scripts use two methods to keep script code understandable:

• Functions: Consolidate smaller tasks in functions, which not only make code easier to grasp but can also be reused conveniently. Once you've created a function for a certain task, you can use it later in other scripts as well.
• Libraries: Embed required functions as a library into your script so you won't need to copy your basic functions into every script, inflating them artificially. Your basic functions can remain in a single script while your current script focuses on just the one task it needs to complete.

Using Functions in Scripts

To be able to use a function inside a script, simply insert the function into the script code. Look at a lengthier script to see how this is done. Open Notepad again:

Then enter the following script and save it:

This script uses param first to define the amount parameter because the script is supposed to calculate the value-added tax payable on a net sum. The script utilizes the strong type specification we saw in Chapter 3 to set the amount parameter as a floating point number (type: double). If the user doesn't name a number, an error message will be generated.

If you then specify a sum, the script will generate an error message anyway and will return an incorrect result:

Apparently, the script couldn't locate the VAT function. Unlike most other script languages, PowerShell functions that you define inside your script must be at the beginning of your script. The functions come into play only after PowerShell has read and created the functions with PowerShell reading scripts rigidly from top to bottom. So, a correctly written script should look like this:

After this transposition, the script now works as expected:

Separating Scripts into Work Scripts and Libraries

Genuine scripts developed to solve practical problems usually include many more than just one function. The scripts may become unclear when function definitions pile up at the beginning of scripts. Functions, once you have created, tested, and approved them, should really not be eye-catching. Prevent that by using script libraries. Save your functions in a separate script file for later inclusion in all your scripts. The scripts can then use the functions saved in the file. Try it out. First, create a script library:

Then, enter this function in Notepad and save the script:

After this step, create a work script. The work script shouldn't include any general functions. Instead, it simply loads the functions it requires from the script library.

Enter the following code and save the script:

The work script will execute the script with the functions first, and then this script will create the required functions. Note that all variables and functions that create a script are as a rule "private" and are valid only within the script. That's critical because scripts must not have unintentional effects on each other. However, because in this case you want the library script to affect the work script (namely by creating new functions that will be disclosed in the work script), the "dot sourced" library script will be invoked: a single dot will be placed in front of the invoked script. The dot will cancel script isolation, and all the functions that the library script creates will also be valid in your work script.

This method is enabling you to load any number of script libraries in your work script. The result is that your work script stays clear and concise while the functions in the libraries can be developed separately.

• Work script: work scripts shouldn't include any general functions, just the code needed to perform current tasks. Required functions are implemented from external scripts. These must be called by using dot sourcing.
• Library: libraries may contain only function definitions and no code except for function definitions because the code would otherwise be immediately executed when the library is reloaded.

Library Scripts Central Directory

You should work out a strategy for optimal storage of library scripts as soon as you start using library scripts in your work scripts. One option would be to store the library scripts in the same directory as the work scripts. That way your work scripts could always access its library scripts over a relative path specification, as seen in the preceding example. Another option would be to copy your work scripts to another location, but in then you would have to remember to copy your library scripts as well.

If you'd prefer to store your library scripts in a central location because you want to deny general access to them, or because the library scripts should be stored in a directory that grants users authorization to read them only, and then type absolute path names in your work script. Utilize environment variables to specify the directory where the library script is. If library scripts are in a user profile in the PSLib directory, you could modify your work script in the following way:

You could use the following lines to create the PSLib directory in a user profile and to copy your locally stored library in this area to which all users could have access:

Creating Pipeline Scripts

PowerShell scripts can be used as building blocks in the pipeline just like functions, which were covered in the last chapter. Moreover, what applies to functions applies to scripts as well: depending on how you program the script, you can either force the pipeline to adopt the slow and memory-intensive sequential mode or enable the rapid streaming mode.

Slow Sequential Mode

If you use a script inside the pipeline, the script will collect the results of the preceding statement in the $input automatic variable. But the script also blocks up the pipeline because the pipeline has to wait first until the preceding statement has fully completed its task. Only then can the pipeline pass on its result in $input to the script. Try out a new test script:

Type this code:

The script will read the results in $input and mark every line in red that includes the ".exe" term. The script functions flawlessly in the pipeline:

Long waiting periods occur because the script doesn't go into action until Dir has done its work. Moreover, because all the results of the preceding statement have to be stored temporarily first, memory consumption is extremely high and may even make Windows unstable:

Quicker Streaming Mode

There are reasons why scripts used in the pipeline should support the rapid streaming mode. It works for scripts just as it does for functions: all you need to do is to define the begin, process, and end script blocks in your script. The code in the begin block will be executed once at the beginning and can carry out initialization tasks or output messages to the user. The code in the process block will be executed in real time for every incoming result of the preceding statement, and the code in the end block will be executed at the end. It could carry out cleanup chores or simply report that the operation is concluded. Your filter script would function in real time as follows:

Writing Pipeline Results

While your script did process the results of the preceding statement faultlessly, it ended the pipeline. That's wasn't as noticeable because no additional statements followed after your script in the pipeline. The reason: your script received the results of the preceding statement, processed them, and then used Write-Host to write them directly in the console. The results were therefore not passed on in the pipeline. That's OK if your script concludes the pipeline.

However, if you want to write an authentic pipeline script that not only receives pipeline data but hands them on to the next statement, you need to make sure that the processed data are subsequently put back into the pipeline. The next script does that by using a Switch condition to validate a number of file extensions. In this specific example, changing the characters of the names to upper case works:

This script simply outputs the results in the process block to the pipeline. In this way, it allows the other following statements to process the results. For this reason, you could use Out-File afterwards to wrap the results in a text file:

Profile: Autostart Scripts

Many changes you make in the PowerShell console are in effect for just a limited period of time. All alias definitions, functions, and changes to Windows environment variables are valid only until you close the PowerShell console. That's why you should use profiles to make basic changes permanent. Profiles are special scripts that PowerShell runs automatically when you start it. Locate all your initialization tasks in profiles so that PowerShell will always use exactly the configuration you want it to use when it starts.

Four Different Profile Scripts

On the whole, PowerShell supports four different profile scripts, which enable you to select a profile that fits your initialization tasks. The first question to ask is: should the initialization tasks apply to you personally or to all users? If you'd like the script to apply to you personally, use your own "current user" profile. However, if your statements are supposed to run for all users whenever PowerShell is started, the correct profile to use is "all users."

There are also "private" options for these two profiles. These only function if you use the Microsoft Windows PowerShell console. Are there others? Indeed there are. More and more companies are supporting PowerShell. Alternative consoles already exist that you could use instead of powershell.exe. Use the general profile if you'd like to have your modifications executed when PowerShell starts with applications developed by other companies. Use the private profile If you want your modifications to be executed only when using the original PowerShell console.

Creating Your Own Profile

Profiles aren't mandatory. That's why you might not have an available profile. You've already seen how easy it is create new PowerShell scripts and it's just as easy to create profile scripts

Perhaps you've created some useful alias shortcuts and would like these alias definitions to be automatically activated whenever PowerShell starts. You can achieve that by creating your own personal profile:

This opens Notepad. It will show whether a profile already exists. If not, it will offer to create a new, empty script. Click Yes.

If a profile script already exists, you should inspect it first. In all probability it originates from some PowerShell extension or other that you downloaded and installed. In this case, simply add some statements to the script. For example, insert the following statement into the profile script to set up a new alias called edit, which will allow you to start Notepad conveniently:

Save the script after that, and then close and reopen the PowerShell console. Your profile script will run invisibly in the background, and your new alias command will be created automatically. You can use it for convenient editing of PowerShell scripts:

Create a Global Profile for All Users

You can create global profile scripts that all system users can use just as easily by specifying the location of the "all users" profile:

Note that this is permitted only if you have administrator privileges. Otherwise, any user could manipulate the start of another user's console. If you aren't the administrator, Windows will deny you permission to store anything at this location.

Windows Vista is a special case. Even when you log on as administrator, Vista will deprive you of administrator status: you're a normal user, at least if you haven't turned off the User Account Control (UAC). Consequently, to create or work on a global profile, you must first activate your full administrator privileges. To accomplish that, don't start PowerShell by clicking in the normal way. Instead, use the right mouse button, and then select Run as Administrator in the shortcut menu. Your PowerShell console will run with full administrator privileges for all programs that you call from within the console, including the Notepad, which you could then use to modify the global profile.

Digital Signatures for Your Scripts

Scripts can be easily faked or modified since they are simple text files. . Digital signatures provide greater security because they confirm the identity of the script author and guarantee that the script has not been altered since it was signed. To the extent that you trust the script publisher, you can be sure that nobody is trying to palm off malicious code on you. Even many experts don't completely understand how that works because these mechanisms are based on wickedly complex theories. Fortunately, in the practical world you need not concern yourself about these theories. What's important is that you familiarize yourself with the mechanisms and procedures. For this reason, all the important steps involved in using signatures will be embedded in easily understandable examples in the following sections.

Finding an Appropriate Certificate

Since it is hardly possible to use a classic fountain pen to sign PowerShell scripts (not to mention all other digital data), you'll need another instrument: a certificate as well as a private and secret key. The certificate is your electronic identity and is proof of who produced the signature. The private and secret key ensures that only the certificate owner can use the certificate to produce signatures.

So you're going to need a suitable certificate before you can digitally sign your own PowerShell scripts. The intended "code signing" purpose must be entered into the certificate and you'll also need a private and secret key for the certificate. PowerShell can find out whether certificates that meet these criteria are available on your computer system because all certificates are located in the cert: virtual drive:

The -codeSigningCert parameter ensures that only those certificates are located that are approved for the intended "code signing" purpose and for which you have a private and secret key.

In this case, just one certificate was found, but it could have been more or even none at all. If you have exactly one personal code-signing certificate, you could access it over this line:

If you have a choice of several certificates, you have to narrow your choices down to one. In this example, you would specify the certificate name as your choice:

You can even use SelectFromCollection() to open an option dialog and easily select a certificate provided that you address the internal functions of the .NET framework from within PowerShell. But first you would have to use LoadWithPartialName() to load the System.Security.dll in advance:

Figure 10.1: Using an option dialog to select a certificate

Creating a New Certificate

In most cases, you won't find any code-signing certificates on your computer so you'll have to obtain one from one of several sources:

• Private: Companies that run their own Public Key Infrastructure (PKI) will provide you with a private PKI. Typically, only business firms that have their own computing centers or universities can offer this option because a PKI is complex and expensive. Moreover, such certificates are usually valid within their own sphere of influence only.
• Purchased: Well-known and recognized certification companies like VeriSign or Thawte will be happy to sell you code-signing certificates in return for payment. You won't need your own private PKI, and such certificates are valid worldwide. However, the transaction is expensive and must usually be repeated regularly, such as every year. In addition, you have to go through elaborate procedures to prove your identity to the certifying enterprise.
• Self-signed:An individual certificate basically requires no complicated PKI. You can simply act as your own signing authority and issue one to yourself. You can then test and tinker with all aspects of the digital signature. Nobody will prevent you from using your own self-signed certificates productively. However, self-signed certificates are not managed by any certifying authorities. You are solely responsible for these certificates and their integrity. If a self-signed certificate lands in the wrong hands, nobody will be able to help you limit damages. For this reason, self-signed certificates are mostly used solely in testing environments and later replaced with certificates issued by a recognized PKI signing authority.

Creating Self-Signed Certificates

The key to making self-signed certificates is the Microsoft tool makecert.exe. Unfortunately, this tool can't be downloaded separately and it may not be spread widely. You have to download it as part of a free "Software Development Kit" (SDK). Makecert.exe is in the .NET framework SDK which you can find athttp://msdn2.microsoft.com/en-us/netframework/aa731542.aspx.

After the SDK is installed, you'll find makecert.exe on your computer and be able to issue a new code-signing certificate with a name you specify by typing the following lines:

It will be automatically saved to the \CurrentUser\My certificate store. From this location, you can now call and use any other certificate:

Examining the Code-Signing Certificate

The code-signing certificate represents your digital identity. But let's first take a look at what the certificate "knows" about you. To do so, first call the certificate and store it in a variable:

Declaring a Certificate "Trusted"

As you will quickly see, the certificate naturally contains only data than you specified yourself when creating the certificate. Even falsehoods are allowed. Nobody is going to prevent you from assuming someone else's identity when you create a certificate yourself. This means that certificates are not tamper-proof. The certificate itself "knows" this: if you use Verify() to check whether you can trust the data given in the certificate, PowerShell will respond with False in the case of self-signed certificates: the certificate is not trusted.

And why is the certificate untrustworthy? You can use a little trick to find out the answer. PowerShell can access the options of the System.Security.dll library of the .NET framework to get DisplayCertificate() to display all the data about the certificate in a clearly understandable dialog box. But first you'll have to use LoadWithPartialName() to reload the library:

The dialog box tells you what's wrong with the certificate: "This CA Root certificate is not to be trusted. To enable trust, install this certificate in the Trusted Root Certificates Authorities store." In the area below this, the dialog box reports that issued by and issued for are identical, meaning that this is a self-signed certificate not issued by any external PKI. To make this certificate trusted, it must be stored additionally in the certificate store of trusted root certification authorities.

Figure 10.2: Certificates must be declared trusted

You can get this done either manually or by letting PowerShell do it for you. The following lines will copy the certificate in $certificate to the store of root certificate authorities:

The certificate is immediately trusted; you can use Verify() to check it, and the result will now be True:

If you open the certificate properties again in the dialog box, this will also tell you that the certificate is acceptable. Click the Certification Path tab, and you will see the enabled trust. For self-signed certificates, it is the certificate itself. For certificates issued by a PKI, you will see which signing authority certifies that the certificate on your computer is trusted. The uppermost certificate in this view is always in your store of trusted root certificate authorities.

Figure 10.3: The trusted certificate may now be used for signatures

To find out what exactly happened and how to also perform this procedure manually, take a look at your certificate store:

Microsoft Management Console (MMC) opens and shows you your certificate store. In the Personal Certificates\Certificates branch, you'll find all your personal certificates, including the code-signing certificates that you created yourself, so you'll also find a copy of your self-signed certificate. If you delete the certificate, it will no longer be trusted. If you use your right mouse button to drag your self-signed certificate from the Personal Certificates\Certificates branch to the Trusted Root Certification Authorities\Certificates branch, you will only need to select Copy here to carry out the same copy procedure that your PowerShell code just automated for you.

Signing PowerShell Scripts

PowerShell script signatures require only two things: a valid code-signing certificate and the script that you want to sign. The cmdlet Set-AuthenticodeSignature takes care of the rest.

Using the First Available Certificate

Dir along with the parameter -codeSigningCert will retrieve appropriate code-signing certificates. In the most rudimentary case, you can use the first available certificate to sign one—or even all—PowerShell scripts in your current directory. The following lines will create a simple PowerShell script named test.ps1 and sign this script file with first available code-signing certificate:

The signature will be directly inserted into the script as a data block and consist of a digital fingerprint of the script (also known as a hash), which can be encrypted using the private key of the certificate. You'll find out how useful this is in the next section.

Recursively Signing All PowerShell Scripts

Set-AuthenticodeSignature allows you to sign not only individual scripts, but also many scripts at once in one operation. That means you could use a few lines to sign all your personal PowerShell scripts with your digital signature. Set-AuthenticodeSignature will also accept arrays as file names that can contain any number of separate file names. Instead of a fixed file name, enclose in parentheses a subexpression in your statement, and let Dir list all the PowerShell scripts in the current directory. They will all be signed immediately.

If you'd like to sign the scripts in your current directory as well as all PowerShell scripts in all subdirectories, the invocation is just as clear because you only need to use the -recurse parameter:

Selecting Certificates Using the Dialog Box

If there's more than one code-signing certificate on your computer, such as certificates used for diverse purposes, then you surely wouldn't want to use the first available certificate but the most suitable one. One option is to use the certificate name if you know it:

Another option is to use the built-in dialog box of .NET framework. It lists all certificates for selection that you pass to SelectFromCollection(). Before you can do this, you must wrap the certificates in a special collection. In the simplest scenario, you should offer all code-signing certificates for selection:

Validating Signed PowerShell Scripts

How exactly do signatures in scripts benefit you and others? The simple answer is they can be validated, both manually and automatically, and tell you whether a PowerShell is trusted or may contain malicious code.

• Validate it yourself: For manual validation, check whether a signature is in a PowerShell script and if it is, whether it is unobjectionable. Among other things, you can find out who signed the script, whether the script code was changed, and whether whoever signed the script is someone you trust.
• Validate automatically: If you set the PowerShell execution policy to AllSigned, PowerShell will carry out validation automatically as soon as you attempt to run the script. The script will run only if the script issuer is trusted and the signature has not been altered since it was signed.

Manual Validation

The cmdlet Get-AuthenticodeSignature validates signatures. This cmdlet requires the name of the script file that you want to examine. The script file doesn't have to include a signature. Whether it does or doesn't, the StatusMessage property will tell you the script status:

Note that this text conveys exactly the same message that you would receive if you ran an unsigned script, even though the execution policy is set to RemoteSigned or AllSigned. This means that PowerShell carries out precisely the same validation procedure internally when, depending on the current execution policy, it examines the scripts you try to start. Another equally useful property is Status, which summarizes the script status in just one concise phrase:

What happens when you inspect script signatures? Table 10.3 provides an overview of possible validation results, as well as causes. You can use get-authenticodesignature to easily ascertain the security status of scripts, which scripts have a valid signature, and which scripts lack signatures or whose contents have been modified:

If you want to see only those scripts that are potentially malicious, whose contents have been tampered with since they were signed (HashMismatch), or whose signature comes from an untrusted certificate (UnknownError), use Where-Object to filter your results:

Automatic Validation

You don't need to validate the signatures of your script files because PowerShell will carry out validation automatically when you try to start a script. The script will run only if the script file signature is valid. In all other cases, you will get an error message like those in Table 10.3. In this way, you can ensure that only those scripts will run that were inspected by a trusted authority and were found to be valid (that is, signed). Automatic validation will alert you as well if the script contents have been subsequently modified.

Automatic validation is always active when you use Set-ExecutionPolicy to set the execution policy either to AllSigned or RemoteSigned. All scripts will be tested in principle if you choose AllSigned.

If you select RemoteSigned, only those scripts will be checked that you downloaded from the Internet, received as an e-mail attachment, or from some other unreliable source. Here's a little test:

The sole difference between a trusted and an untrusted certificate is the question of whether the certificate publisher is specified in the special trusted root certificates authorities store. But even when you invoke a script signed with a trusted certificate, your first invocation will be accompanied by an additional query:

Do you want to run software from this untrusted publisher?
The file "C:\Users\Tobias Weltner\testscript.ps1" is published
by "CN=PowerShellTestCert". This publisher is not trusted on
your system. Only run scripts from trusted publishers.
Never run Do not run [M] Run once Always run
[?] Help (default is "N"):

Only when you answer by selecting "A" for "Always run" will the certificate publisher be placed in the trusted root certificates authorities store. Then, you won't be pestered with further queries for all the scripts signed with this certificate. If you'd like to avoid this query from the start, simply add the publisher of your script to the list of trusted root certificates authorities and also to the list of trusted publishers. With self-signed certificates, you could type:

# Select certificate:
$name = "PowerShellTestCert"
$certificate = Dir cert:\CurrentUser\My |
Where-Object { $_.Subject -eq "CN=$name " }

# Declare certificate publisher to be generally trusted
$Store = New-Object `
system.security.cryptography.X509Certificates.x509Store( `
"root", "CurrentUser")
$Store.Open("ReadWrite")
$Store.Add($certificate)
$Store.Close()

# Run certificates of this publisher:
$Store = New-Object `
system.security.cryptography.X509Certificates.x509Store( `
"TrustedPublisher", "CurrentUser")
$Store.Open("ReadWrite")
$Store.Add($certificate)
$Store.Close()

Building a Miniature PKI

You've seen that you can use self-signed certificates to fully utilize PowerShell security functions without an elaborate PKI. While a managed PKI is the better approach, you should also look at how you can build your own miniature PKI with the help of the Microsoft tool makecert.exe. before you decide to entirely forego the security of digital signatures just because you have no PKI available.

In the following example, the intended aim is to allow a business department to sign PowerShell scripts created by you with valid signatures. The signatures are to be valid across the enterprise. In addition, every staff member of the department will receive a personal certificate so that it will be possible to trace who has signed which script.

Creating a Root Certificate

The first step is to create for the department a root certificate, which will not actually be used later for signing purposes. It serves merely as publisher of staff certificates. The root certificate will not be created in the certificate store of the current user but in the Local Machine store so you will require administrator privileges. This is how to create a root certificate:

Makecert has created the root certificate as well as the files root.pvk and root.cer. Both will be used later but right now you should verify that the certificate was created properly:

Creating Staff Certificates

With the help of the root certificate, you can now create any number of staff certificates as long as you know the secret password that you stipulated when creating the root certificate. Ideally, only the department head knows the password. This is how you would proceed to create a new staff certificate:

Verify that the staff certificate was created properly:

The dialog box will now show differing specifications for Issued by and Issued for. The issuer of the staff certificate is now your new root certificate, and if you click the Certification path tab, you'll then see a genuine chain of trust starting with the root certificate for your department. That has great advantages because now all that remains to be done is to register your root certificate in the store of trusted root certification authorities in the entire enterprise. All the staff certificates originating from your root certificate are now automatically trusted.

Creating a Backup

Every staff member should save a copy of his staff certificate and store it in a protected location. The backup can be done directly from within PowerShell. The following lines will create a password-protected PFX file with the name backup.pfx in the current directory. In the example, the password is set to "strictlyconfidential" and, of course, should never be modified. The certificate, along with its secret and private key can be imported again only if the specified password is known.

If you assume the role of department head, you can now create a code-signing certificate for every staff member, generate a respective pfx backup copy, and then forward this to every staff member. To open this pfx file, a staff member would only need to double-click the file, enter the assigned password, and confirm all further settings. Finally, the certificate could be installed in its own certificate store, and staff members could begin to sign their scripts.

Installing Enterprise-Wide Root Certificates

Your "miniature PKI" should already be functioning on the computer where you stored the root certificate. So that your new staff certificates are recognized enterprise-wide, register the root certificate across the enterprise in the store of trusted root certification authorities. You can do that either manually or you can use Group Policy guidelines in an Active Directory for automatic distribution.

PowerShell installs the root certificate in the root.cer file in the system-wide store of trusted root certification authorities in the following way:

You could likewise open the root.cer file by double-clicking it or invoke it from within PowerShell:

In this case, you would install the certificate interactively with the help of an assistant. In the dialog box, click the Install certificate button. Follow the directions of the assistant, and select the option Save all certificates in the following store. Click Search.

A further dialog box should open. Select the option Display physical store. Then select in the upper tree structure the following branch: Trusted root certification authorities/Local computer. Click OK and then Continue to install the certificate.

Summary

PowerShell scripts are text files with a ".psl" file extension. They function like the batch files of older consoles and may include any PowerShell statements. If you start a PowerShell script, PowerShell will execute its included statements.

You can't start scripts without the permission of the execution policy. This setting initially prohibits scripts from starting, but an administrator can use Set-ExecutionPolicy to change the setting (see Table 10.1) and specify which scripts are allowed to start. The execution policy can specify that only those scripts may run that have a valid digital signature; it can also distinguish between local scripts and scripts originating from the Internet.

To execute a PowerShell script, the script must be invoked with its relative or absolute path name. For this reason, it does not suffice to specify only the script name unless the script is in a trusted directory, meaning all directories that are named in the Path environment variable. Another way to launch scripts comfortably is to use an alias name that you assign to the script with the help of Set-Alias.

Arguments can be passed to scripts. PowerShell automatically analyzes all the data that you specify after a script name when you invoke a script, and it uses a space as separator for arguments. The arguments are provided to the script in $args. Alternatively, the script can also bind arguments to set parameters. To do so, the parameters, much like functions, are defined inside the script by using the Param statement.

So to ensure that elaborate scripts remain clearly understandable, individual tasks should be encapsulated as functions. Functions must always be located at the beginning of a script. However, they can be relocated to an external library script that is subsequently reloaded by a work script similar to an Include statement.

PowerShell scripts may be used inside the pipeline. So that scripts do not block the pipeline, they must, like functions, define at least one process block. The block is separately invoked for every object in the pipeline.

All variables and functions that a script creates are private and apply only within the script. If you want to cancel their isolation, carry out a dot-sourced invocation of scripts and functions, such as typing a single dot in front of them when they are called. Set the validity of separate variable and function layers by using area designators like script: and global:.

When starting, PowerShell automatically looks for a series of profile scripts. If they are present, PowerShell runs them automatically provided that the execution policy allows their execution. You can set up the PowerShell work environment in the profile scripts and define alias names or functions that are to be provided automatically after PowerShell starts.

Digital signatures ensure that a script originates from a trusted source and has not been subsequently modified. You can imagine such scripts as a stamp of quality. Depending on the execution policy setting, PowerShell will permit only those scripts to run that have this stamp of quality.