Skip to content

Add note about installing trusted certs #11641

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jan 7, 2025
Merged

Add note about installing trusted certs #11641

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 44 additions & 40 deletions reference/5.1/Microsoft.PowerShell.Core/About/about_Signing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
description: Explains how to sign scripts so that they comply with the PowerShell execution policies.
Locale: en-US
ms.date: 10/23/2023
ms.date: 01/07/2025
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_signing?view=powershell-5.1&WT.mc_id=ps-gethelp
schema: 2.0.0
title: about_Signing
Expand Down Expand Up @@ -33,33 +33,39 @@ PowerShell checks the Authenticode signature of the following type types:
- `.xaml` XAML script files

For more information about PowerShell execution policies, see
[about_Execution_Policies][01].
[about_Execution_Policies][03].

## To permit signed scripts to run
## Permit the execution of signed scripts

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

The **Restricted** policy doesn't permit any scripts to run.
The **Restricted** policy prevents all scripts from running.

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

```powershell
Get-ExecutionPolicy
```

To run unsigned scripts that you write on your local computer and signed
scripts from other users, start PowerShell with the **Run as Administrator**
option and then use the following command to change the execution policy on the
computer to **RemoteSigned**:
The **RemoteSigned** policy allows you to run signed scripts or unsigned
scripts that you create locally. To configure this policy, start PowerShell
with the **Run as Administrator** option and then use the following command to
change the execution policy.

```powershell
Set-ExecutionPolicy RemoteSigned
```

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

## Running unsigned scripts using the RemoteSigned execution policy
To run a signed script, the script must have a digital signature from a trusted
publisher. The code signing certificate must be issued by a certification
must be issued by a certification authority that is trusted on the computer.
Self-signed certificates must be installed in the **Trusted Root Certificates**
store on the computer.

## Run unsigned scripts using the RemoteSigned policy

If your PowerShell execution policy is **RemoteSigned**, PowerShell won't run
unsigned scripts that are downloaded from the internet, including unsigned
Expand All @@ -85,7 +91,7 @@ procedure.
1. Right-click the script file, and then click **Properties**.
1. Click **Unblock**.

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

Expand All @@ -110,10 +116,8 @@ You can sign the scripts that you write and the scripts that you get from other
sources. Before you sign any script, examine each command to verify that it's
safe to run.

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

For more information about how to sign a script file, see
[Set-AuthenticodeSignature][03].
[Set-AuthenticodeSignature][06].

The `New-SelfSignedCertificate` cmdlet, introduced in the PKI module in
PowerShell 3.0, creates a self-signed certificate that's appropriate for
Expand All @@ -136,10 +140,11 @@ certificate. Two types of certificates are suitable for signing a script file:
on your computer. However, a script signed by a self-signed certificate will
not run on other computers.

Typically, you would use a self-signed certificate only to sign scripts that
you write for your own use and to sign scripts that you get from other sources
that you have verified to be safe. It isn't appropriate for scripts that will
be shared, even within an enterprise.
Self-signed certificate should only be used to sign scripts for testing
purposes.

It isn't appropriate for scripts that will be shared, even within an
enterprise.

If you create a self-signed certificate, be sure to enable strong private key
protection on your certificate. This prevents malicious programs from signing
Expand All @@ -148,7 +153,7 @@ topic.

## Create a self-signed certificate

To create a self-signed certificate, use the [New-SelfSignedCertificate][04]
To create a self-signed certificate, use the [New-SelfSignedCertificate][08]
cmdlet in the PKI module. This module is introduced in PowerShell 3.0. For more
information, see the help topic for the `New-SelfSignedCertificate` cmdlet.

Expand All @@ -169,7 +174,7 @@ Certificate Creation tool `MakeCert.exe`. This tool is included in the
Microsoft .NET SDK (versions 1.1 and later) and in the Microsoft Windows SDK.

For more information about the syntax and the parameter descriptions of the
`MakeCert.exe` tool, see [Certificate Creation Tool (MakeCert.exe)][05].
`MakeCert.exe` tool, see [Certificate Creation Tool (MakeCert.exe)][01].

To use the `MakeCert.exe` tool to create a certificate, run the following
commands in an SDK Command Prompt window.
Expand Down Expand Up @@ -201,7 +206,7 @@ a certificate file in the file system directory.
At the PowerShell prompt, type:

```powershell
Get-ChildItem cert:\CurrentUser\my -codesigning
Get-ChildItem cert:\CurrentUser\my -CodeSigning
```

