PowerShell provides an error message when you try to run a script:

PS > .\Test.ps1
File C:\temp\test.ps1 cannot be loaded because the execution of scripts is disa
bled on this system. Please see "get-help about_signing" for more details.
At line:1 char:10
+ .\Test.ps1 <<<<

To prevent this error message, use the Set-ExecutionPolicy cmdlet to change the PowerShell execution policy to one of the policies that allow scripts to run:

Set-ExecutionPolicy RemoteSigned

As normally configured, PowerShell operates strictly as an interactive shell. By disabling the execution of scripts by default, PowerShell prevents malicious PowerShell scripts from affecting users who have PowerShell installed, but who may never have used (or even heard of!) PowerShell.

You (as a reader of this book and PowerShell user) are not part of that target audience. You will want to configure PowerShell to run under one of the following five execution policies:

When it comes to evaluating script signatures, always remember that a signed script does not mean a safe script! The signature on a script gives you a way to verify who the script came from, but not that you can trust its author to run commands on your system. You need to make that decision for yourself, which is why PowerShell asks you.

Run the Set-ExecutionPolicy cmdlet to configure the system's execution policy. It supports three scopes:

If you specify the value of Undefined for the execution policy at a specific scope, PowerShell removes any execution policy you previously defined for that scope.

Alternatively, you may directly modify the registry key that PowerShell uses to store its execution policy. For the Currentuser and LocalMachine scopes, this is the ExecutionPolicy property under the registry path SOFTWARE\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell.

In an enterprise setting, PowerShell also lets you override this local preference through Group Policy. For more information about PowerShell's Group Policy support, see the section called “Manage PowerShell Security in an Enterprise”.

PowerShell warns you when it tries to load a script from an Intranet (UNC) path.

Enable Internet Explorer's UncAsIntranet setting, or add the UNC path to the list of trusted sites. Example 18.1, “Adding a server to the list of trusted hosts” adds server to the list of trusted sites.

$path = "HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Internet Settings\" +
    "ZoneMap\Domains\server"
New-Item -Path $path | New-ItemProperty -Name File -PropertyType DWORD -Value 2

When using an execution policy that detects Internet-based scripts, you may want to stop PowerShell from treating those scripts as remote.

In an enterprise setting, PowerShell sometimes warns of the dangers of Internet-based scripts even if they are located only on a network share. To remove this warning, first, ensure they have not actually been downloaded from the Internet. Right-click on the file from Windows Explorer, select Properties, and then click Unblock.

If unblocking the file does not resolve the issue (or is not an option), your machine has likely been configured to restrict access to network shares. This is common with Internet Explorer's Enhanced Security Configuration mode. To prevent this message, add the path of the network share to Internet Explorer's Intranet or Trusted Sites zone. For more information on managing Internet Explorer's zone mappings, see the section called “Add a Site to an Internet Explorer Security Zone”.

If you are using an Unrestricted execution policy and still want to get rid of this warning for remote files, you can use the Bypass execution policy to bypass PowerShell's security features entirely. For more information about execution policies, see the section called “Enable Scripting Through an Execution Policy”.

You want to sign a PowerShell script, module, or formatting file so that it may be run on systems that have their execution policy set to require signed scripts.

To sign the script with your standard code-signing certificate, use the Set-AuthenticodeSignature cmdlet:

$cert = @(Get-ChildItem cert:\CurrentUser\My -CodeSigning)[0]
Set-AuthenticodeSignature file.ps1 $cert

Alternatively, you may also use other traditional applications (such as signtool.exe) to sign PowerShell .ps1, .psm1, .psd1, and .ps1xml files.

Signing a script or formatting file provides you and your customers with two primary benefits: publisher identification and file integrity. When you sign a script, module, or formatting file, PowerShell appends your digital signature to the end of that file. This signature verifies that the file came from you and also ensures that nobody can tamper with the content in the file without detection. If you try to load a file that has been tampered with, PowerShell provides the following error message:

