CmdID / PowerShell / Cmdlets / Protect
Protect-CmsMessage
Encrypts content by using the Cryptographic Message Syntax format. PowerShell reference
From the PowerShell reference 5 parameters
What it does
Encrypts content by using the Cryptographic Message Syntax format. The Protect-CmsMessage cmdlet encrypts content by using the Cryptographic Message Syntax (CMS) format. The CMS cmdlets support encryption and decryption of content using the IETF format 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 is not 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. Before you can run the Protect-CmsMessage cmdlet, you must have an encryption certificate set up. To be recognized in PowerShell, encryption certificates require a unique extended key usage (EKU) ID to identify them as data encryption certificates (such as the IDs for Code Signing and Encrypted Mail). For an example of a certificate that would work for document encryption, see Example 1 in this topic.
Protect-CmsMessage [-To] <CmsMessageRecipient[]> [-Content] <PSObject> [[-OutFile] <String>] [<CommonParameters>]Protect-CmsMessage [-To] <CmsMessageRecipient[]> [-Path] <String> [[-OutFile] <String>] [<CommonParameters>]Protect-CmsMessage [-To] <CmsMessageRecipient[]> [-LiteralPath] <String> [[-OutFile] <String>] [<CommonParameters>]Create a certificate for encrypting content
# Create .INF file for certreq
{[Version]
Signature = "$Windows NT$"
[Strings]
szOID_ENHANCED_KEY_USAGE = "2.5.29.37"
szOID_DOCUMENT_ENCRYPTION = "1.3.6.1.4.1.311.80.1"
[NewRequest]
Subject = "cn=youralias@emailaddress.com"
MachineKeySet = false
KeyLength = 2048
KeySpec = AT_KEYEXCHANGE
HashAlgorithm = Sha1
Exportable = true
RequestType = Cert
KeyUsage = "CERT_KEY_ENCIPHERMENT_KEY_USAGE | CERT_DATA_ENCIPHERMENT_KEY_USAGE"
ValidityPeriod = "Years"
ValidityPeriodUnits = "1000"
[Extensions]
%szOID_ENHANCED_KEY_USAGE% = "{text}%szOID_DOCUMENT_ENCRYPTION%"
} | Out-File -FilePath DocumentEncryption.inf
# After you have created your certificate file, run the following command to add
# the certificate file to the certificate store. Now you are ready to encrypt and
# decrypt content with the next two examples.
certreq.exe -new DocumentEncryption.inf DocumentEncryption.cerIdentifyEncrypt a message sent by email
$Protected = "Hello World" | Protect-CmsMessage -To "youralias@emailaddress.com"IdentifyView document encryption certificates
PS C:> cd Cert:\CurrentUser\My
PS Cert:\CurrentUser\My> Get-ChildItem -DocumentEncryptionCertIdentifyIts page in the reference: Protect-CmsMessage.
Parameters
-ContentSpecifies a PSObject that contains content that you want to encrypt. For example, you can
encrypt the content of an event message, and then use the variable containing the message ($Event,
in this example) as the value of the Content parameter:
$event = Get-WinEvent -ProviderName "PowerShell" -MaxEvents 1. You can also use the Get-Content
cmdlet to get the contents of a file, such as a Microsoft Word document, and save the content in a
variable that you use as the value of the Content parameter.-LiteralPathSpecifies the path to content that you want to encrypt. Unlike Path, the value of LiteralPath is used exactly as it is typed. No characters are interpreted as wildcards. 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.-OutFileSpecifies the path and file name of a file to which you want to send the encrypted content.-PathSpecifies the path to content that you want to encrypt.-ToSpecifies 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 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).