This command uses the PowerShell Certificate provider to view information
Expand Down Expand Up @@ -229,10 +234,9 @@ you are using the **AllSigned** execution policy, you must sign the
`Add-Signature.ps1` script before you run it.

> [!IMPORTANT]
> The script must be saved using ASCII or UTF8NoBOM encoding. You can sign a
> script file that uses a different encoding, but the script fails to run or
> the module containing the script fails to import. The script will also fail
> if the file contains Unicode (UTF8) characters.
> Before PowerShell 7.2, the script must be saved using ASCII or UTF8NoBOM
> encoding. PowerShell 7.2 and higher supports signed scripts for any encoding
> format.

To use this script, copy the following text into a text file, and name it
`Add-Signature.ps1`.
Expand Down Expand Up @@ -321,19 +325,19 @@ stamp server ensures that users can use your script for many years to come.

## See also

- [about_Execution_Policies][01]
- [about_Profiles][06]
- [Set-AuthenticodeSignature][03]
- [Get-ExecutionPolicy][07]
- [Set-ExecutionPolicy][08]
- [Introduction to Code Signing][09]

[01]: about_Execution_Policies.md
[02]: /previous-versions/windows/hardware/design/dn653556(v=vs.85)
[03]: xref:Microsoft.PowerShell.Security.Set-AuthenticodeSignature
[04]: xref:pki.New-SelfSignedCertificate
[05]: /previous-versions/dotnet/netframework-2.0/bfsktky3(v=vs.80)
[06]: about_Profiles.md
[07]: xref:Microsoft.PowerShell.Security.Get-ExecutionPolicy
[08]: xref:Microsoft.PowerShell.Security.Set-ExecutionPolicy
[09]: /previous-versions/windows/internet-explorer/ie-developer/platform-apis/ms537361(v=vs.85)
- [about_Execution_Policies][03]
- [about_Profiles][04]
- [Set-AuthenticodeSignature][06]
- [Get-ExecutionPolicy][05]
- [Set-ExecutionPolicy][07]
- [Introduction to Code Signing][02]

<!-- link references -->
[01]: /previous-versions/dotnet/netframework-2.0/bfsktky3(v=vs.80)
[02]: /previous-versions/windows/internet-explorer/ie-developer/platform-apis/ms537361(v=vs.85)
[03]: about_Execution_Policies.md
[04]: about_Profiles.md
[05]: xref:Microsoft.PowerShell.Security.Get-ExecutionPolicy
[06]: xref:Microsoft.PowerShell.Security.Set-AuthenticodeSignature
[07]: xref:Microsoft.PowerShell.Security.Set-ExecutionPolicy
[08]: xref:pki.New-SelfSignedCertificate
77 changes: 41 additions & 36 deletions reference/7.4/Microsoft.PowerShell.Core/About/about_Signing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
description: Explains how to sign scripts so that they comply with the PowerShell execution policies.
Locale: en-US
ms.date: 10/23/2023
ms.date: 01/07/2025
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_signing?view=powershell-7.4&WT.mc_id=ps-gethelp
schema: 2.0.0
title: about_Signing
Expand Down Expand Up @@ -35,33 +35,39 @@ PowerShell checks the Authenticode signature of the following type types:
- `.xaml` XAML script files

For more information about PowerShell execution policies, see
[about_Execution_Policies][01].
[about_Execution_Policies][03].

## To permit signed scripts to run
## Permit the execution of signed scripts

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

The **Restricted** policy doesn't permit any scripts to run.
The **Restricted** policy prevents all scripts from running.

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

```powershell
Get-ExecutionPolicy
```

To run unsigned scripts that you write on your local computer and signed
scripts from other users, start PowerShell with the **Run as Administrator**
option and then use the following command to change the execution policy on the
computer to **RemoteSigned**:
The **RemoteSigned** policy allows you to run signed scripts or unsigned
scripts that you create locally. To configure this policy, start PowerShell
with the **Run as Administrator** option and then use the following command to
change the execution policy.

```powershell
Set-ExecutionPolicy RemoteSigned
```

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

## Running unsigned scripts using the RemoteSigned execution policy
To run a signed script, the script must have a digital signature from a trusted
publisher. The code signing certificate must be issued by a certification
must be issued by a certification authority that is trusted on the computer.
Self-signed certificates must be installed in the **Trusted Root Certificates**
store on the computer.

## Run unsigned scripts using the RemoteSigned policy