File C:\temp\test.ps1 cannot be loaded. The contents of file C:\temp\test.ps1
may have been tampered because the hash of the file does not match the hash
stored in the digital signature. The script will not execute on the system. Please
see "get-help about_signing" for more details.
At line:1 char:10
+ .\test.ps1 <<<<

When it comes to the signing of scripts, modules, and formatting files, PowerShell participates in the standard Windows Authenticode infrastructure. Because of that, techniques you may already know for signing files and working with their signatures continue to work with PowerShell scripts and formatting files. While the Set-AuthenticodeSignature cmdlet is primarily designed to support scripts and formatting files, it also supports DLLs and other standard Windows executable file types.

To sign a file, the Set-AuthenticodeSignature cmdlet requires that you provide it with a valid code-signing certificate. Most certification authorities provide Authenticode code-signing certificates for a fee. By using an Authenticode code-signing certificate from a reputable certification authority (such as VeriSign or Thawte), you can be sure that all users will be able to verify the signature on your script. Some online services offer extremely cheap code-signing certificates, but be aware that many machines may be unable to verify the digital signatures created by those certificates.

The –TimeStampServer parameter lets you sign your script or formatting file in a way that makes the signature on your script or formatting file valid even after your codesigning certificate expires.

For more information about the Set-AuthenticodeSignature cmdlet, type Get-Help Set-AuthenticodeSignature.

It is possible to benefit from the tamper-protection features of signed scripts without having to pay for an official code-signing certificate. You do this by creating a self-signed certificate. Scripts signed with a self-signed certificate will not be recognized as valid on other computers, but you can still sign scripts on your own computer.

When Example 18.2, “New-SelfSignedCertificate.ps1” runs, it prompts you for a password. Windows uses this password to prevent malicious programs from automatically signing files on your behalf.

##############################################################################

if(-not (Get-Command makecert.exe -ErrorAction SilentlyContinue))
{
    $errorMessage = "Could not find makecert.exe. " +
        "This tool is available as part of Visual Studio, or the Windows SDK."

    Write-Error $errorMessage
    return
}

$keyPath = Join-Path ([IO.Path]::GetTempPath()) "root.pvk"

makecert -n "CN=PowerShell Local Certificate Root" -a sha1 `
    -eku 1.3.6.1.5.5.7.3.3 -r -sv $keyPath root.cer `
    -ss Root -sr localMachine

