From 27bd7014b25fda24f1cdc75a165952f73ecd6342 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Tue, 7 Jan 2025 10:12:09 -0600 Subject: [PATCH] Add note about installing trusted certs --- .../About/about_Signing.md | 84 ++++++++++--------- .../About/about_Signing.md | 77 +++++++++-------- .../About/about_Signing.md | 75 +++++++++-------- 3 files changed, 125 insertions(+), 111 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Signing.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Signing.md index 40e2162534d0..ae6d5184e3aa 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Signing.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Signing.md @@ -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 @@ -33,14 +33,14 @@ 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: @@ -48,10 +48,10 @@ To find the effective execution policy on your computer, type: 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 @@ -59,7 +59,13 @@ 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 @@ -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: @@ -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 @@ -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 @@ -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. @@ -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. @@ -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 @@ -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`. @@ -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] + + +[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 diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Signing.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Signing.md index b9e52e1f3445..4efc99d0e5fa 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Signing.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Signing.md @@ -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 @@ -35,14 +35,14 @@ 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: @@ -50,10 +50,10 @@ To find the effective execution policy on your computer, type: 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 @@ -61,7 +61,13 @@ 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 @@ -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: @@ -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 @@ -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 @@ -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. @@ -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. @@ -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 @@ -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] + + +[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 diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Signing.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Signing.md index 6652d4762404..b2c6e2752341 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Signing.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Signing.md @@ -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.5&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Signing @@ -35,14 +35,14 @@ 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: @@ -50,10 +50,10 @@ To find the effective execution policy on your computer, type: 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 @@ -61,7 +61,13 @@ 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 @@ -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: @@ -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 @@ -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 @@ -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. @@ -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. @@ -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] + + +[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