If your PowerShell execution policy is **RemoteSigned**, PowerShell won't run
unsigned scripts that are downloaded from the internet, including unsigned
Expand All @@ -87,7 +93,7 @@ procedure.
1. Right-click the script file, and then click **Properties**.
1. Click **Unblock**.

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

Expand All @@ -112,10 +118,8 @@ You can sign the scripts that you write and the scripts that you get from other
sources. Before you sign any script, examine each command to verify that it's
safe to run.

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

For more information about how to sign a script file, see
[Set-AuthenticodeSignature][03].
[Set-AuthenticodeSignature][06].

The `New-SelfSignedCertificate` cmdlet, introduced in the PKI module in
PowerShell 3.0, creates a self-signed certificate that's appropriate for
Expand All @@ -138,10 +142,11 @@ certificate. Two types of certificates are suitable for signing a script file:
on your computer. However, a script signed by a self-signed certificate will
not run on other computers.

Typically, you would use a self-signed certificate only to sign scripts that
you write for your own use and to sign scripts that you get from other sources
that you have verified to be safe. It isn't appropriate for scripts that will
be shared, even within an enterprise.
Self-signed certificate should only be used to sign scripts for testing
purposes.

It isn't appropriate for scripts that will be shared, even within an
enterprise.

If you create a self-signed certificate, be sure to enable strong private key
protection on your certificate. This prevents malicious programs from signing
Expand All @@ -150,7 +155,7 @@ topic.

## Create a self-signed certificate

To create a self-signed certificate, use the [New-SelfSignedCertificate][04]
To create a self-signed certificate, use the [New-SelfSignedCertificate][08]
cmdlet in the PKI module. This module is introduced in PowerShell 3.0. For more
information, see the help topic for the `New-SelfSignedCertificate` cmdlet.

Expand All @@ -171,7 +176,7 @@ Certificate Creation tool `MakeCert.exe`. This tool is included in the
Microsoft .NET SDK (versions 1.1 and later) and in the Microsoft Windows SDK.

For more information about the syntax and the parameter descriptions of the
`MakeCert.exe` tool, see [Certificate Creation Tool (MakeCert.exe)][05].
`MakeCert.exe` tool, see [Certificate Creation Tool (MakeCert.exe)][01].

To use the `MakeCert.exe` tool to create a certificate, run the following
commands in an SDK Command Prompt window.
Expand Down Expand Up @@ -203,7 +208,7 @@ a certificate file in the file system directory.
At the PowerShell prompt, type:

```powershell
Get-ChildItem cert:\CurrentUser\my -codesigning
Get-ChildItem cert:\CurrentUser\my -CodeSigning
```

This command uses the PowerShell Certificate provider to view information
Expand Down Expand Up @@ -322,19 +327,19 @@ stamp server ensures that users can use your script for many years to come.

## See also

- [about_Execution_Policies][01]
- [about_Profiles][06]
- [Set-AuthenticodeSignature][03]
- [Get-ExecutionPolicy][07]
- [Set-ExecutionPolicy][08]
- [Introduction to Code Signing][09]

[01]: about_Execution_Policies.md
[02]: /previous-versions/windows/hardware/design/dn653556(v=vs.85)
[03]: xref:Microsoft.PowerShell.Security.Set-AuthenticodeSignature
[04]: xref:pki.New-SelfSignedCertificate
[05]: /previous-versions/dotnet/netframework-2.0/bfsktky3(v=vs.80)
[06]: about_Profiles.md
[07]: xref:Microsoft.PowerShell.Security.Get-ExecutionPolicy
[08]: xref:Microsoft.PowerShell.Security.Set-ExecutionPolicy
[09]: /previous-versions/windows/internet-explorer/ie-developer/platform-apis/ms537361(v=vs.85)
- [about_Execution_Policies][03]
- [about_Profiles][04]
- [Set-AuthenticodeSignature][06]
- [Get-ExecutionPolicy][05]
- [Set-ExecutionPolicy][07]
- [Introduction to Code Signing][02]

<!-- link references -->
[01]: /previous-versions/dotnet/netframework-2.0/bfsktky3(v=vs.80)
[02]: /previous-versions/windows/internet-explorer/ie-developer/platform-apis/ms537361(v=vs.85)
[03]: about_Execution_Policies.md
[04]: about_Profiles.md
[05]: xref:Microsoft.PowerShell.Security.Get-ExecutionPolicy
[06]: xref:Microsoft.PowerShell.Security.Set-AuthenticodeSignature
[07]: xref:Microsoft.PowerShell.Security.Set-ExecutionPolicy
[08]: xref:pki.New-SelfSignedCertificate
Loading