makecert -pe -n "CN=PowerShell User" -ss MY -a sha1 `
    -eku 1.3.6.1.5.5.7.3.3 -iv $keyPath -ic root.cer

Remove-Item $keyPath

Get-ChildItem cert:\currentuser\my -codesign | 
    Where-Object { $_.Subject -match "PowerShell User" }
      

For more information about running scripts, see the section called “Run Programs, Scripts, and Existing Tools”.

You want to control PowerShell's security features in an enterprise setting.

To manage PowerShell's security features enterprise-wide:

In addition to PowerShell's execution policy, you want to block scripts by their publisher, location, or similarity to a specific script.

Create new Software Restriction Policy rules to enforce these requirements.

While not common, you may sometimes want to prevent PowerShell from running scripts signed by specific publishers, from a certain path, or with specific content. For all execution policies except for Bypass, PowerShell lets you configure this through the computer's software restriction policies.

To configure these software restriction policies, launch the Local Security Policy MMC snapin listed in the Administrative Tools group of the Start menu. Expand the Software Restriction Policies node, right-click Additional Rules, and then create the desired rules: certificate rules, path rule, or hash rules.

Certificate rules let you configure certain certificates that PowerShell will never trust. Path rules let you define system paths that allow or disallow execution of PowerShell scripts from certain paths. Hash rules let you block specific scripts from execution if they are the same as the script you used to generate the rule.

Figure 18.3, “Adding a new certificate rule” demonstrates how to add a new Certificate Rule.

Figure 18.3. Adding a new certificate rule

Browse to the certificate that represents the publisher you want to block, and then click OK to block that publisher.

Rather than block specific certificates, you can also create certificate policy that allows only certificates from a centrally administered whitelist. To do this, select either Allow only all administrators to manage Trusted Publishers or Allow only enterprise administrators to manage Trusted Publishers from the Trusted Publishers Management dialog.

You want to verify the digital signature of a PowerShell script or formatting file.

To validate the signature of a script or formatting file, use the Get-AuthenticodeSignature cmdlet:

PS > Get-AuthenticodeSignature .\test.ps1

    Directory: C:\temp

SignerCertificate                         Status     Path
-----------------                         ------     ----
FD48FAA9281A657DBD089B5A008FAFE61D3B32FD  Valid      test.ps1

The Get-AuthenticodeSignature cmdlet gets the Authenticode signature from a file. This can be a PowerShell script or formatting file, but the cmdlet also supports DLLs and other Windows standard executable file types.

By default, PowerShell displays the signature in a format that summarizes the certificate and its status. For more information about the signature, use the Format-List cmdlet, as shown in Example 18.3, “PowerShell displaying detailed information about an Authenticode signature”.

PS > Get-AuthenticodeSignature .\test.ps1 | Format-List

SignerCertificate      : [Subject]
                           CN=PowerShell User

                         [Issuer]
                           CN=PowerShell Local Certificate Root

                         [Serial Number]
                           454D75B8A18FBDB445D8FCEC4942085C

                         [Not Before]
                           4/22/2007 12:32:37 AM

                         [Not After]
                           12/31/2039 3:59:59 PM

                         [Thumbprint]
                           FD48FAA9281A657DBD089B5A008FAFE61D3B32FD

TimeStamperCertificate :
Status                 : Valid
StatusMessage          : Signature verified.
Path                   : C:\temp\test.ps1

For more information about the Get-AuthenticodeSignature cmdlet, type Get-Help Get-AuthenticodeSignature.

You want to request sensitive information from the user, but want to do this as securely as possible.

To securely handle sensitive information, store it in a SecureString whenever possible. The Read-Host cmdlet (with the –AsSecureString parameter) lets you prompt the user for (and handle) sensitive information by returning the user's response as a SecureString:

PS > $secureInput = Read-Host -AsSecureString "Enter your private key"
Enter your private key: 
PS > $secureInput
System.Security.SecureString

When you use any string in the .NET Framework (and therefore PowerShell), it retains that string so that it can efficiently reuse it later. Unlike most .NET data, unused strings persist even after you finish using them. When this data is in memory, there is always the chance that it could get captured in a crash dump, or swapped to disk in a paging operation. Because some data (such as passwords and other confidential information) may be sensitive, the .NET Framework includes the SecureString class: a container for text data that the framework encrypts when it stores it in memory. Code that needs to interact with the plain-text data inside a SecureString does so as securely as possible.

When a cmdlet author asks you for sensitive data (for example, an encryption key), the best practice is to designate that parameter as a SecureString to help keep your information confidential. You can provide the parameter with a SecureString variable as input, or the host prompts you for the SecureString if you do not provide one. PowerShell also supports two cmdlets (ConvertTo-SecureString and ConvertFrom-SecureString) that let you securely persist this data to disk. For more information about securely storing information on disk, see the section called “Securely Store Credentials on Disk”.

By default, the SecureString cmdlets use Windows' Data Protection API (DPAPI) when they convert your SecureString to and from its text representation. The key it uses to encrypt your data is based on your Windows logon credentials, so only you can decrypt the data that you've encrypted. If you want the exported data to work on another system or separate user account, you can use the cmdlet options that let you provide an explicit key. PowerShell treats this sensitive data as an opaque blob—and so should you.

However, there are many instances when you may want to automatically provide the SecureString input to a cmdlet rather than have the host prompt you for it. In these situations, the ideal solution is to use the ConvertTo-SecureString cmdlet to import a previously exported SecureString from disk. This retains the confidentiality of your data and still lets you automate the input.

If the data is highly dynamic (for example, coming from a CSV), then the ConvertTo-SecureString cmdlet supports an –AsPlainText parameter:

$secureString = ConvertTo-SecureString "Kinda Secret" -AsPlainText-Force

Since you've already provided plain-text input in this case, placing this data in a SecureString no longer provides a security benefit. To prevent a false sense of security, the cmdlet requires the -Force parameter to convert plain-text data into a SecureString.

Once you have data in a SecureString, you may want to access its plain-text representation. PowerShell doesn't provide a direct way to do this, as that defeats the purpose of a SecureString. If you still want to convert a SecureString to plain text, you have two options:

Your script requires that users provide it with a username and password, but you want to do this as securely as possible.

To request a credential from the user, use the Get-Credential cmdlet:

$credential = Get-Credential

The Get-Credential cmdlet reads credentials from the user as securely as possible and ensures that the user's password remains highly protected the entire time. For an example of using the Get-Credential cmdlet effectively in a script, see the section called “Program: Start a Process As Another User”.

Once you have the username and password, you can pass that information around to any other command that accepts a PowerShell credential object without worrying about disclosing sensitive information. If a command doesn't accept a PowerShell credential object (but does support a SecureString for its sensitive information), the resulting PsCredential object provides a Username property that returns the username in the credential and a Password property that returns a SecureString containing the user's password.

Unfortunately, not everything that requires credentials can accept either a PowerShell credential or SecureString. If you need to provide a credential to one of these commands or API calls, the PsCredential object provides a GetNetworkCredential() method to convert the PowerShell credential to a less secure NetworkCredential object. Once you've converted the credential to a NetworkCredential, the UserName and Password properties provide unencrypted access to the username and password from the original credential. Many network-related classes in the .NET Framework support the NetworkCredential class directly.

If a frequently run script requires credentials, you might consider caching those credentials in memory to improve the usability of that script. For example, in the region of the script that calls the Get-Credential cmdlet, you can instead use the techniques shown by Example 18.4, “Caching credentials in memory to improve usability”.

$credential = $null
if(Test-Path Variable:\Lee.Holmes.CommonScript.CachedCredential)
{
    $credential = ${GLOBAL:Lee.Holmes.CommonScript.CachedCredential}
}

${GLOBAL:Lee.Holmes.CommonScript.CachedCredential} =
   Get-Credential $credential

$credential = ${GLOBAL:Lee.Holmes.CommonScript.CachedCredential}

The script prompts the user for their credentials the first time they call it but uses the cached credentials for subsequent calls. If your command is part of a PowerShell module, you can avoid storing the information in a global variable. For more information about this technique, see the section called “Write Commands that Maintain State”.

To cache these credentials on disk (to support un-attended operation), see the section called “Securely Store Credentials on Disk”.

For more information about the Get-Credential cmdlet, type Get-Help Get-Credential.

If your script requires user credentials, PowerShell offers the PsCredential object. This lets you securely store those credentials, or pass them to other commands that accept PowerShell credentials. When you write a script that accepts credentials, consider letting the user to supply either a username or a preexisting credential. This is the model followed by the Get-Credential cmdlet, and provides an intuitive user experience. Example 18.5, “Start-ProcessAsUser.ps1” demonstrates a useful approach to support this model. As the framework for this demonstration, the script lets you start a process as another user. While this scenario addressed by this specific script is fully handled by the Start-Process cmdlet, it provides a useful framework for discussion.

##############################################################################

param(
  $credential = (Get-Credential),
  [string] $process = $(throw "Please specify a process to start."),
  [string] $arguments = ""
  )

if($credential -is "String")
{
    $credential = Get-Credential $credential
}

if(-not ($credential -is "System.Management.Automation.PsCredential"))
{
    return
}

$startInfo = New-Object Diagnostics.ProcessStartInfo
$startInfo.Filename = $process
$startInfo.Arguments = $arguments

if(($credential.Username -eq "$ENV:Username") -or
    ($credential.Username -eq "\$ENV:Username"))
{
    $startInfo.Verb = "runas"
}
else
{
    $startInfo.UserName = $credential.Username
    $startInfo.Password = $credential.Password
    $startInfo.UseShellExecute = $false
}

[Diagnostics.Process]::Start($startInfo)
      

For a version of this script that lets you invoke PowerShell commands in an elevated session and easily interact with the results, see the section called “Program: Run a Temporarily Elevated Command”.

For more information about running scripts, see the section called “Run Programs, Scripts, and Existing Tools”.

One popular feature of many Unix-like operating systems is the sudo command: a feature that lets you invoke commands as another user without switching context.

This is a common desire in Windows Vista and above, where User Access Control (UAC) means that most interactive sessions do not have their Administrator privileges enabled. Enabling these privileges is often a clumsy task, requiring that you launch a new instance of PowerShell with the "Run as Administrator" option enabled.

Example 18.6, “Invoke-ElevatedCommand.ps1” resolves many of these issues by launching an administrative shell for you, and letting it participate in a regular (non-elevated) PowerShell pipeline.

To do this, it first streams all of your input into a richly-structured CliXml file on disk. It invokes the elevated command, and stores its results into another richly-structure CliXml file on disk. Finally, it imports the structured data from disk, and removes the temporary files.

##############################################################################

<#

.SYNOPSIS
Runs the provided script block under an elevated instance of PowerShell as
through it were a member of a regular pipeline.

.EXAMPLE
PS >Get-Process | Invoke-ElevatedCommand.ps1 {
    $input | Where-Object { $_.Handles -gt 500 } } | Sort Handles

#>

param(
    [Parameter(Mandatory = $true)]
    [ScriptBlock] $Scriptblock,
    
    [Parameter(ValueFromPipeline = $true)]
    $InputObject,
    
    [switch] $EnableProfile
  )

begin
{
    $inputItems = New-Object System.Collections.ArrayList
}

process
{
    $null = $inputItems.Add($inputObject)
}

end
{
    $outputFile = [IO.Path]::GetTempFileName()
    $inputFile = [IO.Path]::GetTempFileName()
    
    $inputItems.ToArray() | Export-CliXml -Depth 1 $inputFile

    $commandLine = ""
    if(-not $EnableProfile) { $commandLine += "-NoProfile " }

    $commandString = "Set-Location '$($pwd.Path)'; " +
        "`$output = Import-CliXml '$inputFile' | " +
        "& {" + $scriptblock.ToString() + "} 2>&1; " +
        "Export-CliXml -Depth 1 -In `$output '$outputFile'"

    $commandBytes = [System.Text.Encoding]::Unicode.GetBytes($commandString)
    $encodedCommand = [Convert]::ToBase64String($commandBytes)
    $commandLine += "-EncodedCommand $encodedCommand"

    $process = Start-Process -FilePath (Get-Command powershell).Definition `
        -ArgumentList $commandLine -Verb RunAs `
        -WindowStyle Hidden `
        -Passthru
    $process.WaitForExit()

    if((Get-Item $outputFile).Length -gt 0)
    {
        Import-CliXml $outputFile
    }

    Remove-Item $outputFile
    Remove-Item $inputFile
}
      

For more information about the CliXml commands, see the section called “Easily Import and Export Your Structured Data”. For more information about running scripts, see the section called “Run Programs, Scripts, and Existing Tools”.

Your script performs an operation that requires credentials, but you don't want it to require user interaction when it runs.

To securely store the credential's password to disk so that your script can load it automatically, use the ConvertFrom-SecureString and ConvertTo-SecureString cmdlets.

PS > $credPath = Join-Path (Split-Path $profile) <CurrentScript>.ps1.credential
PS > $credential.Password | ConvertFrom-SecureString | Set-Content $credPath

$credPath = Join-Path (Split-Path $profile) <CurrentScript>.ps1.credential
$password = Get-Content $credPath | ConvertTo-SecureString
$credential = New-Object System.Management.Automation.PsCredential `
    "CachedUser",$password

