en-US/OpenAuthenticode.dll-Help.xml
|
<?xml version="1.0" encoding="utf-8"?>
<helpItems schema="maml" xmlns="http://msh"> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-OpenAuthenticodeAzKey</command:name> <command:verb>Get</command:verb> <command:noun>OpenAuthenticodeAzKey</command:noun> <maml:description> <maml:para>Get an Azure KeyVault certificate and key for use with Authenticode signing.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Gets the Azure keyVault certificate and key from the vault and key name specified. This key can be used with Set-OpenAuthenticodeSignature (./Set-OpenAuthenticodeSignature.md)to sign a file without having to download the key locally. The authenticated Azure principal must have the following Azure access policy permissions on the requested key:</maml:para> <maml:para>* Key Permissions: `Sign`</maml:para> <maml:para>* Certificate Permissions: `Get`</maml:para> <maml:para></maml:para> <maml:para>The signing workflow does not require the key to be present on the local machine as it calls the Azure `Sign` API with the Authenticode digest. This ensures the key does not leave Azure itself but rather Azure is used to sign the data remotely.</maml:para> <maml:para>Currently only certificates signed with an RSA can be used, ECDSA support is planned for the future. The certificate must also have the Key Usage of `Digital Signature (80)` and Enhanced Key Usage `Code Signing (1.3.6.1.5.5.7.3.3)` for it to be used with Authenticode.</maml:para> <maml:para>Currently authentication relies on the lookup behaviour of DefaultAzureCredential (https://learn.microsoft.com/en-us/dotnet/api/overview/azure/identity-readme?view=azure-dotnet). It will lookup environment variables, device managed identities, az cli contexts, etc to authenticate with Azure. It has not been set to allow for interactive authentication through the web browser.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-OpenAuthenticodeAzKey</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="0" aliases="VaultName"> <maml:name>Vault</maml:name> <maml:description> <maml:para>The name of the Azure KeyVault to find the certificate in.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="CertificateName"> <maml:name>Certificate</maml:name> <maml:description> <maml:para>The name of the Azure KeyVault certificate/key to retrieve.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="CertificateName"> <maml:name>Certificate</maml:name> <maml:description> <maml:para>The name of the Azure KeyVault certificate/key to retrieve.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="0" aliases="VaultName"> <maml:name>Vault</maml:name> <maml:description> <maml:para>The name of the Azure KeyVault to find the certificate in.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para>None</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>OpenAuthenticode.Shared.AzureKey</maml:name> </dev:type> <maml:description> <maml:para>The AzureKey object that can be used with the `-Key` parameter in `Set-OpenAuthenticodeSignature`.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>----------- Example 1: Get key for use with signing -----------</maml:title> <dev:code>PS C:\> $key = Get-OpenAuthenticodeAzKey -Vault code-signing-test -Certificate Authenticode PS C:\> Set-AuthenticodeSignature test.ps1 -Key $key</dev:code> <dev:remarks> <maml:para>Gets the Azure KeyVault key `Authenticode` in the vault `code-signing-test` and uses it to sign the file `test.ps1`. This does not include any pre-requisite steps for setting up the authentication details used by `Get-OpenAuthenticodeAzKey`.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://www.github.com/jborean93/PowerShell-OpenAuthenticode/blob/main/docs/en-US/Get-OpenAuthenticodeAzKey.md</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Azure Key Vault</maml:linkText> <maml:uri>https://azure.microsoft.com/en-au/products/key-vault/</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>DefaultAzureCredential Workflow</maml:linkText> <maml:uri>https://learn.microsoft.com/en-us/dotnet/api/overview/azure/identity-readme?view=azure-dotnet</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-OpenAuthenticodeSignature</command:name> <command:verb>Get</command:verb> <command:noun>OpenAuthenticodeSignature</command:noun> <maml:description> <maml:para>Gets information about the Authenticode signature for a file.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Gets the Authenticode signature information from the path or content specified. This information includes the certificate that signed the file, the hash algorithm used, and the timestamp countersignature information if it was used. An error record is written if the path specified does not have an authenticode signature present.</maml:para> <maml:para>See about_AuthenticodeProviders (./about_AuthenticodeProviders.md)for more information about what providers are currently supported. When using a file path that has no extension, an explicit `-Provider` must be specified to indicate what Authenticode provider needs to be used to retrieve and validate the signature.</maml:para> <maml:para>It is also possible to provide a file to validate using the `-Content` and `-RawContent` which accepts a string and byte array respectively. The `-Content` value is useful for files that are read as string like PowerShell scripts rather than binary files like a `.dll`.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-OpenAuthenticodeSignature</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none"> <maml:name>Content</maml:name> <maml:description> <maml:para>Gets the Authenticode signature from the file strings contents. This is useful if the file is stored in memory and not on the filesystem. The `-Provider` parameter must be provided when using `-Content`.</maml:para> <maml:para>If the string value is from a file with a BOM it is important to ensure the string has the BOM chars present. An example of how to prefix a string with an encoding BOM is as follows.</maml:para> <maml:para></maml:para> <maml:para></maml:para> <maml:para>$encoding = [System.Text.Encoding]::Unicode $bom = $encoding.GetString($encoding.GetPreamble()) $content = $bom + (Get-Content $path -Raw) Note: it is far safer to just use `-Path` in the case above. This example is just to display how a BOM can be prefixed if it was required.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Provider</maml:name> <maml:description> <maml:para>Specify the Authenticode provider used to extract the signature. This is required if the `-Content` or `-RawContent` parameter is specified. If `-Path`, or `-LiteralPath` is specified, the provider is found based on the extension of the file being read. If the file has no extension then an explicit provider must be specified.</maml:para> <maml:para>Valid providers are:</maml:para> <maml:para>* `NotSpecified` - Uses the file extension to find the provider</maml:para> <maml:para>* `PowerShell` - Uses the PowerShell script Authenticode provider</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">AuthenticodeProvider</command:parameterValue> <dev:type> <maml:name>AuthenticodeProvider</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SkipCertificateCheck</maml:name> <maml:description> <maml:para>Skips the CA trust validation of the certificate that signed the file. The signature will still be validated to ensure the file has been tampered with but if this switch is present, the certificate CA trust will not be checked.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>TrustStore</maml:name> <maml:description> <maml:para>A collection of certificate to use as a custom trusted store location instead of the system provided certificates. Any self signed certificates in this collection will be treated as a trusted root CA during the certificate validation, other certificates will be treated as intermediaries used to help build the trust chain. This should only be used for testing purposes and the system store should be used in most production scenarios.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">X509Certificate2Collection</command:parameterValue> <dev:type> <maml:name>X509Certificate2Collection</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Get-OpenAuthenticodeSignature</maml:name> <command:parameter required="true" variableLength="true" globbing="true" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="FilePath"> <maml:name>Path</maml:name> <maml:description> <maml:para>The path to the files to retrieve the Authenticode information for. Wildcards are permitted and a signature will be outputted for every file that matches the wildcard. This is only supported for paths in the FileSystem provider.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Encoding</maml:name> <maml:description> <maml:para>A hint to provide to the Authenticode provider that indicates what the file string encoding method is. This is only used by Authenticode providers that need to read the file as a string, like PowerShell. The default used is dependent on the Authenticode provider but most commonly will be `UTF-8`.</maml:para> <maml:para>This accepts a `System.Text.Encoding` type but also a string or int representing the encoding from `[System.Text.Encoding]::GetEncoding(...)`. Some common encoding values are:</maml:para> <maml:para>* `Utf8` - UTF-8 but without a Byte Order Mark (BOM)</maml:para> <maml:para>* `ASCII` - ASCII (bytes 0-127)</maml:para> <maml:para>* `ANSI` - The ANSI encoding commonly used in legacy Windows encoding</maml:para> <maml:para>* `OEM` - The value of `[System.Text.Encoding]::Default` which is UTF-8 without a BOM</maml:para> <maml:para>* `Unicode` - UTF-16-LE</maml:para> <maml:para>* `Utf8Bom` - UTF-8 but with a BOM</maml:para> <maml:para>* `Utf8NoBom` - Same as `Utf8`</maml:para> <maml:para></maml:para> <maml:para>The `ANSI` encoding typically refers to the legacy Windows encoding used in older PowerShell versions. If creating a script that should be used across the various PowerShell versions, it is highly recommended to use an encoding with a `BOM` like `Utf8Bom` or `Unicode`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Encoding</command:parameterValue> <dev:type> <maml:name>Encoding</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Provider</maml:name> <maml:description> <maml:para>Specify the Authenticode provider used to extract the signature. This is required if the `-Content` or `-RawContent` parameter is specified. If `-Path`, or `-LiteralPath` is specified, the provider is found based on the extension of the file being read. If the file has no extension then an explicit provider must be specified.</maml:para> <maml:para>Valid providers are:</maml:para> <maml:para>* `NotSpecified` - Uses the file extension to find the provider</maml:para> <maml:para>* `PowerShell` - Uses the PowerShell script Authenticode provider</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">AuthenticodeProvider</command:parameterValue> <dev:type> <maml:name>AuthenticodeProvider</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SkipCertificateCheck</maml:name> <maml:description> <maml:para>Skips the CA trust validation of the certificate that signed the file. The signature will still be validated to ensure the file has been tampered with but if this switch is present, the certificate CA trust will not be checked.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>TrustStore</maml:name> <maml:description> <maml:para>A collection of certificate to use as a custom trusted store location instead of the system provided certificates. Any self signed certificates in this collection will be treated as a trusted root CA during the certificate validation, other certificates will be treated as intermediaries used to help build the trust chain. This should only be used for testing purposes and the system store should be used in most production scenarios.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">X509Certificate2Collection</command:parameterValue> <dev:type> <maml:name>X509Certificate2Collection</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Get-OpenAuthenticodeSignature</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Encoding</maml:name> <maml:description> <maml:para>A hint to provide to the Authenticode provider that indicates what the file string encoding method is. This is only used by Authenticode providers that need to read the file as a string, like PowerShell. The default used is dependent on the Authenticode provider but most commonly will be `UTF-8`.</maml:para> <maml:para>This accepts a `System.Text.Encoding` type but also a string or int representing the encoding from `[System.Text.Encoding]::GetEncoding(...)`. Some common encoding values are:</maml:para> <maml:para>* `Utf8` - UTF-8 but without a Byte Order Mark (BOM)</maml:para> <maml:para>* `ASCII` - ASCII (bytes 0-127)</maml:para> <maml:para>* `ANSI` - The ANSI encoding commonly used in legacy Windows encoding</maml:para> <maml:para>* `OEM` - The value of `[System.Text.Encoding]::Default` which is UTF-8 without a BOM</maml:para> <maml:para>* `Unicode` - UTF-16-LE</maml:para> <maml:para>* `Utf8Bom` - UTF-8 but with a BOM</maml:para> <maml:para>* `Utf8NoBom` - Same as `Utf8`</maml:para> <maml:para></maml:para> <maml:para>The `ANSI` encoding typically refers to the legacy Windows encoding used in older PowerShell versions. If creating a script that should be used across the various PowerShell versions, it is highly recommended to use an encoding with a `BOM` like `Utf8Bom` or `Unicode`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Encoding</command:parameterValue> <dev:type> <maml:name>Encoding</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="PSPath"> <maml:name>LiteralPath</maml:name> <maml:description> <maml:para>Specifies the path to the files to extract the Authenticode signature from. Unlike `-Path`, the path is used exactly as it is typed, no wildcard matching will occur.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Provider</maml:name> <maml:description> <maml:para>Specify the Authenticode provider used to extract the signature. This is required if the `-Content` or `-RawContent` parameter is specified. If `-Path`, or `-LiteralPath` is specified, the provider is found based on the extension of the file being read. If the file has no extension then an explicit provider must be specified.</maml:para> <maml:para>Valid providers are:</maml:para> <maml:para>* `NotSpecified` - Uses the file extension to find the provider</maml:para> <maml:para>* `PowerShell` - Uses the PowerShell script Authenticode provider</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">AuthenticodeProvider</command:parameterValue> <dev:type> <maml:name>AuthenticodeProvider</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SkipCertificateCheck</maml:name> <maml:description> <maml:para>Skips the CA trust validation of the certificate that signed the file. The signature will still be validated to ensure the file has been tampered with but if this switch is present, the certificate CA trust will not be checked.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>TrustStore</maml:name> <maml:description> <maml:para>A collection of certificate to use as a custom trusted store location instead of the system provided certificates. Any self signed certificates in this collection will be treated as a trusted root CA during the certificate validation, other certificates will be treated as intermediaries used to help build the trust chain. This should only be used for testing purposes and the system store should be used in most production scenarios.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">X509Certificate2Collection</command:parameterValue> <dev:type> <maml:name>X509Certificate2Collection</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Get-OpenAuthenticodeSignature</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Encoding</maml:name> <maml:description> <maml:para>A hint to provide to the Authenticode provider that indicates what the file string encoding method is. This is only used by Authenticode providers that need to read the file as a string, like PowerShell. The default used is dependent on the Authenticode provider but most commonly will be `UTF-8`.</maml:para> <maml:para>This accepts a `System.Text.Encoding` type but also a string or int representing the encoding from `[System.Text.Encoding]::GetEncoding(...)`. Some common encoding values are:</maml:para> <maml:para>* `Utf8` - UTF-8 but without a Byte Order Mark (BOM)</maml:para> <maml:para>* `ASCII` - ASCII (bytes 0-127)</maml:para> <maml:para>* `ANSI` - The ANSI encoding commonly used in legacy Windows encoding</maml:para> <maml:para>* `OEM` - The value of `[System.Text.Encoding]::Default` which is UTF-8 without a BOM</maml:para> <maml:para>* `Unicode` - UTF-16-LE</maml:para> <maml:para>* `Utf8Bom` - UTF-8 but with a BOM</maml:para> <maml:para>* `Utf8NoBom` - Same as `Utf8`</maml:para> <maml:para></maml:para> <maml:para>The `ANSI` encoding typically refers to the legacy Windows encoding used in older PowerShell versions. If creating a script that should be used across the various PowerShell versions, it is highly recommended to use an encoding with a `BOM` like `Utf8Bom` or `Unicode`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Encoding</command:parameterValue> <dev:type> <maml:name>Encoding</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Provider</maml:name> <maml:description> <maml:para>Specify the Authenticode provider used to extract the signature. This is required if the `-Content` or `-RawContent` parameter is specified. If `-Path`, or `-LiteralPath` is specified, the provider is found based on the extension of the file being read. If the file has no extension then an explicit provider must be specified.</maml:para> <maml:para>Valid providers are:</maml:para> <maml:para>* `NotSpecified` - Uses the file extension to find the provider</maml:para> <maml:para>* `PowerShell` - Uses the PowerShell script Authenticode provider</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">AuthenticodeProvider</command:parameterValue> <dev:type> <maml:name>AuthenticodeProvider</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none"> <maml:name>RawContent</maml:name> <maml:description> <maml:para>Gets the Authenticode signature from the file bytes directly. This is useful if the file is stored in memory and not on the filesystem. The `-Provider` parameter must be provided when using `-RawContent`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Byte[]</command:parameterValue> <dev:type> <maml:name>Byte[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SkipCertificateCheck</maml:name> <maml:description> <maml:para>Skips the CA trust validation of the certificate that signed the file. The signature will still be validated to ensure the file has been tampered with but if this switch is present, the certificate CA trust will not be checked.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>TrustStore</maml:name> <maml:description> <maml:para>A collection of certificate to use as a custom trusted store location instead of the system provided certificates. Any self signed certificates in this collection will be treated as a trusted root CA during the certificate validation, other certificates will be treated as intermediaries used to help build the trust chain. This should only be used for testing purposes and the system store should be used in most production scenarios.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">X509Certificate2Collection</command:parameterValue> <dev:type> <maml:name>X509Certificate2Collection</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none"> <maml:name>Content</maml:name> <maml:description> <maml:para>Gets the Authenticode signature from the file strings contents. This is useful if the file is stored in memory and not on the filesystem. The `-Provider` parameter must be provided when using `-Content`.</maml:para> <maml:para>If the string value is from a file with a BOM it is important to ensure the string has the BOM chars present. An example of how to prefix a string with an encoding BOM is as follows.</maml:para> <maml:para></maml:para> <maml:para></maml:para> <maml:para>$encoding = [System.Text.Encoding]::Unicode $bom = $encoding.GetString($encoding.GetPreamble()) $content = $bom + (Get-Content $path -Raw) Note: it is far safer to just use `-Path` in the case above. This example is just to display how a BOM can be prefixed if it was required.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Encoding</maml:name> <maml:description> <maml:para>A hint to provide to the Authenticode provider that indicates what the file string encoding method is. This is only used by Authenticode providers that need to read the file as a string, like PowerShell. The default used is dependent on the Authenticode provider but most commonly will be `UTF-8`.</maml:para> <maml:para>This accepts a `System.Text.Encoding` type but also a string or int representing the encoding from `[System.Text.Encoding]::GetEncoding(...)`. Some common encoding values are:</maml:para> <maml:para>* `Utf8` - UTF-8 but without a Byte Order Mark (BOM)</maml:para> <maml:para>* `ASCII` - ASCII (bytes 0-127)</maml:para> <maml:para>* `ANSI` - The ANSI encoding commonly used in legacy Windows encoding</maml:para> <maml:para>* `OEM` - The value of `[System.Text.Encoding]::Default` which is UTF-8 without a BOM</maml:para> <maml:para>* `Unicode` - UTF-16-LE</maml:para> <maml:para>* `Utf8Bom` - UTF-8 but with a BOM</maml:para> <maml:para>* `Utf8NoBom` - Same as `Utf8`</maml:para> <maml:para></maml:para> <maml:para>The `ANSI` encoding typically refers to the legacy Windows encoding used in older PowerShell versions. If creating a script that should be used across the various PowerShell versions, it is highly recommended to use an encoding with a `BOM` like `Utf8Bom` or `Unicode`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Encoding</command:parameterValue> <dev:type> <maml:name>Encoding</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="PSPath"> <maml:name>LiteralPath</maml:name> <maml:description> <maml:para>Specifies the path to the files to extract the Authenticode signature from. Unlike `-Path`, the path is used exactly as it is typed, no wildcard matching will occur.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="true" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="FilePath"> <maml:name>Path</maml:name> <maml:description> <maml:para>The path to the files to retrieve the Authenticode information for. Wildcards are permitted and a signature will be outputted for every file that matches the wildcard. This is only supported for paths in the FileSystem provider.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Provider</maml:name> <maml:description> <maml:para>Specify the Authenticode provider used to extract the signature. This is required if the `-Content` or `-RawContent` parameter is specified. If `-Path`, or `-LiteralPath` is specified, the provider is found based on the extension of the file being read. If the file has no extension then an explicit provider must be specified.</maml:para> <maml:para>Valid providers are:</maml:para> <maml:para>* `NotSpecified` - Uses the file extension to find the provider</maml:para> <maml:para>* `PowerShell` - Uses the PowerShell script Authenticode provider</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">AuthenticodeProvider</command:parameterValue> <dev:type> <maml:name>AuthenticodeProvider</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none"> <maml:name>RawContent</maml:name> <maml:description> <maml:para>Gets the Authenticode signature from the file bytes directly. This is useful if the file is stored in memory and not on the filesystem. The `-Provider` parameter must be provided when using `-RawContent`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Byte[]</command:parameterValue> <dev:type> <maml:name>Byte[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>SkipCertificateCheck</maml:name> <maml:description> <maml:para>Skips the CA trust validation of the certificate that signed the file. The signature will still be validated to ensure the file has been tampered with but if this switch is present, the certificate CA trust will not be checked.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>TrustStore</maml:name> <maml:description> <maml:para>A collection of certificate to use as a custom trusted store location instead of the system provided certificates. Any self signed certificates in this collection will be treated as a trusted root CA during the certificate validation, other certificates will be treated as intermediaries used to help build the trust chain. This should only be used for testing purposes and the system store should be used in most production scenarios.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">X509Certificate2Collection</command:parameterValue> <dev:type> <maml:name>X509Certificate2Collection</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.String[]</maml:name> </dev:type> <maml:description> <maml:para>Accepts a list of paths for the `-Path` parameter.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Security.Cryptography.Pkcs.SignedCms / OpenAuthenticode.AuthenticodeSignature</maml:name> </dev:type> <maml:description> <maml:para>The Authenticode signature details from the path specified if it was signed. This object has the following extra properties added as part of the extended type data of `OpenAuthenticode.AuthenticodeSignature`:</maml:para> <maml:para>+ `Path`: The file path that this signature is for</maml:para> <maml:para>+ `Certificate`: The X.509 certificate that signed the file</maml:para> <maml:para>+ `HashAlgorithm`: The hash algorithm that was used in the Authenticode signature</maml:para> <maml:para>+ `TimeStampInfo`: Information about the counter signature timestamp including its certificate, timestamp date in UTC, and timestamp hashing algorithm</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para>Unlike Get-AuthenticodeSignature (https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.security/get-authenticodesignature?view=powershell-7.3)this cmdlet will write an error if there is a Authenticode signature validation problem. The error should contain the details on what went wrong.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>----- Example 1: Get the Authenticode signature for a file -----</maml:title> <dev:code>PS C:\> Get-OpenAuthenticodeSignature -Path test.ps1</dev:code> <dev:remarks> <maml:para>Gets the Authenticode signature information from the PowerShell script `test.ps1`.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>- Example 2: Get the Authenticode signature for multiple files -</maml:title> <dev:code>PS C:\> Get-OpenAuthenticodeSignature -Path file1.ps1, signed.ps1</dev:code> <dev:remarks> <maml:para>Gets the Authenticode signature information for multiple PowerShell script files.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>Example 3: Get the Authenticode signature for a file without an extension</maml:title> <dev:code>PS C:\> Get-OpenAuthenticodeSignature -Path hook -Provider PowerShell</dev:code> <dev:remarks> <maml:para>Gets the Authenticode signature for a PowerShell script without a file extension.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>Example 4: Get the Authenticode signature for a script in memory</maml:title> <dev:code>PS C:\> $myScript = Get-Content -Path script.ps1 -Raw PS C:\> Get-OpenAuthenticodeSignature -Content $myScript -Provider PowerShell</dev:code> <dev:remarks> <maml:para>Gets the Authenticode signature for a PowerShell script as a string.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title> Example 5: Get the Authenticode signature from a file's bytes </maml:title> <dev:code>PS C:\> $bytes = Get-Content -Path script.ps1 -AsByteStream -Raw PS C:\> Get-OpenAuthenticodeSignature -RawContent $bytes -Provider PowerShell -Encoding ANSI</dev:code> <dev:remarks> <maml:para>Gets the Authenticode signature from the files raw bytes. The `-Encoding` parameter is not necessarily for most Authenticode providers but for PowerShell it is a helpful hint to tell it how to read those bytes as a string. By default PowerShell will use the encoding of the BOM if present, otherwise uses `UTF8`. In this example the encoding is set to `ANSI` which is typically `windows-1252`. The `ANSI` encoding refers to the legacy encoding that Windows PowerShell (before 5.1) used to read scripts.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://www.github.com/jborean93/PowerShell-OpenAuthenticode/blob/main/docs/en-US/Get-OpenAuthenticodeSignature.md</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Authenticode Digital Signatures</maml:linkText> <maml:uri>https://learn.microsoft.com/en-us/windows-hardware/drivers/install/authenticode</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Set-OpenAuthenticodeSignature</command:name> <command:verb>Set</command:verb> <command:noun>OpenAuthenticodeSignature</command:noun> <maml:description> <maml:para>Set an authenticode signature on a file.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>This cmdlet can sign the file provided with an Authenticode signature. This signature can be validated using Get-OpenAuthenticodeSignature (./Get-OpenAuthenticodeSignature.md)or any of the Authenticode APIs, including the ones of a Windows host.</maml:para> <maml:para>It is possible to sign a file using a certificate object with an associated key. The simplest way to get a certificate is to use the Get-PfxCertificate cmdlet (https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.security/get-pfxcertificate?view=powershell-7.3)which works on both Windows and non-Windows hosts. It is also possible to get a code signing certificate through the `Cert:` provider alongside the `-CodeSigningCert` parameter on Windows. The certificate must have the Key Usage of `Digital Signature (80)` and Enhanced Key Usage `Code Signing (1.3.6.1.5.5.7.3.3)` for it to be used with Authenticode. While it should be signed by a trusted CA authority for it to be validated normally, it is not a requirement to sign the file.</maml:para> <maml:para>See about_AuthenticodeProviders (./about_AuthenticodeProviders.md)for more information about what providers are currently supported. When using a file path that has no extension, an explicit `-Provider` must be specified to indicate what Authenticode provider needs to be used to sign and embed the signature in the file specified.</maml:para> <maml:para>Setting a signature will edit the file provided, use `-WhatIf` to test whether a signature can be set without actually changing the file.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Set-OpenAuthenticodeSignature</maml:name> <command:parameter required="true" variableLength="true" globbing="true" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="FilePath"> <maml:name>Path</maml:name> <maml:description> <maml:para>The path to the files to sign with an Authenticode signature. Wildcards are permitted and a signature will be outputted for every file that matches the wildcard. This is only supported for paths in the FileSystem provider.</maml:para> <maml:para>If the path does not have a file extension, the `-Provider` parameter must be set to tell the cmdlet how it should be signed.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Certificate</maml:name> <maml:description> <maml:para>The certificate used to sign the files specified. Use the `Get-PfxCertificate` or `Get-ChildItem Cert:\... -CodeSigningCert` (Windows only) to get a certificate to use for signing. The certificate must have access to its associated private key for it to be able to sign the file. It should also have the Key Usage of `Digital Signature (80)` and Enhanced Key Usage `Code Signing (1.3.6.1.5.5.7.3.3)`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">X509Certificate2</command:parameterValue> <dev:type> <maml:name>X509Certificate2</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Encoding</maml:name> <maml:description> <maml:para>A hint to provide to the Authenticode provider that indicates what the file string encoding method is. This is only used by Authenticode providers that need to read the file as a string, like PowerShell. The default used is dependent on the Authenticode provider but most commonly will be `UTF-8`.</maml:para> <maml:para>This accepts a `System.Text.Encoding` type but also a string or int representing the encoding from `[System.Text.Encoding]::GetEncoding(...)`. Some common encoding values are:</maml:para> <maml:para>* `Utf8` - UTF-8 but without a Byte Order Mark (BOM)</maml:para> <maml:para>* `ASCII` - ASCII (bytes 0-127)</maml:para> <maml:para>* `ANSI` - The ANSI encoding commonly used in legacy Windows encoding</maml:para> <maml:para>* `OEM` - The value of `[System.Text.Encoding]::Default` which is UTF-8 without a BOM</maml:para> <maml:para>* `Unicode` - UTF-16-LE</maml:para> <maml:para>* `Utf8Bom` - UTF-8 but with a BOM</maml:para> <maml:para>* `Utf8NoBom` - Same as `Utf8`</maml:para> <maml:para></maml:para> <maml:para>The `ANSI` encoding typically refers to the legacy Windows encoding used in older PowerShell versions. If creating a script that should be used across the various PowerShell versions, it is highly recommended to use an encoding with a `BOM` like `Utf8Bom` or `Unicode`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Encoding</command:parameterValue> <dev:type> <maml:name>Encoding</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>HashAlgorithm</maml:name> <maml:description> <maml:para>The hashing algorithm to use when generating the Authenticode signature. This defaults to SHA256 if not specified.</maml:para> <maml:para>Known algorithms are:</maml:para> <maml:para>* `SHA1`</maml:para> <maml:para>* `SHA256`</maml:para> <maml:para>* `SHA384`</maml:para> <maml:para>* `SHA512`</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">HashAlgorithmName</command:parameterValue> <dev:type> <maml:name>HashAlgorithmName</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>IncludeOption</maml:name> <maml:description> <maml:para>Determines which certificates in the certificate trust chain are included in the digital signature. Existing options are:</maml:para> <maml:para>* `None` - No chain information is included</maml:para> <maml:para>* `ExcludeRoot` - The entire chain is included except for the root certificate</maml:para> <maml:para>* `EndCertOnly` - Only the end certificate is included</maml:para> <maml:para>* `WholeChain` - The whole chain is included</maml:para> <maml:para></maml:para> <maml:para>The default is `ExcludeRoot` which will include all the certs and their intermediaries in the Authenticode signature, except the root CA certificate.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">None</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ExcludeRoot</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">EndCertOnly</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">WholeChain</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">X509IncludeOption</command:parameterValue> <dev:type> <maml:name>X509IncludeOption</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Output the signature information that was placed in the file. If not set, the cmdlet will not output anything.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Provider</maml:name> <maml:description> <maml:para>Specify the Authenticode provider used to sign the file. If the file has no extension then an explicit provider must be specified.</maml:para> <maml:para>Valid providers are:</maml:para> <maml:para>* `NotSpecified` - Uses the file extension to find the provider</maml:para> <maml:para>* `PowerShell` - Uses the PowerShell script Authenticode provider</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">AuthenticodeProvider</command:parameterValue> <dev:type> <maml:name>AuthenticodeProvider</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>TimeStampHashAlgorithm</maml:name> <maml:description> <maml:para>The hashing algorithm used in the counter signature timestamp if `-TimestampServer` was specified. This defaults to the value of `-HashAlgorithm` if not specified.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">HashAlgorithmName</command:parameterValue> <dev:type> <maml:name>HashAlgorithmName</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>TimestampServer</maml:name> <maml:description> <maml:para>The timestamp server used to counter sign the Authenticode signature. The time stamp represents the exact time the certificate was added to the file. A time stamp prevents the signature from being invalidated once the certificate has expired.</maml:para> <maml:para>The value specified here is the URL to an RFC 3161 compliant time stamping server. It is possible to specify the hashing algorithm the timestamp server uses with the `-TimeStampHashAlgorithm`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Set-OpenAuthenticodeSignature</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Certificate</maml:name> <maml:description> <maml:para>The certificate used to sign the files specified. Use the `Get-PfxCertificate` or `Get-ChildItem Cert:\... -CodeSigningCert` (Windows only) to get a certificate to use for signing. The certificate must have access to its associated private key for it to be able to sign the file. It should also have the Key Usage of `Digital Signature (80)` and Enhanced Key Usage `Code Signing (1.3.6.1.5.5.7.3.3)`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">X509Certificate2</command:parameterValue> <dev:type> <maml:name>X509Certificate2</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Encoding</maml:name> <maml:description> <maml:para>A hint to provide to the Authenticode provider that indicates what the file string encoding method is. This is only used by Authenticode providers that need to read the file as a string, like PowerShell. The default used is dependent on the Authenticode provider but most commonly will be `UTF-8`.</maml:para> <maml:para>This accepts a `System.Text.Encoding` type but also a string or int representing the encoding from `[System.Text.Encoding]::GetEncoding(...)`. Some common encoding values are:</maml:para> <maml:para>* `Utf8` - UTF-8 but without a Byte Order Mark (BOM)</maml:para> <maml:para>* `ASCII` - ASCII (bytes 0-127)</maml:para> <maml:para>* `ANSI` - The ANSI encoding commonly used in legacy Windows encoding</maml:para> <maml:para>* `OEM` - The value of `[System.Text.Encoding]::Default` which is UTF-8 without a BOM</maml:para> <maml:para>* `Unicode` - UTF-16-LE</maml:para> <maml:para>* `Utf8Bom` - UTF-8 but with a BOM</maml:para> <maml:para>* `Utf8NoBom` - Same as `Utf8`</maml:para> <maml:para></maml:para> <maml:para>The `ANSI` encoding typically refers to the legacy Windows encoding used in older PowerShell versions. If creating a script that should be used across the various PowerShell versions, it is highly recommended to use an encoding with a `BOM` like `Utf8Bom` or `Unicode`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Encoding</command:parameterValue> <dev:type> <maml:name>Encoding</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>HashAlgorithm</maml:name> <maml:description> <maml:para>The hashing algorithm to use when generating the Authenticode signature. This defaults to SHA256 if not specified.</maml:para> <maml:para>Known algorithms are:</maml:para> <maml:para>* `SHA1`</maml:para> <maml:para>* `SHA256`</maml:para> <maml:para>* `SHA384`</maml:para> <maml:para>* `SHA512`</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">HashAlgorithmName</command:parameterValue> <dev:type> <maml:name>HashAlgorithmName</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>IncludeOption</maml:name> <maml:description> <maml:para>Determines which certificates in the certificate trust chain are included in the digital signature. Existing options are:</maml:para> <maml:para>* `None` - No chain information is included</maml:para> <maml:para>* `ExcludeRoot` - The entire chain is included except for the root certificate</maml:para> <maml:para>* `EndCertOnly` - Only the end certificate is included</maml:para> <maml:para>* `WholeChain` - The whole chain is included</maml:para> <maml:para></maml:para> <maml:para>The default is `ExcludeRoot` which will include all the certs and their intermediaries in the Authenticode signature, except the root CA certificate.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">None</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ExcludeRoot</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">EndCertOnly</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">WholeChain</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">X509IncludeOption</command:parameterValue> <dev:type> <maml:name>X509IncludeOption</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="PSPath"> <maml:name>LiteralPath</maml:name> <maml:description> <maml:para>Specifies the path to the files to sign with an Authenticode signature. Unlike `-Path`, the path is used exactly as it is typed, no wildcard matching will occur.</maml:para> <maml:para>If the path does not have a file extension, the `-Provider` parameter must be set to tell the cmdlet how it should be signed.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Output the signature information that was placed in the file. If not set, the cmdlet will not output anything.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Provider</maml:name> <maml:description> <maml:para>Specify the Authenticode provider used to sign the file. If the file has no extension then an explicit provider must be specified.</maml:para> <maml:para>Valid providers are:</maml:para> <maml:para>* `NotSpecified` - Uses the file extension to find the provider</maml:para> <maml:para>* `PowerShell` - Uses the PowerShell script Authenticode provider</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">AuthenticodeProvider</command:parameterValue> <dev:type> <maml:name>AuthenticodeProvider</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>TimeStampHashAlgorithm</maml:name> <maml:description> <maml:para>The hashing algorithm used in the counter signature timestamp if `-TimestampServer` was specified. This defaults to the value of `-HashAlgorithm` if not specified.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">HashAlgorithmName</command:parameterValue> <dev:type> <maml:name>HashAlgorithmName</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>TimestampServer</maml:name> <maml:description> <maml:para>The timestamp server used to counter sign the Authenticode signature. The time stamp represents the exact time the certificate was added to the file. A time stamp prevents the signature from being invalidated once the certificate has expired.</maml:para> <maml:para>The value specified here is the URL to an RFC 3161 compliant time stamping server. It is possible to specify the hashing algorithm the timestamp server uses with the `-TimeStampHashAlgorithm`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Set-OpenAuthenticodeSignature</maml:name> <command:parameter required="true" variableLength="true" globbing="true" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="FilePath"> <maml:name>Path</maml:name> <maml:description> <maml:para>The path to the files to sign with an Authenticode signature. Wildcards are permitted and a signature will be outputted for every file that matches the wildcard. This is only supported for paths in the FileSystem provider.</maml:para> <maml:para>If the path does not have a file extension, the `-Provider` parameter must be set to tell the cmdlet how it should be signed.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Encoding</maml:name> <maml:description> <maml:para>A hint to provide to the Authenticode provider that indicates what the file string encoding method is. This is only used by Authenticode providers that need to read the file as a string, like PowerShell. The default used is dependent on the Authenticode provider but most commonly will be `UTF-8`.</maml:para> <maml:para>This accepts a `System.Text.Encoding` type but also a string or int representing the encoding from `[System.Text.Encoding]::GetEncoding(...)`. Some common encoding values are:</maml:para> <maml:para>* `Utf8` - UTF-8 but without a Byte Order Mark (BOM)</maml:para> <maml:para>* `ASCII` - ASCII (bytes 0-127)</maml:para> <maml:para>* `ANSI` - The ANSI encoding commonly used in legacy Windows encoding</maml:para> <maml:para>* `OEM` - The value of `[System.Text.Encoding]::Default` which is UTF-8 without a BOM</maml:para> <maml:para>* `Unicode` - UTF-16-LE</maml:para> <maml:para>* `Utf8Bom` - UTF-8 but with a BOM</maml:para> <maml:para>* `Utf8NoBom` - Same as `Utf8`</maml:para> <maml:para></maml:para> <maml:para>The `ANSI` encoding typically refers to the legacy Windows encoding used in older PowerShell versions. If creating a script that should be used across the various PowerShell versions, it is highly recommended to use an encoding with a `BOM` like `Utf8Bom` or `Unicode`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Encoding</command:parameterValue> <dev:type> <maml:name>Encoding</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>HashAlgorithm</maml:name> <maml:description> <maml:para>The hashing algorithm to use when generating the Authenticode signature. This defaults to SHA256 if not specified.</maml:para> <maml:para>Known algorithms are:</maml:para> <maml:para>* `SHA1`</maml:para> <maml:para>* `SHA256`</maml:para> <maml:para>* `SHA384`</maml:para> <maml:para>* `SHA512`</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">HashAlgorithmName</command:parameterValue> <dev:type> <maml:name>HashAlgorithmName</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>IncludeOption</maml:name> <maml:description> <maml:para>Determines which certificates in the certificate trust chain are included in the digital signature. Existing options are:</maml:para> <maml:para>* `None` - No chain information is included</maml:para> <maml:para>* `ExcludeRoot` - The entire chain is included except for the root certificate</maml:para> <maml:para>* `EndCertOnly` - Only the end certificate is included</maml:para> <maml:para>* `WholeChain` - The whole chain is included</maml:para> <maml:para></maml:para> <maml:para>The default is `ExcludeRoot` which will include all the certs and their intermediaries in the Authenticode signature, except the root CA certificate.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">None</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ExcludeRoot</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">EndCertOnly</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">WholeChain</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">X509IncludeOption</command:parameterValue> <dev:type> <maml:name>X509IncludeOption</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Key</maml:name> <maml:description> <maml:para>A custom key object that can be used to signed the file. Currently this is only supported by Azure KeyVault keys and this value can be retrieved from Get-OpenAuthenticodeAzKey (./Get-OpenAuthenticodeAzKey.md).</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">KeyProvider</command:parameterValue> <dev:type> <maml:name>KeyProvider</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Output the signature information that was placed in the file. If not set, the cmdlet will not output anything.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Provider</maml:name> <maml:description> <maml:para>Specify the Authenticode provider used to sign the file. If the file has no extension then an explicit provider must be specified.</maml:para> <maml:para>Valid providers are:</maml:para> <maml:para>* `NotSpecified` - Uses the file extension to find the provider</maml:para> <maml:para>* `PowerShell` - Uses the PowerShell script Authenticode provider</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">AuthenticodeProvider</command:parameterValue> <dev:type> <maml:name>AuthenticodeProvider</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>TimeStampHashAlgorithm</maml:name> <maml:description> <maml:para>The hashing algorithm used in the counter signature timestamp if `-TimestampServer` was specified. This defaults to the value of `-HashAlgorithm` if not specified.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">HashAlgorithmName</command:parameterValue> <dev:type> <maml:name>HashAlgorithmName</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>TimestampServer</maml:name> <maml:description> <maml:para>The timestamp server used to counter sign the Authenticode signature. The time stamp represents the exact time the certificate was added to the file. A time stamp prevents the signature from being invalidated once the certificate has expired.</maml:para> <maml:para>The value specified here is the URL to an RFC 3161 compliant time stamping server. It is possible to specify the hashing algorithm the timestamp server uses with the `-TimeStampHashAlgorithm`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Set-OpenAuthenticodeSignature</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Encoding</maml:name> <maml:description> <maml:para>A hint to provide to the Authenticode provider that indicates what the file string encoding method is. This is only used by Authenticode providers that need to read the file as a string, like PowerShell. The default used is dependent on the Authenticode provider but most commonly will be `UTF-8`.</maml:para> <maml:para>This accepts a `System.Text.Encoding` type but also a string or int representing the encoding from `[System.Text.Encoding]::GetEncoding(...)`. Some common encoding values are:</maml:para> <maml:para>* `Utf8` - UTF-8 but without a Byte Order Mark (BOM)</maml:para> <maml:para>* `ASCII` - ASCII (bytes 0-127)</maml:para> <maml:para>* `ANSI` - The ANSI encoding commonly used in legacy Windows encoding</maml:para> <maml:para>* `OEM` - The value of `[System.Text.Encoding]::Default` which is UTF-8 without a BOM</maml:para> <maml:para>* `Unicode` - UTF-16-LE</maml:para> <maml:para>* `Utf8Bom` - UTF-8 but with a BOM</maml:para> <maml:para>* `Utf8NoBom` - Same as `Utf8`</maml:para> <maml:para></maml:para> <maml:para>The `ANSI` encoding typically refers to the legacy Windows encoding used in older PowerShell versions. If creating a script that should be used across the various PowerShell versions, it is highly recommended to use an encoding with a `BOM` like `Utf8Bom` or `Unicode`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Encoding</command:parameterValue> <dev:type> <maml:name>Encoding</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>HashAlgorithm</maml:name> <maml:description> <maml:para>The hashing algorithm to use when generating the Authenticode signature. This defaults to SHA256 if not specified.</maml:para> <maml:para>Known algorithms are:</maml:para> <maml:para>* `SHA1`</maml:para> <maml:para>* `SHA256`</maml:para> <maml:para>* `SHA384`</maml:para> <maml:para>* `SHA512`</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">HashAlgorithmName</command:parameterValue> <dev:type> <maml:name>HashAlgorithmName</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>IncludeOption</maml:name> <maml:description> <maml:para>Determines which certificates in the certificate trust chain are included in the digital signature. Existing options are:</maml:para> <maml:para>* `None` - No chain information is included</maml:para> <maml:para>* `ExcludeRoot` - The entire chain is included except for the root certificate</maml:para> <maml:para>* `EndCertOnly` - Only the end certificate is included</maml:para> <maml:para>* `WholeChain` - The whole chain is included</maml:para> <maml:para></maml:para> <maml:para>The default is `ExcludeRoot` which will include all the certs and their intermediaries in the Authenticode signature, except the root CA certificate.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">None</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ExcludeRoot</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">EndCertOnly</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">WholeChain</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">X509IncludeOption</command:parameterValue> <dev:type> <maml:name>X509IncludeOption</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Key</maml:name> <maml:description> <maml:para>A custom key object that can be used to signed the file. Currently this is only supported by Azure KeyVault keys and this value can be retrieved from Get-OpenAuthenticodeAzKey (./Get-OpenAuthenticodeAzKey.md).</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">KeyProvider</command:parameterValue> <dev:type> <maml:name>KeyProvider</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="PSPath"> <maml:name>LiteralPath</maml:name> <maml:description> <maml:para>Specifies the path to the files to sign with an Authenticode signature. Unlike `-Path`, the path is used exactly as it is typed, no wildcard matching will occur.</maml:para> <maml:para>If the path does not have a file extension, the `-Provider` parameter must be set to tell the cmdlet how it should be signed.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Output the signature information that was placed in the file. If not set, the cmdlet will not output anything.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Provider</maml:name> <maml:description> <maml:para>Specify the Authenticode provider used to sign the file. If the file has no extension then an explicit provider must be specified.</maml:para> <maml:para>Valid providers are:</maml:para> <maml:para>* `NotSpecified` - Uses the file extension to find the provider</maml:para> <maml:para>* `PowerShell` - Uses the PowerShell script Authenticode provider</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">AuthenticodeProvider</command:parameterValue> <dev:type> <maml:name>AuthenticodeProvider</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>TimeStampHashAlgorithm</maml:name> <maml:description> <maml:para>The hashing algorithm used in the counter signature timestamp if `-TimestampServer` was specified. This defaults to the value of `-HashAlgorithm` if not specified.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">HashAlgorithmName</command:parameterValue> <dev:type> <maml:name>HashAlgorithmName</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>TimestampServer</maml:name> <maml:description> <maml:para>The timestamp server used to counter sign the Authenticode signature. The time stamp represents the exact time the certificate was added to the file. A time stamp prevents the signature from being invalidated once the certificate has expired.</maml:para> <maml:para>The value specified here is the URL to an RFC 3161 compliant time stamping server. It is possible to specify the hashing algorithm the timestamp server uses with the `-TimeStampHashAlgorithm`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Certificate</maml:name> <maml:description> <maml:para>The certificate used to sign the files specified. Use the `Get-PfxCertificate` or `Get-ChildItem Cert:\... -CodeSigningCert` (Windows only) to get a certificate to use for signing. The certificate must have access to its associated private key for it to be able to sign the file. It should also have the Key Usage of `Digital Signature (80)` and Enhanced Key Usage `Code Signing (1.3.6.1.5.5.7.3.3)`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">X509Certificate2</command:parameterValue> <dev:type> <maml:name>X509Certificate2</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Encoding</maml:name> <maml:description> <maml:para>A hint to provide to the Authenticode provider that indicates what the file string encoding method is. This is only used by Authenticode providers that need to read the file as a string, like PowerShell. The default used is dependent on the Authenticode provider but most commonly will be `UTF-8`.</maml:para> <maml:para>This accepts a `System.Text.Encoding` type but also a string or int representing the encoding from `[System.Text.Encoding]::GetEncoding(...)`. Some common encoding values are:</maml:para> <maml:para>* `Utf8` - UTF-8 but without a Byte Order Mark (BOM)</maml:para> <maml:para>* `ASCII` - ASCII (bytes 0-127)</maml:para> <maml:para>* `ANSI` - The ANSI encoding commonly used in legacy Windows encoding</maml:para> <maml:para>* `OEM` - The value of `[System.Text.Encoding]::Default` which is UTF-8 without a BOM</maml:para> <maml:para>* `Unicode` - UTF-16-LE</maml:para> <maml:para>* `Utf8Bom` - UTF-8 but with a BOM</maml:para> <maml:para>* `Utf8NoBom` - Same as `Utf8`</maml:para> <maml:para></maml:para> <maml:para>The `ANSI` encoding typically refers to the legacy Windows encoding used in older PowerShell versions. If creating a script that should be used across the various PowerShell versions, it is highly recommended to use an encoding with a `BOM` like `Utf8Bom` or `Unicode`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Encoding</command:parameterValue> <dev:type> <maml:name>Encoding</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>HashAlgorithm</maml:name> <maml:description> <maml:para>The hashing algorithm to use when generating the Authenticode signature. This defaults to SHA256 if not specified.</maml:para> <maml:para>Known algorithms are:</maml:para> <maml:para>* `SHA1`</maml:para> <maml:para>* `SHA256`</maml:para> <maml:para>* `SHA384`</maml:para> <maml:para>* `SHA512`</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">HashAlgorithmName</command:parameterValue> <dev:type> <maml:name>HashAlgorithmName</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>IncludeOption</maml:name> <maml:description> <maml:para>Determines which certificates in the certificate trust chain are included in the digital signature. Existing options are:</maml:para> <maml:para>* `None` - No chain information is included</maml:para> <maml:para>* `ExcludeRoot` - The entire chain is included except for the root certificate</maml:para> <maml:para>* `EndCertOnly` - Only the end certificate is included</maml:para> <maml:para>* `WholeChain` - The whole chain is included</maml:para> <maml:para></maml:para> <maml:para>The default is `ExcludeRoot` which will include all the certs and their intermediaries in the Authenticode signature, except the root CA certificate.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">X509IncludeOption</command:parameterValue> <dev:type> <maml:name>X509IncludeOption</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Key</maml:name> <maml:description> <maml:para>A custom key object that can be used to signed the file. Currently this is only supported by Azure KeyVault keys and this value can be retrieved from Get-OpenAuthenticodeAzKey (./Get-OpenAuthenticodeAzKey.md).</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">KeyProvider</command:parameterValue> <dev:type> <maml:name>KeyProvider</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="PSPath"> <maml:name>LiteralPath</maml:name> <maml:description> <maml:para>Specifies the path to the files to sign with an Authenticode signature. Unlike `-Path`, the path is used exactly as it is typed, no wildcard matching will occur.</maml:para> <maml:para>If the path does not have a file extension, the `-Provider` parameter must be set to tell the cmdlet how it should be signed.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Output the signature information that was placed in the file. If not set, the cmdlet will not output anything.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="true" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="FilePath"> <maml:name>Path</maml:name> <maml:description> <maml:para>The path to the files to sign with an Authenticode signature. Wildcards are permitted and a signature will be outputted for every file that matches the wildcard. This is only supported for paths in the FileSystem provider.</maml:para> <maml:para>If the path does not have a file extension, the `-Provider` parameter must be set to tell the cmdlet how it should be signed.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Provider</maml:name> <maml:description> <maml:para>Specify the Authenticode provider used to sign the file. If the file has no extension then an explicit provider must be specified.</maml:para> <maml:para>Valid providers are:</maml:para> <maml:para>* `NotSpecified` - Uses the file extension to find the provider</maml:para> <maml:para>* `PowerShell` - Uses the PowerShell script Authenticode provider</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">AuthenticodeProvider</command:parameterValue> <dev:type> <maml:name>AuthenticodeProvider</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>TimeStampHashAlgorithm</maml:name> <maml:description> <maml:para>The hashing algorithm used in the counter signature timestamp if `-TimestampServer` was specified. This defaults to the value of `-HashAlgorithm` if not specified.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">HashAlgorithmName</command:parameterValue> <dev:type> <maml:name>HashAlgorithmName</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>TimestampServer</maml:name> <maml:description> <maml:para>The timestamp server used to counter sign the Authenticode signature. The time stamp represents the exact time the certificate was added to the file. A time stamp prevents the signature from being invalidated once the certificate has expired.</maml:para> <maml:para>The value specified here is the URL to an RFC 3161 compliant time stamping server. It is possible to specify the hashing algorithm the timestamp server uses with the `-TimeStampHashAlgorithm`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.String[]</maml:name> </dev:type> <maml:description> <maml:para>Accepts a list of paths for the `-Path` parameter.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para>No output is present if `-PassThru` is not specified.</maml:para> </maml:description> </command:returnValue> <command:returnValue> <dev:type> <maml:name>System.Security.Cryptography.Pkcs.SignedCms / OpenAuthenticode.AuthenticodeSignature</maml:name> </dev:type> <maml:description> <maml:para>If `-PassThru` is specified, this will output the Authenticode signature details that was signed to the path specified. This object has the following extra properties added as part of the extended type data of `OpenAuthenticode.AuthenticodeSignature`:</maml:para> <maml:para>+ `Path`: The file path that this signature is for</maml:para> <maml:para>+ `Certificate`: The X.509 certificate that signed the file</maml:para> <maml:para>+ `HashAlgorithm`: The hash algorithm that was used in the Authenticode signature</maml:para> <maml:para>+ `TimeStampInfo`: Information about the counter signature timestamp including its certificate, timestamp date in UTC, and timestamp hashing algorithm</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para>Unlike Set-AuthenticodeSignature (https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.security/set-authenticodesignature?view=powershell-7.3)this cmdlet uses an RFC 3161 compliant time stamp server for the counter signatures. Windows treats both an RFC 3161 and the legacy Authenticode timestamped signature as the same so this should not affect the validation of the signature on Windows.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>----------- Example 1: Signs a PowerShell ps1 script -----------</maml:title> <dev:code>PS C:\> $pass = Read-Host -AsSecureString -Prompt "Enter pfx password" PS C:\> $cert = Get-PfxCertificate -FilePath ~/code-signing.pfx -Password $pass PS C:\> Set-OpenAuthenticodeSignature -Path test.ps1 -Certificate $cert</dev:code> <dev:remarks> <maml:para>Signs the script `test.ps1` with the certificate specified.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>Example 2: Signs a PowerShell ps1 script and a counter signature timestamp</maml:title> <dev:code>PS C:\> $pass = Read-Host -AsSecureString -Prompt "Enter pfx password" PS C:\> $cert = Get-PfxCertificate -FilePath ~/code-signing.pfx -Password $pass PS C:\> Set-OpenAuthenticodeSignature -Path test.ps1 -Certificate $cert -TimestampServer http://timestamp.digicert.com</dev:code> <dev:remarks> <maml:para>Like example 1 but also adds a counter signature with the Digicert timestamp server.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>--------- Example 3: Sign using an Azure KeyVault key ---------</maml:title> <dev:code>PS C:\> $key = Get-OpenAuthenticodeAzKey -Vault code-signing-test -Certificate Authenticode PS C:\> Set-AuthenticodeSignature test.ps1 -Key $key</dev:code> <dev:remarks> <maml:para>Gets the Azure KeyVault key `Authenticode` in the vault `code-signing-test` and uses it to sign the file `test.ps1`. This does not include any pre-requisite steps for setting up the authentication details used by `Get-OpenAuthenticodeAzKey`.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri>https://www.github.com/jborean93/PowerShell-OpenAuthenticode/blob/main/docs/en-US/Set-OpenAuthenticodeSignature.md</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Authenticode Digital Signatures</maml:linkText> <maml:uri>https://learn.microsoft.com/en-us/windows-hardware/drivers/install/authenticode</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> </helpItems> |