Set-AuthenticodeSignature
SYNOPSIS
Uses an authenticode signature to sign a Windows PowerShell script or other file.
SYNTAX
Set-AuthenticodeSignature [-filePath] <string[]> [-certificate] <X509Certificate2> [-includeChain <string>] [-timeStampServer <string>] [-force] [-whatIf] [-confirm] [<CommonParameters>]
DETAILED DESCRIPTION
The Set-AuthenticodeSignature cmdlet adds an authenticode signature in any file that supports Session Initiation Protocol (SIP). In a Windows PowerShell script file, the signature takes the form of a block of text that indicates the end of the instructions that are executed in the script. If there is already a signature exists in the file when this cmdlet is run, that signature is removed.
PARAMETERS
-filePath <string[]>
Specifies the path to a file that is being signed.
|
Required? |
true |
|
Position? |
1 |
|
Default value |
Null |
|
Accept pipeline input? |
true (ByValue, ByPropertyName) |
|
Accept wildcard characters? |
true |
-certificate <X509Certificate2>
Specifies the certificate that will be used to sign the script or file. Enter a variable that stores an object representing the certificate or an expression that gets the certificate.
To find the certificate, use Get-PfxCertificate or Get-ChildItem. If the certificate is not valid or does not have code-signing authority, the command fails.
|
Required? |
true |
|
Position? |
2 |
|
Default value |
Null |
|
Accept pipeline input? |
false |
|
Accept wildcard characters? |
false |
-includeChain <string>
Determines which certificates in the certificate trust chain are included in the digital signature. "NotRoot" is the default.
Valid values are:
· "Signer": Includes only the signer's certificate.
· "NotRoot": Include all of the certificates in the certificate chain, except for the root authority.
· "All": Includes all certificates in the certificate chain.
|
Required? |
false |
|
Position? |
named |
|
Default value |
notroot |
|
Accept pipeline input? |
false |
|
Accept wildcard characters? |
false |
-timeStampServer <string>
Uses the specified timestamp server to certify the exact time that the certificate was added to the file. Type the URL of the timestamp server as a string.
|
Required? |
false |
|
Position? |
named |
|
Default value |
|
|
Accept pipeline input? |
false |
|
Accept wildcard characters? |
false |
-force <SwitchParameter>
Overrides restrictions that prevent the command from succeeding, just so the changes do not compromise security. For example, Force will override the read-only attribute or create directories to complete a file path, but it will not attempt to change file permissions.
|
Required? |
false |
|
Position? |
named |
|
Default value |
False |
|
Accept pipeline input? |
false |
|
Accept wildcard characters? |
false |
-whatIf
Describes what would happen if you executed the command without actually executing the command.
|
Required? |
false |
|
Position? |
named |
|
Default value |
|
|
Accept pipeline input? |
false |
|
Accept wildcard characters? |
false |
-confirm
Prompts you for confirmation before executing the command.
|
Required? |
false |
|
Position? |
named |
|
Default value |
|
|
Accept pipeline input? |
false |
|
Accept wildcard characters? |
false |
<CommonParameters>
This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, and -OutVariable. For more information, type, "get-help about_commonparameters".
RETURN TYPE
PsSignatureObject
NOTES
For more information, type "Get-Help Set-AuthenticodeSignature -detailed". For technical information, type "Get-Help Set-AuthenticodeSignature -full".
Before a signature is set in the file and after the certificate has been validated, the value of the Boolean shell variable "SigningApproved" must checked. If this variable is unset or set to something other than true, the ShouldProcess method shall prompt the user to confirm the signing of the script.
If TimeStampServer is set, this indicates that the designated URL should be used to acquire a TimeStamp for the signature.
The "IncludeChain" parameter indicates how much of the certificate trust-chain to embed in the signature block. The three choices allowed for this parameter are:
· None -- Only the signer's certificate shall be encoded and embedded into the script file.
· Notroot -- All certificates in the signer's trust-chain, except for the root certificate, shall be encoded and embedded into the script file.
· Fullchain -- All certificates in the signer's trust-chain, including the root certificate shall be encoded and embedded into the script file.
When specifying multiple values for a parameter, use commas to separate the values. For example, "<parameter-name> <value1>, <value2>".
EXAMPLE 1
$cert=Get-ChildItem -FilePath cert:\CurrentUser\my -CodeSigningCert
Set-AuthenticodeSignature PsTestInternet2.ps1 -cert $cert
These commands retrieve a code-signing certificate from the Windows PowerShell certificate provider and use it to sign a Windows PowerShell script.
The first command uses the Get-Childitemcmdlet and the Windows PowerShell certificate provider to get the certificates in the Cert:\CurrentUser\My subdirectory of the certificate store. (The Cert: drive is the drive exposed by the certificate provider.) The CodeSigningCert parameter, which is supported only by the certificate provider, limits the certificates retrieved to those with code-signing authority. The command stores the result in the $cert variable.
The second command uses the Set-AuthenticodeSignature cmdlet to sign the PSTestInternet2.ps1 script. It uses the FilePath parameter to specify the name of the script and the Cert parameter to specify that the certificate is stored in the $cert variable.
EXAMPLE 2
$cert = Get-PfxCertificate C:\Test\Mysign.pfx
Set-AuthenticodeSignature -Filepath ServerProps.ps1 -Cert $cert
These commands use the Get-PfxCertificatecmdlet to find a code signing certificate and then uses it to sign a Windows PowerShell script.
The first command uses the Get-PfxCertificate cmdlet to find the C:\Test\MySign.pfx certificate and store it in the $cert variable.
The second command use Set-AuthenticodeSignature to sign the script. The FilePath parameter of Set-Authenticode signature specifies the path to the script file being signed and the Cert parameter passes the $cert variable containing the certificate to Set-AuthenticodeSignature.
If the certificate file is password protected, Windows PowerShell prompts you for the password.
EXAMPLE 3
Set-AuthenticodeSignature -filepath c:\scripts\Remodel.ps1 -cert $cert -IncludeChain All -TimeStampServer "http://www.fabrikam.com/TimeManager"
This command adds a digital signature that includes the root authority in the trust chain and is signed by a third-party timestamp server.
The command uses the FilePath parameter to specify the script being signed and the Cert parameter to specify the certificate that is saved in the $cert variable. It uses the IncludeChain parameter to include all of the signatures in the trust chain (including the root authority) and the TimeStampServer parameter to specify the URL of a time stamp server that can certify the time that the script is signed.
RELATED LINKS