When reading the solution, you might at first be wary of storing a password on disk. While it is natural (and prudent) to be cautious of littering your hard drive with sensitive information, the ConvertFrom-SecureString cmdlet encrypts this data using Windows' standard Data Protection API. This ensures that only your user account can properly decrypt its contents.

While keeping a password secure is an important security feature, you may sometimes want to store a password (or other sensitive information) on disk so that other accounts have access to it anyway. This is often the case with scripts run by service accounts or scripts designed to be transferred between computers. The ConvertFrom-SecureString and ConvertTo-SecureString cmdlets support this by letting you to specify an encryption key.

Although the solution stores the password in the directory that contains your profile, you could also load it from the same location as your script. To learn how to load it from the same location as your script, see the section called “Find Your Script's Location”.

For more information about the ConvertTo-SecureString and ConvertFrom-SecureString cmdlets, type Get-Help ConvertTo-SecureString or Get-Help ConvertFrom-SecureString.

You want to retrieve information about certificates for the current user or local machine.

To browse and retrieve certificates on the local machine, use PowerShell's certificate drive. This drive is created by the certificate provider, as shown in Example 18.7, “Exploring certificates in the certificate provider”.

PS > Set-Location cert:\CurrentUserPS > $cert = Get-ChildItem -Rec -CodeSign
PS > $cert | Format-List

