Unprotect-CmsMessage
Decrypts content that has been encrypted by using the Cryptographic Message Syntax format.
Syntax
Unprotect-CmsMessage
[-EventLogRecord] <EventLogRecord>
[[-To] <CmsMessageRecipient[]>]
[-IncludeContext]
[<CommonParameters>]
Unprotect-CmsMessage
[-Content] <string>
[[-To] <CmsMessageRecipient[]>]
[-IncludeContext]
[<CommonParameters>]
Unprotect-CmsMessage
[-Path] <string>
[[-To] <CmsMessageRecipient[]>]
[-IncludeContext]
[<CommonParameters>]
Unprotect-CmsMessage
[-LiteralPath] <string>
[[-To] <CmsMessageRecipient[]>]
[-IncludeContext]
[<CommonParameters>]
Description
The Unprotect-CmsMessage
cmdlet decrypts content that has been encrypted using the Cryptographic
Message Syntax (CMS) format.
The CMS cmdlets support encryption and decryption of content using the IETF standard format for cryptographically protecting messages, as documented by RFC5652.
The CMS encryption standard uses public key cryptography, where the keys used to encrypt content (the public key) and the keys used to decrypt content (the private key) are separate. Your public key can be shared widely, and isn't sensitive data. If any content is encrypted with this public key, only your private key can decrypt it. For more information, see Public-key cryptography.
Unprotect-CmsMessage
decrypts content that has been encrypted in CMS format. You can run this
cmdlet to decrypt content that you have encrypted by running the Protect-CmsMessage
cmdlet. You
can specify content that you want to decrypt as a string, by the encryption event log record ID
number, or by path to the encrypted content. The Unprotect-CmsMessage
cmdlet returns the decrypted
content.
Support for Linux and macOS was added in PowerShell 7.1.
Examples
Example 1: Decrypt a message
In the following example, you decrypt content that's located at the literal path
C:\Users\Test\Documents\PowerShell
. For the value of the required To parameter, this example
uses the thumbprint of the certificate that was used to perform the encryption. The decrypted
message, "Try the new Break All command," is the result.
$parameters = @{
LiteralPath = "C:\Users\Test\Documents\PowerShell\Future_Plans.txt"
To = '0f 8j b1 ab e0 ce 35 1d 67 d2 f2 6f a2 d2 00 cl 22 z9 m9 85'
}
Unprotect-CmsMessage -LiteralPath @parameters
Try the new Break All command
Example 2: Decrypt an encrypted event log message
The following example gets an encrypted event from the PowerShell event log and decrypts it using
Unprotect-CmsMessage
.
$event = Get-WinEvent Microsoft-Windows-PowerShell/Operational -MaxEvents 1 |
Where-Object Id -eq 4104
Unprotect-CmsMessage -EventLogRecord $event
Example 3: Decrypt encrypted event log messages using the pipeline
The following example gets all encrypted events from the PowerShell event log and decrypts them
using Unprotect-CmsMessage
.
Get-WinEvent Microsoft-Windows-PowerShell/Operational |
Where-Object Id -eq 4104 |
Unprotect-CmsMessage
Parameters
-Content
Specifies an encrypted string, or a variable containing an encrypted string.
Type: | String |
Position: | 0 |
Default value: | None |
Required: | True |
Accept pipeline input: | True |
Accept wildcard characters: | False |
-EventLogRecord
Specifies an event log record that contains a CMS encrypted message.
Type: | PSObject |
Position: | 0 |
Default value: | None |
Required: | True |
Accept pipeline input: | True |
Accept wildcard characters: | False |
-IncludeContext
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-LiteralPath
Specifies the path to encrypted content that you want to decrypt. Unlike Path, the value of LiteralPath is used exactly as it's typed. No characters are interpreted as wildcard characters. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell PowerShell not to interpret any characters as escape sequences.
Type: | String |
Position: | 0 |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Path
Specifies the path to encrypted content that you want to decrypt.
Type: | String |
Position: | 0 |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-To
Specifies one or more CMS message recipients, identified in any of the following formats:
- An actual certificate (as retrieved from the certificate provider).
- Path to the a file containing the certificate.
- Path to a directory containing the certificate.
- Thumbprint of the certificate (used to look in the certificate store).
- Subject name of the certificate (used to look in the certificate store).
Type: | CmsMessageRecipient[] |
Position: | 1 |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Inputs
You can pipe an object containing encrypted content to this cmdlet.
Outputs
This cmdlet returns the unencrypted message.