Subject      : CN=PowerShell User
Issuer       : CN=PowerShell Local Certificate Root
Thumbprint   : FD48FAA9281A657DBD089B5A008FAFE61D3B32FD
FriendlyName :
NotBefore    : 4/22/2007 12:32:37 AM
NotAfter     : 12/31/2039 3:59:59 PM
Extensions   : {System.Security.Cryptography.Oid, System.Security.Cryptogr
               aphy.Oid}

The certificate drive provides a useful way to navigate and view certificates for the current user or local machine. For example, if your execution policy requires the use of digital signatures, the following command tells you which publishers are trusted to run scripts on your system:

Get-ChildItem cert:\CurrentUser\TrustedPublisher

The certificate provider is probably most commonly used to select a code-signing certificate for the Set-AuthenticodeSignature cmdlet. The following command selects the "best" code-signing certificate: the one that expires last.

$certificates = Get-ChildItem Cert:\CurrentUser\My -CodeSign
$signingCert = @($certificates | Sort -Desc NotAfter)[0]

In this -CodeSign parameter lets you search for certificates in the certificate store that support code signing. To search for certificates used for other purposes, see the section called “Program: Search the Certificate Store”.

Although the certificate provider is useful for browsing and retrieving information from the computer's certificate stores, it does not let you add or remove items from these locations. If you want to manage certificates in the certificate store, the System.Security.Cryptography.X509Certificates.X509Store class (and other related classes from the System.Security.Cryptography.X509Certificates namespace) from the .NET Framework support that functionality. For an example of this approach, see the section called “Add and Remove Certificates”.

For more information about the certificate provider, type Get-Help Certificate.

One useful feature of the certificate provider is that it supports a –CodeSign parameter that lets you search for certificates in the certificate store that support code signing.

This parameter is called a dynamic parameter: one that has been added by a provider to a core PowerShell cmdlet. You can discover the dynamic parameters for a provider by navigating to that provider, and then reviewing the output of Get-Command -Syntax. For example:

PS > Set-Location cert:PS > Get-Command Get-ChildItem -Syntax
Get-ChildItem [[-Path] <String[]>] [[-Filter] <String>] (...) [-CodeSigningCert]

In addition to reading the output of Get-Command, the help topic for the provider often describes the dynamic parameters it supports. For a list of the provider help topics, type Get-Help -Category Provider.

Code-signing certificates are not the only kind of certificates, however; other frequently used certificate types are Encrypting File System, Client Authentication, and more.

Example 18.8, “Search-CertificateStore.ps1” lets you search the certificate provider for certificates that support a given Enhanced Key Usage (EKU).

##############################################################################

param(
  $ekuName = $(throw "Please specify the friendly name of an " +
                     "Enhanced Key Usage (such as 'Code Signing'")
  )

foreach($cert in Get-ChildItem cert:\CurrentUser\My)
{
    foreach($extension in $cert.Extensions) 
    { 
        foreach($certEku in $extension.EnhancedKeyUsages) 
        { 
            if($certEku.FriendlyName -eq $ekuName) 
            { 
                $cert 
            } 
        } 
    } 
}
      

For more information about running scripts, see the section called “Run Programs, Scripts, and Existing Tools”.

You want to add and remove certificates from the certificate store.

Use the certificate store APIs from the .NET Framework, as shown in Example 18.9, “Adding and removing certificates”.

## Removing a certificate
$cert = Get-ChildItem cert:\currentuser\TrustedPublisher\<thumbprint>
$store = New-Object System.Security.Cryptography.X509Certificates.X509Store `
    "TrustedPublisher","CurrentUser"
$store.Open("ReadWrite")
$store.Remove($cert)
$store.Close()

$cert = Get-PfxCertificate <path_to_certificate>
$store = New-Object System.Security.Cryptography.X509Certificates.X509Store `
    "TrustedPublisher","CurrentUser"
$store.Open("ReadWrite")
$store.Add($cert)
$store.Close()

The certificate drive provides a useful way to navigate and view certificates for the current user or local machine. For example, if your execution policy requires the use of digital signatures, the following command tells you which publishers are trusted to run scripts on your system:

Get-ChildItem cert:\CurrentUser\TrustedPublisher

The certificate provider is ultimately a read-only view of your certificates, however. After using the certificate provider to retrieve a certificate, you can then use the .NET APIs to remove it from the certificate store permanently.

Likewise, the Get-PfxCertificate cmdlet lets you review a certificate from a file that contains it, but does not let you install it into the certificate store permanently. The .NET APIs are also the way to import the certificate for good.

For more information about retrieving certificates from the certificate provider, see the section called “Access User and Machine Certificates”. For more information about working with classes from the .NET Framework, see the section called “Work with .NET Objects”.

You want to work with a security identifier in Security Descriptor Definition Language (SDDL) form.

Use the System.Security.AccessControl.CommonSecurityDescriptor class from the .NET Framework, as shown by Example 18.10, “Automating security configuration of PowerShell Remoting”.

## Get the SID for the "PowerShell Remoting Users" group
$account = New-Object Security.Principal.NTAccount "PowerShell Remoting Users"
$sid = $account.Translate([Security.Principal.SecurityIdentifier]).Value

$config = Get-PsSessionConfiguration Microsoft.PowerShell
$existingSddl = $config.SecurityDescriptorSddl

$arguments = $false,$false,$existingSddl
$mapper = New-Object Security.AccessControl.CommonSecurityDescriptor $arguments

$mapper.DiscretionaryAcl.AddAccess("Allow",$sid,268435456,"None","None")

$newSddl = $mapper.GetSddlForm("All")

Set-PSSessionConfiguration Microsoft.PowerShell -SecurityDescriptorSddl $newSddl

Security descriptors are often shown (or requested) in SDDL form. The SDDL form of a security descriptor is cryptic, highly-specific, and plain text. All of these aspects make it difficult to work with reliably, so you can use the System.Security.AccessControl.CommonSecurityDescriptor class from the .NET Framework to do most of the gritty work for you.

For more information about the SDDL format, see http://msdn.microsoft.com/en-us/library/aa379570%28VS.85%29.aspx. For an example of this in action, see the section called “Configure User Permissions for Remoting”.